改进代码库架构

工程开发 社区

技能解读

设计思路

improve-codebase-architecture 是 mattpocock 的「架构改进」skill——用《A Philosophy of Software Design》里的「deep / shallow module」这把尺子,找出当前代码库里浅 + 漏的接口,提议加深它们。skill 的灵魂是 grilling loop——选定候选后并不直接动手,而是和用户一起拷问设计树,让候选在对话中成形。

Glossary(按作者原文)

  • Locality:彼此调用得很近的代码应该住得很近——降低跳转成本。
  • Deletion test:怀疑某个模块「shallow」时问:删掉它是把复杂度集中了,还是只是搬家了?「集中」就是好信号——这正是我们想加深的对象。

流程

1. 寻找候选 扫代码库找:

  • 哪些重复模式调用方式各异(缺 locality)
  • 紧耦合模块在哪些 seam 漏出去
  • 哪些部分没测试 / 通过当前接口很难测

对怀疑「shallow」的部分跑 deletion test,回答「集中」就是候选。

2. 呈现候选(编号列表) 每条候选给:

  • Files 涉及哪些文件 / 模块
  • Problem 为什么当前架构在制造摩擦
  • Solution 改成什么样(白话)
  • Benefits 用 locality / leverage 解释、说测试如何变好

用 CONTEXT.md 的领域词汇 + LANGUAGE.md 的架构词汇——CONTEXT.md 里定义了「Order」就说「Order intake 模块」,不要叫「FooBarHandler」也不要叫「Order service」。

ADR 冲突处理:候选与现有 ADR 冲突时,只在摩擦真实到值得 reopen ADR 时才提;并明确标注「contradicts ADR-0007 — but worth reopening because…」。不要列出 ADR 禁止的所有理论 refactor。

关键纪律:还不要提议接口形状——先问用户:「想探索哪一项?」

3. Grilling Loop 用户选定候选后,进入拷问对话——和他一起遍历设计树:约束、依赖、加深后的模块形状、缝隙后藏什么、哪些测试存活。

对话中即时副作用:

  • 加深的模块用了 CONTEXT.md 没有的概念 → 当场加进去(同 grill-with-docs 纪律)
  • 用户用了模糊词 → 当场把它沉淀进 CONTEXT.md
  • 用户拒绝候选并给出 load-bearing 理由 → 提议建 ADR:「Want me to record this as an ADR so future architecture reviews don't re-suggest it?」仅当理由对未来探索者有用时才提;临时性理由("not worth it right now")和不证自明的不要提。
  • 探索接口形状 → 跳到 INTERFACE-DESIGN.md

适合谁

  • 重构准备阶段的资深工程师
  • 想用「集中复杂度而非搬家复杂度」标准做架构判断的 Tech Lead
  • 准备做 deep / shallow 评估的代码 review 时机

不适合

  • 项目早期、形状没定——加深动作过早
  • 简单 bug fix——不到架构层

配套

grill-with-docs(同源的拷问 + CONTEXT 纪律)、design-an-interface(接口形状探索)、request-refactor-plan(提出重构 plan)、diagnose(Phase 5/6 暴露架构问题时的上一步)。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@mattpocock · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Improve Codebase Architecture

Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

This command is _informed_ by the project's domain model and built on a shared design vocabulary:

- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.

## Process

### 1. Explore

**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:

- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.

Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.

Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:

- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow**, with an interface nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
- Where do tightly-coupled modules leak across their seams?
- Which parts of the codebase are untested, or hard to test through their current interface?

Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

### 2. Present candidates as an HTML report

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.

The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.

For each candidate, render a card with:

- **Files**: which files/modules are involved
- **Problem**: why the current architecture is causing friction
- **Solution**: plain English description of what would change
- **Benefits**: explained in terms of locality and leverage, and how tests would improve
- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge

End the report with a **Top recommendation** section: which candidate you'd tackle first and why.

**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."

**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.

See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.

Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"

### 3. Grilling loop

Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.

Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:

- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。