이 워크플로우를 사용하기 전에 .codex/docs/codex-runtime.md를 읽으십시오. 현재 사용자 인증 및 호스트 권한을 따르십시오.
인수: [path-to-design-doc] [--review full|lean|solo]
진행하기 전에 프로젝트 루트에서 다음 설정 명령을 실행하십시오:
bash ".codex/hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,system_overrides
위 명령을 그대로 사용하여 설정을 해석하십시오. --review는 review_mode를 재정의합니다. --depth는 동일한 플래그의 1.1 이전 이름입니다. --depth <mode>를 --review <mode>와 동일하게 처리하고, 이름이 변경되었음을 한 번 언급하십시오. 두 플래그가 모두 제공된 경우 --review가 우선하며 --depth는 무시됩니다. 이 사실을 명시하십시오. 블록이 없으면 .codex/docs/config-resolution.md의 기본값을 사용하십시오.
디자인 검토
0단계: 인수 분석
전체 검사 패턴은 .codex/docs/director-gates.md를 참조하십시오. 개별 게이트 정의는 .codex/docs/director-gates/[gate-id].md에 있습니다. 생성된 에이전트는 자신의 게이트 파일을 읽습니다. 상위 세션에서는 이 파일을 읽지 마십시오.
모든 request_user_input 호출은 .codex/docs/automation-modes.md를 따릅니다 (협력적 요청은 항상 · 안내 모드는 주요 작업만 · 자율 모드는 기록 후 진행). automation_always_ask 카테고리는 항상 프롬프트를 표시합니다.
**workflow**는 검토 대상 GDD에 대한 것입니다. 블록에 시스템별 값이 명시된 경우 system_overrides 행의 <system> 값을 사용하고, 그렇지 않으면 프로젝트 값을 사용합니다. 검증 범위는 티어를 따릅니다:
full— 전체 8개 섹션 검증; 누락된 섹션이 있으면 승인 불가.standard— 필수 5개 섹션(개요, 상세 규칙, 예외 사례, 의존성, 승인 기준)이 누락되면 승인 불가. 공식(Formulas) 섹션은 시스템이 수치 규칙(비율, 곡선, 임계값, 비용)을 정의하는 경우에만 차단. 플레이어 환상(Player Fantasy) 및 튜닝 노브(Tuning Knobs)는 권고 사항(경고, 차단 안 함)이며,workflow_overrides에서 요구하지 않는 한 차단하지 않음.minimal— GDD가 예상되지 않음. 존재하는 경우 5개 표준 섹션을 권고적으로 검증.
해결된 모드는 검토의 세부 수준을 제어합니다:
full: 전체 검토 — 모든 단계 + 전문가 에이전트 위임 (3b단계)lean: 모든 단계, 전문가 에이전트 없음 — 더 빠른 단일 세션 분석solo: 1~4단계만, 위임 없음, 5단계 다음 단계 프롬프트 없음 — 다른 스킬 내에서 호출될 때 사용
1단계: 문서 로드
먼저 신선도 검사 수행 — 변경되지 않은 문서를 재검토하면 전체 비용이 발생하고 동일한 판정이 반복됩니다. 실행:
Bash: bash .codex/scripts/review-receipts.sh check "design/gdd/reviews/[doc-name]-review-log.md" "[target-doc-path]" "design/registry/entities.yaml" ".agents/skills/design-review/SKILL.md"
레지스트리가 검사에 포함되는 이유는 이 검토가 문서 간 사실을 확인할 때 레지스트리를 참조하기 때문입니다. 변경되지 않은 GDD가 변경된 레지스트리와 함께 검토되면 다른 결론에 도달할 수 있으므로, 모든 줄이 UNCHANGED로 표시될 때만 건너뛰기가 안전합니다 (존재하지 않았던 레지스트리는 출력에 나타나지 않으며 건너뛰기를 차단하지 않습니다). 이 스킬의 파일이 포함된 이유는 변경된 스킬이 검토 방식에 영향을 주기 때문입니다. 또한 검사는 로그가 기록한 다른 모든 파일(관련 GDD, 이전 검토에서 읽은 컨셉, 브리프, 내러티브 파일)을 비교하고, 더 이상 존재하지 않는 파일에 대해 GONE:을 출력합니다.
그런 다음 최신 항목의 Review mode: 줄을 읽습니다. 해당 검토가 이번 실행을 포함하는 것은 해당 모드가 현재 해결된 모드와 같거나 더 깊고(full > lean > solo), 워크플로우가 같거나 더 깊을 (full > standard > minimal) 때만입니다. 해당 줄이 없는 항목은 그 줄이 생성되기 전에 작성된 것이며 아무것도 포함하지 않습니다.
- **모두
UNCHANGED**이고 로그의 최신 항목에 판정이 있는 경우 — 이를 표면화: "이 문서는 [날짜]에 마지막으로 검토된 이후로 바이트가 동일합니다 ([모드] 검토, 판정: [판정])." 해당 판정이 APPROVED였고 이번 실행을 포함하는 경우request_user_input을 통해 다음을 제공:[A] 이전 판정 사용 (권장)/[B] 다시 검토—guided는 [A]로 진행하고 기록;autonomous는log_decision으로 기록하고 이전 판정 사용. APPROVED였지만 지금 요청된 검토가 기록된 것보다 더 깊은 경우 — "[모드] 검토, 워크플로우 [티어]였습니다. 이번 실행은 [모드], [티어]를 요청합니다." — 라고 말하고[A] [모드]로 재검토 (권장)/[B] 이전 [모드] 판정 사용을 제공;guided와autonomous는 재검토 (autonomous는log_decision으로 기록). NEEDS REVISION 또는 MAJOR REVISION NEEDED인 경우 명확히 말함: 문서가 검토 실패 이후 변경되지 않음 — 이전 결과가 유효함; 문서 수정이 다음 단계이지 재검토가 아님. 로그에서 이전 결과를 표시하는 옵션을 제공. - 대상 문서와 이 스킬의 파일이
UNCHANGED이고, 레지스트리 또는 다른 기록된 문서 간 파일만CHANGED,NEW또는GONE인 경우 — 문서 간 사실을 제외하고 이전 판정이 유효함: 변경된 파일에 대해 문서의 값을 다시 확인하고 판정을 재발행; 충돌이 발생하거나 해당 검토가 이번 실행을 포함하지 않는 경우 전체 재검토로 상향. - 대상 문서 또는 이 스킬의 파일이
CHANGED또는NEW이거나RECEIPT: NONE인 경우 — 아래 전체 검토를 진행. 변경되지 않은 섹션 읽기/재분석을 건너뛰는 부분/델타 재검토를 제공하지 마십시오. 섹션 범위 재검토는 전체 검토가 찾는 결함을 놓칠 수 있으며 시간 절약 효과도 거의 없습니다. "마지막 검토 이후 변경되지 않음"은 단지 당시 검토된 내용과 바이트가 동일하다는 의미일 뿐, 이전 검토 자체가 완전했는지에 대해서는 아무것도 말해주지 않으며, 모든 것을 스캔하라는 지시에도 불구하고 주의가 표시된 변경 사항에만 집중됩니다.
대상 디자인 문서를 전체 읽기. 이 단계에서는 전체 GDD가 필요합니다: 헤딩별로 범위를 나누어 읽습니다 (Grep 도구 사용: 패턴 ^#, 콘텐츠 모드). 40KB가 넘는 전체 파일 읽기는 거부됩니다. AGENTS.md를 읽어 프로젝트 컨텍스트와 표준을 이해하십시오.
문서 간 사실의 경우, 형제 GDD보다 레지스트리를 우선시하십시오. design/registry/entities.yaml이 존재하고 이 시스템에 대한 항목을 나열하는 경우, 이를 grep하십시오 — 이는 이 GDD가 모순되어서는 안 되는 확립된 사실이며, 형제 GDD를 다시 읽어 재발견할 필요가 없습니다:
Grep pattern="source: design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -A 6
Grep pattern="design/gdd/[system].md" path="design/registry/entities.yaml" output_mode="content" -B 8
첫 번째는 이 시스템이 소유한 항목을 찾습니다 — -A 6 컨텍스트에는 referenced_by: 블록이 포함됩니다. 두 번째는 이 시스템을 참조하는 항목을 찾습니다 — referenced_by:는 블록 시퀀스이므로(키와 경로가 별도 줄에 있음), -B 8 컨텍스트로 경로를 일치시켜 참조 항목이 아닌 소유 항목을 확인합니다.
design/registry/entities.yaml이 존재하지 않거나 이 시스템에 대한 항목이 없는 경우 — 파일이 빈 스텁으로 제공되므로 $design-system이 채울 때까지 이 상태가 기본값입니다 — 대상 문서가 의존성 섹션에 명명한 관련 GDD를 읽는 것으로 대체합니다. 읽기 범위를 해당 GDD로 제한하고, "암시된" 모든 것은 읽지 마십시오. design/gdd/의 모든 파일을 글로브 읽기하지 마십시오.
의존성 그래프 검증: 의존성 섹션에 나열된 각 시스템에 대해 Glob을 사용하여 design/gdd/에 해당 GDD 파일이 있는지 확인하십시오. 아직 존재하지 않는 파일은 플래그를 지정하십시오 — 이는 다운스트림 작성자가 직면할 끊어진 참조입니다.
로어/내러티브 정렬: design/gdd/game-concept.md (또는 rigor: minimal의 경우 한 페이지 브리프 design/game-brief.md) 또는 design/narrative/의 파일이 존재하는 경우 읽으십시오. 이 GDD의 기계적 선택이 확립된 세계 규칙, 분위기 또는 디자인 핵심 원칙과 모순되는지 기록하십시오. 이 컨텍스트를 3b단계에서 game-designer에게 전달하십시오.
이전 검토 확인: design/gdd/reviews/[doc-name]-review-log.md가 존재하는지 확인하십시오. 존재하는 경우 가장 최근 항목을 읽고 어떤 판정이 내려졌고 어떤 차단 항목이 나열되었는지 기록하십시오. 이 세션은 재검토입니다. 이전 항목이 해결되었는지 추적하십시오.
2단계: 완전성 검사
2a단계 — 결정론적으로 섹션 존재 여부 수집 (문서 읽기 없음):
Bash: bash .codex/scripts/gdd-structure-check.sh [target-doc-path]
이 명령은 PRESENT: 목록과, 해당되는 경우 ABSENT: 목록 및 PLACEHOLDER: 목록(있는 섹션이지만 [설계 예정]만 포함: 아직 작성되지 않았으므로 체크리스트에서 누락된 것으로 처리)을 출력합니다. 존재 여부만 보고하며 REQUIRED/ADVISORY 판단은 하지 않습니다 — 이는 2b단계의 작업입니다. ## Detailed Design을 Detailed Rules 요구 사항을 충족하는 것으로 이미 인정하므로, 이를 누락으로 플래그 지정하지 마십시오.
2b단계 — 티어 적용. 2a단계 목록을 사용하여 아래 디자인 문서 표준 체크리스트에 대해 평가하십시오. 해결된 워크플로우 티어(0단계)에 따라 각 섹션을 REQUIRED 또는 ADVISORY로 표시하십시오. 누락된 REQUIRED 섹션은 승인을 차단합니다. 누락된 ADVISORY 섹션은 권장 사항으로 표시되지만 차단하지 않습니다.
PRESENT로 보고된 섹션이라도 빈 제목인 경우 검토에 실패할 수 있습니다 — 판정이 실제로 좌우되는 섹션을 스팟 읽기하십시오.
- 개요(Overview) 섹션 있음 (한 문단 요약) — 모든 티어에서 REQUIRED
- 플레이어 환상(Player Fantasy) 섹션 있음 (의도된 느낌) —
full에서 REQUIRED;standard에서 ADVISORY - 상세 규칙(Detailed Rules) 섹션 있음 (모호하지 않은 메커니즘) —
full/standard에서 REQUIRED. GDD 템플릿은 이 섹션의 제목을## Detailed Design으로 지정합니다 (핵심 규칙/상태/상호작용 하위 제목 포함). 이 요구 사항을 충족하는 것으로 두 제목 모두 인정하십시오 —## Detailed Design섹션이 있을 때 "Detailed Rules"가 누락되었다고 플래그 지정하지 마십시오. - 공식(Formulas) 섹션 있음 (모든 수학이 변수로 정의됨) —
full에서 REQUIRED;standard에서는 시스템이 수치 규칙(비율, 곡선, 임계값, 비용, 피해, 드롭 가중치)을 정의할 때마다 REQUIRED, 그 외에는 ADVISORY. 시스템의Category는 힌트일 뿐 테스트가 아닙니다 — 카테고리 토큰만으로 이 항목을 통과시키지 마십시오. - 예외 사례(Edge Cases) 섹션 있음 (비정상 상황 처리) —
full/standard에서 REQUIRED - 의존성(Dependencies) 섹션 있음 (다른 시스템 나열) —
full/standard에서 REQUIRED - 튜닝 노브(Tuning Knobs) 섹션 있음 (구성 가능한 값 식별) —
full에서 REQUIRED;standard에서 ADVISORY (workflow_overrides.tuning_knobs가 없는 경우) - 승인 기준(Acceptance Criteria) 섹션 있음 (테스트 가능한 성공 조건) —
full/standard에서 REQUIRED
3단계: 일관성 및 구현 가능성
내부 일관성:
- 공식이 설명된 동작과 일치하는 값을 생성합니까?
- 예외 사례가 주요 규칙과 모순됩니까?
- 의존성이 양방향입니까 (다른 시스템이 이 시스템에 대해 알고 있습니까)?
구현 가능성:
- 규칙이 프로그래머가 추측 없이 구현할 수 있을 만큼 정밀합니까?
- 세부 정보가 누락된 "얼버무리는" 섹션이 있습니까?
- 성능 영향이 고려되었습니까?
- 모든 승인 기준이 독립적으로 테스트 가능합니까? 그렇지 않은 각 기준을 인용하여 플래그 지정하십시오 — "밸런스가 맞는 느낌", "올바르게 작동", "성능이 좋음"은 기준이 아닙니다 — 측정 가능한 재작성과 함께 제시하십시오.
full모드에서는qa-lead도 이를 확인합니다 (3b단계).lean및solo에서는 전문가가 실행되지 않으므로 이 메인 검토 확인이 유일한 확인입니다.
교차 시스템 일관성:
- 이것이 기존 메커니즘과 충돌합니까?
- 이것이 다른 시스템과 의도치 않은 상호작용을 생성합니까?
- 이것이 게임의 확립된 분위기 및 핵심 원칙과 일관됩니까?
레지스트리 값, GDD가 명시하는 모든 곳에서. 표, 카탈로그 항목 또는 변형 노트에 재진술된 값은 상세 규칙에 있는 값만큼 확실하게 레지스트리와 모순됩니다. 섹션별로 읽으면 해당 본문을 간과하기 쉽습니다. 레지스트리의 항목 이름을 나열한 다음 (grep -E '^ - name:' design/registry/entities.yaml), 대상 전체 문서에서 해당 이름과 그들이 전달하는 숫자 키를 대소문자 구분 없이 한 번에 검색하십시오. 각 _를 [_ ]로 작성하여 goblin_scout가 "Goblin scouts"도 일치하도록 하십시오:
grep -n -i -E 'goblin[_ ]scout|iron[_ ]sword|health|value[_ ]gold' [target-doc-path]
출력된 모든 줄을 레지스트리와 대조하여 확인하십시오. 어떤 섹션에 있든 관계없이, 한 방, 변형, 레벨 또는 예외에 대해서라도 항목에 다른 값을 부여하는 줄은 소유 GDD와 모순됩니다: 구현 전 필수 사항 아래에 줄 번호, 이 문서의 값 및 레지스트리의 값을 함께 나열하십시오. 레지스트리 항목이 없는 경우, 관련 GDD가 정의하는 엔티티와 값에 대해 동일한 검색을 실행하십시오.
3b단계: 대립적 전문가 검토 (full 모드 전용)
lean 또는 solo 모드에서는 이 단계를 건너뜁니다.
이 단계는 full 모드에서 MANDATORY입니다. 건너뛰지 마십시오.
에이전트를 생성하기 전에 다음 공지를 출력하십시오:
"전체 검토: 전문가 에이전트를 병렬로 생성합니다. 일반적으로 8~15분이 소요됩니다. 더 빠른 단일 세션 분석을 위해
--review lean을 사용하십시오."
1단계 — GDD가 다루는 모든 도메인 식별
이미 1단계에서 로드된 GDD를 사용하여 — 다시 읽지 마십시오 — 존재하는 모든 도메인을 식별하십시오. 하나의 GDD가 여러 도메인을 동시에 다룰 수 있습니다 — 철저히 하십시오. 일반적인 신호:
| GDD에 다음이 포함된 경우... | 다음 에이전트 생성 |
|---|---|
| 비용, 가격, 드롭, 보상, 경제 | economy-designer |
| 전투 능력치, 피해, 체력, DPS | game-designer, systems-designer |
| AI 행동, 경로 찾기, 타겟팅 | ai-programmer |
| 레벨 배치, 스폰, 웨이브 구조 | level-designer |
| 플레이어 진행, XP, 잠금 해제 | economy-designer, game-designer |
| UI, HUD, 메뉴, 플레이어 대상 디스플레이 | ux-designer, ui-programmer |
| 대화, 퀘스트, 스토리, 로어 | narrative-director |
| 애니메이션, 느낌, 타이밍, 쥬스 | gameplay-programmer |
| 멀티플레이어, 동기화, 복제 | network-programmer |
| 오디오 큐, 음악 트리거 | audio-director |
| 성능, 드로우 콜, 메모리 | performance-analyst |
| 엔진 특정 패턴 또는 API | 기본 엔진 전문가 (<engine>-specialist from engine.name — Godot→godot-specialist, Unity→unity-specialist, Unreal→unreal-specialist; ## Engine Specialists의 Primary 라인으로 대체 |
…
[번역을 위해 잘림]