Archon System Review 工作流：对 AI 实现做"流程级复盘"，把计划与执行的偏差转化为工程资产
【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon
System Review 是 Archon 仓库中为 AI 编码流程设计的元层复盘机制：它不做代码评审，而是评审"过程"本身——Agent 是否忠实地执行了计划、偏差发生在哪里、以及如何通过改进 CLAUDE.md（实际为 AGENTS.md）、计划模板和命令来防止同类问题复发。读完本文，你将掌握 System Review 的四份输入工件、五步分析流程、完整报告结构与评分模型，并能把它接入 Archon 现有的 plan → execute → report → validate 开发闭环。
为什么需要"流程级"的评审
System Review 的定义在 system-review.md 中有一个极其清晰的边界声明：
System review is NOT code review.You're not looking for bugs in the code - you're looking for bugs in the process.
代码评审（对应仓库中的 code-review.md，负责 bug、安全、性能与约定合规）解决"代码写得好不好"；System Review 解决"过程为什么让代码偏离了计划"。它关注四件事：
- 分析计划遵循度与偏差模式（plan adherence and divergence patterns）
- 区分哪些偏差是合理的、哪些是有问题的
- 暴露能预防未来问题的流程改进点
- 建议更新 Layer 1 资产（CLAUDE.md、计划模板、命令）
文档给出的三条核心哲学，构成了整个评审的价值判断基准：
| 现象 | 含义 | 正确的改进方向 |
|---|---|---|
| Good divergence（合理偏差） | 暴露了计划的局限性 | 改进规划过程（improve planning） |
| Bad divergence（问题偏差） | 暴露了需求不清晰 | 改进沟通（improve communication） |
| 反复出现的问题 | 缺少自动化支撑 | 创建命令（create commands） |
这套判断框架的隐含前提是：偏差不是噪声，而是信号。每一次计划与现实的偏离，都在为下一轮规划提供可学习的证据。
四份输入工件：评审所需的最小上下文
System Review 不是凭空分析，它要求同时审阅四份关键工件。在 Archon 的命令体系中，这四份工件恰好构成了一个完整的开发循环。
1. 计划命令：Plan Command
plan-feature.md 是规划的"元流程"定义，评审者需要先读它，理解 Agent 在规划阶段"应该怎么做"。
从源码可以看到，规划阶段会产出.claude/archon/plans/{kebab-case-name}.md格式的计划文件，内容包括：Overview、Success Criteria、Affected Packages、Architecture Notes、Implementation Tasks（每个任务带 File/Type/Description/Depends on）、Validation Steps 和 Rollback Notes。其中与 System Review 强相关的关键约束包括：
- 包影响分析：需要识别 8 个包（
paths、git、isolation、workflows、core、adapters、server、web）中哪些受影响； - 接口变更识别：是否触及
IPlatformAdapter、IAgentProvider、IDatabase、IWorkflowStore； - 依赖方向约束：
paths ← git ← isolation/workflows ← core ← adapters ← server，禁止循环依赖； - 禁止模式清单：
import * as core from '@archon/core'、无理由的any、根目录直接跑bun test等。
这些内容决定了评审时"计划本来应该写清楚什么"。
2. 生成的计划：Generated Plan（参数 $1）
这是 Agent 实际产出的计划文件，评审者从中提取：规划了哪些功能、指定了什么架构、定义了哪些验证步骤、引用了哪些模式。
3. 执行命令：Execute Command
execute.md 定义了执行阶段的"元流程"：先通读整个计划、验证工作树干净（git status）、按依赖顺序执行任务、每步修改后跑bun run type-check、遵守导入/日志/错误处理/包边界约定、按包增量验证、最后跑全量bun run validate并输出结构化报告。评审者读它，是为了对照"Agent 本该遵循的执行纪律"。
4. 执行报告：Execution Report（参数 $2）
execution-report.md 是 Agent 执行完后的自我复盘，通常保存到.agents/execution-reports/[feature-name].md。它要求记录：计划文件路径、新增/修改文件清单、变更行数、四层验证结果、顺利之处、遇到的挑战，以及每一条偏差的 Planned / Actual / Reason / Type 四元组。这份报告正是 System Review 最主要的证据来源——评审者从中提取"实际做了什么、与计划哪里分叉、遇到了什么挑战、跳过了什么以及为什么"。
值得强调的是：System Review 命令本身也指定了自己的产物路径，即.agents/system-reviews/[feature-name]-review.md，与执行报告形成对称的归档结构。
五步分析工作流
System Review 的分析过程被拆解为五个明确步骤，每一步都有具体的提取目标和产出。
Step 1：理解计划方案
读取计划文件（$1），提取四类信息：
- 规划了哪些功能？
- 指定了什么架构？
- 定义了哪些验证步骤？
- 引用了哪些模式？
这一步的目的不是审查计划好坏，而是建立"应有状态"基线，后续所有偏差判断都以它为准。
Step 2：理解实际实现
读取执行报告（$2），提取四类信息：
- 实际实现了什么？
- 与计划有哪些分叉？
- 遇到了哪些挑战？
- 跳过了什么、为什么跳过？
Step 3：对每条偏差分类
对执行报告中识别出的每一条偏差，归入两类之一：
Good Divergence ✅（合理偏差），典型情形包括：
- 计划假设了代码库中不存在的东西（plan assumed something that didn't exist in the codebase）；
- 实现过程中发现了更好的模式；
- 需要性能优化；
- 发现了安全问题、必须改用不同方案。
Bad Divergence ❌（问题偏差），典型情形包括：
- 无视了计划中的明确约束；
- 没有沿用既有模式，而是另起炉灶建新架构；
- 走了捷径、引入技术债；
- 误解了需求。
Step 4：追溯根因
对每一条问题偏差，回答四个方向性问题，定位根因究竟出在哪个环节：
- 计划是否不清晰？具体在哪、为什么？
- 上下文是否缺失？缺了什么、为什么？
- 验证是否缺失？缺在哪个环节、为什么？
- 是否存在反复出现的手工步骤？出现在哪、为什么？
文档特别强调：要具体，不要泛泛而谈。不能说"计划不清晰"，而要说"计划没有指定使用哪种 auth 模式"（don't say "plan was unclear" - say "plan didn't specify which auth pattern to use"）。
Step 5：生成流程改进建议
基于跨偏差的模式（而非单次偶发问题），从四个层面给出建议：
- CLAUDE.md 更新：记录实现中发现的通用模式或反模式；
- 计划命令更新：澄清有歧义的指令、补充缺失的步骤；
- 新建命令：把重复了 3 次以上的手工流程自动化（对应
/command-name）； - 补充验证：增加能更早捕获问题的检查项。
评审报告的结构与评分模型
System Review 的输出不是口头结论，而是结构化的评审报告，保存到.agents/system-reviews/[feature-name]-review.md。报告共分五个区块。
区块一：元信息（Meta Information）
记录被评审的计划路径（$1）、执行报告路径（$2）和评审日期，保证评审可回溯。
区块二：总体对齐评分（Overall Alignment Score: X/10）
评分指南给出了明确的分段定义：
| 分数 | 含义 |
|---|---|
| 10 | 完美遵循，所有偏差都有正当理由 |
| 7–9 | 存在少量合理偏差 |
| 4–6 | 合理偏差与问题偏差混杂 |
| 1–3 | 存在重大问题偏差 |
区块三：偏差分析（Divergence Analysis）
对执行报告中的每条偏差，用 YAML 形式结构化输出：
divergence: [what changed] planned: [what plan specified] actual: [what was implemented] reason: [agent's stated reason from report] classification: good ✅ | bad ❌ justified: yes/no root_cause: [unclear plan | missing context | etc]这个 YAML 模板是整份报告里最值得复用的部分——它强制把"计划说了什么 / 实际做了什么 / 为什么这么做 / 是否合理 / 根因在哪"五个维度写全，避免了评审流于主观感受。
区块四：模式合规检查（Pattern Compliance）
用一份勾选清单评估对仓库既有模式的遵循度：
- 遵循 monorepo 包边界（Followed monorepo package boundaries）
- 使用了文档化的导入模式（
import type、禁止import * as core） - 正确应用测试模式（
mock.module()隔离） - 满足验证要求（type-check + lint + test）
- 尊重 CLAUDE.md 约定（Respected CLAUDE.md conventions）
- 查阅了相关
.claude/rules/文件获取领域上下文
区块五：系统改进行动（System Improvement Actions）
将分析结论落到可执行的资产更新清单上，分为四组复选框：
Update CLAUDE.md:
- 记录实现中发现的模式 X
- 为 Y 增加反模式警告
- 澄清技术约束 Z
Update Plan Command（$1）:
- 为缺失步骤补充指令
- 澄清歧义指令
- 为 X 增加验证要求
Create New Command:
- 为重复 3 次以上的手工流程创建
/[command-name]
Update Execute Command:
- 在执行检查清单中增加验证步骤
区块六：关键学习（Key Learnings）
最后以三个小清单收尾：What worked well（哪些环节顺畅）、What needs improvement（识别出的流程缺口）、For next implementation（下次具体尝试的改进）。这一部分确保评审的产出不只是归档，而是直接作用于下一轮实现。
把"模式合规"落到 Archon 的实际工程约定上
System Review 的合规清单不是抽象口号，仓库里有大量可对照的实现事实。评审者在逐项打勾时，可以依据以下证据。
包边界与依赖方向
AGENTS.md 明确要求"Preserve package boundaries"，而 plan-feature.md 给出了精确的依赖方向paths ← git ← isolation/workflows ← core ← adapters ← server。execute.md 进一步细化了边界：@archon/workflows不得从@archon/core导入、@archon/git不得从@archon/core或@archon/workflows导入、@archon/paths零@archon/*依赖。评审时若发现偏差触发了循环依赖或越界导入，应直接判定为 Bad Divergence。
导入与代码风格约定
执行阶段约定（见 execute.md）：类型导入必须用import type { ... }；值导入用具名导入而非命名空间导入（import * as git仅对子模块可接受）；所有函数需要显式返回类型；日志采用惰性 logger 模式与{domain}.{action}_{state}事件命名；错误绝不静默吞掉，记录后 re-throw。这些约定同时被 plan-feature.md 的"Prohibited Patterns"清单强化。
测试隔离与验证门禁
仓库的验证体系在 validate.md 中定义为五级：bun run type-check、bun run lint（--max-warnings 0零容忍）、bun run format:check、bun run test、以及全量门禁bun run validate（等价于前四者串联）。关键事实是：Bun 的mock.module()是进程级且永久的，从仓库根目录直接跑bun test会引发约 135 个 mock 污染失败，因此必须使用bun --filter '*' test按包隔离执行（core7 个批次、workflows5 个批次、adapters3 个批次、isolation3 个批次）。评审时如果执行报告显示绕过了这些隔离规则，就是典型的模式违规。
"CLAUDE.md 约定"的实际情况
有意思的仓库事实是：根目录的 CLAUDE.md 全文只有一行——"Agent rules: read @AGENTS.md"，真正的项目级规范全部收敛在 AGENTS.md 中。这意味着 System Review 中"Update CLAUDE.md"这一行动在 Archon 语境下实际指向的是更新 AGENTS.md 这一单一事实源，恰好呼应了 AGENTS.md 中"Project guidance should be available, not sprayed everywhere"的原则。
评审 → 资产更新的闭环：让改进真正生效
System Review 的最后一步也是最关键的一步：把评审结论写回 Layer 1 资产。这个闭环由三条纪律保证：
- 聚焦模式而非单点：一次性的偶发问题不可执行（one-off issues aren't actionable），只有反复出现的模式才值得写进规范；
- 行动导向：每一条发现都必须对应一个具体的资产更新建议，而不是停在"下次注意"；
- 给出可用的文本：不要只分析，要真的给出建议写入 CLAUDE.md 或命令的具体措辞。
这套闭环与仓库其他命令形成互补：执行阶段由 execute.md 的 Step 6 输出报告、由 execution-report.md 记录偏差四元组、由 validate.md 把关验证门禁、由 code-review.md 负责提交前的代码质量——而 System Review 站在所有这些之上，负责让下一轮计划与执行都变得更好。这正是它被设计为"元层（meta-level）"分析的原因。
实战要点速览
在 Archon 仓库中实际使用 System Review 时，记住以下要点：
- 调用方式：命令声明为
argument-hint: "[plan-file] [execution-report-file]"，即/system-review后跟计划文件与执行报告两个参数； - 产物位置：评审报告按约定保存到
.agents/system-reviews/[feature-name]-review.md，与执行报告.agents/execution-reports/对称归档； - 证据优先：评审的每一句话都应能指回计划文件、执行报告或仓库源码，偏差 YAML 中的
root_cause必须填写具体环节而非笼统归因； - 门槛意识：在把结论写回资产前，先对照 validate.md 的验证纪律确认现状——毕竟"评审者"自身也应遵循被评审对象所依赖的工程约定。
<输出文章> <输出文章> System Review 的价值不在于评判一次实现的成败，而在于让计划、执行与规范三者之间形成持续自我改进的循环：合理偏差改进规划、问题偏差改进沟通、重复问题催生自动化。对于任何依赖 AI Agent 执行多步骤开发任务的工程团队，这套"流程级复盘"方法论都值得直接借鉴——它把 AI 开发中最高频的痛点（计划与现实的偏离）从偶然事故变成了可分类、可追溯、可改进的工程资产。 </输出文章>
【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
