improve-codebase-architecture

改进代码库架构

找出那些难以理解或修改的代码：调用方必须协调本应归属同一处的细节。提出能隐藏这些细节、让行为更易测试的模块。

如果用户已经选定候选项或具体的目标改动，就检查该目标并直接开始探索。不要再列出候选项让用户选择，也不要要求用户重复选择。如果用户仍在询问哪项改动最有帮助，也可以用具名子系统限定发现范围。

此命令以项目的领域模型为依据，并采用共享的设计词汇：

• 如果有 codebase-design 技能，请参考其中关于深模块原则、调用方契约和接缝合理性的深入说明。结合既有的产品和仓库词汇，运用其中的架构区分。评估接口隐藏了什么、调用方获得了什么；仅凭适配器数量，既不能证明也不能否定某个接缝是否合理。
• 项目的词汇表为良好的接缝命名；其 ADR 记录已确定的决策。除非摩擦足以重新审议该决策，否则不要提出会推翻决策的改动（参见下文 ADR 冲突）。遵循现有文档位置，不要假定使用 CONTEXT.md 和 docs/adr/。

在可用技能目录中按名称查找配套技能，并使用目录提供的位置或加载机制。如果某项技能不可用，请继续执行此处的流程；不要猜测其安装路径，也不要获取外部指南。

流程

1. 探索

深化模块的价值在于让今后修改它更容易，因此应重点关注代码库中经常变动的部分。先选择区域，再阅读代码：

• 如果用户指定了方向（某个模块、子系统或痛点），就按此方向探索，并跳过以下推断步骤。
• 否则，利用近期提交历史找出变动最频繁的文件，例如 git log --since='6 months ago' --name-only --format='' | sort | uniq -c | sort -rn | head，从反复变动、可能意味着维护成本较高的部分入手。只有在证据或用户要求的覆盖范围需要时，才扩大范围。

首先阅读所涉及区域已有的领域词汇表和 ADR。

直接探索限定范围内的区域。如果可以委派，且独立调查能在开展有价值的本地工作的同时提升证据质量或节省时间，就委派一项范围明确、只读的任务。向 Agent 说明要调查的问题、目标模块或路径、已知要求和约束，以及预期结果：具体代码位置或调用方追踪、它们体现的维护成本、可行的改进方向，以及任何不确定之处。如果无法委派，或委派帮助不大，就在本地继续。

在代码中寻找有证据支持的摩擦：

• 理解一个概念是否需要在许多小模块之间来回切换？
• 是否存在浅模块，其接口几乎和实现一样复杂？
• 是否有纯函数仅为便于测试而被提取出来，导致真正的 bug 隐藏在测试从未覆盖的调用方中？
• 紧密耦合的模块是否跨越接缝泄漏细节？
• 代码库中有哪些部分未经测试，或难以通过现有接口进行测试？

建议移除某个模块之前，先确认这不会导致不必要的转发，也不会让调用方不得不自行处理该模块原本承担的工作。展示发现之前，先依据代码核实委派结果。当你能说明所请求区域中的具体成本和有用的改进，或指出仍缺少哪些事实时，就停止探索。没有值得推荐的候选项，也是有效结果。

2. 以实用的格式呈现发现

遵循指定的格式和环境实际支持的渲染能力。对于精简的评审，在宿主环境支持渲染时，使用简洁的文字并配以内嵌图示。对于便于移植的报告，或适合单独成篇的比较，使用 HTML。如果无法进行可视化渲染，应以文字说明各项关系并指出这一限制，而不是因此中止分析。

在图示有助于说明归属、依赖关系、调用方所需投入或拟议改动时使用图示。结构差异重要时，适合使用前后对比图；不要为了充实报告而虚构多个候选方案或图示类型。酌情使用宿主环境支持的 Mermaid 渲染、内嵌 SVG 或简单的 HTML/CSS。

对于每个候选方案，提供足以进行判断的证据：

• 证据：相关文件、符号和调用方追踪
• 问题：具体的摩擦点及其后果
• 解决方案：用通俗文字描述将发生的变化
• 收益：为调用方和维护者带来的具体改善；如有影响，也包括可测试性
• 权衡：哪些方面会变得更困难，以及必须保留哪些契约
• 结构对比：通过图示或简洁说明，阐明调用方和维护者之后需要了解什么
• 建议强度与不确定性：证据对该改动的支持程度，以及仍未验证的事项

如果用户要求进行探索，请推荐证据最充分的候选方案。对于已选定的目标，说明证据是否支持该改动，并继续探讨其设计问题。凡是单靠图示无法传达契约或权衡之处，都应辅以简洁的说明性文字。

对领域概念使用项目的术语表，并保留 "Order service" 等既有名称。如果区分很重要，应说明这些名称与正在讨论的架构角色之间的对应关系。

ADR 冲突：如果候选方案与现有 ADR 冲突，只有当摩擦确实严重到值得重新审视 ADR 时，才提及该冲突。报告中应说明冲突以及重新审议该决定的证据。不要列出 ADR 所禁止的所有理论上的重构方案。

仅在要生成 HTML 成品时阅读 HTML-REPORT.md。如果环境允许，应检查渲染后的报告并说明任何渲染方面的不足；生成文件并不代表其中的图示清晰易读。

对于仅要求探索的请求，提交发现结果后即停止。如果用户还要求进一步探索，而仍有多个实质上不同的候选方案，应先呈现证据，再询问用户要深入探索哪一个。如果目标已经明确，则无需暂停等待用户选择，直接继续。

3. 探索选定的改动

结合调用方、约束、依赖和现有测试，为选定的候选方案提供依据。如果已有明确结论可复用，且证据充分支持具体的接口或迁移建议，就直接给出建议。如果有尚未解决且影响重大的选择，并且 grilling 技能可用，请使用该技能；否则直接针对这些选择提出聚焦的问题。如果不需要人的决策，就不要强行进行访谈。

如果 domain-modeling 技能可用，请使用它来确保含义和记录保持一致。遵循现有文档惯例和获准的工作模式：只有在获准更新文档时才进行写入；对于只读或讨论类工作，将建议文本保留在对话中。

• 是否要用新的领域概念为一个扩展后的模块命名？ 将双方认可的定义记录到现有术语表中，或在讨论模式下提出词条。
• 是否已消除某个术语上的重大歧义？ 含义明确后，更新或提出定义；无伤大雅的措辞差异无需新建记录。
• 用户因某个未来评审需要了解的理由而拒绝提案？ 提出将该理由记录到 ADR 中，以免后续评审在不了解背景的情况下重复提出该方案。跳过“现在不值得”这类临时理由，以及代码或文档中已清楚说明的理由。
• 想探索扩展后模块的其他接口方案？ 如果 codebase-design 技能可用，请遵循其中的替代接口比较指南。否则，针对相同的调用方需求、受保护的契约和迁移约束，比较具体的接口方案。适用且可用时，请使用并行 Agent。

最后给出所需的发现或设计建议、依据、保留的契约，以及仍需进行的验证或决策。实施、提交或对外发布均须获得相应授权；仅选择候选方案并不代表已获授权。