AGENT SKILL

improve-codebase-architecture

扫描代码库中的深化机会,以可视化 HTML 报告呈现,然后针对你选中的机会深入追问。

License 许可
MIT
最近更新
2026-07-23
Stars
★ 1
Forks
0

01 前言 Front Matter

name
improve-codebase-architecture
description
扫描代码库中的深化机会,以可视化 HTML 报告呈现,然后针对你选中的机会深入追问。
disable-model-invocation
true

02 资源文件 2

03 SKILL.md 正文

改进代码库架构

找出架构摩擦并提出深化机会——将浅模块转变为深模块的重构。目标是提高可测试性和 AI 可导航性。

此命令以项目领域模型为 依据,并建立在共享设计词汇之上:

  • 运行 /codebase-design 技能,获取架构词汇(模块、接口、深度、接缝、适配器、杠杆效应、局部性)及其原则(删除测试、“接口就是测试表面”、“一个适配器 = 假想接缝,两个适配器 = 真实接缝”)。每项建议都必须准确使用这些术语——不要偏移到“component”“service”“API”或“boundary”。
  • CONTEXT.md 中的领域语言为良好接缝命名;docs/adr/ 中的 ADR 记录本命令不应重新争论的决策。

流程

1. 探索

扫描前先确定范围——YAGNI。 深化模块的价值在于让未来对它的修改更容易,因此要格外关注代码库中最近发生变更的部分。先决定要看哪里,再开始查看:

  • 如果用户指定了方向——某个模块、子系统或痛点——就按该方向处理,跳过下面的推断。
  • 否则,沿提交历史向前查看足够长的一段(git log --oneline),找出代码库的热点——反复出现的文件和区域——并优先让这些路径引导你的注意力。如果变更分散、没有明显热点,则扩大范围。

首先阅读项目领域术语表(CONTEXT.md)以及所涉及区域的所有 ADR。

然后使用 Agent 工具并设置 subagent_type=Explore,遍历代码库。不要遵循僵化的启发式规则——自然地探索,并记录你在何处遇到摩擦:

  • 在哪里,理解一个概念需要在许多小模块之间反复跳转?
  • 哪些模块很浅——接口几乎与实现一样复杂?
  • 哪些地方仅为可测试性提取了纯函数,但真正的缺陷却隐藏在调用方式中(缺少局部性)?
  • 哪些紧密耦合的模块存在跨接缝泄漏?
  • 代码库中的哪些部分未经测试,或难以通过当前接口测试?

对任何疑似浅模块应用删除测试:删除它会集中复杂性,还是只会转移复杂性?“是,会集中”正是你要寻找的信号。

2. 以 HTML 报告呈现候选项

将自包含 HTML 文件写入操作系统临时目录,避免任何内容进入仓库。从 $TMPDIR 解析临时目录,无法解析时回退到 /tmp(Windows 上为 %TEMP%),并写入 <tmpdir>/architecture-review-<timestamp>.html,确保每次运行都会获得新文件。为用户打开该文件——Linux 使用 xdg-open <path>,macOS 使用 open <path>,Windows 使用 start <path>——并告知绝对路径。

报告通过 CDN 中的 Tailwind 实现布局和样式,并在图/流程/时序能够可靠传达结构时,通过 CDN 中的 Mermaid 绘制图表。将 Mermaid 与手工编写的 CSS/SVG 视觉元素混用——当关系呈图结构(调用图、依赖关系、时序)时使用 Mermaid;需要更具编辑设计感的效果(体量图、剖面图、收拢动画)时使用手工 div/SVG。每个候选项都要有之前/之后的可视化。务必以视觉呈现。

为每个候选项渲染一张卡片,其中包含:

  • 文件——涉及哪些文件/模块
  • 问题——当前架构为何造成摩擦
  • 解决方案——用平实中文描述将发生的变更
  • 收益——用局部性和杠杆效应解释,并说明测试将如何改进
  • 之前/之后图——并排、定制绘制,展示浅薄结构和深化结果
  • 推荐强度——强烈推荐、值得探索、推测性 三者之一,以徽章呈现

报告最后以首选建议章节收尾:你会优先处理哪个候选项,以及原因。

领域方面使用 CONTEXT.md 词汇,架构方面使用 /codebase-design 词汇。 如果 CONTEXT.md 定义了“Order”,就讨论“Order 接收模块”——而不是“FooBarHandler”,也不是“Order 服务”。

ADR 冲突:如果候选项与现有 ADR 冲突,只有当摩擦真实到足以重新审视 ADR 时才将其提出。在卡片中明确标记(例如警告提示:“与 ADR-0007 冲突——但值得重新讨论,因为……”)。不要列出 ADR 所禁止的每一种理论重构。

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

此时不得提出接口。文件写完后询问用户:“你想探索其中哪一个?”

3. 深度追问循环

用户选定候选项后,运行 /grilling 技能,与用户一起遍历设计树——约束、依赖、深化后模块的形态、接缝后面的内容,以及哪些测试能够保留。

决策逐渐明确时,要就地产生相应副作用——运行 /domain-modeling 技能,在推进过程中保持领域模型最新:

  • 以 CONTEXT.md 中不存在的概念命名深化后的模块? 将该术语添加到 CONTEXT.md。如果文件不存在,则延迟创建。
  • 在对话中推敲含糊术语? 就地更新 CONTEXT.md。
  • 用户因不可或缺的原因拒绝候选项? 提议创建 ADR,表述为:“需要我把这项决策记录为 ADR,避免未来的架构审查再次提出它吗?” 只有当未来的探索者确实需要该原因才能避免重复建议时才提议——跳过临时原因(“现在不值得做”)和不言自明的原因。
  • 想探索深化后模块的备选接口? 运行 /codebase-design 技能,并使用其中“设计两次”的并行子智能体模式。

04 同仓库更多 Skills