improve-codebase-architecture

改进代码库架构

找出架构摩擦，并提出加深机会——将浅模块重构为深模块。目标是提升可测试性和 AI 导航能力。

适用场景

• 用户用英语请求或提到此技能（例如：“use /improve-codebase-architecture”“run improve-codebase-architecture”）。
• 用户用葡萄牙语请求或提到此技能（例如：“use /improve-codebase-architecture”“execute improve-codebase-architecture”）。

术语表

每条建议都要准确使用这些术语。保持用语一致是关键——不要改用“组件”“服务”“API”或“边界”。完整定义见 LANGUAGE.md。

• 模块 — 任何具有接口和实现的东西（函数、类、包、代码片段）。
• 接口 — 调用方使用模块必须了解的一切：类型、不变量、错误模式、顺序、配置。不只是类型签名。
• 实现 — 内部代码。
• 深度 — 接口带来的杠杆效应：在小接口后封装大量行为。深 = 杠杆效应高。浅 = 接口几乎和实现一样复杂。
• 接缝 — 接口所在之处；无需就地编辑即可改变行为的位置。（使用此术语，不要用“边界”。）
• 适配器 — 在接缝处满足接口的具体实现。
• 杠杆效应 — 调用方从深度中获得的收益。
• 局部性 — 维护者从深度中获得的收益：将变更、Bug 和知识集中在一处。

关键原则（完整列表见 LANGUAGE.md）：

• 删除测试：设想删除该模块。如果复杂性消失，它就是传递层。如果复杂性在 N 个调用方之间重新出现，那它就发挥了应有的作用。
• 接口就是测试面。
• 一个适配器 = 假设的接缝。两个适配器 = 真实的接缝。

此技能_以_项目领域模型为指导。.claude/CONTEXT.md 中的领域语言和 .claude/MEMORY.md 中的跨会话上下文为良好的接缝命名；docs/architecture/ 中已批准的架构决策记录了此技能不应重新讨论的约束。

流程

1. 探索

首先阅读项目领域术语表（.claude/CONTEXT.md）、跨会话记忆（.claude/MEMORY.md），以及 docs/architecture/ 中涉及相关领域的已批准架构决策（如果项目仍在使用 docs/adr/，则阅读其中的决策）。

然后启动一个只读探索子 Agent，遍历代码库。不要遵循僵化的启发式规则——以自然的方式探索，并记录你遇到的摩擦：

• 理解一个概念是否需要在许多小模块之间来回跳转？
• 哪些模块是浅的——接口几乎和实现一样复杂？
• 是否有纯函数只是为了可测试性而被提取出来，但真正的 Bug 隐藏在调用方式中（缺乏局部性）？
• 紧密耦合的模块是否会越过接缝泄漏？
• 代码库中哪些部分没有测试，或难以通过当前接口进行测试？

对任何怀疑较浅的模块应用删除测试：删除它会让复杂性集中起来，还是只会把复杂性转移走？如果答案是“会集中起来”，这就是你要找的信号。

2. 将候选方案呈现为 HTML 报告

将一个独立的 HTML 文件写入操作系统的临时目录，确保仓库中不会留下任何文件。根据 $TMPDIR 确定临时目录，若未设置则回退到 /tmp（Windows 上为 %TEMP%），并写入 <tmpdir>/architecture-review-<timestamp>.html，确保每次运行都会生成新文件。为用户打开该文件——Linux 上使用 xdg-open <path>，macOS 上使用 open <path>，Windows 上使用 start <path>——并告知用户绝对路径。

报告使用 Tailwind CDN 进行布局和样式设计；当图表能可靠地传达结构时，使用 Mermaid CDN 绘制图表。将 Mermaid 与手工制作的 CSS/SVG 视觉效果结合起来——关系呈图形结构时（调用图、依赖关系、序列）使用 Mermaid；想要更具编辑感的呈现方式时（质量图、剖面图、折叠动画）则使用手工制作的 div/SVG。每个候选方案都要有改造前/改造后的可视化。注重视觉效果。

每个候选方案都采用与之前相同的模板，但以卡片形式呈现：

• 文件——涉及哪些文件/模块
• 问题——当前架构为何造成阻碍
• 解决方案——用通俗语言描述需要做哪些改变
• 收益——从局部性和杠杆作用的角度说明收益，以及测试将如何改进
• 改造前/改造后图示——并排绘制自定义图示，展现浅层结构及其深化后的形态
• 建议力度——取值为 Strong、Worth exploring、Speculative 之一，并以徽章形式呈现

报告末尾添加 首选建议 部分：说明你会先处理哪个候选方案，以及原因。

领域术语使用 .claude/CONTEXT.md 中的词汇，架构术语使用 LANGUAGE.md 中的词汇。 如果 .claude/CONTEXT.md 定义了“Order”，就使用“Order 接单模块”来描述——而不是“FooBarHandler”或“Order 服务”。

决策冲突：如果某个候选方案与现有已批准的 SPEC SDD 或架构决策相矛盾，只有在实际摩擦足以值得重新审议该决策时才提出。请在卡片中明确标出（例如，使用警告提示框：“与 SPEC-20260908-order-intake 相矛盾，但值得重新审议，因为……”）。不要列出记录在案的决策所禁止的所有理论性重构方案。

完整的 HTML 脚手架、图示模式和样式指南请参见 HTML-REPORT.md。

暂时不要提出接口。写完文件后，用葡萄牙语询问用户：

Relatorio salvo em [CAMINHO_ABSOLUTO].

Qual dessas oportunidades voce quer explorar primeiro?

➡️ Meu palpite: comecamos pelo [NOME_CANDIDATO_TOP1].

3. 讨论循环

用户选定一个候选方案后，进入深入讨论。与用户一起梳理设计树——约束、依赖关系、深化后模块的形态、接口背后包含的内容，以及哪些测试会保留。

随着决策逐步明确，在讨论过程中同步处理副作用：

• 将深化后的模块命名为 .claude/CONTEXT.md 中未定义的概念？ 将该术语添加到 .claude/CONTEXT.md——遵循与 /write-specs 相同的规范。如果文件不存在，则按需创建。
• 在讨论中明确含糊的术语？ 立即更新 .claude/CONTEXT.md。
• 用户基于关键理由否决候选方案？ 使用 SPEC SDD 模板，让 plan 子 Agent（或 /write-specs）在 .specs/SPEC-{YYYYMMDD}-{slug}.md 中编写一份 SPEC SDD，并用葡萄牙语提出：“Quer que eu registre isso como um SPEC em .specs/ para revisoes futuras nao sugerirem a mesma coisa?” 仅当该理由确实能帮助未来的探索者避免再次提出同一建议时才提出；对于暂时不值得做等临时性理由，以及不言自明的理由，则跳过。
• 想要探索深化后模块的其他接口方案？ 请参见 INTERFACE-DESIGN.md。