使用 improve-codebase-architecture 技能扫描代码库、生成可视化架构审查报告并完成重构纵深探讨

使用 improve-codebase-architecture 技能扫描代码库、生成可视化架构审查报告并完成重构纵深探讨【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills本篇文章全面解析当前仓库skills13/skills中的improve-codebase-architecture技能Agent Skill它如何以深模块deep module为架构理想态通过三阶段流程——探索代码库发现加深机会 → 生成自包含的可视化 HTML 报告 → 针对选定候选做多轮探讨grilling——把浅层模块shallow modules重构成深层模块最终目标是把代码库变得可测试testability且对 AI 可导航AI-navigability。读完本文你将掌握该技能的完整工作流、HTML 报告的制作规范含 Mermaid 与手绘 SVG 的混合绘图模式、以及它与codebase-design、domain-modeling、grilling等兄弟技能如何协同可直接在你的仓库中落地这套架构审查流程。一、技能定位从修修补补到系统性加深在 skills/engineering/improve-codebase-architecture/SKILL.md 的开头技能明确了自己的使命Surface architectural friction and proposedeepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.也就是说它不关心零散的代码风格问题而是聚焦于架构摩擦architectural friction找出那些接口和实现几乎一样复杂的浅层模块并提出将它们加深deepening的重构机会。这里的底层设计词汇并非该技能自创而是由一个共享词汇表支撑调用 Skill 工具加载codebase-design获取架构词汇module、interface、depth、seam、adapter、leverage、locality及其原则删除测试、接口即测试面、一个适配器 假设性接缝两个 真实接缝。技能要求在所有建议中严格使用这些术语不得漂移到 component、service、API、boundary 等词汇。项目的CONTEXT.md领域术语表为好的接缝提供命名docs/adr/中的 ADR架构决策记录记录的是本技能不应重新争论的既有决策。为什么统一的词汇如此重要在 skills/engineering/codebase-design/SKILL.md 中这套词汇被定义为全仓库的共享语言其一致性本身就是重点Consistent language is the whole point术语精确定义避免替换Module任何拥有接口与实现的东西刻意保持尺度无关函数、类、包、跨层切片unit、component、serviceInterface调用方为正确使用模块而必须知道的一切类型签名、不变式、排序约束、错误模式、所需配置、性能特征API、signature过窄只指类型层面Implementation模块内部的东西、其代码主体——Depth接口处的杠杆leverage调用方或测试每学习一单位接口所能行使的行为量。接口小而实现多的模块是深的接口和实现几乎一样复杂的是浅的——SeamMichael Feathers在不直接编辑该处的情况下改变行为的地方模块接口所在的位置。接缝放哪里本身就是独立的设计决策boundary与 DDD 的限界上下文重载冲突Adapter在接缝处满足接口的具体东西描述的是角色它填补哪个槽位而非实质内部是什么——Leverage调用方从深度中获得的东西每学习一单位接口获得更多能力一份实现回报 N 个调用点与 M 个测试——Locality维护者从深度中获得的东西变更、缺陷、知识、验证集中在一处而非分散到调用方一次修复处处生效——codebase-design还用两个直观的 ASCII 图展示了深/浅模块的对比深模块 小接口 大量实现 浅模块 大接口 少量实现 ┌─────────────────────┐ ┌─────────────────────────────────┐ │ Small Interface │ ← 少数方法、简单参数 │ Large Interface │ ← 很多方法、复杂参数 ├─────────────────────┤ ├─────────────────────────────────┤ │ Deep Implementation│ ← 复杂逻辑被隐藏 │ Thin Implementation │ ← 仅仅透传 └─────────────────────┘ └─────────────────────────────────┘improve-codebase-architecture正是把这份词汇当作探测仪在扫描代码库时凡是出现接口几乎与实现一样复杂的地方就是候选的浅层模块。二、Process 全流程总览整个架构审查过程分为三个明确的阶段每个阶段产出一个可验证的中间结果阶段做什么产出物1. Explore先定范围YAGNI、读领域术语、派子代理漫游代码库、记录摩擦点、应用删除测试候选加深机会candidates清单2. Present candidates as an HTML report写一个自包含的 HTML 报告到系统临时目录并打开给用户看每个候选渲染成卡片tmpdir/architecture-review-timestamp.html3. Grilling loop用户选定一个候选后用grilling技能走决策树过程中用domain-modeling技能维护领域模型已敲定的加深方案 更新的CONTEXT.md/ 新增 ADR下文按这三个阶段逐一展开。三、阶段一Explore——先定范围再有机探索3.1 扫描之前先定范围YAGNI技能的开篇告诫非常直接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. Decidewhereto look before you look.加深一个模块的回报在于让未来对它的修改更容易因此要优先关注最近频繁变动的部分。具体的定范围策略如果用户点名了方向某个模块、子系统或痛点直接采用跳过下面的推断否则往回翻一段 commit 历史git log --oneline找出代码库的热点hot spots——那些反复出现的文件和区域让这些路径先吸引你的注意力。如果变更零散、没有明确热点就扩大搜索范围。这种先决定往哪里看再去看的顺序避免了被代码库的随机细节牵着走。3.2 先读领域材料再派子代理定好范围后先阅读项目领域术语表CONTEXT.md以及所涉区域的任何 ADRdocs/adr/。这一步保证后面的探索不会违背已经记录的架构决策。然后派一个子代理去漫游代码库。技能特别强调不要遵循僵硬的启发式规则而要有机地探索并在探索过程中记录你感受到的摩擦点理解一个概念需要在小模块之间反复跳转的地方在哪里即概念散布问题哪些模块是浅的——接口几乎和实现一样复杂哪些纯函数只是为了可测试性被抽取出来但真正的 bug 却藏在它们的调用方式里没有 locality哪些紧耦合的模块跨越接缝泄漏代码库的哪些部分没有测试或很难通过当前接口测试3.3 删除测试the deletion test——判断浅的试金石对任何你怀疑是浅层的模块应用删除测试Would deleting it concentrate complexity, or just move it? A yes, concentrates is the signal you want.如果删除后复杂度消失了 → 它只是个透传pass-through是浅层模块如果删除后复杂度在 N 个调用方身上重新出现→ 它在赚自己的存在价值deep。codebase-design的原文把这条原则表述为The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. 当你对某个候选得到是的删除会让复杂度集中起来说明它有价值但接口太浅需要加深的信号时就找到了想要的候选。四、阶段二把候选呈现为 HTML 报告探索阶段找到的候选必须以可视化 HTML 报告的形式呈现。完整规范见 skills/engineering/improve-codebase-architecture/HTML-REPORT.md。4.1 输出位置与打开方式写一个自包含self-contained的 HTML 文件到操作系统临时目录保证什么都不落进仓库从$TMPDIR解析临时目录回退到/tmpWindows 上是%TEMP%文件名带时间戳tmpdir/architecture-review-timestamp.html保证每次运行都是全新文件打开它给用户看Linux 用xdg-open pathmacOS 用open pathWindows 用start path并告知绝对路径。4.2 技术选型Tailwind Mermaid 双 CDN混合手绘视觉报告通过 CDN 引入 Tailwind做布局与样式通过 CDN 引入 Mermaid绘制图/流程/时序类图表。技能的关键提醒是两者要混用——Mermaid 负责图结构的关系调用图、依赖图、时序图手写的 div 与内联 SVG 负责编辑型的视觉质量图 mass diagrams、横截面、折叠动画。不要全部交给 Mermaid否则报告会显得千篇一律。完整的 HTML 骨架scaffold如下来自 HTML-REPORT.md!doctype html html langen head meta charsetutf-8 / titleArchitecture review for {{repo name}}/title script srchttps://cdn.tailwindcss.com/script script typemodule import mermaid from https://cdn.jsdelivr.net/npm/mermaid11/dist/mermaid.esm.min.mjs; mermaid.initialize({ startOnLoad: true, theme: neutral, securityLevel: loose }); /script style /* small custom layer for things Tailwind doesnt cover cleanly: dashed seam lines, hand-drawn-feeling arrow heads, etc. */ .seam { stroke-dasharray: 4 4; } .leak { stroke: #dc2626; } .deep { background: linear-gradient(135deg, #0f172a, #1e293b); } /style /head body classbg-stone-50 text-slate-900 font-sans main classmax-w-5xl mx-auto px-6 py-12 space-y-12 header.../header section idcandidates classspace-y-10.../section section idtop-recommendation.../section /main /body /html注意这里的几个细节Mermaid 以ESM module方式从jsdelivr引入mermaid11的.esm.min.mjs并初始化startOnLoad: true、theme: neutral、securityLevel: loose自定义 CSS 层只处理 Tailwind 覆盖不好的东西虚线接缝线.seam、红色泄漏箭头.leak、深模块的深色渐变.deep唯一的脚本就是 Tailwind CDN 与 Mermaid ESM 引入报告其余部分保持静态无应用代码、除 Mermaid 自身渲染外无交互。4.3 Header紧凑图例直接进入候选报告头部包含仓库名、日期、一段紧凑图例实线框 模块、虚线 接缝、红色箭头 泄漏、粗深色框 深模块。不需要介绍段落直接进入候选区。4.4 候选卡片Candidate card规范图表承担主要表达任务文字保持稀疏、平实并且使用词汇表中的术语不做任何修饰without ceremony。每个候选是一个article包含元素说明Title简短直接命名这个加深动作例如 Collapse the Order intake pipeline折叠订单入口管道Badge row推荐强度徽章Strong 翡翠绿 emeraldWorth exploring 琥珀色 amberSpeculative 石板灰 slate外加依赖类别标签in-process、local-substitutable、ports adapters、mockFiles涉及的文件的等宽字体列表font-mono text-smBefore / After diagram中心内容两列并排的自绘示意图说明浅层与加深后的对比模式见下文Problem一句话现在伤在哪里Solution一句话会改变什么Wins要点列表每条 ≤ 6 个词例如 Tests hit one interface、Pricing logic stops leaking、Delete 4 shallow wrappersADR callout如适用琥珀色框中一行提示技能对文字的要求极其严格不写解释性段落——If the diagram needs a paragraph to be understood, redraw the diagram如果图表需要一段话来解释那就重画图表。4.5 五种图表模式Diagram patterns报告要视觉化Be visual但每种候选要选最贴切的模式并且混用——不要每张图都长得一样多样性本身就是目的。模式 1Mermaid graph依赖/调用流的主力当要点是X 调 Y 调 Z看看这团乱麻时用 Mermaidflowchart或graph。用 Tailwind 卡片包裹用classDef把泄漏边染红、把深模块染深。时序图适合表达before: 6 次往返; after: 1 次。div classrounded-lg border border-slate-200 bg-white p-4 pre classmermaid flowchart LR A[OrderHandler] -- B[OrderValidator] B -- C[OrderRepo] C -.leak.- D[PricingClient] classDef leak stroke:#dc2626,stroke-width:2px; class C,D leak /pre /div模式 2手绘 boxes-and-arrows当 Mermaid 的布局跟你作对时模块用带边框和标签的div箭头用定位在相对容器上的内联 SVGline或path。当你想让 after 图呈现一个粗边框深模块、内部灰化的效果时用它因为 Mermaid 渲染不出这种重量感。模式 3横截面Cross-section适合分层浅层性用堆叠的水平色带h-12 border-l-4展示一次调用要穿过的层。Before6 个薄层各自啥也不干After1 条粗色带标注合并后的职责。模式 4质量图Mass diagram适合接口和实现一样宽每个模块画两个矩形一个表示接口表面积一个表示实现。Before接口矩形几乎和实现矩形一样高浅After接口矩形变矮、实现矩形变高深。这是把深度这一抽象概念变成一眼可读的直观视觉。模式 5调用图折叠Call-graph collapseBefore函数调用树渲染成嵌套方框After整棵树折叠进一个方框现在已内部的调用以淡色显示在框内。4.6 风格指南Style guidance编辑风格而非仪表盘风格留白充足标题可用衬线体font-serif与 stone/slate 配色搭配得很好克制用色一个强调色emerald 或 indigo加红色泄漏、琥珀色警告图表高度保持约320px让 before/after 可以舒服地并排而不滚动图内模块标签用text-xs uppercase tracking-wider让它读起来像示意图而非 UI报告其余部分静态见 4.2。4.7 Top recommendation 区块报告以Top recommendation收尾一张更大的卡片写明哪个候选应该最先处理、为什么并给出指向该候选卡片的锚点链接。它帮助用户或 AI 代理避免选择困难直接获得一个带理由的起点。4.8 领域词汇与 ADR 冲突的处理报告写作有两条硬性纪律领域用CONTEXT.md的词汇架构用/codebase-design的词汇。例如如果CONTEXT.md定义了 Order就谈论 the Order intake module订单入口模块而不是 the FooBarHandler也不是 the Order service。ADR 冲突如果某个候选与既有 ADR 矛盾只有当摩擦真实到值得重新审视该 ADR 时才呈现它并在卡片里清楚标记例如警告提示框contradicts ADR-0007, but worth reopening because…。不要列出 ADR 禁止的每一个理论性重构。报告写完、文件落盘后不要立即提出接口方案——技能明确要求停下来问用户Which of these would you like to explore?你想探索哪一个五、阶段三Grilling loop——选定候选后的深入探讨用户选定候选后进入多轮探讨循环。5.1 用grilling走决策树调用 Skill 工具加载grilling技能与用户一起走决策树约束条件、依赖关系、加深后模块的形状、接缝后面是什么、哪些测试能存活下来。grilling技能的机制见 skills/productivity/grilling/SKILL.md是把这个过程建模为一棵设计树design tree每个决策都分支为挂在它下面的后续决策。按**轮次rounds**工作前沿frontier 前置条件已满足、现在就能问的决策集合一轮问完整个前沿给每个问题编号并给出你的推荐答案然后等用户回答再进入下一轮用户的回答重塑设计树已定决策把前沿向外推解锁依赖它们的后续问题。依赖于本轮其他未决问题的题属于更晚的轮次查找事实是你的工作、永远不是用户的前沿问题需要环境事实文件系统、工具等时派子代理去查而不是问用户任何你自己能查到的东西且不要因此阻塞——正在运行的探索是一个未定的前置条件只有它下游的问题要等其余前沿问题现在就可以问会话在前沿为空时结束设计树的每个分支都被访问过没有东西被悄悄假设。决策是用户的把每个决策交给用户并等待。在用户确认达成共识之前不要行动。5.2 边敲定边维护领域模型domain-modeling随着决策逐步结晶副作用要即时发生调用domain-modeling技能让领域模型保持最新。技能原文给出了四个具体触发器给一个CONTEXT.md里没有的概念命名了一个加深后的模块把该术语加进CONTEXT.md文件不存在就懒创建。对话中澄清了一个模糊术语就地更新CONTEXT.md。用户用一个有分量的理由拒绝了该候选提议记一条 ADR措辞是Want me to record this as an ADR so future architecture reviews dont re-suggest it?要不要我把它记成一条 ADR这样未来的架构审查就不会再建议它。只在该理由确实是未来探索者避免重复建议所必需时才提议跳过短暂性理由现在不值得和显而易见的理由。想为加深后的模块探索替代接口调用codebase-design使用其design-it-twice并行子代理模式。5.3 加深候选的依赖分类来自 DEEPENING.md在探讨接缝后面是什么、怎么测时skills/engineering/codebase-design/DEEPENING.md 提供了判断加深策略的关键框架——按依赖类别分类类别决定加深后的模块如何跨接缝测试类别定义加深策略与测试方式1. In-process纯计算、内存态、无 I/O总是可加深合并模块直接通过新接口测试。无需适配器2. Local-substitutable有本地测试替身的依赖Postgres 的 PGLite、内存文件系统若有替身则可加深。用测试套件中的替身测试加深后的模块接缝是内部的外部接口无端口3. Remote but ownedPorts Adapters你自己跨网络边界的服务微服务、内部 API在接缝处定义端口port。深模块拥有逻辑传输层作为注入的适配器。测试用内存适配器生产用 HTTP/gRPC/队列适配器4. True externalMock你无法控制的第三方服务Stripe、Twilio 等加深后的模块把外部依赖作为注入端口接收测试提供 mock 适配器推荐的措辞形态针对第 3 类是Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though its deployed across a network.5.4 接缝纪律与替换而非分层的测试策略接缝纪律有两条硬规则一个适配器意味着假设性接缝两个适配器意味着真实接缝。除非至少有两个适配器有正当理由通常是生产 测试否则不要引入端口。单适配器的接缝只是间接层。内部接缝 vs 外部接缝。深模块可以有内部接缝实现私有、供自身测试使用也可以有外部接缝在接口处。不要仅仅因为测试用内部接缝就把它们暴露到接口上。测试策略替换不要分层replace, dont layer一旦深模块接口处的测试存在浅模块上的旧单元测试就变成浪费删除它们在加深后模块的接口处写新测试——接口就是测试面the interface is the test surface测试断言的是通过接口可观察的结果而非内部状态测试应能在内部重构后存活因为它们描述行为而非实现。如果测试在实现变化时必须跟着变说明它在测试接口之外的东西。5.5 探索替代接口Design It Twice 并行子代理当用户想为加深后的模块探索多种替代接口时codebase-design提供design-it-twice模式见 skills/engineering/codebase-design/DESIGN-IT-TWICE.md其思想来自 Ousterhout你的第一个想法不太可能是最好的。Step 1 — 框定问题空间写出面向用户的候选问题空间说明新接口必须满足的约束、依赖及其类别、一段粗糙的示意代码——只是让约束具体化不是提案展示给用户后立刻进入 Step 2用户阅读思考的同时子代理并行工作。Step 2 — 派生 3 并行子代理每个必须产出截然不同的接口Agent 1Minimize the interface: aim for 1–3 entry points max. Maximise leverage per entry point.最小化接口最多 1–3 个入口点最大化每个入口点的杠杆。Agent 2Maximise flexibility: support many use cases and extension.最大化灵活性支持大量用例与扩展。Agent 3Optimise for the most common caller: make the default case trivial.为最常见的调用方优化让默认场景变得微不足道。Agent 4如适用Design around ports adapters for cross-seam dependencies.围绕端口与适配器设计跨接缝依赖。每个子代理都要在简报中同时包含codebase-design词汇与CONTEXT.md词汇保证命名一致。每个子代理输出接口类型、方法、参数 不变式、排序、错误模式、调用方使用示例、实现隐藏在接缝后的内容、依赖策略与适配器、权衡杠杆高在哪、薄在哪。Step 3 — 呈现与对比按顺序逐一呈现设计让用户吸收然后用文字对比从深度接口处的杠杆、locality变更集中在哪里、接缝位置三个维度比较。最后给出你自己的推荐哪个设计最强、为什么若可融合则提出混合方案。要有主见the user wants a strong read, not a menu.六、整套技能的仓库落地与上下文improve-codebase-architecture是skills13/skills仓库中 engineering 技能集 的一员被列为User-invoked用户主动调用——其 frontmatter 中disable-model-invocation: true即模型不会隐式调用只有用户显式触发对应 Claude Code 的开关在 Codex 侧对应agents/openai.yaml中的policy.allow_implicit_invocation: false本技能的 agents/openai.yaml 即此配置。它与兄弟技能的分工一目了然codebase-design提供架构词汇与深模块原则本技能的语言层其 DEEPENING.md 与 DESIGN-IT-TWICE.md 分别支撑加深策略与替代接口探索grilling决策树式的多轮追问本技能的探讨引擎domain-modeling维护CONTEXT.md与 ADR本技能的记忆层其格式规范见 CONTEXT-FORMAT.md 与 ADR-FORMAT.md。关于CONTEXT.md与 ADR 的落地位置仓库内也能找到真实范例domain-modeling技能定义的标准结构是仓库根目录CONTEXT.md单上下文多上下文时用CONTEXT-MAP.mdADRs 存于docs/adr/采用顺序编号0001-slug.md、0002-slug.md目录在第一条 ADR 需要时才懒创建在本仓库中领域词汇表见根目录的 CONTEXT.md例如定义了Issue tracker、Issue、Decision ticket、Triage role等术语及其Avoid列表ADR 实例见 .agents/adr/含0001-explicit-setup-pointer-only-for-hard-dependencies.md与0002-ship-as-a-claude-code-plugin.md——你可以对照 ADR-FORMAT.md 的模板阅读它们理解一条 ADR 可以只是单段落的实践形态。一句话总结整套架构审查的哲学用统一的词汇描述摩擦用可视化的报告呈现机会用决策树探讨落实方案用领域建模固化共识——最终让模块变深、让测试变自然、让代码库对人与 AI 都更可导航。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考