ac-reviewing-codebase

审查代码库

对多个仓库中的技能、代码和基础设施进行全面审查。将整个仓库组合视为一个相互关联的系统——最危险的 Bug 往往出现在衔接处：一个技能的输出成为另一个技能的输入；技能描述的代码已发生变化；或者两个仓库以不同方式实现同一约定。交叉审查不只是技能与代码之间的审查，还包括整个仓库组合中的仓库与仓库、技能与技能，以及代码与代码之间的审查。

使命：重新提升质量，而不只是报告（不可妥协）

AI 辅助的变更会不断累积架构熵——快速但浅显的编辑每进行一轮，都会让仓库略微变差：臃肿模块不断膨胀，依赖防护规则变得过时或失效，代码异味层层叠加。这项技能的任务是遏制这种退化，而不是描述它。每轮审查都要主动提升质量：严格评估自上次审查以来的架构变更；如果修复方案明确，就在同一会话中完成改进（遵循规则 9——直接实现，不要推迟）。如果审查只列出问题，却让架构维持原样，就没有完成使命。交付成果应是实实在在有所改善的代码库，而不是一份报告。只有当变更过大，或设计存在歧义、无法在本次会话中安全落实时，才将其“记录待办”；即便如此，也要立即修复影响范围明确且安全的部分，并为其余部分提出具体设计方案。

依赖项

独立运行。没有对其他技能的硬性依赖。

建议搭配的技能（如适用，在阶段 0 加载）：

• ac-python — 当被审查的仓库包含 Python 脚本或测试时，加载此技能，以采用其集成优先的测试理念和代码风格指南。
• ac-django — 当被审查的仓库使用 Django 时（检查依赖项中是否包含 django 或是否存在 manage.py），加载此技能，以采用 Django 特定的模式和约定。

符合条件时，必须加载搭配技能。 如果被审查的代码使用 Python，就加载 ac-python。如果使用 Django，就加载 ac-django。跳过搭配技能会导致审查不完整。

配置：~/.ac-reviewing-codebase

启动时，如果 ~/.ac-reviewing-codebase（硬编码路径）存在，就加载它。这是一个可由 Shell 加载、变量名使用大写形式的配置文件。

# Root the repo scan walks. Every repo path below is relative to it.
WORKSPACE_DIR="~/workspace"

# Regex matched against resolved skill paths.
# Skills whose real path matches are owned by the user and can be modified.
MAINTAINED_SKILLS="my-repo/|other-repo/internal/(my-skill/)"

# Regex matched against repo paths relative to WORKSPACE_DIR.
# All git repos under WORKSPACE_DIR whose relative path matches are managed.
MANAGED_REPOS="<org>/(repo-a|repo-b|repo-c)$"

# Boilerplate -> dependent repos mapping.
# Format: boilerplate_name:dep1,dep2;boilerplate_name:dep1,dep2
BOILERPLATE_MAP="<boilerplate-repo>:<dep-repo-1>,<dep-repo-2>"

# PR-sweep policy per repo (consumed by the sweeping-prs skill).
# Format: repo_pattern:policy;repo_pattern:policy
# Policies: bulk-update (default — refresh PR from main, do not merge)
#           serial-merge (refresh, wait for CI green, squash-merge, then next PR)
SWEEP_POLICY="<owned-org>/(repo-a|repo-b):serial-merge"

变量	用途	缺失时的回退值
WORKSPACE_DIR	仓库扫描所遍历的根目录	~/workspace
MAINTAINED_SKILLS	所有权检查所用的正则表达式——匹配的技能可自由修改	修改任何技能前先询问用户
MANAGED_REPOS	用于在 WORKSPACE_DIR 下发现仓库，以便查看状态、审计或压缩提交的正则表达式	询问用户要管理哪些仓库
BOILERPLATE_MAP	将样板仓库映射到其依赖仓库，以支持回移工作流	不进行回移
SWEEP_POLICY	sweeping-prs 技能的逐仓库策略——bulk-update 仅从 main 更新 PR；serial-merge 还会先进行 squash 合并，再处理下一个 PR（避免自有仓库中出现冲突级联）	所有仓库默认使用 bulk-update（仅更新）

此文件是 CLI 读取的唯一配置。较早的版本曾将另一份 TOML 格式的工作区配置作为 workspace_dir 的来源；但没有任何代码会读取它，因此在该处设置工作区根目录的用户最终会回退到 ~/workspace，并且得到一份悄然出错的仓库列表。

此文件可以与生命周期工具共享（该工具会读取此文件中的工作区和所有权配置）。此类工具的用户可以在设置过程中生成该文件。否则，请手动创建。

外部参考

• Anthropic 技能编写最佳实践
• Agent Skills 概述

确定性 CLI

统一入口为 scripts/cli.py——它通过 Typer 连接其旁边的同级模块（review_config、skill_frontmatter、repo_status、codebase_metrics、review_gate、ui），保持精简。

仓库选择只用一个标志：--root，其值为仓库 PATH。status 会检查所有受管理的仓库，因此可通过 --name 按目录 NAME 缩小范围（保留 --repo 作为别名）。

# FIRST action of every review — render the enforced completion checklist
uv run ac-reviewing-codebase/scripts/cli.py review-checklist [--out PATH]

# LAST action of every review — gate: exits non-zero until the review is complete
uv run ac-reviewing-codebase/scripts/cli.py review-verify [CHECKLIST]

# Validate SKILL.md frontmatter in a skills repo
uv run ac-reviewing-codebase/scripts/cli.py check [--root PATH]

# Show delivery status across all managed repos
uv run ac-reviewing-codebase/scripts/cli.py status [--name NAME] [--verbose]

# Inventory config files and health checks
uv run ac-reviewing-codebase/scripts/cli.py config

# Run deterministic codebase metrics → JSON
# Counts that can span vendored code are reported per scope. Vendored paths are
# read from the repo (.gitattributes `linguist-vendored`, then the ruff config's
# exclude, then a conventional vendor dir); `--vendored` overrides when the repo
# declares none. When ruff is configured to skip the vendored tree, the report
# says so instead of printing a 0 nobody measured.
uv run ac-reviewing-codebase/scripts/cli.py assess [--root PATH] [--vendored PREFIX]... [--json]

在本仓库的 pre-commit 钩子中，check 命令会自动运行。交互式审查其他仓库时，请在深入审查前显式调用。

完成状态由机制强制保证，而非靠记忆（不可妥协）

这项审查包含约 40 个必做项，分布在 1,500 行参考说明中。反复出现的失败情况是：Agent 运行 Phase 0，发现真实问题并提交修复，然后报告“审查已完成”，但实际只覆盖了部分范围。这套流程在结构上无法区分已完成的审查和中途放弃的审查；此前反对这种做法的文字规则（规则 12）也未能奏效，因为要求 Agent 记住 40 件事的规则，与之前失效的机制属于同一类。

因此，完成状态通过可执行机制来保证：

1. 开始每次审查时，都先运行 review-checklist。它会将 references/review-manifest.md——范围的唯一事实来源——生成一份工作清单。
2. 完成每项后立即勾选，并附上证据，说明你实际运行或阅读了什么。勾选只需按一次键，在差异中看起来和实际工作完全一样；证据行才是让差别显而易见的关键。
3. **只有 review-verify 以 0 退出后，才能报告审查已完成。**只要有任何不可妥协项未勾选，或任何勾选项的 evidence: 为空，它就会失败。

确实不适用的项目，应勾选并填写 evidence: n/a — <reason>。声明某项不适用是一种会留下记录的判断；而这道门槛要捕获的，恰恰就是默默跳过。

如果审查确实大到无法在一次会话中完成，请如实说明并报告清单状态——如实报告部分审查没有问题。将部分审查报告为已完成则不行。

**给提出审查请求的人。**没有任何指令能强迫 Agent 运行命令，因此这道门槛真正的作用，是让你能通过一条命令证伪完成声明：

uv run ac-reviewing-codebase/scripts/cli.py review-verify .review-checklist.md

返回非零意味着审查尚未完成，不管摘要怎么说。如果清单根本不存在，就说明审查从未依据这份清单界定范围——这本身就是答案。要求对方在提交发现结果时一并提供清单；它能说明实际覆盖了多少范围，是交付物的一部分。

质量原则

开始任何审查前，请阅读 references/quality-principles.md。该文件定义了评估每项技能和代码库时都要遵循的 8 项原则：可靠性、健壮性、平台独立性、自动化与升级处理、Agent 无关性、自我改进、范式适配性，以及技能与模型的平衡。

规则

1. 机械式证据收集：默认在主线程中进行紧凑扫描；并行派发子 Agent 是升级手段，不是第一步。每个仓库的机械性信号（git status、git log @{u}..HEAD、git stash list、lint、format-check、test summary、TODO/noqa 计数）输出都少且容易限制——使用计数、tail -N 和单行摘要即可，因此仅针对机械性工作的上下文预算理由，并不足以支持分派。默认在主线程中直接逐个仓库运行，并严格限制输出。这比派发更快、更可靠（实际观察：即使应用了所有应对措施，4/4 个并行 Explore Agent 仍未通过审计——出现混乱、从压缩摘要中臆造“TEXT ONLY”限制，以及直接拒绝）。 仅在工作需要大量判断且彼此独立时（例如，为评估架构而阅读每个代码库中的大量完整文件），或项目组合规模过大、即使限制每个代码库的扫描范围也会耗尽上下文时，才升级为并行子 Agent。如果确实需要分派：
   • **每个 Agent 只负责一个代码库。**切勿在一个提示词中合并两个代码库。
   • 指定确切的命令，不要只列出检查维度。不要写“审查卫生状况”，而要写“运行 git status --short、git log --oneline @{u}..HEAD、git stash list 并逐字报告结果”。
   • 限制报告长度（≤300 个单词），并禁止总结发现——Agent 应返回原始证据，由你在主线程中综合。
   • 重新分派失败一次后，改为在主线程中扫描该代码库。不要继续重新分派。 无论哪种情况，需要大量判断的综合工作（架构评估、跨审查衔接处的核查、决定整合哪些内容、实现）都应留在主对话中。这条规则要防范的反模式，是在主线程中对多个仓库串行执行耗时的完整文件读取，而不是在主线程中运行快速、有上限的机械扫描；后者才是首选做法。
2. 在工作树中操作源代码仓库（由 git 跟踪），绝不要在主克隆或 Agent 运行时 skills 目录下的符号链接目标中操作。编辑之前，为每个仓库创建一个审查分支和工作树。
3. **全面细致，不求快速。**克制尽快完成的冲动。每个阶段的存在都有其理由。
4. **有歧义时就询问（不可妥协）。**遇到不明确的设计决策、模糊的范围，或存在多个有效选项时，停下来询问用户。在检查器模式下，将有歧义的项目标记为错误并返回 FAIL。例外——常规仓库整理不属于此类歧义。调查过时的工作树、领先于默认分支的分支、遗留的 stash、已合并 PR 的清理事项（内容是否已合并？是否存在独有的未完成工作？是否已被取代？），并根据结论采取行动。不要为日常整理事项列出“删除／保留／检查”的选项。只有当内容确实存在歧义，或操作具有破坏性且不可逆（例如删除包含尚未合并且未被取代的工作的分支）时，才上报用户。
5. **只使用通用术语。**使用“项目专属技能”“通用／框架技能”“生命周期技能”等术语，绝不要在此文件中硬编码实际的技能名称。
6. **积极整合。**关键操作知识若埋藏在项目专属手册中，就容易被忽略。审查者必须主动搜寻被埋藏的知识并将其提炼出来。
7. **尊重内容的发布状态。**当 draft: false 时，内容已发布，不得修改——指出问题，但不要编辑。
8. **此技能属于元层级——必须保持中立。**不得包含特定技能名称、项目名称、仓库结构或工具栈。适用于任何项目组合。
9. **立即实施，不要推迟（不可妥协）。**审查发现具体改进时，必须在同一会话中实施。TODO 注释就是拖延。
10. **积极提取共用部分。**脚本、仓库或技能之间的重复逻辑都属于发现项。应提取到共享模块、工具或参考文件中。不确定重复是否有意为之时，询问用户。
11. **文档必须保持最新或自动生成。**检查文档（README、BLUEPRINT、生成的 API 文档）是否与代码保持一致。若由人工维护，指出偏差；若为自动生成，确认生成钩子存在于 pre-commit 或 CI 中。应自动生成却未自动生成的文档属于发现项。
12. 阶段 0 的修复不等于审查，清单是证明审查完成的方式（不可妥协）。阶段 0 的前置检查经常会发现可以快速修复的问题，例如生成器脚本中的过期引用、shim 错误或缺失的依赖声明。提交这些修复固然值得肯定，但这并不等于完成审查。本规则过去要求“在宣布审查完成前，明确列出范围内的每个仓库，并确认每个仓库都已完成阶段 1–4”，但这行不通：它要求 Agent 记住，而记忆正是会失效的机制。现在，完成审查必须通过 review-verify 来判定（参见 §“完成状态由强制校验，而非记忆”）。先运行 review-checklist，逐项勾选并附上证据；只有当校验关卡以 0 退出码结束后，才能报告审查完成。若范围内有 8 个仓库却只审查了 2 个，那就只完成了 25%，并未完成——清单会明确说明这一点。
13. 行为评估覆盖是建议，绝非强制要求。确定性测试评估代码的行为；它们无法评估技能指示 Agent 做什么，也无法判断运行时非确定性、由 AI 评估的行为是否成立。当审查的技能包含关键规则，或运行时行为取决于 LLM Agent 说了什么／调用了什么时，建议覆盖行为评估（按技能嵌入评估，和／或上层集成 AI 评估）。这是有条件的：建议采用能够覆盖该行为的最低成本方案（代码可强制执行 → 确定性测试；仅限 LLM 输出 → 对话记录场景）；仅部分建议（覆盖技能中的关键规则，而非每一行）；若仓库已有自己的评估／行为测试机制，绝不要建议再加一层，应与现有机制保持一致。这是用户可以拒绝的发现项，而非关卡。有关机制的说明，请参阅 references/ai-eval-review.md，确保每项此类发现都提出具体方案。
14. **采取行动前先验证标记的问题。**顺带发现的问题——例如子扫描中的附带说法，或某种“看起来不对”的模式——只是线索，不是已确认的发现项。在据此阻止流程或将其记录为长期发现项之前，应针对实际代码复现问题（运行命令、追踪路径）。未经验证就被当作事实传播的说法，会浪费作者的时间并损害审查的可信度。
15. **独立视角比作者本人的视角更容易发现问题。**审查的大部分价值来自审查者不是改动的作者——自我审查会忽略正是导致 bug 的假设。条件允许时，应让不同人员或另一次独立的 Agent 运行来执行审查，而不是让编写代码的同一方审查。这是关于提高审查有效性的原则，不是工作流强制要求——无论由人工还是自动化执行，都适用。
16. 注释即代码——一行，或不写（属于发现项，绝非关卡）。名称、类型和结构承载含义。注释只有在说明代码本身无法表达、且不言自明的原因时才有价值，并且必须用一行写明。若多行注释只是在叙述下方代码已经做的事情，那就是发现项；修复方式是重命名或拆分，而不是缩短文字。当然也存在正当例外（威胁模型、协议特性、经测量得出的常量）；应具体判断，而不是一概禁止。要确保这一原则切实有效，有两条限制：只评判此次改动新增的内容——重写原有注释会使 diff 扩大为无关改动；绝不要把几个不同要点挤成一行来满足规则，应删去不值得保留的要点。绝不要引入会因注释长度而阻断流程的 lint 规则、钩子或 CI 关卡：这种摩擦带来的成本高于臃肿注释的代价，因此只能将其作为作者可以拒绝的发现项报告。允许的最强自动化措施是提示性警告。

---

审查阶段

flowchart LR
    P0["**0** Prerequisites"] --> P1["**1** Discovery &<br/>Architecture"]
    P1 --> P2["**2** Content<br/>Review"]
    P2 --> P3["**3** Technical<br/>Review"]
    P3 --> P4["**4** Quality<br/>Review"]
    P4 --> PA["**A** Codebase<br/>Assessment"]
    PA --> P5["**5** Plan &<br/>Implement"]
    P5 --> P6["**6** Regression<br/>& Delivery"]
    P6 -.->|iterate| P1

阶段 0 — 前提条件

0. 渲染检查清单——这是开始任何工作前必须完成的事项。 运行 cli.py review-checklist。以下所有内容以及后续每个阶段，都是该检查清单中的一项；在每项都勾选并附上证据之前，review-verify 都不会通过。 不先执行此步骤就开始审查，审查最终就会只完成 25%，却被报告为已完成。

然后：

1. 验证由 Git 跟踪的源代码仓库。 对范围内的每个仓库，确认技能目录是由 Git 跟踪的源代码，而不是符号链接目标。如果用户的当前工作目录（cwd）是多个技能仓库的父目录（其本身不是仓库），请逐一验证每个子仓库。

2. 检查符号链接状态。 扫描 Agent 技能目录，查找由 MAINTAINED_SKILLS 正则表达式匹配的受维护技能，确认它们是否为受管理的安装，而不是指向实时克隆的符号链接。报告过期安装。

3. 检查尚未暂存的更改和主克隆的整洁度。 在每个受管理的仓库中运行 git status。如果存在未提交的更改，请在开始前提交——这样可以将审查更改清晰地隔离开来。主克隆停留在功能分支上且有未提交的编辑，属于违反 worktree 规则：将未提交的工作转移到新的分支和 worktree，恢复主克隆到默认分支，然后继续。

   暂存与过期分支分类处理（不可妥协）。 对于每个遗留暂存内容或领先于默认分支的分支，在决定应用还是丢弃之前，先验证其内容是否已存在于项目组合的其他位置——例如某条 CLI 命令、同级技能或参考文件，或已合并的（通常通过 squash 合并的）PR。如果已存在，则内容并非独有：只应用真正新增的差异，并与规范归属位置进行整合，而不是创建第三份分化副本；其余内容全部丢弃。通过提交数量或 git diff 内容相等来检测“此分支是否已合并”在 squash 合并工作流中并不可靠（squash 会创建新的 SHA，且默认分支会继续前进）——应以 PR 合并状态为权威信号；如果项目提供了 worktree 清理命令，也可以使用该命令，而不要自行编写启发式判断。

4. 检查所有未关闭的 PR（不可妥协）。 审查必须基于最新状态——即将合并的未处理 PR 会导致审查结果过时，并迫使你重新审查。

   • **首选方式：**如果会话提供了生命周期工具专用的 PR 扫描技能，请调用该技能，并在其返回后继续。SWEEP_POLICY（见 § 配置）中声明了 serial-merge 的仓库会在扫描返回前全部合并完成；采用 bulk-update 的仓库则只会基于 main 更新。
   • **如果不可用：**询问用户是否有可供安装的此类技能。如果用户拒绝，则手动扫描：向用户询问正确执行所需的少量问题（涉及哪些仓库、纳入/排除哪些 PR、冲突解决偏好、是否等待 CI、对于完全由用户负责的仓库，CI 通过后是否也要合并每个 PR），然后逐一处理每个未关闭的 PR——从基准分支更新、推送、监控 CI、修复根本原因（绝不使用 --no-verify），并且（对于用户希望全部处理完毕的仓库）在处理下一个 PR 之前先通过 squash 合并；最终报告中应列出任何跳过的 PR。

5. 确定审查范围。 使用配置中的 MAINTAINED_SKILLS 查找范围内的所有仓库和技能。按仓库列出发现的技能，并请用户确认或缩小范围。 然后按照变更情况排序。 预算有限，因此应把精力花在自上次审查以来发生代码变更的地方——新的偏差就出现在那里。直接从代码树获取排序结果（git log --since=<last review> --name-only --pretty= | sort | uniq -c | sort -rn）。上次审查时未发生变更且状态良好的区域，是剩下最不值得查看的地方。

6. 动态发现 Agent 记忆和配置文件。 扫描各平台专属位置（例如，~/.claude/projects/*/memory/、~/.codex/、~/.cursor/）以查找记忆文件。检查每个项目根目录中是否有仓库级 Agent 配置（AGENTS.md、.cursorrules 或类似文件）。将所有发现的文件纳入资产清单，以便交叉审查。

7. 完整阅读所有选定的技能。 加载每个 SKILL.md、每份参考资料、每个脚本以及每项钩子配置。不要略读。

---

阶段 1 — 发现与架构

结合上下文审查技能。 审查多个技能时，应将它们视为相互关联的系统。即使只审查单个技能，也要检查它与其他内容的关联。

1.1–1.5：技能与代码架构

• 1.1 依赖关系图。 绘制技能及其相邻项之间的依赖关系图。检查耦合方向：通用技能绝不能导入项目专属技能。
• 1.2 架构评估。 技能/代码的拆分是否合理？是否需要合并、拆分或重构？中等评估：超过 60% 的流程是确定性的 → 可考虑工具化。
• 1.3 依赖关系文档。 每个技能都必须声明依赖项，或注明“Standalone”。
• 1.4 托管资产清单。 列出外部资产（配置、仓库、记忆文件、钩子），并分类为：自有、引用、指令。
• 1.5 跨技能/跨模块一致性。 在所有技能和代码仓库中搜索共享模式。同一概念在不同位置使用不同名称 = 已过时。

1.6：交叉审查 — 全局一致性（不可妥协）

这是该技能的关键差异点。 审查应着眼全局，跨越所有边界：技能与代码、技能与技能、代码与代码，以及仓库与仓库。检查作品集中的每个制品，并与其交互的所有其他制品进行核对。

技能 ↔ 代码：

1. 技能 → 代码验证。 对于引用 CLI 命令、API 模式、文件路径或代码规范的每个技能，都要对照实际代码库验证这些引用。运行命令，检查路径是否存在。如果技能要求“运行 tool setup”，就要确认该命令确实存在且能按描述正常工作。
2. 代码 → 技能验证。 对于应由技能规范约束的代码模式（测试规范、提交工作流、部署流程），要验证技能是否准确描述当前行为。如果代码自技能编写后发生了变化，那么两者之一就已过时。

仓库 ↔ 仓库：

3. 跨仓库规范一致性。 多个仓库采用相同规范（分支命名、提交消息格式、测试结构、CI 流水线步骤）时，要验证它们是否一致。仓库之间的差异是“在仓库 A 中有效，在仓库 B 中却出问题”的最常见原因。
4. 共享依赖契约。 仓库共享库、API 或数据格式时，要验证生产方和消费方对契约的理解是否一致。检查各仓库之间的版本兼容性。

样板代码提取（不可妥协）： 5. 将常见模式提取为样板。 当 2 个或更多仓库包含相同的配置、脚本、CI 流水线或项目结构时，这就是提取样板的候选项。共享模式应放在样板仓库中，并同步到依赖它的仓库，而不是复制粘贴。标记每个实例并建议提取。 6. 使现有副本保持一致。 如果已有样板仓库，请确认依赖它的仓库始终与其保持一致。样板与依赖仓库之间的偏差属于待发现问题——要么回移更改，要么记录依赖仓库为何存在差异。没有合理依据的差异 = 过时副本。 7. 最大限度提高组件间的相似性。 即使无法实际将所有内容提取到样板中，承担相似职责的仓库（例如，多个微服务、多个技能仓库）也应尽可能相似：使用相同的目录结构、相同形态的 CI 配置、相同版本的工具、相同的 pre-commit 钩子。无谓的差异会增加认知负担，并掩盖真正重要的差异。

接口接缝验证：

8. 验证接口接缝处的契约。 当一个技能生成的输出由另一个技能（或代码）使用时，请验证生产方的输出格式是否符合消费方预期的输入。在每个交接点追踪完整生命周期。
9. 命名一致性。 在范围内的所有技能和代码仓库中，搜索关键术语（分支名称、CLI 命令、函数名称、状态标签）。同一概念使用不同名称 = 过时引用。

覆盖与路由验证（不可妥协）：

10. 验证方法覆盖契约。 对于 overlay/plugin 架构，列出 overlay 在组合类（OverlayMetadata、OverlayConfig 等）上定义的每个方法，并验证对应的基类中都存在同名方法。子类中存在而基类中不存在的方法，要么是新的扩展（应在基类中声明），要么是失效的覆盖（会悄然变成死代码）。具体检查：grep -n 'def ' overlay/*.py | grep -v '__' → 对每个方法，验证其名称是否出现在基类中。批量重命名（例如，MR→PR）是导致覆盖悄然失效的首要原因。
11. 技能提取后的路由完整性。 对于 skills/ 中的每个技能，验证它都有可供加载的路径：(a) 它出现在 Python 代码中的至少一个关键词映射或路由表（_AGENT_TASK_KEYWORDS、_PHASE_TO_SKILL）中；(b) agents/*.md 中的一个 Agent 定义在其 skills: frontmatter 中列出了它；(c) 它的触发关键词不会与另一个技能的关键词冲突，除非有明确的优先级胜出者。没有路由路径的技能无法被访问。尤其是在从另一个技能中提取技能后，这项检查至关重要——必须在同一更改中更新路由基础设施。

1.7：静默的质量检测（不可妥协）

查找被手动抑制的代码质量信号——降低覆盖率阈值、# noqa 抑制、从 pre-commit 中排除文件、放宽 per-file-ignores、缺少钩子、配套技能违规。完整清单见 references/review-phases.md § 3.14。

---

阶段 2–4 — 内容、技术与质量审查

完整检查清单请参阅 references/review-phases.md。概要：

• 阶段 2 — 内容审查： 重复内容与分歧副本、简洁性、自给自足与知识放置、跨仓库记忆扫描、技能 ↔ 仓库配置边界、信息边界、知识整合、交叉引用、不写死路径、护栏分类、多层重叠。
• 阶段 3 — 技术审查： 脚本语言与约定、提交前钩子、跨仓库基础设施、脚本验证、钩子脚本、代码质量与简化、注释比例（每条新增注释占一行 — 见规则 16；只报告，不设门槛）、将插件/覆盖层平台封装提升为核心后端、安全审查、优先选择 CLI 还是 MCP、单一 CLI 入口、子 Agent 安全性、测试覆盖率、非确定性行为的行为评估覆盖（建议但不强制 — 见规则 13 和 references/ai-eval-review.md）、优先上游、CLI 结构与命名一致性（所有仓库中的命令、参数、退出代码、文件层级保持一致）、文档时效性、因子化、被抑制的质量信号、最精简的可配置与可插拔接口（§ 3.17 — 变更新增的设置或扩展点，是否采用了足以表达差异的最窄形式？）。
• 阶段 4 — 质量审查： 生产级标准、归属说明、Agent 无关性、注重细节、格式一致性、技能编写最佳实践。

---

阶段 A — 代码库评估

确定性指标 + LLM 架构判断。完整方法请参阅 references/codebase-assessment.md。

概要：

1. 通过 scripts/cli.py assess 运行确定性指标。 收集：ruff 违规、测试覆盖率缺口、圈复杂度、TODO/FIXME 数量、依赖过时情况、lint 抑制项。解读每个计数时都要结合其范围：lint、复杂度、抑制项、TODO 和覆盖率均先按第一方与供应方拆分；lint 和抑制项还会按规则代码进一步拆分；抑制项还会按是否指定规则名称，以及标记覆盖一行还是整个文件进一步拆分。供应方总数不代表本仓库存在问题，而占主导的一种规则代码代表一种约定，不是广泛存在的技术债。如果 ruff 配置为跳过某个目录树，那么基于该目录树得出的 ruff 计数属于缺少测量，而非一切正常——报告会将其标记为 not linted。此外，还会通过手动检查 git ls-files，获取轻量的文件层级信号（根目录文件数、每个目录的文件数、最大树深度、超大模块、混合无关文件类型的目录）——见 references/codebase-assessment.md 第 1 部分。
2. 架构判断（由 LLM 驱动）：命名一致性、关注点分离、抽象质量、模块边界、耦合分析、文件层级与模块组织（内聚性/范围、文件放置不当、根目录杂乱、上帝模块、__init__ 接口、测试镜像源代码——给出具体的 from -> to 移动方案；见 references/codebase-assessment.md § 2h）、关于代码的说明文字（注释比例和文档时效性 — § 2i；只报告，不设门槛）、重复与因子化（脚本/模块/仓库之间重复的逻辑，以及两个仓库以不同方式编码的相同约定 — § 2j）。
3. 输出： 三项评分（整洁度、可维护性、架构，各为 1–10 分）+ 按影响/工作量/受影响文件排序的改进清单。
4. 行动项优先，评分次之。 没有人会根据“架构得分为 6”采取行动。他们会根据“从视图层提取支付逻辑（高影响、中等工作量、涉及 4 个文件）”采取行动。

---

阶段 5 — 计划与实施

5.1 变更计划

将阶段 1–4 + A 的所有发现汇总为结构化变更计划，按仓库和类型分组。

对于计划修改文件而非直接修复的问题（任务中明确排除的过于庞大或设计有歧义的问题），每个根本原因单独创建一个工单，绝不合并成一个大型问题。工单需包含 file:line、预期与实际情况，以及问题违反的规则或评估标准。接手该问题的会话不应需要重新推导原因。

5.2 逐步澄清（不可妥协）

对没有歧义的项目，明确表示“将处理”。对于有歧义的项目，一次只问一个问题。绝不要一次抛出一大串问题。

5.3 实施

• **编辑每个文件前检查归属（不可妥协）：**解析真实路径，并与 MAINTAINED_SKILLS 核对。不匹配时先询问。
• 实施所有已批准的变更。每完成一组逻辑相关的修改后，简要总结。

---

阶段 6 — 回归与交付

6.1–6.5：回归审查

提交、更深入的检查、提交前验证、最终提交、完成定义。详见 references/review-phases.md。

“完成”意味着在相同范围内重新运行此审查，不会发现任何新问题。

在整个审查被报告为完成、但实际只覆盖一小部分范围的期间，这句话一直存在于此文件中。这证明仅有完成定义并不能充当门槛。可执行的做法是：**review-verify 以 0 退出。**请在撰写任何完成消息之前运行它。如果退出码非 0，则审查尚未完成——请完成列出的问题，或如实报告检查清单的状态为部分完成。

6.6：合并自己的提交

交付前，将与审查相关的提交合并为清晰、规模适中的提交单元。规范规则详见 references/repo-management.md § Squash & Prepare。

6.7：交付状态与推送

对所有受管理的仓库运行交付状态检查，并询问是否继续推送。详见 references/repo-management.md § Delivery Status。

6.8：回顾与迭代

如果有可用的回顾技能，则运行该技能以记录元层面的改进。如果用户要求迭代，则返回阶段 1。

---

仓库管理工作流

这些工作流既可独立调用，也可作为完整审查的一部分调用。完整详情请阅读 references/repo-management.md。

工作流	用途
交付状态	快速概览所有受管理仓库中尚未推送的提交、脏文件、分支和储藏
合并并准备	将相关的未推送提交合并为清晰的单元。合并规则的规范来源。
基础设施审计	比较并统一各仓库中的 .pre-commit-config.yaml、pyproject.toml、.editorconfig
样板代码回移植	将样板仓库中的变更传播到依赖仓库
架构健康检查	依赖项审计、跨仓库代码分析、技术栈审查、整合建议

---

技能编写最佳实践

审查技能文件时，请依据 references/skill-authoring-best-practices.md 进行评估。该文档整合了 Anthropic 的官方规范和社区建议。