IronClaw 的评审与修复纪律：从全契约审查到“护栏即代码“的工程实践

• 人工智能
• AI 应用
• 交互助手
• AI Agent

本文基于 IronClaw 仓库的评审纪律规范 review-discipline.md，系统讲解这个以隐私、安全与可扩展性为核心的 Agent OS 项目如何在代码评审、Bug 修复与重构中维持质量基线。文章覆盖评审契约、机械陷阱清单、必跑命令、范围纪律、删除"冗余"层时的行为保全策略，以及"护栏即代码"的落地机制，并给出crates/、scripts/、.github/workflows/中的源码级佐证，帮助你理解并在自己的 Rust 仓库中复用这套纪律。

一、评审整个契约（Review the whole contract）

IronClaw 的评审纪律首先要求：一次 Bug 修复的评审对象不是那一个补丁，而是围绕它的整个契约。规范原文要求检查六类面：

• 实现本身（implementation）；
• 调用方（callers）；
• 持久化（persistence）；
• 线上/线缆类型（wire types）；
• 前端消费方（frontend consumers）；
• 测试，以及相关的Reborn 契约（项目内部对 Reborn 化架构的契约约束）。

具体手法上，规范强调两点搜索纪律：

1. 跨 crate 搜索 Bug 模式：不要只修被报告的那一处，而要在整个crates/目录下检索同类缺陷（即后文"Pattern fixes"），因为同一模式往往在兄弟实现中成片存在。
2. 双向验证否定性断言：当你在 PR 里声称"这里不可能出问题"时，必须同时用符号搜索（symbol search，按类型/函数名检索）和概念搜索（concept search，按语义关键词检索）来验证，防止因命名差异而漏掉实现。

每个修复都必须带回归测试

规范中不可妥协的一条：每个 Bug 修复都需要一个在修复前必然失败的回归测试。具体形式可以是：

• #[test]单元测试；
• #[tokio::test]异步测试；
• 契约测试（contract test）；
• 集成场景（integration scenario）。

当包装器（wrapper）、计算输入（computed inputs）或副作用把辅助函数与实际行为隔开时，规范明确要求优先选择调用方级或集成级测试——只测被隔离的辅助函数无法证明行为修复在真实路径上生效。纯文档变更（documentation-only changes）可以豁免；若回归测试确实不可行（genuinely infeasible），则必须在 PR 中说明原因，并使用仓库明确的"回归检查豁免"机制（regression-check exemption），而不是默默省略覆盖。这与tests/integration/下大量场景化测试（如 budget.rs、trace_capture.rs、triggered_submit.rs）的组织方式一致——每一个都对应一条真实用户路径。

二、机械评审陷阱清单（Mechanical review traps）

规范把最容易在 AI 辅助开发中反复出现的问题归纳为八类"机械陷阱"，每类都给出了明确的规避手段：

1. 零警告（Zero warnings）：被改动的 Reborn crate 必须通过clippy --all-targets --all-features -- -D warnings。提交前要跑一遍工作区级命令（见第三节），并修复其暴露的每一个警告——包括不在本次改动文件内的既有警告。

2. 特性矩阵，而不是只跑--all-features：--all-features无法捕获特性门控的死代码——一个只在#[cfg(feature = "x")]下存在的调用方，会让其辅助函数在--all-features下"存活"、而在特性关闭时"死亡"（触发-D warnings错误）。关键背景：PR CI 只跑精简的all-features通道，更宽的default通道在合并后（post-merge）才跑，因此这一类缺陷可能在 PR 全绿之后才破坏main。规范给出的对策是：新增或移动#[cfg(feature = ...)]门控、或改动只经由某个特性可达的辅助函数时，合入前必须在本地跑相关特性通道；当你把某个辅助函数的唯一调用方用特性门控包住时，必须用相同的#[cfg]门控辅助函数本身的定义。

3. UTF-8 边界：永远不要用&value[..n]对用户或外部字符串做字节切片（多字节字符会 panic）。应改用char_indices()、chars()，或经过is_char_boundary()校验的边界。这条规则的工程落地可以在 scripts/pre-commit-safety.sh 检查 1 中看到：它会扫描新增代码中的[..切片，排除is_char_boundary|char_indices|// safety:等安全模式后发出 UTF8 警告。

4. 大小写不敏感的外部值：大小写不敏感的标识符、媒体类型、扩展名、平台敏感的路径比较，必须在边界处用to_ascii_lowercase()或eq_ignore_ascii_case()归一化；不要把小写化施加到大小写敏感的透明值（opaque values）上。同样在 scripts/pre-commit-safety.sh 检查 2 中落地：检测ends_with(".png")这类未先小写化的扩展名比较。

5. 装饰器委托（Decorator delegation）：为 trait 新增方法时，必须逐一枚举所有生产实现、装饰器（decorator）、适配器（adapter）和测试替身（test double），保证整条包装链都被覆盖。规范给出了一个具体起点命令：对LlmProvider，先执行rg -n "impl LlmProvider for" crates找出全部实现，再沿完整包装链测试。

6. 生产代码禁止 panic：搜索改动过的生产文件中新增的.unwrap()与.expect()——测试之外一律禁止，必须改向显式传播错误。这也是 scripts/pre-commit-safety.sh 检查 6（PANIC）与 scripts/check_no_panics.py 在 CI 中共同守护的底线，后者还维护了一份生产代码无 panic 基线 no_panics_reborn_baseline.txt。

7. 导入风格：跨模块导入优先crate::；super::仅在紧耦合子模块与测试内可接受。

8. 模式修复（Pattern fixes）：修复一处 Bug 后，要在整个crates/下搜索同类缺陷的兄弟实例，一并评估处理。

陷阱清单在护栏脚本中的完整对应

上述规则并非只是文档主张。scripts/pre-commit-safety.sh 把其中大部分直接做成了可执行检查（检查 1 UTF8、检查 2 CASE、检查 3 硬编码 /tmp 路径、检查 4 未脱敏日志、检查 5 多步 DB 操作缺事务、检查 6 生产代码 panic、检查 10 零调用方的公共 API、检查 11 架构蔓延、检查 13 composition 质量预算），并提供三种行内豁免注释：

• // safety: <reason>—— 通用豁免；
• // pub-api-exempt: <reason>—— 针对"新公共 API 零调用方"检查；
• // arch-exempt: <category>, <reason>, plan #NNNN—— 针对架构蔓延，要求携带类别与后续计划编号。

同时 clippy.toml 以配置形式固化了复杂度护栏（认知复杂度阈值 15、单文件行数阈值 100、参数个数阈值 7 等），并禁用了一个会导致读写分裂的反模式构造器（ironclaw_outbound::OutboundStateStore::new）。

三、必跑检查命令（Required checks）

规范给出了从窄到宽的命令序列，强调"先跑最窄的 crate 测试与 clippy"：

# 1. 架构约束测试（依赖边界、废弃词汇表等，见第四节） cargo test -p ironclaw_architecture_tests # 2. 改动所属 crate 的全目标、全特性零警告 clippy cargo clippy -p OWNING_CRATE --all-targets --all-features -- -D warnings # 3. 本地提交前安全脚本（支持独立运行，也可由 dev-setup.sh 安装为 git pre-commit 钩子） scripts/pre-commit-safety.sh

然后是工作区级零警告 clippy：

cargo clippy --workspace --all-targets --all-features -- -D warnings

以及特性矩阵——它复现的是合并后（post-merge）的Code Style门禁，而 PR CI 只跑all-features通道。规范要求：只要改动新增、移动或依赖了#[cfg(feature = ...)]门控，两条通道都要跑：

# default 通道 cargo clippy --all --tests --examples -- -D warnings # all-features 通道 cargo clippy --all --tests --examples --all-features -- -D warnings

最后，当改动跨越**回合（turns）、能力（capabilities）、授权（authorization）、审批（approvals）、持久化（persistence）、运行时通道（runtime lanes）、网络（networking）、密钥（secrets）、产品编排（product orchestration）或用户可见传输（user-visible transport）**时，必须运行 Reborn 集成或 E2E 测试装置（harness）。

这套命令在 CI 中的真实形态可以在 .github/workflows/code_style.yml 里验证：PR 的clippyjob 只对变更过的包跑--all-features精简通道（clippy_matrix在pull_request时只含all-features一项），而 merge_group 与 push 到 main 时矩阵展开为all-features与default两条，且有一条专门步骤"Assert the full clippy matrix ran (merge queue + push)"——若矩阵意外退回精简形态会直接 fail。这正是文档所述"PR CI 只跑精简 all-features 通道、宽 default 通道合并后跑"的工程实锤。

四、范围纪律（Scope discipline）

规范对 PR 的"边界"提出三条硬性要求：

1. PR 标题与正文必须描述完整 diff。如果一次改动跨越多个层（layers），要么在标题中明确点出该范围，要么拆分 PR。
2. 纯移动（move-only）改动必须声明"行为不变"（behavior is unchanged），行为修复与移动分开，并在移动过程中发现的问题单独记录跟进 issue。
3. 移动或重命名代码后，必须搜索以下位置是否存在陈旧路径（stale paths）引用：.claude/、根级AGENTS.md、CLAUDE.md、crates/AGENTS.md、docs/internal/reborn/contracts/以及其他 Markdown 引用。

这一点与仓库的"引导一致性"门禁相互印证：code_style.yml 的 fast-checks 中运行的 check-guidance.py 会校验仓库中被文档引用的路径全部真实存在、.claude/rules的paths:触发规则至少匹配一个被跟踪文件（一个匹配不到任何文件的 glob 就是一条永不触发的规则）。

五、删除"冗余"层会暴露行为（Removing a "redundant" layer un-masks behavior）

这是规范着墨最深、也是最具实战价值的一节。核心论断是：你认定"冗余"而删除的那一层，往往在静默地"托底"（backstopping）下游代码没有复现的行为。删除它并不会消除该行为——而是把缺口暴露出来：运气好时是测试失败，运气不好时是静默回归。这是合并/去重（consolidation/dedup）类重构的首要隐患。

动机案例：PR #6386/#6392 的 authorize() 策略整合

规范引用了一个真实案例：删除ironclaw_host_runtime中"冗余"的预授权（pre-authorization）后，共暴露了五类此前被掩盖的行为：

1. 一个陈旧导入（stale import）；
2. 模型消息净化（model-message sanitization）缺失；
3. 未知能力（unknown capabilities）场景下的运行记录排序问题；
4. 恢复路径（resume paths）上运行时策略执行（runtime-policy enforcement）被丢弃；
5. mismatch-vs-unknown 优先级翻转（precedence flip）。

删除疑似冗余层时必须遵守的纪律

第一，跑全量、不过滤的测试套件：对每个被触动的 crate 执行cargo test -p <crate> --no-fail-fast，并且不要把输出接进head/tail。规范明确指出：部分视图会少算失败数（在 #6392 中曾两次掩盖三个真实失败）——"过滤后的绿色不是绿色"（Filtered green is not green）。

第二，每个浮出水面的失败都是候选的真实行为，而不是一个需要改写的测试。对每个失败都要判断：被删层是否在提供该行为？幸存代码是否复现了它？保留行为，不要为了变绿而削弱断言——除非你能证明旧行为本身就是错的（并在 PR 中说明）。静默更新测试以匹配新输出，正是整合型重构带上回归的方式。

第三，承重可观测项是失败的"种类"与持久状态（RuntimeFailureKind、运行状态迁移、审计error_kind），而不是消息文本。种类必须原样保留；净化后的模型可见消息是另一个更弱的契约（详见 error-handling.md）。

第四，"冗余"是分路径（per-path）的。在某个入口路径（如 invoke/spawn）上冗余的检查，可能是另一个路径（如 resume/auth-resume）上的唯一副本。删除前必须确认幸存代码覆盖了每一条路径，而不只是你检查过的那条。

当工作被切片给多个子代理（subagent）时，给每个切片下达固定指令：遇到浮出的行为就停下上报，而不是提交绿色或削弱测试——增量是否可接受由评审者决定，而不是切片作者。

源码佐证：闭集失败词汇表的"零遗留门"

"承重可观测项是失败种类而非消息文本"在源码中有直接体现。result_meta.rs 用declare_failure_kinds!宏把唯一一份FailureKind闭集词汇表及其 wire tag、ALL常量一次性声明出来：枚举、标签、完整性三者由编译器绑定，任何新变体都必须同时出现在所有投影中。fate()（决定 Retry / ModelVisible / Park / Terminal）与CapabilityRecoveryHint::for_failure_kind()（决定模型下一步动作）都是无通配符的穷尽匹配——新增一个变体若未分类将直接编译失败，这个编译错误本身就是"可恢复性评审"。

而 reborn_retired_failure_vocabulary.rs 则是把"旧词汇表不得复活"做成了一道零遗留门（zero-legacy gate）：被淘汰的RuntimeFailureKind、CapabilityFailureKind、CapabilityErrorClass及开放集逃逸口（如Unknown(载荷变体、#[non_exhaustive]）被扫描crates/与tests/下的全部.rs代码，出现一次即失败。它甚至自带对注释豁免契约的测试（strip_comments_tests模块验证行注释、块注释、嵌套块注释都被正确剥离而代码中的命中不会被藏住）——这正是规范"护栏自己的豁免规则必须被测试，而不是被信任"的样板。

六、护栏即代码（Guardrails are code）

规范的收尾一节把整套纪律上升为工程原则：检查与钩子（checks and hooks）本身也需要回归测试，必须能处理多行语法，并且必须在其自身文件变更时运行。三条操作性要求：

1. 永远不要在未实际执行强制命令的情况下宣称"已强制"（Never claim enforcement without executing the enforcing command）；
2. 注释和文档承诺的保证，必须与代码和测试一致；
3. 护栏自身的触发条件不能失效——一个匹配不到任何文件的 glob、一条永不运行的检查，等于没有护栏。

仓库里可以找到大量"护栏自测"的实例：

• code_style.yml 的 fast-checks 中专门有一大步Static-check self-tests，批量运行test-check-include-str-paths.sh、test-check-hermetic-env.sh、test-classify-test-scope.sh、test-changed_workspace_packages.py、test_ws12_workflow_contracts.py等护栏自身的测试——代码里还明确注释了 #7144 的教训：一个 204 个测试的模块此前从未被任何通道运行，导致五条断言与所守护的代码静默漂移。
• composition 质量预算门（composition-budget.toml 与其执行器 check-composition-budget.sh）配置了ceiling_bp（占比上限）、loc_ceiling（绝对 LOC 上限，防"分母被污染"）、arc_dyn_ceiling（Arc 分发点上限）等多维棘轮指标，并在 CI 中由test-check-composition-budget.sh自测。
• pre-commit-safety.sh 顶部注释明确说明它既支持独立运行也支持作为 pre-commit 钩子，且当"composition 或门自身被暂存"时触发第 13 项检查——即护栏自身文件变更时护栏会运行。
• 前面提到的 reborn_retired_failure_vocabulary.rs 更是"护栏即代码 + 豁免规则必须被测试"的双重典范。

七、总结：把纪律固化成可执行、可验证的工程资产

IronClaw 的review-discipline.md之所以值得借鉴，不在于它罗列了多少条"应该"，而在于它把每一条都对应到了可执行命令、可运行脚本与可编译的测试上：评审要覆盖整个契约并用回归测试锁定；机械陷阱有pre-commit-safety.sh与 clippy 配置兜底；必跑命令区分了 PR 与合并后的特性矩阵差异；删除冗余层有"跑全量套件、保留行为种类、按路径确认覆盖"的四步纪律；而"护栏即代码"则要求每一道检查都有自测、能处理多行语法、并在自身变更时运行。

对于同样在推进"AI 辅助开发 + 大仓库重构"的团队，这套纪律提供了一个可复制的模板：把评审经验写成规则，把规则变成命令，把命令配上自测，把自测接入 CI——四个环节环环相扣，才能让质量基线在自动化程度不断提高的开发流程中不退化。

• 人工智能
• AI 应用
• 交互助手
• AI Agent