Agent Skills
返回列表
💻

代码库架构深化

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/sammcj-agentic-coding-improve-codebase-architecture。

技能介绍

背景:浅层模块比「坏设计」更隐蔽

许多团队卡在测试难写、改一处牵一片、AI 辅助读代码总要跳几十个文件——根因往往不是缺分层,而是模块太浅:接口几乎和实现一样复杂,没有真正的 seam(接缝),复杂度散在调用方之间。本技能用统一术语(见 LANGUAGE.md 的 Module / Interface / Depth / Locality 等)把这类架构摩擦说清楚,并只推动「加深」类重构,而不是泛泛谈整洁代码。

技能如何工作

流程分三段:

  1. Explore:先按 YAGNI 定范围(用户指定模块/痛点,或从近 20 次提交热区入手),读领域 glossary 与 ADR,再用只读子代理扫库,记录:理解一个概念要跨多少小模块、删除测试(删掉模块后复杂度是消失还是摊到 N 个 caller)、测试只测了纯函数但 bug 在调用编排里(缺 locality)、接缝渗漏等。
  2. Present:在系统临时目录写自包含 architecture-review-*.html(Tailwind + Mermaid),每张候选卡片含涉及文件、问题、方案、locality/leverage 收益、前后对比图、推荐强度(Strong / Worth exploring / Speculative),并给出 Top recommendation;术语对齐 CONTEXT.md 与 ADR,冲突 ADR 仅在摩擦足够大时标注。
  3. 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 的架构守护者