grill-with-docs-codex

Grill-with-Docs-Codex — ドメインについて徹底的に検討し、レビューを受ける

2幕構成です。第1幕では、意図をすり合わせ、更新され続けるドキュメントの正確さも保ちます。第2幕では、別のモデルに結果を攻撃的にレビューさせます。

• 第1幕は、Matt Pocock の grill-with-docs を MIT ライセンスのもとで使用します（THIRD-PARTY-NOTICES.md を参照）。ユーザーに質問を重ね、CONTEXT.md／ADR と照らし合わせて計画に異議を唱え、インラインでドキュメントを更新します。
• 第2幕は、オリジナルの Codex による敵対的レビューのループです。モデルをまたいで、読み取り専用で、範囲を限定して行います。

開始するのは2つの時点です。徹底的な検討への回答時と、収束した計画への承認時です。

---

第1幕 — ドキュメントを使った徹底的な検討（あなた ↔ Claude）

この計画のあらゆる側面について、共通理解に達するまで徹底的に質問してください。設計ツリーの各分岐をたどり、意思決定間の依存関係を一つずつ解決してください。質問ごとに、推奨する回答も提示してください。

質問は一度に1つずつ行い、それぞれの質問へのフィードバックを待ってから次に進んでください。

コードベースの調査で回答できる質問は、代わりにコードベースを調査してください。

ドメインの把握

コードベースを調査する際は、既存のドキュメントも探してください。

ファイル構成

ほとんどのリポジトリには、コンテキストが1つだけあります。

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

ルートに CONTEXT-MAP.md がある場合、そのリポジトリには複数のコンテキストがあります。このマップに、それぞれの場所が示されています。

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

ファイルは必要になってから作成してください。書き込む内容がある場合にのみ作成します。CONTEXT.md がない場合は、最初の用語が確定した時点で作成してください。docs/adr/ がない場合は、最初の ADR が必要になった時点で作成してください。

セッション中

用語集と照らし合わせる

ユーザーが CONTEXT.md の既存の用語と矛盾する用語を使ったら、すぐに指摘してください。「用語集では『キャンセル』を X と定義していますが、ここでは Y の意味で使っているようです。どちらでしょうか？」

曖昧な表現を明確にする

ユーザーが曖昧な用語や複数の意味に取れる用語を使ったら、正確で標準的な用語を提案してください。「『アカウント』と言っていますが、Customer と User のどちらを指していますか？この2つは別の概念です。」

具体的なシナリオを話し合う

ドメイン内の関係性について話し合う際は、具体的なシナリオを使って検証してください。境界事例を探り、概念間の境界を正確にする必要があるシナリオを考案してください。

コードと照合する

ユーザーが何かの仕組みについて述べたら、コードと一致しているか確認してください。矛盾が見つかった場合は、提示してください。「コードでは Order 全体をキャンセルしていますが、先ほど部分的なキャンセルも可能だと言っていました。どちらが正しいでしょうか？」

CONTEXT.md をインラインで更新する

用語が確定したら、その場で CONTEXT.md を更新してください。後でまとめて更新せず、確定した時点で記録してください。CONTEXT-FORMAT.md の形式を使用してください。

CONTEXT.md に実装の詳細を含めてはいけません。CONTEXT.md を仕様書、作業メモ、実装上の意思決定の記録として扱わないでください。これは用語集であり、それ以外のものではありません。

ADR の提案は必要最小限にする

次の3つすべてに当てはまる場合に限り、ADR の作成を提案してください。

1. 覆しにくい — 後から考えを変えるコストが無視できない
2. 背景がないと意外に思われる — 将来の読者が「なぜこのようにしたのか」と疑問に思う
3. 実際のトレードオフの結果である — 現実的な選択肢が複数あり、具体的な理由からそのうちの1つを選んだ

3つのうち1つでも当てはまらない場合は、ADR を作成しないでください。ADR-FORMAT.md の形式を使用してください。

第2幕への引き継ぎ

意思決定ツリーの解決が終わり、用語集／ADR が更新され、合意が取れたら、合意した計画を PLAN.md に記述し（CONTEXT.md の標準用語を使用して）、第2幕を実行してください。

# Plan: <task>
_Locked via grill-with-docs — by Claude + <user>. Terms per CONTEXT.md._

## Goal
<one paragraph, in the project's ubiquitous language>

## Approach
<numbered, concrete steps>

## Key decisions & tradeoffs
<the contestable choices the grill resolved — link any ADRs created>

## Risks / open questions
<anything still open>

## Out of scope
<bounds>

PLAN-REVIEW-LOG.md を初期化します。

# Plan Review Log: <task>
Act 1 (grill-with-docs) complete — plan locked, CONTEXT.md/ADRs updated. MAX_ROUNDS=<n>.

---

第2幕 — レビュー（Claude ↔ Codex）

確定した計画を Codex に渡し、敵対的レビューを受けます。仕組みはエンドツーエンドで検証済みです（2026-06-04）。

前提条件

• codex --version が 0.130 以上であること（古い CLI ではデフォルトの gpt-5.5 モデルでエラーになります）。
• Codex が認証済みであること（codex login。ChatGPT アカウントで問題ありません）。認証またはモデルのエラーが発生した場合は、ユーザーに伝えてください。黙って再試行してはいけません。
• -m を固定しないでください（設定のデフォルトが使用されます。gpt-5.x-codex 系のモデルは、ChatGPT アカウント認証で 400 エラーになります）。
• Round 1 の前に、アクティブなモデルを表示してユーザーが確認できるようにしてください。~/.codex/config.toml から model の行を読み取り（存在しない場合は「CLI のデフォルト」）、解決済みの調整可能値とともに示します。ユーザーが異議を唱えた場合は、ラウンドを開始する前に停止してください。

調整可能値（引数があればそれを使用し、なければデフォルト）

Var	デフォルト	意味
MAX_ROUNDS	5	上限。ループは必ずここで終了します。
PLAN_FILE	PLAN.md	Act 1 で作成した計画です。
LOG_FILE	PLAN-REVIEW-LOG.md	追記専用の議論記録です。

たとえば rounds=3 で呼び出された場合は、その値を使用します。まず解決済みの値を表示してください。

レビュープロンプト（各ラウンド）

あなたは実装計画の敵対的レビュー担当者です。懐疑的かつ具体的に、同意するのではなく、何が破綻するかを見つけることを役割としてください。PLAN.md（およびドメイン用語を確認するための CONTEXT.md／ADR）と、必要なリポジトリ内のファイルを読み取ってください（読み取り専用です）。具体的な欠陥を特定してください。セキュリティの穴、競合状態、抜けているエッジケース、スキーマの不整合、ドメイン用語の不一致、誤った前提、可観測性の不足、より単純な代替案などです。それぞれについて、1 行の修正案を示してください。ファイルは変更しないでください。最後は、必ず次のいずれか 1 行だけで締めくくってください：VERDICT: APPROVED または VERDICT: REVISE。

Round 1 — 新しいセッション（thread_id を取得）

codex exec -s read-only --json -o /tmp/codex-verdict.txt "$(cat REVIEW_PROMPT)" \
  < /dev/null 2>/dev/null | grep '"type":"thread.started"'

thread.started の行から thread_id を解析します。/tmp/codex-verdict.txt に批評を出力します。判定ファイルがなく、thread.started もない場合は、実行失敗（認証／モデル）として停止し、ユーザーに伝えてください。2>/dev/null は、見た目上の MCP／認証関連のノイズを隠します。< /dev/null は必須です。codex exec はプロンプト引数に加えて標準入力も読み取るため、非対話型ドライバー（Claude Code の Bash ツール、CI、TTY ではないパイプラインなど）では、標準入力の EOF を待って永久にブロックします。これは CPU 使用率がほぼ 0％のまま、気づかれずにハングする状態です。このリダイレクトにより、すぐに EOF が渡されます。

Rounds 2..MAX — 同じセッションを再開

# resume REJECTS -s. Force read-only via -c sandbox_mode, or Codex inherits
# config.toml (possibly danger-full-access) and could WRITE files. Critical
# safety line — verified 2026-06-04.
codex exec resume "$THREAD_ID" -c sandbox_mode="read-only" --json \
  -o /tmp/codex-verdict.txt \
  "I revised the plan. Re-review PLAN.md — check prior findings + flag anything new. End with VERDICT: APPROVED or VERDICT: REVISE." \
  < /dev/null 2>/dev/null >/dev/null

再開呼び出しにも < /dev/null のリダイレクトが必要です。Round 1 と同様に、非対話型の標準入力によってハングします。

**タイムアウトガード（両ラウンド）：**将来の停止時に黙ってハングせず、明確に失敗するよう、すべての codex exec／codex exec resume に 10 分の上限を設けてください。Claude Code の Bash ツールでは、ツール呼び出しに timeout: 600000 を指定します（デフォルトのツールタイムアウトである 2 分では、実際のレビューには短すぎて実行途中で終了してしまいます）。通常のシェルでは、コマンドの先頭に timeout 600（Linux／Git Bash）または gtimeout 600（coreutils 経由の macOS。標準の macOS には timeout はありません）を付けます。上限に達した場合は実行失敗として扱い、やみくもに再試行せず、停止してユーザーに伝えてください。

各ラウンド

1. 判定ファイルを読み、## Round <n> — Codex と批評を LOG_FILE に追記します。
2. 最終行の判定が APPROVED の場合は Resolution（収束）へ進みます。REVISE の場合は、何を実行する価値があるかを Claude が判断し（最終決定者）、PLAN_FILE を改訂して、### Claude's response（変更または却下した内容とその理由）を追記し、ラウンド番号を増やします。
3. round が MAX_ROUNDS を超えた場合は Resolution（デッドロック）へ進みます。

Resolution（あなたが承認）

• **APPROVED：**最終計画、2 つの Act で改善された点の 3 項目の要約、ラウンド数を提示します。今すぐ実装するか、Codex が実装する（/codex-build）、Claude が実装する、または中止するかを尋ねます。いずれの Act の間もコードは書きません。
• **デッドロック（上限に達しても APPROVED にならない）：**未解決の点と Claude の反対意見を列挙し、ユーザーに判断を委ねます。収束したように装ってはいけません。
• **Act 3（任意）：**ユーザーが Codex を選んだ場合は、SPEC_FILE=PLAN.md と同じ LOG_FILE を指定して codex-build スキルを呼び出します。役割が逆転し、Codex がフルアクセスで実装し、Claude が差分をレビューして検証を実行します。ビルドのラウンドは同じログに追記します。

---

厳守事項

• Act 1 は Act 2 に先行します。CONTEXT.md は用語集のみとし、実装の詳細は記載しません。
• Codex は毎回必ず読み取り専用にします（最初は -s read-only、再開時は -c sandbox_mode="read-only"。再開時に -s は不要です）。書き込みは一切行いません。
• ループは必ず MAX_ROUNDS で終了します。REVISE の場合、Claude が最終判断を下します（記録した理由とともに却下します）。承認後にのみコードを作成します。納品物は LOG_FILE です。

してはいけないこと

• すでに作成済みのコードをレビューしないでください（/codex:review）。ChatGPT 認証で -codex バリアントを固定しないでください。Codex にファイルを編集させないでください。Act 1 を省略しないでください。