rlm-workflow

RLM 工作流

概述

按照 .agent/PLANS.md 中的规范 RLM 流程实现仓库工作，并遵循 .codex/AGENTS.md 中的调用约定。将仓库产物视为事实来源，并将提示词保留为基于路径的命令。

触发示例

• Implement requirement '2026-02-24-add-oauth'
• Run RLM Phase 2 for .codex/rlm/2026-02-24-add-oauth/
• Resume requirement '2026-02-24-add-oauth' after manual QA
• Verify locks for .codex/rlm/2026-02-24-add-oauth/
• Lock Phase 3 for run '2026-02-24-add-oauth'

引导预检（始终首先运行）

在执行任何其他操作之前，确保仓库脚手架已存在且为最新状态：

• .codex/AGENTS.md 包含 RLM Workflow 区块（通过托管标记块更新）
• .agent/PLANS.md 包含来自 references/plans-canonical.md 的规范工作流区块（通过托管标记块更新）
• .codex/rlm/ 存在
• 安装脚本（scripts/install-rlm-workflow.ps1 或 scripts/install-rlm-workflow.py）创建的任何其他文件均存在

如果有任何内容缺失或过时，请运行：

# Windows PowerShell:
powershell -ExecutionPolicy Bypass -File ./scripts/install-rlm-workflow.ps1 -RepoRoot .

# PowerShell 7+ (pwsh):
pwsh -NoProfile -File ./scripts/install-rlm-workflow.ps1 -RepoRoot .

# Python (Windows/macOS/Linux):
python ./scripts/install-rlm-workflow.py --repo-root .
# or:
python3 ./scripts/install-rlm-workflow.py --repo-root .

# Bash wrapper (macOS/Linux):
bash ./scripts/install-rlm-workflow.sh --repo-root .

如果无法执行脚本，请手动执行等效的引导操作：

• 创建上述缺失的目录/文件
• 使用托管标记，将 references/plans-canonical.md 中的规范计划更新到 .agent/PLANS.md
• 使用托管标记，将“RLM Workflow Skill”区块更新到 .codex/AGENTS.md

然后继续工作流阶段。

阅读顺序

1. 阅读 .codex/AGENTS.md 的引言部分，了解本地调用约定。
2. 阅读 .agent/PLANS.md，了解规范阶段规则和要求。
3. 如果 AGENTS 与 PLANS 的表述不一致，请遵循 PLANS（AGENTS 声明 PLANS 为规范依据），并在相关阶段产物中注明不一致之处。

触发示例

• Implement requirement '<run-id>'
• Run RLM Phase 2 for .codex/rlm/<run-id>/
• Create .codex/rlm/<run-id>/02-to-be-plan.md with Coverage and Approval gates
• Update tests and lock Phase 4 artifact for this run

调用模式

• 单命令模式：
  • 收到 Implement requirement '<run-id>' 后，解析运行文件夹并按顺序执行各阶段。
  • 仅在 Phase 5 等待人工 QA 签核。
• 单阶段模式：
  • 收到 Run RLM Phase N 后，仅执行该阶段并写入该阶段的输出，但前提是所有所需的前置阶段均已通过锁定验证。

单命令约定（强制）

• 将运行文件夹解析为 .codex/rlm/<run-id>/。
• 如果运行文件夹或 00-requirements.md 缺失，请停止并索取。不要臆造需求。
• 根据当前状态自动恢复：
  • 阶段 0（需求）： 确认 00-requirements.md 存在（由用户创建的起始文件）。如果缺失，请停止。
  • 阶段 0（Worktree）： 创建/进入隔离的 worktree，然后从该 worktree 执行本次运行。
  • 如果阶段工件标记为 DRAFT 或未通过门禁，则恢复该阶段。
  • 如果阶段工件缺失，则按顺序为下一阶段创建工件。
  • 绝不回头编辑已锁定的前序阶段工件。
• 按顺序执行：阶段 0 至阶段 7。
• 阶段 0（Worktree 隔离 - 必需）：
  • 将 00-requirements.md 视为本次运行的起始输入（必须已存在）。
  • 检查 .worktrees/<run-id> 或已配置的位置是否存在 worktree。
  • 如果当前位于 main/master 分支：必须征得明确同意，或自动创建 worktree。
  • 验证 worktree 目录是否被 Git 忽略（如果位于项目内）。
  • 运行项目设置（npm install、cargo build 等）。
  • 验证测试基线干净。
  • 创建/锁定 00-worktree.md，然后再继续。
  • 技能： skills/rlm-worktree/SKILL.md
• 阶段 1.5（调试模式 - 可选）：
  • 判断需求是否需要调试（修复错误、测试失败、行为异常）。
  • 如果需要：在阶段 2 之前创建/锁定 01.5-root-cause.md。
  • 阶段 1.5 使用系统化调试方法（参见 skills/rlm-debugging/SKILL.md）。
• 阶段 5：
  • 编写 05-manual-qa.md，其中的场景标记为 DRAFT。
  • 暂停并请求用户提供结果/签字确认。
  • 在下一次调用时，记录结果、锁定阶段 5，然后继续阶段 6 和 7。

阶段转换防护措施（强制，遇阻即停）

• 开始阶段 N 之前，使用 .agent/PLANS.md 验证所有前序阶段（0..N-1）的锁定链。
• 如果阶段 0 存在： 在阶段 1/2 开始前，必须确认其锁定有效（已验证 worktree 隔离）。
• 如果阶段 1.5 存在： 在阶段 2 开始前，必须确认其锁定有效。
• 只有当阶段基础工件和阶段内附加文件均为 LOCKED、包含 LockedAt 和 LockHash，且以 Coverage: PASS 和 Approval: PASS 结尾时，该前序阶段才视为锁定有效。
• 锁定验证： 验证 LockHash 是否与规范化工件内容的 SHA-256 匹配（换行符为 LF；移除 LockHash: 行）。使用 scripts/verify-locks.py（跨平台）或 scripts/verify-locks.ps1（PowerShell）进行自动验证。
• 如果任何前序阶段的锁定无效，不要创建或更新后续阶段工件。
• 恢复最早的失败阶段并修复，直至锁定有效，然后继续。
• 除非 05-manual-qa.md 锁定有效，否则绝不开始阶段 6 或 7。
• 只有阶段 5 的手动 QA 会按计划暂停；其他所有暂停均为阻塞。

主分支保护（强制）

铁律：未经明确同意，绝不在 MAIN/MASTER 分支上工作。

自动保护

从 main/master 分支调用时：

1. 停止并显示警告
2. **默认操作：**创建隔离的 worktree
3. 必须征得明确同意才能在 main 分支上继续

同意要求

如果用户坚持在 main 分支上工作：

• 记录其已知悉风险
• 记录明确同意及时间戳
• 说明例外原因
• **建议：**今后的需求使用 worktree

创建 Worktree（默认）

# Create feature branch worktree
git worktree add .worktrees/<run-id> -b rlm/<run-id>
cd .worktrees/<run-id>

后续所有阶段均在 worktree 环境中执行。

TDD 规范（阶段 3 强制）

铁律：先编写一个会失败的测试，再编写生产代码。

第 3 阶段的 RED-GREEN-REFACTOR

1. RED 阶段：

   • 编写最精简的测试，展示预期行为
   • 运行测试，确认测试按预期失败
   • 在第 3 阶段的产物「TDD 合规日志」中记录失败情况

2. GREEN 阶段：

   • 编写能通过测试的最简单代码
   • 运行测试，确认测试通过
   • 记录最精简的实现

3. REFACTOR 阶段：

   • 在保持测试通过的同时清理代码
   • 记录清理内容

TDD 合规日志

每个第 3 阶段的产物都必须包含：

## TDD Compliance Log

### R1: [description]
**Test:** `path/to/test.ts` - "[name]"
**RED:** [timestamp] - Failed as expected: [output]
**GREEN:** [timestamp] - Minimal implementation: [description]
**REFACTOR:** [timestamp] - Cleanups: [description]

危险信号——删除并重新开始

• 先写代码再写测试 -> 删除代码
• 测试立即通过 -> 修正测试
• “我稍后会补上测试” -> 不会补的

参考： skills/rlm-tdd/SKILL.md

TODO 纪律（所有阶段都必须遵守）

铁律：TODO 尚未全部勾选时，不得锁定阶段或进入下一阶段。

TODO 要求

每个阶段的产物都必须包含 ## TODO 部分，其中包括：

1. 每项任务、子阶段和交付物对应的可勾选事项
2. 随工作完成而逐步勾选
3. 锁定前不得有未勾选项

TODO 结构

## TODO

- [ ] Task 1: [description]
- [ ] Task 2: [description]
  - [ ] Sub-task 2a: [description]
  - [ ] Sub-task 2b: [description]
- [ ] Task 3: [description]

TODO 规则

#### TODO 硬性门槛

在满足以下条件前，不得锁定阶段或进入下一阶段：

• 所有 TODO 项均已勾选（[x]）
• 没有未勾选项（[ ] 或空框）
• 没有“进行中”或“已延期”事项

例外： 无。锁定前必须完成所有 TODO。

各阶段 TODO 模式

第 0 阶段工作树：

• 已创建工作树
• 已验证分支保护
• 已确认基线干净
• 已编写第 0 阶段工作树产物

第 0 阶段需求：

• 已收集需求
• 已定义验收标准
• 已记录范围外事项
• 已编写第 0 阶段产物

第 1 阶段 AS-IS：

• 已记录当前行为
• 已记录代码位置
• 已列出已知未知项
• 已编写第 1 阶段产物

第 1.5 阶段（如使用）：

• 已完成错误分析
• 已确认可复现
• 已找出根本原因
• 已编写第 1.5 阶段产物

第 2 阶段：

• 已定义子阶段（如有需要）
• 已指定文件变更
• 已记录测试命令
• 已编写第 2 阶段产物

第 3 阶段：

• 已实现并测试 SP1
• 已实现并测试 SP2
• ……（针对每个子阶段）
• 已完成 TDD 合规日志
• 已编写第 3 阶段产物

第 3.5 阶段（如使用）：

• 已验证计划一致性
• 已评估代码质量
• 已对问题分类
• 已记录结论
• 已编写第 3.5 阶段产物

第 4 阶段：

• 已完成测试前实现审查（将第 3 阶段总结与需求及第 2 阶段计划进行比对）
• 已执行单元测试
• 已执行集成测试
• 已执行端到端测试（Tier A）
• 已编写第 4 阶段产物

第 5 阶段：

• 已执行 QA 场景
• 已观察结果
• 已记录用户签字确认
• 已编写第 5 阶段产物

执行要求

将 Status: LOCKED 设为锁定状态前：

1. 扫描产物，查找任何未勾选的 [ ] 项
2. 如果发现未勾选项：完成工作或将其转为补充说明
3. 确认所有方框均已勾选为 [x]
4. 只有完成上述步骤后，才能继续锁定

常见反模式

反模式	正确做法
“稍后完成”	现在完成，或创建补充说明
部分勾选	仅在完全完成时勾选
“做工作”之类的模糊事项	具体描述： “实现身份验证处理程序”
没有 TODO 部分	每个阶段的产物都必须包含

阶段顺序隔离（强制，不得并行处理阶段）

• 工作流严格按顺序执行：每次运行在任何时候只能有一个活动阶段。
• 活动阶段 = 基础产物缺失或未通过锁定验证的最早阶段。
• 活动阶段尚未解决时，不得为任何后续阶段创建、更新或锁定产物。
• 同一时间最多只能有一个阶段基础产物处于 DRAFT 状态。
• 如果多个阶段产物处于 DRAFT 状态，则仅将最早的 DRAFT 阶段视为活动阶段；后续的 DRAFT 产物属于无效的并行预处理，在活动阶段通过锁定验证前不得继续处理。
• 活动阶段通过锁定验证后，按顺序继续执行，并仅在后续阶段成为活动阶段时，重新创建或覆盖任何无效的后续阶段 DRAFT 产物。

运行文件夹和产物

• 主要运行路径：.codex/rlm/<run-id>/
• 每次运行的产物：
  • 00-worktree.md（必需——阶段 0 工作树设置）
  • 00-requirements.md
  • 01-as-is.md
  • 01.5-root-cause.md（可选，用于调试模式）
  • 02-to-be-plan.md
  • 03-implementation-summary.md
  • 04-test-summary.md
  • 05-manual-qa.md
  • addenda/
  • evidence/（截图/日志/性能数据/跟踪记录；在阶段 4/5 中引用）
• 全局产物：
  • .codex/DECISIONS.md
  • .codex/STATE.md
• 工作树位置（隔离）：
  • .worktrees/<run-id>/（默认，项目本地，隐藏）
  • 或 ~/.config/rlm-workflow/worktrees/<project>/<run-id>/（全局）
• 技能（供参考）：
  • skills/rlm-worktree/SKILL.md - 阶段 0 工作树隔离
  • skills/rlm-tdd/SKILL.md - 阶段 3 的 TDD 准则
  • skills/rlm-debugging/SKILL.md - 阶段 1.5 的系统化调试
• 脚本（实用工具）：
  • scripts/install-rlm-workflow.py - 跨平台引导安装/更新
  • scripts/rlm-init.py - 初始化新的运行文件夹和模板（跨平台）
  • scripts/rlm-init.ps1 - 初始化新的运行文件夹和模板（PowerShell 等效版本）
  • scripts/rlm-status.py - 运行状态和锁定链摘要（跨平台）
  • scripts/rlm-status.ps1 - 运行状态和锁定链摘要（PowerShell 等效版本）
  • scripts/lint-rlm-run.py - 产物结构和 TODO 准则检查器（跨平台）
  • scripts/lint-rlm-run.ps1 - 产物结构和 TODO 准则检查器（PowerShell 等效版本）
  • scripts/verify-locks.py - 自动验证锁定哈希（跨平台）
  • scripts/verify-locks.ps1 - 自动验证锁定哈希（PowerShell 等效版本）

阶段执行协议

1. 从 .agent/PLANS.md 中识别阶段输入基础文件。
2. 将每项输入扩展为有效输入：基础文件加上按字典序排列的阶段本地附录。
3. 起草输出前，阅读所有有效输入。
4. 创建/更新阶段产物，并包含必需的标头字段：
   • Run、Phase、Status、Inputs、Outputs、Scope note
5. 添加 Traceability 部分，将每个 R# 映射到其对应的处理位置和证据。
6. 以 Coverage Gate 和 Approval Gate 结尾，并在每个部分末尾明确写明 PASS 或 FAIL。
7. 在两个关卡都通过前，保持 Status: DRAFT。
8. 通过后，锁定产物：
   • 将 Status 设为 LOCKED
   • 添加 LockedAt（ISO8601）
   • 添加 LockHash（规范化产物内容的 SHA-256；参见 /.agent/PLANS.md / references/plans-canonical.md）

确切的标头和关卡框架请使用 references/artifact-template.md。

必须执行的 PLANS 章节

在适用时，始终执行 .agent/PLANS.md 中的以下章节：

• Large requirements: Implementation sub-phases (required when scope is large or risky)
• Playwright tagging for RLM runs and implementation sub-phases (required)
• Testing discipline (TDD + Playwright)（适用于 Phase 2、4 和 5）
• RLM TDD Discipline (Phase 3)——RED-GREEN-REFACTOR 循环、铁律
• RLM Systematic Debugging (Phase 1.5)——何时以及如何使用调试模式
• RLM single-command orchestration ("Implement requirement '<run-id>'")
• Run folder resolution
• Phase auto-resume and phase selection
• Phase transition hard-stop lock chain (required)
• Strict sequential phase execution (no parallel phase work)
• Manual QA stop (the only intentional pause)
• Locking rules for single-command execution

不可变性与补充说明

• 切勿编辑已锁定的前序阶段产物。
• 如果发现已锁定的上游产物存在缺漏，请在当前阶段创建上游缺漏补充说明。
• 补充说明的命名规则：
  • 阶段本地：<base>.addendum-01.md
  • 上游缺漏：<current>.upstream-gap.<prior>.addendum-01.md
• 阶段锁定时，锁定在该阶段创建的所有补充说明。

各阶段要求

0. 阶段 0（00-worktree.md）——必须隔离

   • 触发条件： 每次 RLM 运行开始时，必须先执行此阶段，再开展任何其他工作。
   • 铁律： 未经明确许可，绝不在 MAIN/MASTER 分支上工作。
   • 在 .worktrees/<run-id>/（或配置的位置）创建隔离的 Git worktree。
   • 如果 worktree 位于项目目录中，确认其目录已被 Git 忽略。
   • 运行项目设置（自动检测：npm install、cargo build、pip install 等）。
   • 确认测试基线正常（所有测试均通过）。
   • 记录 worktree 的位置、分支名称和基线状态。
   • 技能： skills/rlm-worktree/SKILL.md

1. 阶段 0 要求（00-requirements.md）

   • 定义稳定 ID：R1..Rn 和 OOS1..OOSn。
   • 为每个 R# 定义可观察的验收标准。
   • 由用户创建，用于初始化本次运行。

2. 阶段 1 现状（01-as-is.md）

   • 提供新手可运行的复现步骤、当前行为、代码位置和已知未知项。
   • 在 worktree 环境中执行。

3. 阶段 1.5（01.5-root-cause.md）——调试模式（可选）

   • 触发条件： 需求涉及修复 Bug 或调查意外行为时使用。
   • 铁律： 未先调查根本原因，不得修复。
   • 按系统化调试流程执行：错误分析 -> 复现 -> 数据流追踪 -> 假设验证 -> 根本原因总结。
   • 如果启用，必须在阶段 2 前锁定。
   • 技能： skills/rlm-debugging/SKILL.md

4. 阶段 2（02-to-be-plan.md）

   • 制定达到 ExecPlan 级别的计划，列明具体文件修改、命令、测试和手动 QA 场景。
   • 范围或风险较大时，添加实施子阶段（SP1、SP2……）。
   • 如果存在阶段 1.5，则将根本原因调查结果纳入修复计划。

5. 阶段 3（03-implementation-summary.md）——TDD 纪律与并行化

   • 铁律： 未先编写一个失败测试，不得编写生产代码。
   • 必须包含 TDD 合规日志，记录 RED-GREEN-REFACTOR 循环。
   • 并行模式（子 Agent）： 如果有 3 个或更多独立子阶段，且可创建子 Agent：
     • 为每个子阶段分派一个全新的子 Agent
     • 两阶段审查：规范符合性 -> 代码质量
     • 反复审查，直到批准
     • 所有子阶段完成后进行集成测试
   • 串行模式（回退方案）： 如果无法使用子 Agent：
     • 由主 Agent 按顺序执行各子阶段
     • 使用扩展的自审清单
     • 每个子阶段之间进行集成测试
   • 技能： TDD 使用 skills/rlm-tdd/SKILL.md，并行化使用 skills/rlm-subagent/SKILL.md

6. 阶段 3.5（03.5-code-review.md）——代码审查（可选）

   • 触发条件： 变更较大、涉及关键路径或需要额外信心时
   • 适用场景： 高风险变更、复杂的子阶段，或需要外部验证时
   • 并行模式： 分派 code-reviewer 子 Agent
   • 串行模式： 主 Agent 使用扩展的清单进行自审
   • 如果启用，必须在阶段 4 前锁定
   • 技能： skills/rlm-subagent/SKILL.md

7. 阶段 4（04-test-summary.md）——并行测试

   • 运行测试前，对照 00-requirements.md 和 02-to-be-plan.md 审查 03-implementation-summary.md 中的实施情况，并记录不一致之处、补充内容或确认结果。
   • 记录具体的验证命令、结果和需求覆盖情况。
   • 确认符合 TDD 要求：阶段 3 编写的所有测试均已通过。
   • 并行模式： 为相互独立的测试套件分派子 Agent：
     • 子 Agent 1：单元测试
     • 子 Agent 2：集成测试
     • 子 Agent 3：E2E Tier A
     • 所有测试并发运行，汇总结果
   • 串行模式： 由主 Agent 按顺序运行测试套件

8. 阶段 5（05-manual-qa.md）

   • 暂停并等待用户签字确认；记录观察到的结果和明确批准。

9. 阶段 6 和 7

   • 先更新 .codex/DECISIONS.md，再更新 .codex/STATE.md。
   • 变更在 worktree 环境中进行；准备就绪后由用户合并功能分支。

RLM 技能优先级

当一项需求涉及多个方面时，请按以下优先级顺序确定首先应用哪些技能／阶段：

优先级顺序

1. 调试（修复 Bug）-> 首先运行阶段 1.5 根因分析

   • 触发条件： 需求提及 Bug、测试失败或意外行为
   • 操作： 在阶段 1 和阶段 2 之间插入阶段 1.5
   • 技能： skills/rlm-debugging/SKILL.md
   • 原因： 了解根因是规划修复的前提

2. 设计／分析（新功能或变更）-> 执行完整的阶段 1 AS-IS 分析

   • 触发条件： 新功能、增强功能或行为修改
   • 操作： 在阶段 2 之前彻底执行阶段 1
   • 原因： 必须先了解当前状态，才能定义未来状态

3. 实现 -> 分析完成后进入阶段 2+

   • 触发条件： 阶段 1（或阶段 1.5）已锁定并准备就绪
   • 操作： 开始阶段 2（TO-BE 规划）
   • 原因： 规划需要完整了解当前状态／调试状态

4. 测试 -> 在阶段 3 遵循 TDD 原则

   • 触发条件： 任何实现工作
   • 操作： 在阶段 3 应用 TDD
   • 技能： skills/rlm-tdd/SKILL.md
   • 原因： 测试用于验证实现是否符合需求

5. 审查 -> 在实现与最终验证之间进行代码审查

   • 触发条件： 实现完成（阶段 3 已锁定）
   • 操作： 可在阶段 4 之前进行阶段 3.5 代码审查
   • 原因： 在最终验证之前发现问题

决策流程

Requirement received
  |
  v
Is it a bug fix? --YES--> Phase 1.5 (Root Cause Analysis)
  |                          |
  NO                         v
  |                    Phase 2 (incorporate findings)
  v                          v
Phase 1 (AS-IS) -------> Phase 3 (TDD implementation)
  |                          |
  v                          v
Phase 2 (TO-BE) -------> Phase 4 (validation)
  |                          |
  v                          v
Phase 3 (TDD) ---------> Phase 5 (Manual QA)
                             |
                             v
                       Phase 6/7 (global updates)

示例

需求	应用的优先级	执行顺序	执行模式
“修复登录崩溃”	优先调试	阶段 0 -> 1 -> 1.5 -> 2 -> 3 -> 4 -> 5...	顺序执行或并行执行
“添加深色模式”	优先设计	阶段 0 -> 1 -> 2 -> 3 -> 4 -> 5...	顺序执行（单个 SP）
“空输入时崩溃”	优先调试	阶段 0 -> 1 -> 1.5 -> 2 -> 3 -> 4...	顺序执行或并行执行
“实现 OAuth”	设计 + 审查	阶段 0 -> 1 -> 2 -> 3 -> 3.5 -> 4 -> 5...	并行执行（多个 SP）
“多域重构”	设计 + 并行	阶段 0 -> 1 -> 2 -> 3 -> 3.5 -> 4 -> 5...	并行执行（子 Agent）

执行模式说明：

• 顺序执行： 单个子阶段，无需并行
• 并行执行： 多个子阶段，可使用子 Agent -> 并发执行
• 顺序执行或并行执行： 根据子 Agent 可用性检查结果决定模式

硬性关卡

硬性关卡是必须通过、不可协商的检查点，必须满足后才能继续。

### 阶段 0 -> 1/2 硬性关卡

在以下条件满足之前，不要进入阶段 1 或 2：

• 已创建并验证阶段 0 工作树
• 工作树目录已加入 git 忽略列表（如果位于项目本地）
• 已验证干净的测试基线
• 已确认主分支保护
• 阶段 0 产物已锁定，并填写 LockedAt 和 LockHash

例外： 无。所有运行都必须执行阶段 0。

### 阶段 1 -> 2 硬性关卡

在 01-as-is.md 锁定并满足以下条件之前，不要创建 02-to-be-plan.md：

• 覆盖率：通过
• 审批：通过
• 已填写 LockedAt 和 LockHash

例外： 如果存在阶段 1.5，也必须先锁定该阶段才能进入阶段 2。

### 阶段 1.5 -> 2 硬性关卡（调试模式）

在根因分析完成之前，不要创建 TO-BE 计划：

• 阶段 1.5 产物已锁定
• 已确定根因（而不只是症状）
• 已定义修复策略
• 覆盖率：通过
• 审批：通过

例外： 无。调试模式要求在规划之前完成分析。

### 阶段 3 TDD 硬性关卡

在以下条件满足之前，不要编写实现代码：

• 已存在失败测试并已运行
• 测试失败已记录在阶段 3 产物的 TDD 合规日志中
• 已通过实际测试输出验证 RED 阶段

例外： 无。铁律没有例外。

### 阶段 4 -> 5 硬性门槛

在以下条件满足前，不要进入人工 QA：

• 在阶段 4 产物中记录实现审计（对照 00-requirements.md 和 02-to-be-plan.md）
• 阶段 3 的所有测试均已通过
• 已验证 TDD 合规性
• 在阶段 4 产物中记录测试证据
• 阶段 4 已锁定

### 阶段 5 人工 QA 硬性门槛

在以下条件满足前，不要更新 DECISIONS.md 或 STATE.md：

• 用户已明确批准 QA 场景
• 05-manual-qa.md 包含所有场景的实测结果
• 批准状态：PASS，并记录用户姓名和日期
• 阶段 5 已锁定，且 LockHash 与内容匹配

例外： 无。必须完成 QA 才能进行全局更新。

### 锁定链硬性门槛（适用于所有阶段转换）

除非所有先前阶段（0 至 N-1）均通过锁定验证，否则不要开始阶段 N：

• 状态：LOCKED
• LockedAt：已填写
• LockHash：与内容的 SHA-256 匹配
• 覆盖率：PASS
• 批准状态：PASS

例外： 无。锁定链是绝对要求。

执行模式：并行与顺序

RLM 在阶段 3（实现）和阶段 4（测试）中支持两种执行模式：

并行模式（由子 Agent 驱动）

要求：

• 可使用子 Agent 生成功能
• 定义了 3 个或更多相互独立的子阶段
• 子阶段不共享文件，或依赖关系极少

优势：

• 多个子阶段的执行速度提升 3 到 5 倍
• 每个子阶段使用全新上下文（避免混淆）
• 由不同子 Agent 独立审查
• 自然地强制执行 TDD

流程：

1. 控制器从阶段 2 计划中提取所有子阶段
2. 为每个子阶段分派一个实现者子 Agent（并行）
3. 每个实现者：实现、测试并提交
4. 为每个子阶段分派一个规范审查者（并行）
5. 规范审查通过后，为每个子阶段分派一个代码审查者（并行）
6. 发现问题时进入审查循环
7. 全部获批后进行集成测试

文档记录： 在阶段 3 产物中记录模式和子 Agent 的使用情况

顺序模式（回退方案）

触发条件：

• 当前环境不支持子 Agent 生成
• 用户明确要求顺序执行
• 子 Agent 能力检查失败

特点：

• 由主 Agent 按顺序执行各子阶段
• 使用扩展版自审清单
• 在每个子阶段之间进行集成测试
• 速度较慢，但同样严格

回退触发流程：

**Subagent Check:** NOT AVAILABLE
**Reason:** [Tool not found / Platform limitation / User request]
**Action:** Using SEQUENTIAL fallback mode

模式检测

在阶段 3 开始时自动检测：

1. 尝试确定是否具备子 Agent 能力
2. 如果具备 -> 使用并行模式
3. 如果不具备 -> 使用顺序模式，并明确记录

针对平台的检测方式：

• Claude Code： 检查是否有 Task 工具
• Codex： 检查原生子 Agent 支持
• OpenCode： 检查 skill 工具功能
• Cursor： 子 Agent 支持有限 -> 通常采用顺序模式

用户覆盖

用户可以明确指定模式：

"Implement requirement 'X' using parallel subagents"
-> Attempt parallel, fallback if unavailable

"Implement requirement 'X' with sequential execution"
-> Force sequential even if subagents available

模式对比

方面	并行模式	顺序模式
执行方式	并发运行子 Agent	主 Agent 按顺序执行
速度	快 3 到 5 倍	线性
审查	子 Agent 独立审查	自我审查
上下文	每个子阶段均为全新上下文	持续累积
严谨性	两阶段外部审查	扩展版自我审查
回退方案	不可用时自动回退	默认模式

两种模式下的质量保障

并行模式质量保障：

• 两阶段审查（规范 + 代码质量）
• 独立验证
• 通过审查循环修复问题

顺序模式质量保障：

• 扩展版自审清单
• 明确的验证步骤
• 子阶段之间进行回归测试

两种模式都会强制执行：

• TDD 规范
• 产物锁定
• 门槛合规
• 集成测试

人工 QA 暂停规则

仅在阶段 5 暂停，以等待用户明确验证和批准。其他阶段若门槛可通过机械方式评估，则不要暂停等待批准。

运行规则

• 保持提示词简短并基于路径；将实质性要求和计划保存在仓库文档中。
• 使用确定性、可复现的命令进行实现和验证。
• 如果缺少必需输入，则创建最小化的当前阶段补充文档；不要回溯修改已锁定的历史记录。