Reference · User-invoked · Codebase health

improve-codebase-architecture 速查

架构体检扫描仪的口袋版。完整教学见 Lesson 0017； 原文见 SKILL.md、 HTML-REPORT.md。

一句话

扫代码库找 deepening opportunity（浅模块加深的候选）→ 写一份临时目录里的 HTML 报告 → 你挑一张卡片 → 面试着把决定落进 CONTEXT.md / ADR。 只体检，不动刀：不碰业务代码，重构交回主流程。

启动方式

人输入 /improve-codebase-architecture。AI 不会自取： disable-model-invocation: true + agents/openai.yaml 的 allow_implicit_invocation: false。

何时用 / 何时不用

• 用：每隔几天的定期保养；「懂一个概念要跳很多小文件」；diagnosing-bugs 复盘移交（没有好接缝锁 bug）；triage 分拣出架构债
• 不用：已知要改哪个模块、只要词汇 → codebase-design（扫描仪 vs 工作台）；新想法 → grill-with-docs

三步流程卡

1. Explore：先定范围（YAGNI）——用户指方向就用方向；否则 git log --oneline 找热点（最近常改的路径优先），太散就放宽。先读 CONTEXT.md + 相关 ADR。派 Explore 子代理有机地走，记摩擦（跳文件、浅模块、为测试抽的纯函数、跨 seam 泄漏、不可测）。可疑浅模块套删除测试：「会集中」才算数。
2. HTML report：写 <$TMPDIR|/tmp|%TEMP%>/architecture-review-<timestamp>.html，open/xdg-open/start 打开。Tailwind + Mermaid 走 CDN，混手绘 SVG。禁止此时设计接口。写完停下问：「Which of these would you like to explore?」
3. Grilling loop：对选中候选跑 /grilling（约束、依赖、形状、seam 后藏什么、哪些测试活下来），边面试边跑 /domain-modeling 落字。

报告卡片规格

• 字段：Files · Problem · Solution · Benefits（locality/leverage + 测试怎么变好）· Before/After 图 · 强度徽章
• 徽章：Strong（emerald）/ Worth exploring（amber）/ Speculative（slate）；另加依赖类别标签：in-process · local-substitutable · ports & adapters · mock
• 结尾必有 Top recommendation；图承重不写段落——「图要段落才懂就重画」
• 用词：CONTEXT.md 领域词 + codebase-design 架构词；禁 component/service/API/boundary；ADR 冲突只有值得重开才标注

面试的四条落字分支

会改什么（副作用矩阵）

依赖 / 被依赖

• 拉进来：codebase-design（词汇 + design-it-twice）、grilling（面试）、domain-modeling（落字）、Explore 子代理
• 被拉：diagnosing-bugs（复盘移交）、triage（架构债）、ask-matt（Codebase health 路由）

下一步

• 面试完 → 想法进主流程：to-spec → to-tickets → implement(+tdd)
• design-it-twice 后 → 接口决定进 spec / ADR（不可逆时）
• 否决落 ADR → 下次扫描自动回避该候选
• 一张没挑 → 关报告即可，仓库零变化

微调入口（症状 → 改哪）