Community程式設計與開發github.com

mattpocock/codebase-design

用於設計深度模組的共享詞彙。當使用者想要設計或改善模組的介面、尋找深化機會、決定接縫位置、讓程式碼更容易測試或讓AI易於導航,或其他技能需要深度模組詞彙時使用。

codebase-design 是什麼?

此技能提供了一套嚴謹且一致的詞彙,用於設計所謂的「深度模組」——即透過小而精簡的介面提供大量行為的模組,這些模組放置在清晰的接縫處,並可透過其介面進行測試。其主要目標是為呼叫者提供槓桿作用,為維護者提供局部性,並為所有人提供可測試性。它定義了「模組」、「介面」、「實現」、「深度」、「接縫」和「適配器」等關鍵術語,並嚴格區分了它們與「元件」、「服務」或「邊界」等常見但被認為過於模糊或過載的術語。該技能也概述了評估介面深度的原則(例如刪除測試),並提供了設計可測試性的具體準則,例如接受依賴而非建立它們、回傳結果而非產生副作用,並保持介面面積小。最後,它引用了兩個補充文件來深入探討深化集群和探索替代介面設計,使其成為重構或設計新系統時的強大工具。此技能設計為可跨多種平台使用,包括Claude Code、Cursor和Codex。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

程式碼庫設計

設計深度模組:在乾淨的接縫處放置一個小介面背後的大量行為,並可透過該介面進行測試。在設計或重構程式碼的任何地方,都使用這些語言和原則。目標是為呼叫者提供槓桿作用,為維護者提供局部性,並為所有人提供可測試性。

詞彙表

請精確使用這些術語——不要替換為「元件」、「服務」、「API」或「邊界」。一致的語言是重點。

模組 — 任何具有介面和實作的東西。刻意與規模無關:一個函式、類別、套件或跨層級的切片。避免:單元、元件、服務。

介面 — 呼叫者正確使用模組時必須知道的一切:型別簽章,但也包括不變條件、排序約束、錯誤模式、所需配置和效能特性。避免:API、簽章(太狹隘——它們僅指型別層級的表面)。

實現 — 模組內部的東西,其程式碼主體。與適配器不同:某物可以是一個帶有大量實現的小型適配器(像是Postgres儲存庫),也可以是一個帶有少量實現的大型適配器(像是記憶體模擬)。當接縫是主題時,使用「適配器」;否則使用「實現」。

深度 — 介面上的槓桿作用:呼叫者(或測試)在必須學習的每個介面單位上可以使用的行為量。當大量行為位於小型介面背後時,模組是深的;當介面幾乎與實現一樣複雜時,模組是淺的。

接縫 (Michael Feathers) — 一個可以在不直接編輯該位置的情況下改變行為的地方;是模組介面存在的位置。將接縫放在哪裡本身就是一個設計決策,與背後放置的內容不同。避免:邊界(與DDD的限界上下文過載)。

適配器 — 滿足接縫處介面的具體事物。描述角色(它填補了什麼插槽),而不是實質(內部是什麼)。

槓桿作用 — 呼叫者從深度中獲得的東西:每學習一個介面單位就能獲得更多能力。一個實作在N個呼叫點和M個測試中回報。

局部性 — 維護者從深度中獲得的東西:變更、錯誤、知識和驗證集中在一個地方,而不是分散在呼叫者之間。一次修復,處處固定。

深 vs 淺

深度模組 = 小介面 + 大量實現:

┌─────────────────────┐
│   小型介面            │  ← 少數方法,簡單參數
├─────────────────────┤
│                     │
│   深度實現            │  ← 隱藏複雜邏輯
│                     │
└─────────────────────┘

淺度模組 = 大介面 + 少量實現(應避免):

┌─────────────────────────────────┐
│         大型介面                │  ← 許多方法,複雜參數
├─────────────────────────────────┤
│   薄實現                       │  ← 僅傳遞
└─────────────────────────────────┘

設計介面時,請詢問:

  • 我可以減少方法的數量嗎?
  • 我可以簡化參數嗎?
  • 我可以在內部隱藏更多複雜性嗎?

原則

  • 深度是介面的屬性,而非實現的屬性。 一個深度模組可以在內部由小的、可模擬的、可互換的部分組成——它們只是不屬於介面的一部分。一個模組可以具有內部接縫(對其實現私有,供其自身測試使用)以及其介面上的外部接縫。
  • 刪除測試。 想像刪除該模組。如果複雜性消失,那麼它就是一個直通模組。如果複雜性重新出現在N個呼叫者中,那麼它就在發揮其作用。
  • 介面就是測試表面。 呼叫者和測試跨越相同的接縫。如果你想測試超越介面,那模組的形狀可能不對。
  • 一個適配器意味著一個假設的接縫。兩個適配器意味著一個真正的接縫。 除非有些東西實際上跨接縫變化,否則不要引入接縫。

為可測試性設計

好的介面讓測試自然:

  1. 接受依賴,而非建立它們。

    // 可測試
    function processOrder(order, paymentGateway) {}
    
    // 難以測試
    function processOrder(order) {
      const gateway = new StripeGateway();
    }
    
  2. 回傳結果,而非產生副作用。

    // 可測試
    function calculateDiscount(cart): Discount {}
    
    // 難以測試
    function applyDiscount(cart): void {
      cart.total -= discount;
    }
    
  3. 小表面積。 更少的方法 = 需要更少的測試。更少的參數 = 更簡單的測試設定。

關係

  • 一個模組恰好有一個介面(它呈現給呼叫者和測試的表面)。
  • 深度是模組的屬性,相對於其介面來衡量。
  • 接縫是模組****介面所在的位置。
  • 適配器位於接縫處並滿足介面。
  • 深度為呼叫者產生槓桿作用,為維護者產生局部性。

被拒絕的框架

  • 深度作為實現行數與介面行數的比例 (Ousterhout):獎勵填充實現。我們改用深度即槓桿作用。
  • 「介面」作為TypeScript的interface關鍵字或類別的公開方法:太狹隘——這裡的介面包括呼叫者必須知道的每一個事實。
  • 「邊界」:與DDD的限界上下文過載。應使用接縫或介面。

深入探討

  • 鑑於其依賴關係深化集群 — 請參閱 DEEPENING.md:依賴類別、接縫紀律以及取代而非分層測試。
  • 探索替代介面 — 請參閱 DESIGN-IT-TWICE.md:啟動並行子代理,以多種截然不同的方式設計介面,然後在深度、局部性和接縫放置方面進行比較。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

mattpocock/ask-matt

Ask which skill or flow fits your situation. A router over the skills in this repo.

mattpocock/caveman

Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman.

mattpocock/claude-handoff

Hand the current conversation off to a fresh background agent that picks up the work immediately.

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

mattpocock/diagnose

Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.

mattpocock/diagnosing-bugs

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

mattpocock/domain-modeling

Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.

mattpocock/edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

mattpocock/git-guardrails-claude-code

Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

mattpocock/grilling

Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

mattpocock/grill-with-docs

Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.

mattpocock/handoff

Compact the current conversation into a handoff document for another agent to pick up.

mattpocock/implement

Implement a piece of work based on a PRD or set of issues.

mattpocock/implement-spec

Implement a specification in code.

mattpocock/improve-codebase-architecture

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

mattpocock/loop-me

Grill me about specs for the workflows I want to build, within this workspace.

mattpocock/migrate-to-shoehorn

Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.

mattpocock/obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

相關技能