このワークフローを使用する前に、.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 は同じフラグの v1.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 カテゴリは常にプロンプトを表示)。
レビュー対象の GDD の workflow — ブロックにシステムがリストされている場合は <system> の system_overrides 行を使用し、それ以外の場合はプロジェクトの値を使用します。検証範囲はティアに従います:
full— 全 8 セクションを検証。欠落セクションがあれば承認をブロック。standard— 5 つの必須セクション (概要、詳細ルール、エッジケース、依存関係、受け入れ基準) が欠落しているとブロック。数式は、システムが数値ルール (レート、曲線、しきい値、コスト — カテゴリはヒントでありテストではありません) を定義する場合にのみブロックします。プレイヤーファンタジーとチューニングノブは、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 全体が必要です。40 KB を超えるファイル全体の読み取りは拒否されるため、見出し (Grep ツール: パターン ^#、コンテンツモード) で範囲を区切って読み取ります。プロジェクトのコンテキストと標準を理解するために 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: ブロックが含まれます。2 番目のコマンドは、このシステムを 参照する エントリを見つけます。referenced_by: はブロックシーケンスであるため (referenced_by.*name のワンライナーはブロック形式と一致しません)、パスを -B 8 コンテキストで一致させて、所有エントリを表示します。
design/registry/entities.yaml が存在しない場合、またはこのシステムのエントリがリストされていない場合 — ファイルは空のスタブとして出荷されるため、$design-system がデータを投入するまでのデフォルトです — 対象ドキュメントが依存関係セクションで指定している関連 GDD を読み取るフォールバックを行います。読み取りをそれらの GDD に限定し、"暗黙的に" 示唆されるすべてのものには及びません。design/gdd/ 内のすべてをグロブ読み取りしないでください。
依存関係グラフの検証: 依存関係セクションにリストされているシステムごとに、Glob を使用してその GDD ファイルが design/gdd/ に存在するかどうかを確認します。まだ存在しないものがあればフラグを立てます。これらは、下流の作成者が遭遇する壊れた参照です。
ロア/ナラティブの整合性: design/gdd/game-concept.md (または、rigor: minimal の場合は 1 ページのブリーフ 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: リスト ([To be designed] のみを保持する存在するセクション: まだ作成されていないため、チェックリストでは欠落として扱います) が出力されます。存在のみ を報告し、REQUIRED/ADVISORY の判断は行いません — これはステップ 2b の役割です。## Detailed Design が Detailed Rules 要件を満たすものとしてすでに受け入れているため、それを欠落としてフラグを立てないでください。
ステップ 2b — ティアを適用します。 ステップ 2a のリストを使用して、以下の設計ドキュメント標準チェックリストに照らして評価します。解決されたワークフローティア (フェーズ 0) に従って、各セクションを REQUIRED または ADVISORY としてマークします。 必須セクションの欠落は承認をブロックします。アドバイザリセクションの欠落は推奨事項として表面化されますが、ブロックはしません。
PRESENT と報告されたセクションでも、空の見出しの場合はレビューに不合格となる可能性があります。評決が実際に依存するセクションをスポット読み取りしてください。
- 概要セクション (1 段落の要約) がある — すべてのティアで REQUIRED
- プレイヤーファンタジーセクション (意図する感覚) がある —
fullで REQUIRED。standardでは ADVISORY - 詳細ルールセクション (曖昧さのないメカニクス) がある —
full/standardで REQUIRED。GDD テンプレートはこのセクションに## Detailed Designというタイトルを付けています (コアルール/ステート/インタラクションの小見出しを持ちます)。この要件を満たすものとして どちらかの 見出しを受け入れます。## Detailed Designセクションが存在する場合に "Detailed Rules" が欠落しているとしてフラグを立てないでください。 - 数式セクション (すべての計算式が変数で定義されている) がある —
fullで REQUIRED。standardでは、システムが数値ルール (レート、曲線、しきい値、コスト、ダメージ、ドロップ重み) を定義する場合は常に REQUIRED。それ以外の場合は ADVISORY。システムのカテゴリはヒントであり、テストではありません。カテゴリトークンのみでこれをクリアしないでください。 - エッジケースセクション (異常な状況の処理) がある —
full/standardで REQUIRED - 依存関係セクション (他のシステムのリスト) がある —
full/standardで REQUIRED - チューニングノブセクション (設定可能な値の特定) がある —
fullで REQUIRED。standardでは、workflow_overrides.tuning_knobsがない限り ADVISORY - 受け入れ基準セクション (テスト可能な成功条件) がある —
full/standardで REQUIRED
フェーズ 3: 一貫性と実装可能性
内部一貫性:
- 数式は、説明されている動作と一致する値を生成しますか?
- エッジケースはメインルールと矛盾していますか?
- 依存関係は双方向ですか (相手システムはこのシステムについて知っていますか)?
実装可能性:
- ルールは、プログラマーが推測せずに実装できるほど正確ですか?
- 詳細が欠落している "ごまかし" のセクションはありますか?
- パフォーマンスへの影響は考慮されていますか?
- すべての受け入れ基準は独立してテスト可能ですか? テスト可能でないものをそれぞれ引用してフラグを立ててください — "バランスが取れている"、"正しく動作する"、"パフォーマンスが良い" は基準ではありません — 測定可能な書き直しを提案してください。
fullモードではqa-leadもそれらをチェックします (フェーズ 3b)。leanおよびsoloモードでは専門家は実行されないため、このメインのレビューチェックのみが行われます。
システム間の一貫性:
- これは既存のメカニクスと競合しますか?
- これは他のシステムとの意図しない相互作用を生み出しますか?
- これはゲームの確立されたトーンと柱と一致していますか?
GDD が述べている場所であれば、レジストリの値。 テーブル、カタログエントリ、またはバリアントノートで再記述された値は、詳細ルールに記載されているのと同じくらい確実にレジストリと矛盾します。セクションごとに読むと、これらの本文を見落としがちです。レジストリのエントリ名 (grep -E '^ - name:' design/registry/entities.yaml) をリストし、次に対象ドキュメント全体をそれらすべてとそれらが持つ数値キーについて、大文字小文字を区別せずに 1 回検索します。各 _ を [_ ] と記述して、goblin_scout が "Goblin scouts" にも一致するようにします:
grep -n -i -E 'goblin[_ ]scout|iron[_ ]sword|health|value[_ ]gold' [target-doc-path]
出力されるすべての行を、それがどのセクションに含まれているかに関係なく、レジストリと照合してチェックします。エントリに異なる値を与える行は、たとえ 1 つの部屋、バリアント、レベル、例外であっても、所有 GDD と矛盾します。[Required Before Implementation] の下に、その行番号、このドキュメントの値、レジストリの値をリストします。レジストリエントリがない場合は、関連する GDD が定義するエンティティと値に対して同じ検索を実行します。
フェーズ 3b: 敵対的専門家レビュー (フルモードのみ)
このフェーズは lean または solo モードではスキップします。
このフェーズはフルモードでは必須です。 スキップしないでください。
エージェントを生成する前に、次の通知を出力します:
"完全レビュー: 専門エージェントを並列生成中。通常 8〜15 分かかります。より高速な単一セッション分析には
--review leanを使用してください。"
ステップ 1 — GDD が触れるすべてのドメインを特定する
フェーズ 1 で既に読み込まれている GDD を使用して — 再読み取りしないでください — 存在するすべてのドメインを特定します。1 つの GDD が複数のドメインに同時に触れる可能性があります。徹底的に行ってください。一般的なシグナル:
| GDD に含まれるもの... | これらのエージェントを生成 |
|---|---|
| コスト、価格、ドロップ、報酬、経済 | economy-designer |
| 戦闘統計、ダメージ、体力、DPS | game-designer、systems-designer |
| AI 動作、経路探索、ターゲット設定 | ai-programmer |
| レベルレイアウト、スポーン、ウェーブ構成 | level-designer |
| プレイヤーの進行、経験値、アンロック | 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。## エンジンスペシャリスト のプライマリ行にフォールバック |
(翻訳が切り詰められました...)