代码库架构深化
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/sammcj-agentic-coding-improve-codebase-architecture。
技能介绍
背景:浅层模块比「坏设计」更隐蔽
许多团队卡在测试难写、改一处牵一片、AI 辅助读代码总要跳几十个文件——根因往往不是缺分层,而是模块太浅:接口几乎和实现一样复杂,没有真正的 seam(接缝),复杂度散在调用方之间。本技能用统一术语(见 LANGUAGE.md 的 Module / Interface / Depth / Locality 等)把这类架构摩擦说清楚,并只推动「加深」类重构,而不是泛泛谈整洁代码。
技能如何工作
流程分三段:
- Explore:先按 YAGNI 定范围(用户指定模块/痛点,或从近 20 次提交热区入手),读领域 glossary 与 ADR,再用只读子代理扫库,记录:理解一个概念要跨多少小模块、删除测试(删掉模块后复杂度是消失还是摊到 N 个 caller)、测试只测了纯函数但 bug 在调用编排里(缺 locality)、接缝渗漏等。
- Present:在系统临时目录写自包含
architecture-review-*.html(Tailwind + Mermaid),每张候选卡片含涉及文件、问题、方案、locality/leverage 收益、前后对比图、推荐强度(Strong / Worth exploring / Speculative),并给出 Top recommendation;术语对齐CONTEXT.md与 ADR,冲突 ADR 仅在摩擦足够大时标注。 - Grilling:用户选定候选后进入追问对话, crystallize 决策时可增量更新
CONTEXT.md、在拒绝理由承载架构决策时提议写 ADR;接口细节走INTERFACE-DESIGN.md,此阶段不先手撕接口设计。
适用边界
- 适合已有一定规模、变更频繁、且存在领域文档或 ADR 习惯的项目;纯脚本堆或无人碰的代码 deepen 可能 YAGNI。
- 报告 intentionally 不落库,避免污染仓库;需要你本地能打开临时 HTML。
- 它是架构评审与决策陪练,不替代你跑测试或落地大块重构的体力活。
使用场景
- 老模块接口臃肿、单测只能 mock 一整条调用链,想用删除测试筛出值得加深的浅层模块
- 近期同一批文件在 git 里反复改动,需要先出一份带前后对比图的架构候选清单再排优先级
- 领域里有 Order 等业务词但代码里全是 Handler 命名,评审报告希望对齐 CONTEXT.md 再谈接缝
- 候选方案和 ADR-0007 之类决策冲突,但线上摩擦明显,需要在 HTML 报告里标出是否值得重开 ADR
适合人员
- 维护中型单体或模块化单体、每周都要在几块热区改逻辑的后端/全栈工程师
- Tech Lead 要在不改代码的前提下先和团队对齐「先 deepen 哪一块」并留存 ADR 决策
- 引入 Claude Code 等代理读库的同事,希望模块接口更短、代理少在碎片文件间跳转
- 已有 LANGUAGE/CONTEXT 文档纪律、愿意在 grilling 阶段顺手补 glossary 或 ADR 的架构守护者