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），僅供參考