grill-with-docs-codex

Grill-with-Docs-Codex — 围绕你的领域进行 Grill，然后接受审查

两个阶段。阶段 1 对齐意图，并且确保持续更新的文档准确；阶段 2 则由另一个模型对结果进行对抗性审查。

• 阶段 1 使用 Matt Pocock 的 grill-with-docs，遵循 MIT 许可（见 THIRD-PARTY-NOTICES.md）。它会向你提问，依据 CONTEXT.md/ADR 挑战你的计划，并在对话中更新这些文档。
• 阶段 2 是原版 Codex 对抗性审查循环——跨模型、只读、范围受限。

你需要在两个节点参与：回答 Grill 的问题，以及为收敛后的计划签字确认。

---

阶段 1 — 使用文档进行 Grill（你 ↔ Claude）

就这份计划的方方面面不断深入地采访我，直到我们达成共识。沿着设计树逐一探讨每个分支，逐项理清决策之间的依赖关系。每个问题都要提供你的推荐答案。

一次只问一个问题；等待我对每个问题的反馈后再继续。

如果某个问题可以通过探索代码库来回答，就去探索代码库。

领域认知

探索代码库时，也要查找现有文档：

文件结构

大多数代码库只有一个上下文：

/
├── 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？这是两个不同的概念。”

讨论具体场景

讨论领域关系时，用具体场景进行压力测试。构造一些能探测边缘情况、促使用户明确概念边界的场景。

对照代码进行核查

当用户说明某项功能的工作方式时，检查代码是否一致。如果发现矛盾，就指出来：“你的代码会取消整个 Order，但你刚才说可以部分取消——到底哪种说法正确？”

在对话中更新 CONTEXT.md

术语得到确认后，立即更新 CONTEXT.md。不要攒到之后再处理——边讨论边记录。使用 CONTEXT-FORMAT.md 中的格式。

CONTEXT.md 中绝不能包含任何实现细节。不要把 CONTEXT.md 当作规范、临时记录或实现决策的存放处。它只是术语表，仅此而已。

谨慎提出 ADR

只有同时满足以下三项时才提出创建 ADR：

1. 难以逆转——日后改变主意的成本很高
2. 没有背景就会令人意外——未来的读者会想知道“为什么要这样做？”
3. 源于真正的权衡——确实存在其他方案，而你基于具体原因选择了其中一个

只要有一项不满足，就跳过 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 错误）。
• 第 1 轮开始前，回显当前使用的模型，让用户确认：读取 ~/.codex/config.toml 中的 model 行（不存在则为 “CLI default”）；将其与解析后的可调参数一并说明。如果用户有异议，就在消耗一轮之前停止。

可调参数（参数优先，否则使用默认值）

变量	默认值	含义
MAX_ROUNDS	5	硬性上限。循环始终在此处终止。
PLAN_FILE	PLAN.md	第 1 幕的计划。
LOG_FILE	PLAN-REVIEW-LOG.md	仅追加的论证记录。

例如，调用时传入 rounds=3 → 使用该值。先回显解析后的值。

审查提示词（每一轮）

你是实施计划的对抗性审查者。保持怀疑并提出具体意见——你的任务是找出会出问题的地方，而不是一味赞同。阅读 PLAN.md 中的计划（以及用于了解领域语言的 CONTEXT.md/ADR），并查看所需的任何仓库文件（只读）。找出具体缺陷：安全漏洞、竞态条件、遗漏的边缘情况、架构冲突、领域语言不匹配、错误假设、可观测性缺口、更简单的替代方案。每项都给出一行修复建议。不要修改任何文件。最后必须以且仅以一行结束：VERDICT: APPROVED 或 VERDICT: REVISE。

第 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 中进行评审。没有 verdict 文件且没有 thread.started = 运行失败（身份验证/模型错误）→ 停止并告知用户。2>/dev/null 会隐藏非关键的 MCP/身份验证噪声。必须使用 < /dev/null： codex exec 除了提示词参数外还会读取 stdin，因此在非交互式驱动程序（Claude Code 的 Bash 工具、CI、任何非 TTY 管道）下，它会一直等待 stdin EOF，导致程序永久阻塞——CPU 使用率约为 0% 的静默挂起。此重定向会立即提供 EOF。

第 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 重定向——与第 1 轮相同的非交互式 stdin 挂起问题。

超时保护（两轮均适用）： 每次运行 codex exec / codex exec resume 时都设置 10 分钟上限，确保未来发生任何卡顿时会明确失败，而不是静默挂起。通过 Claude Code 的 Bash 工具调用时，在工具调用中传入 timeout: 600000（默认的 2 分钟工具超时不足以完成实际审查，会在运行中途终止）。在普通 shell 中，在命令前加上 timeout 600（Linux / Git Bash）或 gtimeout 600（通过 coreutils 安装的 macOS 版本——原生 macOS 不带 timeout）。如果触发上限，则视为运行失败：停止并告知用户，不要盲目重试。

每一轮

1. 读取 verdict 文件；将 ## Round <n> — Codex + 评审内容追加到 LOG_FILE。
2. 最后一行 verdict：APPROVED → 进入 Resolution（已收敛）；REVISE → 由 Claude 决定哪些意见值得采纳（最终裁决者），修改 PLAN_FILE，追加 ### Claude 的回应（说明修改或驳回了什么及原因），并递增轮次。
3. round > MAX_ROUNDS → 进入 Resolution（陷入僵局）。

Resolution（由你签字确认）

• APPROVED： 提交最终计划 + 3 条要点，总结这两个阶段做了哪些改进 + 轮次。询问：现在实施吗——由 Codex 构建（/codex-build）、由 Claude 构建，还是停止？两个阶段都不写代码。
• 陷入僵局（达到上限但未 APPROVED）： 列出未解决的问题 + Claude 的反方立场；交由用户处理。不要假装已经达成一致。
• 第 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 处终止。Claude 是 REVISE 时的最终裁决者（拒绝并记录原因）。只有签字批准后才能编写代码。LOG_FILE 是交付物。

不要做的事

• 不要审查已编写的代码（/codex:review）。不要在 ChatGPT 身份验证中固定使用 -codex 变体。不要让 Codex 编辑文件。不要跳过 Act 1。