부록. 실무 템플릿

엔터프라이즈 Next.js 모노레포에 바로 적용할 수 있는 운영 템플릿 모음

핵심 요약

각 장의 원칙을 바로 적용하는 최소 운영 템플릿 모음으로, 조직명·앱 이름·보안 정책만 바꿔 시작합니다.
turbo.json·GitHub Actions CI(--affected)·Vercel Deploy(prebuilt)·CODEOWNERS 템플릿으로 빌드·배포·소유권 게이트를 구성합니다.
Codex requirements.toml과 Claude/Codex Hook Policy 템플릿으로 에이전트 권한·sandbox·MCP를 제한하되, 훅은 권한 프로필·CI 게이트를 대체하지 않습니다.
Incident Runbook은 Triage→Stabilize→Recover→Learn 4단계로 구성하고 포스트모템에 owner와 due date를 지정합니다.
ADR 템플릿은 상태·맥락·결정·대안·결과를 한 형식으로 기록해 의사결정 이력을 남깁니다.

이 부록은 각 장의 원칙을 프로젝트에 적용할 때 쓰는 최소 템플릿입니다. 조직명, 앱 이름, 보안 정책만 바꿔 시작한 뒤 실제 운영 데이터에 맞게 좁혀가세요.

turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "stream",
  "globalDependencies": ["package.json", "yarn.lock", "tsconfig.json"],
  "globalEnv": ["NODE_ENV", "VERCEL_URL"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", "!**/*.test.*", "!**/*.spec.*"],
      "outputs": [".next/**", "dist/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_APP_URL", "DATABASE_URL"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.*", "playwright.config.*"],
      "outputs": ["coverage/**", "test-results/**", "playwright-report/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

GitHub Actions CI

name: CI
on:
  pull_request:
  push:
    branches: [main]

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: yarn

      - run: corepack enable
      - run: yarn install --immutable
      - run: turbo run lint typecheck test build --affected

--affected는 변경된 패키지와 그 영향을 받는 패키지만 실행합니다. fetch-depth: 0이 없으면 기준 브랜치 비교가 불안정해질 수 있습니다.

Vercel Deploy

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm install -g vercel
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

Rolling Releases를 쓰는 프로젝트는 Vercel Dashboard에서 단계를 관리하거나 vercel rolling-release configure로 10% -> 50% -> 100% 같은 승격 단계를 명시합니다.

CODEOWNERS

*                    @acme/engineering-leads

/apps/web/           @acme/frontend-team
/apps/admin/         @acme/frontend-team
/apps/docs/          @acme/platform-team

/packages/db/        @acme/backend-team @acme/platform-team
/packages/ui/        @acme/design-system-team
/packages/utils/     @acme/platform-team

/.github/            @acme/platform-team
/turbo.json          @acme/platform-team
/package.json        @acme/platform-team

Branch protection에서 "Require review from Code Owners"를 켜야 CODEOWNERS가 실제 게이트로 동작합니다.

Codex requirements.toml

allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
allowed_web_search_modes = ["cached"]
allowed_approvals_reviewers = ["user", "auto_review"]

[features]
codex_hooks = true
in_app_browser = false
computer_use = false

[permissions.filesystem]
deny_read = [
  "./.env*",
  "./private/**",
]

[rules]
prefix_rules = [
  { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use an explicit cleanup script instead." },
  { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require human review before changing shared history." },
]

[mcp_servers.docs]
identity = { command = "codex-mcp" }

Business/Enterprise 조직은 이 파일을 cloud-managed requirements, MDM, 또는 시스템 requirements.toml로 배포할 수 있습니다. 로컬 프로젝트 설정보다 조직 정책이 우선합니다.

Claude/Codex Hook Policy

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "node ./scripts/agent-policy-check.mjs"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|apply_patch",
        "command": "node ./scripts/agent-change-log.mjs"
      }
    ]
  }
}

훅은 보안 정책을 대체하지 않습니다. 훅이 실패하거나 우회될 때도 권한 프로필, sandbox, CODEOWNERS, CI 게이트가 별도로 동작해야 합니다.

Incident Runbook

# Incident Runbook

## 1. Triage
- [ ] 영향 앱과 배포 URL 확인
- [ ] P0/P1/P2/P3 심각도 지정
- [ ] Incident Commander와 커뮤니케이션 담당자 지정

## 2. Stabilize
- [ ] Vercel Analytics, Speed Insights, Sentry, 로그 확인
- [ ] Rolling Release 중이면 단계 중지 또는 abort
- [ ] 필요 시 Instant Rollback 실행

## 3. Recover
- [ ] 핫픽스 또는 롤백 후 핵심 사용자 흐름 재검증
- [ ] 오류율, latency, Core Web Vitals 회복 확인
- [ ] 상태 페이지와 고객 커뮤니케이션 갱신

## 4. Learn
- [ ] 24~48시간 안에 포스트모템 작성
- [ ] 재발 방지 작업에 owner와 due date 지정
- [ ] 모니터링, 테스트, 배포 게이트 보강

ADR Template

# ADR-000: 제목

## 상태
제안됨 | 승인됨 | 대체됨

## 맥락
결정이 필요한 배경, 제약, 실패 비용을 적습니다.

## 결정
선택한 접근을 한 문단으로 명확히 씁니다.

## 대안
- 대안 A: 장점과 배제 이유
- 대안 B: 장점과 배제 이유

## 결과
코드, 운영, 비용, 보안, 팀 프로세스에 생기는 변화를 적습니다.

핵심 요약

각 장의 원칙을 바로 적용하는 최소 운영 템플릿 모음으로, 조직명·앱 이름·보안 정책만 바꿔 시작합니다.
turbo.json·GitHub Actions CI(--affected)·Vercel Deploy(prebuilt)·CODEOWNERS 템플릿으로 빌드·배포·소유권 게이트를 구성합니다.
Codex requirements.toml과 Claude/Codex Hook Policy 템플릿으로 에이전트 권한·sandbox·MCP를 제한하되, 훅은 권한 프로필·CI 게이트를 대체하지 않습니다.
Incident Runbook은 Triage→Stabilize→Recover→Learn 4단계로 구성하고 포스트모템에 owner와 due date를 지정합니다.
ADR 템플릿은 상태·맥락·결정·대안·결과를 한 형식으로 기록해 의사결정 이력을 남깁니다.

turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "stream",
  "globalDependencies": ["package.json", "yarn.lock", "tsconfig.json"],
  "globalEnv": ["NODE_ENV", "VERCEL_URL"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", "!**/*.test.*", "!**/*.spec.*"],
      "outputs": [".next/**", "dist/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_APP_URL", "DATABASE_URL"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.*", "playwright.config.*"],
      "outputs": ["coverage/**", "test-results/**", "playwright-report/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

GitHub Actions CI

name: CI
on:
  pull_request:
  push:
    branches: [main]

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: yarn

      - run: corepack enable
      - run: yarn install --immutable
      - run: turbo run lint typecheck test build --affected

--affected는 변경된 패키지와 그 영향을 받는 패키지만 실행합니다. fetch-depth: 0이 없으면 기준 브랜치 비교가 불안정해질 수 있습니다.

Vercel Deploy

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm install -g vercel
      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

Rolling Releases를 쓰는 프로젝트는 Vercel Dashboard에서 단계를 관리하거나 vercel rolling-release configure로 10% -> 50% -> 100% 같은 승격 단계를 명시합니다.

CODEOWNERS

*                    @acme/engineering-leads

/apps/web/           @acme/frontend-team
/apps/admin/         @acme/frontend-team
/apps/docs/          @acme/platform-team

/packages/db/        @acme/backend-team @acme/platform-team
/packages/ui/        @acme/design-system-team
/packages/utils/     @acme/platform-team

/.github/            @acme/platform-team
/turbo.json          @acme/platform-team
/package.json        @acme/platform-team

Branch protection에서 "Require review from Code Owners"를 켜야 CODEOWNERS가 실제 게이트로 동작합니다.

Codex requirements.toml

allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
allowed_web_search_modes = ["cached"]
allowed_approvals_reviewers = ["user", "auto_review"]

[features]
codex_hooks = true
in_app_browser = false
computer_use = false

[permissions.filesystem]
deny_read = [
  "./.env*",
  "./private/**",
]

[rules]
prefix_rules = [
  { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use an explicit cleanup script instead." },
  { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require human review before changing shared history." },
]

[mcp_servers.docs]
identity = { command = "codex-mcp" }

Claude/Codex Hook Policy

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "node ./scripts/agent-policy-check.mjs"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|apply_patch",
        "command": "node ./scripts/agent-change-log.mjs"
      }
    ]
  }
}

훅은 보안 정책을 대체하지 않습니다. 훅이 실패하거나 우회될 때도 권한 프로필, sandbox, CODEOWNERS, CI 게이트가 별도로 동작해야 합니다.

Incident Runbook

# Incident Runbook

## 1. Triage
- [ ] 영향 앱과 배포 URL 확인
- [ ] P0/P1/P2/P3 심각도 지정
- [ ] Incident Commander와 커뮤니케이션 담당자 지정

## 2. Stabilize
- [ ] Vercel Analytics, Speed Insights, Sentry, 로그 확인
- [ ] Rolling Release 중이면 단계 중지 또는 abort
- [ ] 필요 시 Instant Rollback 실행

## 3. Recover
- [ ] 핫픽스 또는 롤백 후 핵심 사용자 흐름 재검증
- [ ] 오류율, latency, Core Web Vitals 회복 확인
- [ ] 상태 페이지와 고객 커뮤니케이션 갱신

## 4. Learn
- [ ] 24~48시간 안에 포스트모템 작성
- [ ] 재발 방지 작업에 owner와 due date 지정
- [ ] 모니터링, 테스트, 배포 게이트 보강

ADR Template

# ADR-000: 제목

## 상태
제안됨 | 승인됨 | 대체됨

## 맥락
결정이 필요한 배경, 제약, 실패 비용을 적습니다.

## 결정
선택한 접근을 한 문단으로 명확히 씁니다.

## 대안
- 대안 A: 장점과 배제 이유
- 대안 B: 장점과 배제 이유

## 결과
코드, 운영, 비용, 보안, 팀 프로세스에 생기는 변화를 적습니다.

turbo.json

GitHub Actions CI

Vercel Deploy

CODEOWNERS

Codex requirements.toml

Claude/Codex Hook Policy

Incident Runbook

ADR Template

목차

부록. 실무 템플릿

turbo.json

GitHub Actions CI

Vercel Deploy

CODEOWNERS

Codex requirements.toml

Claude/Codex Hook Policy

Incident Runbook

ADR Template

목차