codebase-improver

Codebase Improver

将代码库从“我觉得有问题”推进到“问题已梳理、排定优先级并修复”——端到端进行，并在每个关口由人类掌控。

改进引擎基于深模块（John Ousterhout，《A Philosophy of Software Design》）：深模块具有小型接口，隐藏大型实现。深模块更易测试，更便于 AI 导航，也让你能够在边界处而非内部进行测试。深化阶段的目标是将浅层、紧密耦合的集群转变为深模块。

此技能独立自包含（Python/TS）；默认情况下，工作角色以内联方式运行，也可以使用明确授权的委派。

Map ──► Audit ──► Deepen (recursive) ──► (next round)
 │        │          │
scan    audit      explore → candidates → design N interfaces
        roles      → RFC → optionally implement → recurse

---

主机可移植性

如果没有委派权限，请以内联串行方式运行每个工作角色；这不需要调用任何 AgentTool。在选择不同工作角色之前，请应用运行默认设置。不要声称内联角色彼此独立或并行；如果隔离对用户请求的结果至关重要，请说明无法提供隔离。

---

核心原则

1. **独立自包含。**映射以内联方式进行；检查和约定位于内置的 references/ 中。不需要其他技能。
2. **蓝图是加分项，而非必需项。**如果存在 BLUEPRINT.md，请将其用作更有力的锚点；否则依靠轻量扫描和内置检查。
3. **目标是深模块。**改进意味着深化：缩小接口、隐藏复杂性、在边界处测试。阅读代码时遇到的阻力就是信号。
4. **组合工作角色；仅在有权限时委派。**主 Agent 负责安排工作流、汇总结果、运行检查点并管理有状态决策。请求的工作角色须遵守用户授权的委派范围；否则，相同角色以内联方式运行。
5. **每个关口都有人参与。**绝不自行决定范围、要处理哪个候选项、采用哪个接口、是否递归，或是否提交/推送。暂停并询问。本技能从设计上就采用 HITL——不同于无人值守的自动驾驶模式，它不会捏造需要由人类把关的决定。
6. **证据胜于断言。**每项发现都要引用真实的 path:line。
7. **递归有界且受控。**绝不自动递归。每深入一层，都需要用户明确同意，并设有默认深度上限（参见“递归控制”）。
8. **尊重有意作出的决定。**在 CLAUDE.md、决策规范或蓝图中记录的选择不属于发现。
9. **简明胜于简短。**目标是清晰，而非行数。当转换能让代码更易读（显式而非取巧、使用有名的中间步骤、扁平而非嵌套）时，即使增加行数也应优先采用。这适用于模块内部的实现；模块接口仍应保持精简。行为必须保持不变，并通过测试加以证明；不得为了增加行数而填充代码。参见 references/simplify-playbook.md。
10. **实现采用测试驱动，并经过质量循环。**代码变更须经过 TDD + 审查 + QA 循环（先写测试 → 实现 → 审查 → 修复 → 模拟 QA → 修复 → 重复，直至通过；有次数上限）。参见 references/quality-loop.md。

---

阶段 1 — 映射

使用选定的执行模式，通过只读映射角色了解仓库结构。

1. **检测技术栈。**目标为 Python 和 TypeScript（清单文件：pyproject.toml/requirements.txt/setup.py；package.json/tsconfig.json）。两者都不符合 → 说明情况并停止。两者都符合 → 将其视为各自独立的项目。
2. 轻量结构扫描：

   find . -maxdepth 2 -type f \( -name 'pyproject.toml' -o -name 'requirements.txt' \
     -o -name 'setup.py' -o -name 'package.json' -o -name 'tsconfig.json' \) \
     -not -path '*/node_modules/*' -not -path '*/.venv/*'
   tree -L 3 -I 'node_modules|.venv|venv|dist|build|.next|__pycache__' 2>/dev/null || \
     find . -maxdepth 3 -type d -not -path '*/node_modules/*' -not -path '*/.venv/*' | sort
   

   记录项目根目录、可能的分层结构和重复出现的文件夹模式。
3. **按需查看蓝图。**如果存在 BLUEPRINT.md（.claude/…、docs/…），请阅读以获取更有力的锚点。如果不存在，继续进行——不要因此停下。
4. （可选）为大模型打包上下文：如果用户需要单文件快照，可使用 repomix / tree -L 3。

---

阶段 2 — 审计（整个仓库）

主 Agent 根据所选执行模式，组合只读审计角色。目录：

• references/universal-checks.md — 与语言无关的反模式。
• references/audit-catalog.md — Python/TS 健康信号 + 检测命令。
• references/audit-worker.md — 每个审计角色都必须遵循的约定。

1. 划分范围：根据阶段 1 的扫描结果，将仓库划分为不同范围：每个重要模块（局部检查）分配一个每子树工作器，另分配一个跨领域工作器（重复代码、清单依赖方向、过时依赖、整个仓库的机密信息）。每个模块约 1 个工作器；小型仓库分配 2–4 个。
2. 运行每个工作器。 内联角色按顺序运行；明确授权的委派可以并发运行。每个工作器都要获得其范围、目录、蓝图路径和临时输出路径。工作器只能只读。
3. 汇总（主 Agent）：合并片段，去重重复的 path:line，分配 ID，按严重性排序。
4. **执行模式：**无论采用哪种模式，都使用相同的划分和输出格式；记录实际隔离情况。

呈现问题清单：

ID	问题	证据（path:line）	类别	锚点	严重性

⏸ 检查点 A（始终执行）：

“审计发现 N 个问题：X 个阻塞项、Y 个应修复项、Z 个小问题。在我寻找可深化的机会之前，请先审核一下？你认为其中哪些是有意为之或不在范围内？”

该清单会提供给深化阶段：它会将探索引向摩擦较大的区域。默认仅临时保留；只有在用户要求时，才保存至 docs/audit/findings-<YYYY-MM-DD>.md。

---

阶段 3 — 深化（递归）

此阶段将取代扁平的“先规划再执行”模式。它会运行深度模块流程，然后以以下三种形式递归。每个处理的候选项都算作一次深化轮次；轮次可以嵌套。

3.1 探索深化机会

在所选执行模式下运行一个探索角色，让其像 AI 一样有机地探索代码库，而不是依赖僵化的启发式规则，并以审计问题为起点。记录遇到的摩擦：

• 理解一个概念需要在许多小文件之间来回跳转。
• 某个模块过于浅薄，其接口几乎和实现一样复杂。
• 提取纯函数只是为了便于测试，但真正的 bug 隐藏在调用方式中。
• 紧密耦合的模块在衔接处造成集成风险。
• 未经测试或难以测试的部分。

摩擦本身就是信号。

3.2 呈现候选项

以编号列表列出深化机会。每项包括：

• 关联范围 — 涉及哪些模块/概念。
• 耦合原因 — 共享类型、调用模式、共同拥有的概念。
• 依赖类别 — references/deep-module-reference.md 中的四类之一。
• 测试影响 — 哪些现有测试会由边界测试取代。

暂勿提出接口。

⏸ 检查点 B： “你想探索其中哪些机会？”

3.3 梳理问题空间

针对选定的候选项，撰写面向用户的说明：任何新接口都必须满足哪些约束、必须依赖哪些依赖项，以及一段用于具体说明这些约束的大致示例代码（仅作示意，不是方案）。展示说明后，立即继续执行 3.4——用户可以在设计轮次运行时思考。

3.4 设计多个接口

默认串行内联运行 3 个以上设计角色（参见 references/interface-designer.md）； 只有获得明确授权的不同工作者才能并发运行。每个角色都在不同约束下设计一个截然不同的接口：

• Agent 1：尽量精简接口——最多 1–3 个入口。
• Agent 2：尽量提高灵活性——支持多种用例和扩展点。
• Agent 3：针对最常见的调用方进行优化——让默认情况简单易用。
• Agent 4（如果依赖跨越边界）：端口与适配器。

每个设计都应提供：接口签名、用法示例、隐藏的复杂性、依赖策略和权衡。

依次展示这些设计，用文字进行比较，然后给出你自己明确的推荐意见——指出设计最有力之处及其原因；如果某些元素能很好地组合，也可以推荐混合方案。用户希望得到明确的判断，而不是一份选项清单。

**⏸ 检查点 C：**用户选择一个接口，或接受推荐方案。

3.5 整理为 RFC

使用 references/deep-module-reference.md 中的模板，在 docs/ 中创建重构 RFC Markdown 文件。不要征求预先审查意见——直接创建并告知文件路径。

3.6（可选）实施 — TDD + QA 质量循环

深层模块工作流按设计止步于 RFC。如果用户希望现在就实施，运行 references/quality-loop.md 中的质量循环。该循环采用测试驱动开发，组合工作者角色，并反复执行审查→修复→QA→修复，直到没有问题（有迭代上限）。主 Agent 负责协调，并把控 git/HITL 检查关卡。

⏸ 检查点 D（任何代码更改之前）："现在要在分支上实现这份 RFC，还是暂时将其保留为 RFC？（如果要实现：我会采用 TDD——先写测试——然后实施、审查并模拟 QA，循环直到没有问题。）"

用户同意后，按以下顺序执行：

1. 创建分支 git switch -c improve/<rfc-slug>（确认；未经明确许可，绝不推送或创建 PR）。
2. **先写测试（红灯）。**测试编写角色根据 RFC 的验收标准和保留行为编写边界测试；运行这些测试以明确目标。
3. **实施（绿灯）。**实施者角色逐步让测试通过，并应用 references/simplify-playbook.md。
4. **审查。**按照 references/review-rubric.md 运行正确性和可维护性审查角色；合并并去重审查结果。
5. **QA 计划 + 模拟。**运行 QA 计划和 QA 模拟角色；保留通过/失败/跳过的证据。
6. **修复并循环。**阻塞性发现或 QA 失败 → 修复角色处理问题 → 返回第 4 步。最多执行 MAX_QUALITY_ITERATIONS 次（默认为 3 次），然后报告“需要人工处理”。
7. 报告更改内容、测试、审查与 QA 状态，以及 path:line。

循环会运行至完成后再报告——不会在循环中途提示用户，但也绝不会捏造决定：任何确实需要人工处理的情况（依赖受阻、行为变更含糊不清）都会中止该分支并予以标记，遵循原则 5。

配置（默认值，可用普通语言覆盖）

• MAX_QUALITY_ITERATIONS = 3 — 将审查→修复→QA 循环执行至此次数后，标记为“需要人工处理”。
• REVIEW_BLOCKING_SEVERITY = high — 仅达到或超过此严重级别的发现会阻塞；较低级别的发现会记录，但不会阻塞。
• GIT_STRATEGY = branch — 创建分支并提交；只有获得明确许可后才创建 PR/推送；绝不自动合并。

3.7 递归——三种形式，每种都需确认

每轮完成后，询问用户下一步怎么做。绝不自动递归。

• 分解（向下）。 如果选定的候选项太大，无法作为一个整体深入分析，就将其拆分为若干子部分，并对每个子部分执行 3.1–3.6。子部分沿用父项的分析框架。
• 重新探索（深入）。 重构完成后，重新执行 3.1，范围限定在改动区域——深入一个模块往往会暴露其下一个层次的摩擦点。简化检查（对改动的代码应用 references/simplify-playbook.md）也是一种有效的轻量形式。
• 重新审计（向外）。 选定的候选项处理完毕后，可以选择重新执行 Stage 2，以找出整个代码库中的下一轮问题，然后返回此处。

⏸ 检查点 E（每轮之后）：

“本轮完成。要递归吗？(a) 进一步分解此候选项，(b) 重新探索刚才改动的区域，(c) 重新审计整个代码库，寻找下一轮问题，还是 (d) 到此为止？”

---

递归控制

递归功能强大，也很容易失控，因此需要设限：

• 默认深度上限 = 3 个嵌套层级（一轮内再进行一轮，后者又再进行一轮）。若要继续深入，请明确询问：“我们已经深入 3 层了。还要继续吗？”
• 始终需要确认。 每次进入更深层级之前，都必须先通过检查点 E。不得静默地继续。
• 追踪调用栈。 简短地展示当前位置，例如 payments → refund flow → idempotency key，确保用户始终清楚进展脉络。
• 收益递减时停止。 如果某个层级只发现细枝末节的问题，应如实说明，并建议停止，而不是为了递归而递归。

---

文件存放位置

产物	位置	时机
问题清单	默认放在聊天中；如有要求，则保存到 docs/audit/findings-<YYYY-MM-DD>.md	Stage 2
重构 RFC	docs/<rfc-slug>.md	Stage 3.5
QA 测试计划	docs/qa/test-plan-<branch>.md	Stage 3.6，在实施时
代码变更	在分支 improve/<rfc-slug> 上直接编辑	Stage 3.6
Repomix 快照（可选）	仓库根目录下的 repomix-output.xml	Stage 1，如有要求
BLUEPRINT.md	仅在文件存在时读取——此技能绝不会创建该文件	Stage 1

审计、探索和设计角色应将中间片段写入临时工作区，而非仓库。只有 RFC 和（如有要求）保存的问题清单会放入 docs/。绝不在仓库外写入文件；未经询问，绝不覆盖当天已有的文件。

---

停止并询问检查点摘要

#	检查点	时机
A	审查问题清单	Stage 2 结束时，始终执行
B	选择要探索的候选项	Stage 3.2，始终执行
C	选择接口设计	Stage 3.4，始终执行
D	立即实施还是仅编写 RFC	Stage 3.6，在任何代码变更之前
E	递归还是停止	每轮之后，始终执行
—	分支 / 提交 / 推送	即将产生任何 git 副作用时

遇到真正模糊不清的情况时，随时暂停询问。绝不擅自替人做决定。

---

此技能不会做什么

• 它不依赖任何其他技能——映射、检查和设计契约均已打包其中。
• 在用户选择候选项之前，它不会提出接口；在用户批准之前，它不会实施。
• 它不会自行递归、静默地超过深度上限，也不会进行大规模重写。
• 未经逐项明确批准，它不会推送分支、创建 PR 或提交更改。

---

另请参阅

• references/deep-module-reference.md — 四类依赖项 + RFC 模板。
• references/simplify-playbook.md — 以清晰易懂为先的转换（更简单，即使更长；保留行为）。
• references/interface-designer.md — 接口设计角色的契约。
• references/quality-loop.md — TDD + 审查 + QA 实施循环（由多个角色组成，有上限）。
• references/review-rubric.md — 正确性（偏重召回）+ 可维护性（极其严格）审查标准。
• references/qa-test-plan.md — 手动端到端 QA 计划流程 + 格式。
• references/audit-worker.md — 审计角色的契约。
• references/universal-checks.md — 与语言无关的反模式目录。
• references/audit-catalog.md — Python/TS 健康信号 + 检测命令。