codebase-tidy

Codebase Tidy：一波功能之后收拢架构

仅在用户显式调用 $codebase-tidy 时运行。适用场景：一个分支或一段时间里聚合了大量来回拉扯的改动，需要把项目重新收拢到“架构意图成立、关键行为有测试锁住、下一位接手者能读懂”的状态。单项高风险重构（共享组件、数据访问、跨语言替换）在本流程内按 $safe-refactor 执行，测试的判定与增删按 $test-audit 执行；只想复盘一次会话用 $distill。

整理是 tidy，不是重写：每一步都小、可单独验证、可单独回滚，行为除有意修正外保持不变。

0. 项目事实

先从 AGENTS.md、docs/、ADR、CI 和脚本里查，查不到的才问用户；用户在调用时给出的约定优先。

事实	用途
整理范围：起点（上次整理标记、tag 或 merge-base）到聚合分支	盘点只看这段变更及其波及面
架构意图：核心 / 插件 / 壳层等边界和依赖方向	判断“漂移”的基准
兼容边界：哪些接口可破坏（同仓内部、开发阶段），哪些必须兼容（外部或商业消费者、已发布 SDK、持久化格式）	决定重构能动到哪
分支策略：聚合分支、feature / fix 分支、重构分支	决定修改落在哪
部署与 smoke：聚合环境的部署命令和脚本化 smoke	每步收尾验证

首次运行把查到或问到的事实写进项目的权威文档（缺少架构说明时，从代码反推一份并列入待审查），之后的整理直接读，不再重复询问。

1. 盘点

产出一份发现清单，每项带 file:line、类别、工作量（S/M/L）、风险（低/中/高）和一行修复方向。类别：

• 架构漂移：违反依赖方向、职责放错层、命名空间与位置不符。
• 遗留与死代码：已决定废弃的功能仍在、无引用的类型与成员、只为旧路径存在的开关和配置。
• 重复：同一规则或映射散在多处，加一个字段要改 N 处。
• 巨型类：多职责混在一起，列出职责、共享状态和拆分后的协作者。
• 无效测试：按 $test-audit 的垃圾模式和保留标准逐条判定（保留 / 修断言 / 合并 / 删除），每条附证据。
• 文档漂移：文档与代码或已定决策冲突，逐条给出处。
• 回归缺口：近期功能里行为重要、容易被后续改坏、却没有测试锁住的部分。

完成标准：范围内每个改动区域都看过，发现都经 rg 或读代码核实；不确定的标为待验证。仓库大时按区域派只读子 Agent 并行盘点，由主 Agent 汇总和复核。

2. 先锁行为

对盘点出的回归缺口，在整理会触及的区域动手前补测试。选测试的层级按“行为在哪被观察”：

• 对外契约（HTTP / IPC / CLI / SDK）用 API 级测试；
• 关键用户路径用端到端或浏览器自动化；
• 纯规则与计算用单元测试。

新测试过 $test-audit 的编写门禁：能说出它防的是哪种改坏，并在故意破坏实现时变红。兼容边界上的接口必须有测试锁住。删除无效测试前，先确认它覆盖的契约已有更强的测试兜底。

3. 分步整理

推荐顺序：删遗留与死代码 → 纠正文档漂移 → 合并重复、建立单一事实源 → 拆巨型类 → 修正架构漂移。先做低风险高收益的，后面的步骤在更干净的基础上进行。

每一步：

1. 改动聚焦一个主题，单独提交（大主题拆成多个可独立验证的提交）。
2. 构建、全量测试通过；有意的行为修正在提交说明里写明。
3. 合入聚合分支后执行第 4 节的部署 smoke，通过后再开始下一步。

分支落点：已合入聚合分支的 feature / fix 本身有漏洞，直接在原分支修；独立的重构从聚合分支拉新分支做。

拿不准的决定（架构调整、兼容边界附近的改动、删除看似无用但无法完全证实的代码）先按最合理的方案做完，记入待审查清单，不停下等确认。

4. 每步部署 smoke

每完成一步，部署聚合分支到集成环境，运行脚本化 smoke。失败时先修复或回滚这一步，再继续。项目没有可用的部署或 smoke 脚本时，在报告里写明缺口，并把“补一个 smoke 脚本”列入发现清单。

5. 教训沉淀为规则

把这一轮看到的问题归成三类：

• 不应该犯的错：明确违背了已有约定或常识；
• 验证不足：问题本可被测试、lint 或 smoke 抓住；
• 以后想避免的模式：不算错，但持续制造维护成本。

每条教训落到能自动执行的最强形式：lint / analyzer 规则、架构测试（如依赖方向测试）、CI 检查、脚本 > 文档规则。文档规则写进唯一权威位置，同时清理已过时或重复的旧规则。