拓冰网站定制 
Windmill 代码库架构改进实践用 improve-codebase-architecture 技能扫描、可视化与打磨深模块【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill本指南以 Windmill 仓库内置的.claude/skills/improve-codebase-architecture/SKILL.md技能定义为主线完整讲解一套面向 AI 协作的代码库架构改进工作流先用“删除测试deletion test”找出浅模块shallow module并给出加深deepening机会再把候选以自包含 HTML 可视化报告呈现最后通过“拷问循环grilling loop”逐个打磨新接口的形状。读完本文你将掌握这套技能的完整流程、其背后的深模块设计词汇表module / interface / depth / seam / adapter / leverage / locality以及如何在本仓库中实际落地执行。技能定位从“改进代码库”到“加深模块”improve-codebase-architecture是 Windmill 仓库中一个禁用手动调用的 Claude Code 技能disable-modelin-invocation: true其设计目标非常明确发现架构摩擦architectural friction并提出“加深机会”deepening opportunities——也就是把浅模块重构为深模块。技能描述强调的两个最终收益是可测试性testability测试只需跨过一个接口interfaceAI 可导航性AI-navigability理解一个概念不需要在众多小模块之间来回跳转。该技能本身不凭空发明术语而是建立在两个共享设计语言之上/codebase-design技能提供的架构词汇表与原则见 .claude/skills/codebase-design/SKILL.md项目根目录的 CONTEXT.md 提供的领域语言——它给“好的接缝seam”命名让代码、文档与评审用同一个词说同一件事。技能要求在所有建议中严格使用这些术语module、interface、depth、seam、adapter、leverage、locality明确禁止漂移到 “component”“service”“API”“boundary” 等措辞——因为“语言一致本身就是目的”。在 Windmill 仓库中CONTEXT.md 已经为领域词汇定下了基调例如 flow 中的节点叫Step而非 module/node/action、每个步骤的运行时选项叫Step setting而非 advanced setting、轮询流程的第一步叫Trigger step而非 poll script、权限体系中的主体叫Member、访问级别叫Role。这些词就是本技能在分析 Windmill 前端/流程引擎代码时应当沿用的命名。完整工作流总览技能把一次架构改进会话拆成三个阶段阶段产出关键动作1. Explore探索候选清单按最近改动热点确定扫描范围先读CONTEXT.md派出子代理有机探索并记录摩擦点2. Present呈现自包含 HTML 报告写入 OS 临时目录并打开每个候选一张卡片 before/after 图 推荐强度徽章3. Grilling loop拷问循环敲定的新模块形状运行/grilling技能走设计决策树决策成型时内联更新领域模型下面逐阶段展开。阶段一Explore——先定范围再扫描技能开篇给出的第一条纪律是“Scope before you scan — YAGNI”加深一个模块的收益在于“让未来对它的修改更容易”因此应当把更多权重放在最近频繁变动的代码区域。具体策略分两条路径用户指定了方向某个模块、某个子系统、某个痛点直接采用跳过下述推断用户未指定方向先回溯一段提交历史git log --oneline找出代码库的“热点”hot spots——那些反复出现的文件与区域——让这些路径优先吸引注意力如果改动分散、没有清晰热点则扩大搜索网。接下来按顺序做两件事先读领域词汇表CONTEXT.md派出子代理sub-agent走查代码库——不套用僵硬的启发式规则而是有机探索并记录“你在哪里感受到了摩擦”。技能给出了五个具体的摩擦探测点这些是扫描时应当持续追问自己的问题理解某个概念是否需要在许多小模块之间来回跳转哪些模块是浅的——接口复杂度几乎与实现相当哪些纯函数仅仅为了可测试性被抽出来而真正的 bug 藏在“它们如何被调用”里缺少 locality哪些紧耦合模块在接缝处泄漏leak across their seams代码库哪些部分未被测试或难以通过当前接口测试删除测试识别浅模块的判定标准对任何怀疑是浅模块的东西应用删除测试deletion test想象删除这个模块。如果复杂度随之消失说明它只是透传pass-through如果复杂度重新散布到 N 个调用方身上说明它正在挣它的存在价值。技能原文给出的信号是“yes, concentrates”删除会集中复杂度就是你要的加深信号。也就是说一个值得加深的模块删除后复杂度不会消失而是摊回所有调用者——这恰恰证明它的接口在替调用方吸收复杂性。这条原则在.agents/skills/codebase-design/DEEPENING.md中被进一步形式化为依赖分类详见后文“按依赖分类决定测试策略”。阶段二Present——把候选渲染成自包含 HTML 报告扫描结束、候选清单成型后技能要求生成一份自包含self-contained的 HTML 文件并遵循两条硬规则写入 OS 临时目录绝不让文件落进仓库从$TMPDIR解析临时目录回退到/tmpWindows 为%TEMP%文件名形如tmpdir/architecture-review-timestamp.html保证每次运行都是新文件为用户打开它Linux 用xdg-open pathmacOS 用open pathWindows 用start path并告知绝对路径。报告的完整 HTML 脚手架、图表模式与样式指引集中在.agents/skills/improve-codebase-architecture/HTML-REPORT.md相对仓库根目录技能文件本身只给出要点。下面把两份文档的要求合并成可执行的规范。技术选型Tailwind Mermaid 手绘式 div/SVG布局与样式使用TailwindCDN 引入图表使用MermaidCDN 引入且初始化参数固定为startOnLoad: true, theme: neutral, securityLevel: looseMermaid 与手写 CSS/SVG 混用当结构是图状关系调用图、依赖图、时序图时用 Mermaid当想要更具编辑感的视觉质量图 mass diagrams、剖面图 cross-sections、折叠动画时用手工 div/SVG。技能明确告诫不要什么都用 Mermaid否则报告会显得千篇一律。脚手架骨架如下来自 HTML-REPORT.md!doctype html html langen head meta charsetutf-8 / titleArchitecture review — {{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 /* Tailwind 覆盖不到的自定义层虚线接缝、手绘感箭头等 */ .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头部区域只放仓库名、日期与一张紧凑图例实线框 模块、虚线 接缝、红色箭头 泄漏、粗黑框 深模块。不写引言段落直接进入候选卡片——报告靠图说话。候选卡片的内容结构每个候选是一张article卡片包含七个要素标题——简短直接命名这次加深例如 “Collapse the Order intake pipeline”徽章行——推荐强度徽章Strong emerald 绿、Worth exploring amber 琥珀、Speculative slate 灰外加一个依赖类别标签in-process、local-substitutable、ports adapters、mock类别定义见下文Files——涉及的模块/文件用等宽字体列表font-mono text-smBefore / After 图——整张卡片的中心左右两列并排自定义绘制用于同时展示“现在的浅”与“加深后的深”Problem——一句话当前架构为什么造成摩擦Solution——一句话会改变什么Wins——每项不超过 6 个词的要点用词汇表术语命名收益例如 “Tests hit one interface”“Pricing logic stops leaking”“Delete 4 shallow wrappers”。HTML-REPORT.md 特别强调如果一张图需要一段文字才能看懂那就重画这张图。卡片不设解释段落散文要稀疏、平实。五种图表模式报告文档提供了五种可复用的图表模式要求混合使用、避免千篇一律Mermaid graph依赖/调用流的主力当要点是“X 调用 Y 调用 Z看这团乱麻”时使用 flowchart/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手写 boxes-and-arrows当 Mermaid 的自动布局跟你作对时用带边框与标签的div表示模块用绝对定位的内联 SVGline/path画箭头尤其适合“after”图想呈现一个粗边框深模块、内部灰显的场景——Mermaid 渲染不出这种权重感。Cross-section剖面图适合层叠浅化把多个横向色带h-12 border-l-4堆叠起来展示一次调用要穿过的层。Before6 条啥也不干的薄层After一条粗色带标注合并后的责任。Mass diagram质量图适合“接口和实现一样宽”每个模块画两个矩形——接口表面积与实现。Before接口矩形几乎与实现矩形等高浅After接口矩形矮、实现矩形高深。Call-graph collapse调用图折叠Before 是嵌套盒子组成的函数调用树After 是同一棵树塌缩进一个盒子如今内部的调用以淡色绘制在盒子内。样式与语气规范风格要“编辑感”而非“仪表盘”留白充足标题可用衬线字体font-serif与 stone/slate 色系搭配良好颜色克制一种强调色emerald 或 indigo红色只用于泄漏琥珀只用于警告图高控制在 ~320px保证 before/after 并排时不需滚动图内模块标签用text-xs uppercase tracking-wider——它们应读作示意图而不是 UI唯一脚本就是 Tailwind CDN 与 Mermaid ESM 导入其余全部静态报告结尾是Top recommendation区块一张更大的卡片给出候选名、一句“为什么先做它”、以及指向对应卡片的锚点链接。语气层面文档列了严格的用词纪律与示范句式“Order intake module is shallow — interface nearly matches the implementation.”“Pricing leaks across the seam.”“Deepen: one interface, one place to test.”“Two adapters justify the seam: HTTP in prod, in-memory in tests.”必须精确使用module、interface、implementation、depth、deep、shallow、seam、adapter、leverage、locality。禁止替换为component、service、unit代替 moduleAPI、signature代替 interfaceboundary代替 seamlayer、wrapper在指 module 时。Wins 要点必须用词汇表术语命名收益locality / leverage / interface shrinks禁止写 “easier to maintain”“cleaner code” 这类不在词汇表里、不配出现的词。关键约束先不要提接口先把选择权交给用户阶段二结束时有一个容易被忽略但非常重要的约束Do NOT propose interfaces yet此时不要提议任何接口。报告写完后技能要求原样询问用户“Which of these would you like to explore?”——候选由用户挑选接口的形状留到下一阶段通过拷问共同决定。阶段三Grilling loop——拷问循环中敲定接口用户选定候选后进入拷问循环运行/grilling技能与用户一起走设计决策树decision tree覆盖以下维度约束constraints依赖dependencies加深后的模块的形状the shape of the deepened module什么站在接缝后面what sits behind the seam哪些测试能存活下来what tests survive。/grilling技能的机制见 .claude/skills/grilling/SKILL.md是把每个决策建模为设计树上的分支按轮次推进前沿frontier即“前提已定、现在可以问的问题”。每轮把整个前沿一次问完每个问题编号并给出推荐答案格式为❓ Qn - 标题➡️ 推荐答案然后等待用户答复再进入下一轮。查事实是 Agent 的职责而不是用户的——需要环境事实文件系统、工具等时派子代理去找但决策权始终在用户。前沿清空、没有遗留的静默假设时会话才算结束且在用户确认达成共识之前不得动手实施。决策成型时内联维护领域模型在拷问过程中技能要求“side effects happen inline”——决策一结晶就同步维护领域模型为此运行/domain-modeling技能见 .claude/skills/domain-modeling/SKILL.md触发三种内联更新给一个新加深的模块命名而该概念不在CONTEXT.md里把术语加进CONTEXT.md文件不存在则惰性创建对话中把一个模糊术语打磨精确当场更新CONTEXT.md想为加深后的模块探索备选接口运行/codebase-design技能使用其 “design-it-twice” 并行子代理模式——派多个子代理用截然不同的方式设计接口再在 depth、locality、seam 放置上做对比。/domain-modeling技能同时强调两条纪律CONTEXT.md必须彻底不含实现细节——它是且仅是词汇表不是规格书、草稿本或实现决策的仓库如果仓库根出现CONTEXT-MAP.md说明有多个上下文由该地图指路每个CONTEXT.md的位置。底层支撑一codebase-design 词汇表与原则improve-codebase-architecture的所有输出都建立在/codebase-design技能.claude/skills/codebase-design/SKILL.md之上。理解这套词汇是执行本技能的前提核心定义如下术语定义避用Module任何有接口与实现的东西刻意与规模无关函数、类、包、跨层切片unit、component、serviceInterface调用方正确使用模块所需知道的一切类型签名还有不变量、顺序约束、错误模式、所需配置、性能特征API、signatureImplementation模块内部、它的代码主体与Adapter相对——接缝是话题时说 adapter否则说 implementation—Depth接口处的杠杆调用方或测试每学习一单位接口所能驱动的行为量。深 大行为量藏在小接口后浅 接口与实现几乎一样复杂—SeamMichael Feathers一个不在此处编辑就能改变行为的位置模块接口所栖居的位置。接缝放哪里本身就是独立的设计决策boundaryAdapter在接缝处满足接口的具体事物描述角色填哪个槽而非实质—Leverage调用方从深度得到的每学习一单位接口获得更多能力。一次实现回报 N 个调用点、M 个测试—Locality维护者从深度得到的变更、bug、知识、验证集中在一处而非散布在调用方。修一处处处修复—技能还明确拒绝了三种错误框架把 depth 当“实现行数 / 接口行数”的比率Ousterhout 式会奖励给实现注水把 “Interface” 窄化为 TypeScriptinterface关键字或类的公有方法以及用 “boundary” 指代 seam与 DDD 有界上下文重名。四条核心原则Depth 是接口的属性不是实现的属性深模块内部可以由小的、可 mock、可替换的部件组成——它们只是不在接口里。模块既可以有内部接缝私有于实现、供自身测试使用也可以有外部接缝在其接口处。删除测试如上文删除后复杂度若重现于 N 个调用方模块就在挣它的价值。接口就是测试面The interface is the test surface调用方和测试跨过同一条接缝。如果想“测到接口背后去”模块形状大概率错了。一个 adapter 意味着接缝是假设的两个 adapter 才意味着接缝是真的除非有东西真的在接缝两端变化否则不要引入接缝。可测试性设计的三个实操准则接受依赖不要创建依赖function processOrder(order, paymentGateway) {}可测在函数内部new StripeGateway()则难测。返回结果不要制造副作用function calculateDiscount(cart): Discount {}可测function applyDiscount(cart): void直接改cart.total则难测。小表面积方法越少需要的测试越少参数越少测试搭建越简单。关系总结一个Module恰好一个InterfaceDepth是 Module 相对其 Interface 的属性Seam是 Module 的 Interface 栖居之处Adapter坐在 Seam 上满足 InterfaceDepth为调用方产出Leverage、为维护者产出Locality。底层支撑二DEEPENING——按依赖分类决定加深与测试策略当候选依赖已明确时.agents/skills/codebase-design/DEEPENING.md提供了“如何安全加深一簇浅模块”的操作指南。核心是把依赖分成四类类别直接决定加深后的模块如何跨接缝测试类别特征加深与测试策略1. In-process纯计算、内存态、无 I/O总是可加深——合并模块、直接通过新接口测试无需 adapter2. Local-substitutable有本地测试替身PGLite 之于 Postgres、内存文件系统只要替身存在就可加深测试套件里用替身跑接缝是内部的模块外部接口不设端口3. Remote but ownedPorts Adapters你自己跨网络边界的服务微服务、内部 API在接缝处定义端口深模块拥有逻辑传输层以adapter注入测试用内存 adapter生产用 HTTP/gRPC/queue adapter4. True externalMock不受你控制的三方服务Stripe、Twilio 等深模块把外部依赖作为注入的端口接收测试提供 mock adapter对类别 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.”接缝纪律一个 adapter 假设的接缝两个 adapter 真的接缝除非至少有两个 adapter 站得住脚通常是生产 测试否则别引入端口——单 adapter 的接缝只是间接层indirection。内部接缝 vs 外部接缝深模块可以有内部接缝私有于实现、供自身测试用以及接口处的外部接缝。不要因为测试用到了内部接缝就把它们暴露到接口上。测试策略替换而不是叠加深模块接口处的测试就位后旧的浅模块单元测试变成废料应当删除新测试写在加深后模块的接口处——接口就是测试面测试断言接口可观察的结果而不是内部状态测试应能经受内部重构——它们描述行为而非实现。如果实现一变测试就得改说明你在测接口背后。在 Windmill 仓库中落地这套技能领域词汇已经就位Windmill 根目录的 CONTEXT.md 是执行本技能的第一站。它已为两大领域钉好了词汇FlowsStep流程中的一个节点、Step setting每个步骤的运行时选项与步骤输入和代码相区分、Configured说一个 step setting 的配置对象在步骤上存在而非“会改变运行时行为”、Trigger step轮询流程的第一步按调度运行并返回上次以来的条目、Default predicate创建 trigger step 时种下的stop_after_if表达式一个值、一个归属、被所有创建路径共享、Connect武装一个输入以便下一个选中的属性填充它、Step input 与 Expression input输入表单中的参数 vs 循环迭代器/跳过谓词/重试条件等处的表达式输入。PermissionsMember在文件夹、组或条目的额外 ACL 上被授予角色的人UI 统一显示为 “Members (n)”、Roleviewer/writer/admin 或 member/admin、Owner专指路径前缀u/alice或f/team文件夹的 admin 成员在 UI 中绝不能叫 owner。这些正是扫描 Windmill 前端frontend/src与流程引擎代码时应当沿用的命名也是架构报告中“好接缝的名字”的来源。一次典型会话的执行顺序在 Windmill 仓库中运行本技能时可复现的执行路径如下读 CONTEXT.md 与 .claude/skills/codebase-design/SKILL.md 建立语言基础git log --oneline回溯提交历史定位近期热点文件Windmill 有 CHANGELOG.md 与数十个子 crate改动热点往往集中在windmill-api、windmill-worker、frontend/src等目录派子代理按“五个摩擦探测点”走查对可疑浅模块应用删除测试生成tmpdir/architecture-review-timestamp.html用 Tailwind Mermaid 手工 SVG 混排渲染候选卡片与 before/after 图结尾给出 Top recommendation然后只问用户“选哪个”用户选定后按/grilling的设计树逐轮敲定接口决策结晶时用/domain-modeling的格式内联更新CONTEXT.md格式模板见 .agents/skills/domain-modeling/CONTEXT-FORMAT.md。本仓库中可对照的实现证据技能定义本体.claude/skills/improve-codebase-architecture/SKILL.md流程总纲HTML 报告完整规范.agents/skills/improve-codebase-architecture/HTML-REPORT.md脚手架、五种图表模式、样式与语气加深实操指南.agents/skills/codebase-design/DEEPENING.md依赖四分类、接缝纪律、replace-dont-layer 测试策略词汇表与原则.claude/skills/codebase-design/SKILL.md备选接口并行设计.agents/skills/codebase-design/DESIGN-IT-TWICE.md领域词汇基线CONTEXT.md。总结improve-codebase-architecture把“改进代码库架构”从一句空泛的指令变成了三步可执行、词汇统一、产出可视的工程流程Explore用删除测试在热点区域定位浅模块Present用 Tailwind Mermaid 的自包含 HTML 报告把候选与 before/after 图呈现给用户Grilling loop用设计决策树与内联领域建模把“加深后的模块形状”敲定下来。它的全部判断都锚定在一套精确的架构词汇module / interface / depth / seam / adapter / leverage / locality和项目自己的 CONTEXT.md 领域语言上——对 Windmill 这样横跨 Rust 后端、Svelte 前端与几十个子 crate 的大型仓库来说这套流程为 AI 与人类协作重构代码提供了统一的语言、可验证的判定标准与可落地的产出物。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Windmill 代码库架构改进实践：用 improve-codebase-architecture 技能扫描、可视化与打磨深模块
Windmill 代码库架构改进实践用 improve-codebase-architecture 技能扫描、可视化与打磨深模块【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill本指南以 Windmill 仓库内置的.claude/skills/improve-codebase-architecture/SKILL.md技能定义为主线完整讲解一套面向 AI 协作的代码库架构改进工作流先用“删除测试deletion test”找出浅模块shallow module并给出加深deepening机会再把候选以自包含 HTML 可视化报告呈现最后通过“拷问循环grilling loop”逐个打磨新接口的形状。读完本文你将掌握这套技能的完整流程、其背后的深模块设计词汇表module / interface / depth / seam / adapter / leverage / locality以及如何在本仓库中实际落地执行。技能定位从“改进代码库”到“加深模块”improve-codebase-architecture是 Windmill 仓库中一个禁用手动调用的 Claude Code 技能disable-modelin-invocation: true其设计目标非常明确发现架构摩擦architectural friction并提出“加深机会”deepening opportunities——也就是把浅模块重构为深模块。技能描述强调的两个最终收益是可测试性testability测试只需跨过一个接口interfaceAI 可导航性AI-navigability理解一个概念不需要在众多小模块之间来回跳转。该技能本身不凭空发明术语而是建立在两个共享设计语言之上/codebase-design技能提供的架构词汇表与原则见 .claude/skills/codebase-design/SKILL.md项目根目录的 CONTEXT.md 提供的领域语言——它给“好的接缝seam”命名让代码、文档与评审用同一个词说同一件事。技能要求在所有建议中严格使用这些术语module、interface、depth、seam、adapter、leverage、locality明确禁止漂移到 “component”“service”“API”“boundary” 等措辞——因为“语言一致本身就是目的”。在 Windmill 仓库中CONTEXT.md 已经为领域词汇定下了基调例如 flow 中的节点叫Step而非 module/node/action、每个步骤的运行时选项叫Step setting而非 advanced setting、轮询流程的第一步叫Trigger step而非 poll script、权限体系中的主体叫Member、访问级别叫Role。这些词就是本技能在分析 Windmill 前端/流程引擎代码时应当沿用的命名。完整工作流总览技能把一次架构改进会话拆成三个阶段阶段产出关键动作1. Explore探索候选清单按最近改动热点确定扫描范围先读CONTEXT.md派出子代理有机探索并记录摩擦点2. Present呈现自包含 HTML 报告写入 OS 临时目录并打开每个候选一张卡片 before/after 图 推荐强度徽章3. Grilling loop拷问循环敲定的新模块形状运行/grilling技能走设计决策树决策成型时内联更新领域模型下面逐阶段展开。阶段一Explore——先定范围再扫描技能开篇给出的第一条纪律是“Scope before you scan — YAGNI”加深一个模块的收益在于“让未来对它的修改更容易”因此应当把更多权重放在最近频繁变动的代码区域。具体策略分两条路径用户指定了方向某个模块、某个子系统、某个痛点直接采用跳过下述推断用户未指定方向先回溯一段提交历史git log --oneline找出代码库的“热点”hot spots——那些反复出现的文件与区域——让这些路径优先吸引注意力如果改动分散、没有清晰热点则扩大搜索网。接下来按顺序做两件事先读领域词汇表CONTEXT.md派出子代理sub-agent走查代码库——不套用僵硬的启发式规则而是有机探索并记录“你在哪里感受到了摩擦”。技能给出了五个具体的摩擦探测点这些是扫描时应当持续追问自己的问题理解某个概念是否需要在许多小模块之间来回跳转哪些模块是浅的——接口复杂度几乎与实现相当哪些纯函数仅仅为了可测试性被抽出来而真正的 bug 藏在“它们如何被调用”里缺少 locality哪些紧耦合模块在接缝处泄漏leak across their seams代码库哪些部分未被测试或难以通过当前接口测试删除测试识别浅模块的判定标准对任何怀疑是浅模块的东西应用删除测试deletion test想象删除这个模块。如果复杂度随之消失说明它只是透传pass-through如果复杂度重新散布到 N 个调用方身上说明它正在挣它的存在价值。技能原文给出的信号是“yes, concentrates”删除会集中复杂度就是你要的加深信号。也就是说一个值得加深的模块删除后复杂度不会消失而是摊回所有调用者——这恰恰证明它的接口在替调用方吸收复杂性。这条原则在.agents/skills/codebase-design/DEEPENING.md中被进一步形式化为依赖分类详见后文“按依赖分类决定测试策略”。阶段二Present——把候选渲染成自包含 HTML 报告扫描结束、候选清单成型后技能要求生成一份自包含self-contained的 HTML 文件并遵循两条硬规则写入 OS 临时目录绝不让文件落进仓库从$TMPDIR解析临时目录回退到/tmpWindows 为%TEMP%文件名形如tmpdir/architecture-review-timestamp.html保证每次运行都是新文件为用户打开它Linux 用xdg-open pathmacOS 用open pathWindows 用start path并告知绝对路径。报告的完整 HTML 脚手架、图表模式与样式指引集中在.agents/skills/improve-codebase-architecture/HTML-REPORT.md相对仓库根目录技能文件本身只给出要点。下面把两份文档的要求合并成可执行的规范。技术选型Tailwind Mermaid 手绘式 div/SVG布局与样式使用TailwindCDN 引入图表使用MermaidCDN 引入且初始化参数固定为startOnLoad: true, theme: neutral, securityLevel: looseMermaid 与手写 CSS/SVG 混用当结构是图状关系调用图、依赖图、时序图时用 Mermaid当想要更具编辑感的视觉质量图 mass diagrams、剖面图 cross-sections、折叠动画时用手工 div/SVG。技能明确告诫不要什么都用 Mermaid否则报告会显得千篇一律。脚手架骨架如下来自 HTML-REPORT.md!doctype html html langen head meta charsetutf-8 / titleArchitecture review — {{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 /* Tailwind 覆盖不到的自定义层虚线接缝、手绘感箭头等 */ .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头部区域只放仓库名、日期与一张紧凑图例实线框 模块、虚线 接缝、红色箭头 泄漏、粗黑框 深模块。不写引言段落直接进入候选卡片——报告靠图说话。候选卡片的内容结构每个候选是一张article卡片包含七个要素标题——简短直接命名这次加深例如 “Collapse the Order intake pipeline”徽章行——推荐强度徽章Strong emerald 绿、Worth exploring amber 琥珀、Speculative slate 灰外加一个依赖类别标签in-process、local-substitutable、ports adapters、mock类别定义见下文Files——涉及的模块/文件用等宽字体列表font-mono text-smBefore / After 图——整张卡片的中心左右两列并排自定义绘制用于同时展示“现在的浅”与“加深后的深”Problem——一句话当前架构为什么造成摩擦Solution——一句话会改变什么Wins——每项不超过 6 个词的要点用词汇表术语命名收益例如 “Tests hit one interface”“Pricing logic stops leaking”“Delete 4 shallow wrappers”。HTML-REPORT.md 特别强调如果一张图需要一段文字才能看懂那就重画这张图。卡片不设解释段落散文要稀疏、平实。五种图表模式报告文档提供了五种可复用的图表模式要求混合使用、避免千篇一律Mermaid graph依赖/调用流的主力当要点是“X 调用 Y 调用 Z看这团乱麻”时使用 flowchart/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手写 boxes-and-arrows当 Mermaid 的自动布局跟你作对时用带边框与标签的div表示模块用绝对定位的内联 SVGline/path画箭头尤其适合“after”图想呈现一个粗边框深模块、内部灰显的场景——Mermaid 渲染不出这种权重感。Cross-section剖面图适合层叠浅化把多个横向色带h-12 border-l-4堆叠起来展示一次调用要穿过的层。Before6 条啥也不干的薄层After一条粗色带标注合并后的责任。Mass diagram质量图适合“接口和实现一样宽”每个模块画两个矩形——接口表面积与实现。Before接口矩形几乎与实现矩形等高浅After接口矩形矮、实现矩形高深。Call-graph collapse调用图折叠Before 是嵌套盒子组成的函数调用树After 是同一棵树塌缩进一个盒子如今内部的调用以淡色绘制在盒子内。样式与语气规范风格要“编辑感”而非“仪表盘”留白充足标题可用衬线字体font-serif与 stone/slate 色系搭配良好颜色克制一种强调色emerald 或 indigo红色只用于泄漏琥珀只用于警告图高控制在 ~320px保证 before/after 并排时不需滚动图内模块标签用text-xs uppercase tracking-wider——它们应读作示意图而不是 UI唯一脚本就是 Tailwind CDN 与 Mermaid ESM 导入其余全部静态报告结尾是Top recommendation区块一张更大的卡片给出候选名、一句“为什么先做它”、以及指向对应卡片的锚点链接。语气层面文档列了严格的用词纪律与示范句式“Order intake module is shallow — interface nearly matches the implementation.”“Pricing leaks across the seam.”“Deepen: one interface, one place to test.”“Two adapters justify the seam: HTTP in prod, in-memory in tests.”必须精确使用module、interface、implementation、depth、deep、shallow、seam、adapter、leverage、locality。禁止替换为component、service、unit代替 moduleAPI、signature代替 interfaceboundary代替 seamlayer、wrapper在指 module 时。Wins 要点必须用词汇表术语命名收益locality / leverage / interface shrinks禁止写 “easier to maintain”“cleaner code” 这类不在词汇表里、不配出现的词。关键约束先不要提接口先把选择权交给用户阶段二结束时有一个容易被忽略但非常重要的约束Do NOT propose interfaces yet此时不要提议任何接口。报告写完后技能要求原样询问用户“Which of these would you like to explore?”——候选由用户挑选接口的形状留到下一阶段通过拷问共同决定。阶段三Grilling loop——拷问循环中敲定接口用户选定候选后进入拷问循环运行/grilling技能与用户一起走设计决策树decision tree覆盖以下维度约束constraints依赖dependencies加深后的模块的形状the shape of the deepened module什么站在接缝后面what sits behind the seam哪些测试能存活下来what tests survive。/grilling技能的机制见 .claude/skills/grilling/SKILL.md是把每个决策建模为设计树上的分支按轮次推进前沿frontier即“前提已定、现在可以问的问题”。每轮把整个前沿一次问完每个问题编号并给出推荐答案格式为❓ Qn - 标题➡️ 推荐答案然后等待用户答复再进入下一轮。查事实是 Agent 的职责而不是用户的——需要环境事实文件系统、工具等时派子代理去找但决策权始终在用户。前沿清空、没有遗留的静默假设时会话才算结束且在用户确认达成共识之前不得动手实施。决策成型时内联维护领域模型在拷问过程中技能要求“side effects happen inline”——决策一结晶就同步维护领域模型为此运行/domain-modeling技能见 .claude/skills/domain-modeling/SKILL.md触发三种内联更新给一个新加深的模块命名而该概念不在CONTEXT.md里把术语加进CONTEXT.md文件不存在则惰性创建对话中把一个模糊术语打磨精确当场更新CONTEXT.md想为加深后的模块探索备选接口运行/codebase-design技能使用其 “design-it-twice” 并行子代理模式——派多个子代理用截然不同的方式设计接口再在 depth、locality、seam 放置上做对比。/domain-modeling技能同时强调两条纪律CONTEXT.md必须彻底不含实现细节——它是且仅是词汇表不是规格书、草稿本或实现决策的仓库如果仓库根出现CONTEXT-MAP.md说明有多个上下文由该地图指路每个CONTEXT.md的位置。底层支撑一codebase-design 词汇表与原则improve-codebase-architecture的所有输出都建立在/codebase-design技能.claude/skills/codebase-design/SKILL.md之上。理解这套词汇是执行本技能的前提核心定义如下术语定义避用Module任何有接口与实现的东西刻意与规模无关函数、类、包、跨层切片unit、component、serviceInterface调用方正确使用模块所需知道的一切类型签名还有不变量、顺序约束、错误模式、所需配置、性能特征API、signatureImplementation模块内部、它的代码主体与Adapter相对——接缝是话题时说 adapter否则说 implementation—Depth接口处的杠杆调用方或测试每学习一单位接口所能驱动的行为量。深 大行为量藏在小接口后浅 接口与实现几乎一样复杂—SeamMichael Feathers一个不在此处编辑就能改变行为的位置模块接口所栖居的位置。接缝放哪里本身就是独立的设计决策boundaryAdapter在接缝处满足接口的具体事物描述角色填哪个槽而非实质—Leverage调用方从深度得到的每学习一单位接口获得更多能力。一次实现回报 N 个调用点、M 个测试—Locality维护者从深度得到的变更、bug、知识、验证集中在一处而非散布在调用方。修一处处处修复—技能还明确拒绝了三种错误框架把 depth 当“实现行数 / 接口行数”的比率Ousterhout 式会奖励给实现注水把 “Interface” 窄化为 TypeScriptinterface关键字或类的公有方法以及用 “boundary” 指代 seam与 DDD 有界上下文重名。四条核心原则Depth 是接口的属性不是实现的属性深模块内部可以由小的、可 mock、可替换的部件组成——它们只是不在接口里。模块既可以有内部接缝私有于实现、供自身测试使用也可以有外部接缝在其接口处。删除测试如上文删除后复杂度若重现于 N 个调用方模块就在挣它的价值。接口就是测试面The interface is the test surface调用方和测试跨过同一条接缝。如果想“测到接口背后去”模块形状大概率错了。一个 adapter 意味着接缝是假设的两个 adapter 才意味着接缝是真的除非有东西真的在接缝两端变化否则不要引入接缝。可测试性设计的三个实操准则接受依赖不要创建依赖function processOrder(order, paymentGateway) {}可测在函数内部new StripeGateway()则难测。返回结果不要制造副作用function calculateDiscount(cart): Discount {}可测function applyDiscount(cart): void直接改cart.total则难测。小表面积方法越少需要的测试越少参数越少测试搭建越简单。关系总结一个Module恰好一个InterfaceDepth是 Module 相对其 Interface 的属性Seam是 Module 的 Interface 栖居之处Adapter坐在 Seam 上满足 InterfaceDepth为调用方产出Leverage、为维护者产出Locality。底层支撑二DEEPENING——按依赖分类决定加深与测试策略当候选依赖已明确时.agents/skills/codebase-design/DEEPENING.md提供了“如何安全加深一簇浅模块”的操作指南。核心是把依赖分成四类类别直接决定加深后的模块如何跨接缝测试类别特征加深与测试策略1. In-process纯计算、内存态、无 I/O总是可加深——合并模块、直接通过新接口测试无需 adapter2. Local-substitutable有本地测试替身PGLite 之于 Postgres、内存文件系统只要替身存在就可加深测试套件里用替身跑接缝是内部的模块外部接口不设端口3. Remote but ownedPorts Adapters你自己跨网络边界的服务微服务、内部 API在接缝处定义端口深模块拥有逻辑传输层以adapter注入测试用内存 adapter生产用 HTTP/gRPC/queue adapter4. True externalMock不受你控制的三方服务Stripe、Twilio 等深模块把外部依赖作为注入的端口接收测试提供 mock adapter对类别 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.”接缝纪律一个 adapter 假设的接缝两个 adapter 真的接缝除非至少有两个 adapter 站得住脚通常是生产 测试否则别引入端口——单 adapter 的接缝只是间接层indirection。内部接缝 vs 外部接缝深模块可以有内部接缝私有于实现、供自身测试用以及接口处的外部接缝。不要因为测试用到了内部接缝就把它们暴露到接口上。测试策略替换而不是叠加深模块接口处的测试就位后旧的浅模块单元测试变成废料应当删除新测试写在加深后模块的接口处——接口就是测试面测试断言接口可观察的结果而不是内部状态测试应能经受内部重构——它们描述行为而非实现。如果实现一变测试就得改说明你在测接口背后。在 Windmill 仓库中落地这套技能领域词汇已经就位Windmill 根目录的 CONTEXT.md 是执行本技能的第一站。它已为两大领域钉好了词汇FlowsStep流程中的一个节点、Step setting每个步骤的运行时选项与步骤输入和代码相区分、Configured说一个 step setting 的配置对象在步骤上存在而非“会改变运行时行为”、Trigger step轮询流程的第一步按调度运行并返回上次以来的条目、Default predicate创建 trigger step 时种下的stop_after_if表达式一个值、一个归属、被所有创建路径共享、Connect武装一个输入以便下一个选中的属性填充它、Step input 与 Expression input输入表单中的参数 vs 循环迭代器/跳过谓词/重试条件等处的表达式输入。PermissionsMember在文件夹、组或条目的额外 ACL 上被授予角色的人UI 统一显示为 “Members (n)”、Roleviewer/writer/admin 或 member/admin、Owner专指路径前缀u/alice或f/team文件夹的 admin 成员在 UI 中绝不能叫 owner。这些正是扫描 Windmill 前端frontend/src与流程引擎代码时应当沿用的命名也是架构报告中“好接缝的名字”的来源。一次典型会话的执行顺序在 Windmill 仓库中运行本技能时可复现的执行路径如下读 CONTEXT.md 与 .claude/skills/codebase-design/SKILL.md 建立语言基础git log --oneline回溯提交历史定位近期热点文件Windmill 有 CHANGELOG.md 与数十个子 crate改动热点往往集中在windmill-api、windmill-worker、frontend/src等目录派子代理按“五个摩擦探测点”走查对可疑浅模块应用删除测试生成tmpdir/architecture-review-timestamp.html用 Tailwind Mermaid 手工 SVG 混排渲染候选卡片与 before/after 图结尾给出 Top recommendation然后只问用户“选哪个”用户选定后按/grilling的设计树逐轮敲定接口决策结晶时用/domain-modeling的格式内联更新CONTEXT.md格式模板见 .agents/skills/domain-modeling/CONTEXT-FORMAT.md。本仓库中可对照的实现证据技能定义本体.claude/skills/improve-codebase-architecture/SKILL.md流程总纲HTML 报告完整规范.agents/skills/improve-codebase-architecture/HTML-REPORT.md脚手架、五种图表模式、样式与语气加深实操指南.agents/skills/codebase-design/DEEPENING.md依赖四分类、接缝纪律、replace-dont-layer 测试策略词汇表与原则.claude/skills/codebase-design/SKILL.md备选接口并行设计.agents/skills/codebase-design/DESIGN-IT-TWICE.md领域词汇基线CONTEXT.md。总结improve-codebase-architecture把“改进代码库架构”从一句空泛的指令变成了三步可执行、词汇统一、产出可视的工程流程Explore用删除测试在热点区域定位浅模块Present用 Tailwind Mermaid 的自包含 HTML 报告把候选与 before/after 图呈现给用户Grilling loop用设计决策树与内联领域建模把“加深后的模块形状”敲定下来。它的全部判断都锚定在一套精确的架构词汇module / interface / depth / seam / adapter / leverage / locality和项目自己的 CONTEXT.md 领域语言上——对 Windmill 这样横跨 Rust 后端、Svelte 前端与几十个子 crate 的大型仓库来说这套流程为 AI 与人类协作重构代码提供了统一的语言、可验证的判定标准与可落地的产出物。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考