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
- 参考文档agents/openai.yaml157 B
- 参考文档HTML-REPORT.md6.7 KB
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
writing-great-skills
出色编写和编辑技能的参考资料——让技能具备可预测性的词汇与原则。
teach
在此工作区内向用户教授新的技能或概念。
handoff
将当前对话压缩成交接文档,以便另一个智能体接手。
grilling
围绕计划、决策或想法对用户进行不留情面的深度追问。当用户想对自己的思路进行压力测试,或使用任何“深度追问”触发措辞时使用。
grill-me
通过不留情面的深度追问打磨计划或设计。
obsidian-vault
使用 wikilink 和索引笔记搜索、创建和管理 Obsidian 仓库中的笔记。当用户想要在 Obsidian 中查找、创建或整理笔记时使用。