red-green-mode：AI Agent 工具实践指南

团队讨论red-green-mode时，我会先把用途说清楚：自主编码代理的退出代码护栏：检测假绿色测试篡改，证明验证者有牙齿，停止停滞的循环，以及门并行工作。对软件开发任务来说，依赖、接口和异常处理往往比主路径更影响采用往往决定它能否落地，不能只用安装成功来判断。短测时我会在隔离分支完成一个可回滚的小任务，并保留安装步骤、接口契约、测试结果和错误信息的结果，方便团队复盘。我的判断是，它更适合需要可检查开发流程而非单次演示的工程师；若眼下没有这类需求，先保留观察即可。

名称：红绿模式 版本：0.23.0 描述：>- 自主测试修复循环：运行客观验证程序（测试、类型检查、lint、CI），修复问题 仅当验证器退出代码全部为绿色时，红色，重新运行并完成。当用户需要时使用 在没有监督的情况下推动绿色工作，包括长期运行或并行运行（红绿灯模式/ 跑到全绿/把CI修改到全绿）。不适用于没有验证者或一次性编辑的主观工作；使用 测试驱动开发编写测试和系统调试以找出一个错误的根本原因。

红绿模式

这是什么/何时使用它

无人值守的自我验证循环：当验证器全绿时完成，停止并修复 红色的是什么，然后再次验证。

验证者的退出码决定对与错。代理人的意见没有。

• 此模式仅控制外部编排 - 何时停止、什么算作已完成、不作弊、始终留有后路。
• 它不教您诊断红色（即systematic-debugging），并且不编写您的测试（即test-driven-development）。
• 三个前提，缺一不可：①有明辨是非的客观验证者； ②值得信赖的裁判（红色是真红，绿色还能抓虫子，绿色不是同义反复）； ③明确的任务。当①缺失时，构造一个你实际上可以修复的红色——不要只是说“切换到TDD”然后走开。
• 钱/人/合约/SOPs/公式→首先清除业务规则发现门。任务运送 PRD → 在完成之前清除 PRD- 覆盖门（“测试绿色”≠“PRD 已交付”）。
• 默认单代理。 长期运行和任务并行是可选的外部模式；不传递任何标志，行为不变。
• VERSION-AND-STATE.md 是状态文件所有权、停止条件分层和运行时降级的单一事实来源；发布历史记录位于 CHANGELOG.md 中。

硬机制（强制退出代码——实际运行这些）

# ① First step of any run: create the ledger (mandatory, however small the task; it powers the
#    wrap-up timing report. Only exemption: no write permission)
python tools/rgm_ledger.py init --task "" --workspace "$PWD" \
  --skill-version "red-green-mode v0.23.0" --verify "python -m pytest -q" --out .rgm-ledger.json
# ② Every verify round (including INNER_VERIFY): record the remaining red count as a number, then
#    let the script rule on stalling (patience defaults to 5 rounds)
python tools/rgm_ledger.py add --out .rgm-ledger.json --state OUTER_VERIFY --result "4 failed" --red-count 4
python tools/rgm_ledger.py stall-check --out .rgm-ledger.json    # 0=continue 1=stalling, stop now and report honestly
# ③ Anti-cheat: scan the diff for newly introduced skips / weakened assertions / deleted assertions
#    / ignores / mocking out the logic under test
python tools/rgm_anticheat.py scan --diff-file             # 0=clean 1=cheating 2=bad input; escape hatch `# rgm-allow: reason`
# ④ Acceptance contract (the SSOT across PRD → TDD → red-green): validate / SHA-256 lock the
#    verifiers / dependency-aware ready ordering
python tools/acceptance_contract.py validate --file acceptance-contract.json      # 0=valid 1=invalid
python tools/acceptance_contract.py verify-attest --file acceptance-contract.json # 1=a verifier was swapped out
python tools/acceptance_contract.py ready --file acceptance-contract.json         # the loop may only stop at gates[]
# ⑤ Contract-quality gate: mutation testing catches dead targets that nothing can kill
#    (a target that loose means green proves nothing)
python tools/rgm_mutation.py check --contract acceptance-contract.json --root .   # 0=live target 1=dead target 2=bad input
# ⑤b Point-patch check: did the fix change the logic, or only the inputs the tests use? Records the
#    test's inputs to the target function, perturbs them, compares the old and new versions.
#    Run it when a fix to production code made a red test green.
python tools/rgm_pointpatch.py check --after  --base  --root . --func  --record ""  # 0=OK/INCONCLUSIVE 1=SUSPECT 2=cannot run
# ⑥ Partition gate (parallel mode only): exit 0 or no parallelism, and it refuses to split a
#    depends_on edge across two units
python tools/rgm_partition.py check --units units.json --contract acceptance-contract.json  # non-zero=fall back to a single agent
# ⑦ Wrap-up GATE state: the aggregate verdict (re-run verifiers / anti-cheat / contract coverage /
#    project constraints)
python tools/rgm_gate.py --ledger .rgm-ledger.json --diff-file  --contract acceptance-contract.json --root .
#   add --mutation and --pointpatch-base  to run the two opt-in checks on every AC target
#   0 = sentinel RGM_GATE=PASS — the only credential that permits reporting FULL_GREEN
#   1 = any sub-check FAILed → go back to TRIAGE / PLAN_ONE_FIX, or report the gap honestly. FULL_GREEN is forbidden
#   2 = missing ledger / no --verify recorded → PRECHECK was incomplete. Go back and finish it;
#       do not claim BLOCKED_BY_INFRA

硬执行（Claude Code，选择加入）：tools/rgm_stop_hook.sh 挂钩 Stop 事件并退出 2 当门出现故障时，物理阻塞终点（安装：tools/STOP-HOOK-INSTALL.md）。开 Codex 那里只有软执行——代理必须按照自己的纪律来运行大门。 反作弊是一条启发式安全带；它的边界是tools/ANTICHEAT-LIMITATIONS.md。

状态机顺序

INTAKE → CONTEXT_PACK → PRECHECK → BASELINE → TRIAGE → PLAN_ONE_FIX → INNER_VERIFY → OUTER_VERIFY → SMOKE_ASSERT → QUALITY_REVIEW → PRD_COVERAGE → GATE → REPORT
                                 ↘ BLOCKED_BY_INFRA / TEST_QUESTION / FLAKY / STOPPED_NO_PROGRESS ↗

• PRECHECK嵌入子流程：业务规则发现门RULE_DISCOVERY → EVIDENCE_GATHERING → ASSERTION_DRAFT；在完成之前先使用 PRD、PRD_PARSE → COVERAGE_MAP，然后使用 GAP_CHECK。
• 前置工具：rgm_intake.py（这是否应该进入红绿？）→rgm_context_pack.py build（先看正确的东西）→rgm_codemap.py build/select。所有这三个都是输入工件，而不是完成证明。
• 在 PLAN_ONE_FIX 之前，当任务可能邀请新的抽象、依赖、包装器或广泛重构时，运行软 minimality/scope 审查：检查重用 → stdlib/native → 最小正确差异，并记录任何有意简化的上限并重新访问触发器。读取 references/minimality-and-scope.md。该审查可以改进计划或得出结论；它绝不是行计数目标、验证器或 safety/tests 的替代品。
• 准确选择一种完成状态 - “基本完成”不是其中之一：FULL_GREEN / TASK_GREEN_WITH_BASELINE_RED / BLOCKED_BY_INFRA / STOPPED_NO_PROGRESS。
• 每状态退出条件和故障路由 → references/state-machine-and-ledgers.md。

铁定规则（9——全文 references/ironclad-rules-and-reporting.md ）

1. 永远不要假绿色：删除/跳过/注释掉测试，削弱断言，type: ignore，模拟失败的逻辑——所有这些都是禁止的。如果您确信测试是错误的，停下来询问用户。由 rgm_anticheat.py 强制执行。
2. 停止条件：停止是由 stall-check 的退出代码决定的，而不是通过目视来决定。在对同一错误进行 3 次修复、运行失败的假设或已绿色检查中的回归后也停止。
3. 检查点并保持可恢复：记录起点，并在每个全绿上设置检查点。如果你偏离了轨道，请恢复到最后一个绿色状态 - 切勿将更改叠加在脏状态上。
4. ✅ 首先是基线，最后是完成状态：预先运行所有内容，记录基线，标记每个红色，然后报告四种状态之一加上 before → after。
5. 不要扩大范围：仅更改将此任务的红色变为绿色所需的内容。已经是红色的不相关故障被标记为 BASELINE_RED，单独列出，并单独保留。
6. 隔离片状：在排除环境和隔离问题后，仍然呈红绿色→隔离并报告。不要追，更不要删除。
7. 人为控制仍然适用：删除、批量移动、外部发布和更改受保护的配置仍然需要用户确认。 “这是为了走向绿色”并不是一个许可。
8. 长时间运行：重新启动之前外部化：真实状态进入分类帐/PROGRESS.md。代理人的工作是让损失便宜，而不是打开一个新窗口。
9. 并行：永远不要并行改变共享树：没有分区门，没有并行性。合并是单作者的，合并后，您在完成之前重新验证整个树。

详细信息所在的位置（相对于 references/ 的路径）