Communityコーディング&開発github.com

mattpocock/codebase-design

ディープモジュールを設計するための共有語彙。ユーザーがモジュールのインターフェースを設計・改善したい、深化の機会を見つけたい、シームの位置を決めたい、コードをテストしやすくしたりAIでナビゲートしやすくしたりしたい場合、または別のスキルがディープモジュールの語彙を必要とする場合に使用します。

codebase-design とは?

このスキルは、コードベース設計における「ディープモジュール」の概念とその実践的な語彙を提供します。ディープモジュールとは、小さなインターフェースの背後に多くの振る舞いを隠蔽した設計であり、呼び出し元にとってのレバレッジ(少ない学習で多くの機能を利用できる)、保守者にとっての局所性(変更やバグの影響範囲が限定される)、そしてテスト容易性を実現します。Claude CodeやCursorなどのAIエージェントが、モジュール設計やリファクタリングの議論を行う際に、一貫した用語(Module、Interface、Seam、Depthなど)を使用できるようにします。この語彙は、従来の「コンポーネント」「サービス」「API」「境界」といった曖昧な用語を避け、設計上のトレードオフを正確に議論するための基盤を提供します。

対応~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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

コードベース設計(Codebase Design)

ディープモジュールを設計する:小さなインターフェースの背後に多くの振る舞いを置き、それをクリーンなシームに配置し、そのインターフェースを通じてテスト可能にする。コードを設計または再構築するあらゆる場面で、この言語と原則を使用すること。目的は、呼び出し元にとってのレバレッジ、保守者にとっての局所性、そしてすべての人にとってのテスト容易性である。

用語集(Glossary)

これらの用語を厳密に使用すること — 「コンポーネント」「サービス」「API」「バウンダリ」などに置き換えないこと。一貫した言語こそがすべての要点である。

モジュール(Module) — インターフェースと実装を備えたもの。意図的にスケールに依存しない:関数、クラス、パッケージ、もしくは階層をまたぐスライス。避けること:ユニット、コンポーネント、サービス。

インターフェース(Interface) — モジュールを正しく使用するために呼び出し元が知っておくべきすべてのこと:型シグネチャだけでなく、不変条件、順序制約、エラーモード、必要な設定、パフォーマンス特性も含む。避けること:API、シグネチャ(これらは狭すぎる — 型レベルの表面のみを指す)。

実装(Implementation) — モジュールの内側、そのコード本体。アダプタ(Adapter) とは区別する:何かは、大きな実装を持つ小さなアダプタ(PostgreSQLリポジトリ)にもなり得るし、小さな実装を持つ大きなアダプタ(インメモリのフェイク)にもなり得る。シームが話題の中心であれば「アダプタ」を使い、そうでなければ「実装」を使う。

深さ(Depth) — インターフェースにおけるレバレッジ:呼び出し元(またはテスト)が、学習しなければならないインターフェースの単位あたりに発揮できる振る舞いの量。モジュールは、小さなインターフェースの背後に大量の振る舞いがある場合に深いと呼ばれ、インターフェースが実装とほぼ同じくらい複雑な場合に浅いと呼ばれる。

シーム(Seam) (Michael Feathers) — その場所で編集することなく振る舞いを変更できる場所。モジュールのインターフェースが存在する位置。シームをどこに置くかは、その背後に何を置くかとは別の設計上の決定である。避けること:バウンダリ(DDDの境界づけられたコンテキストと重複する)。

アダプタ(Adapter) — シームにおいてインターフェースを満たす具体的なもの。役割(どのスロットを埋めるか)を記述し、中身(何が内側にあるか)は記述しない。

レバレッジ(Leverage) — 呼び出し元が深さから得るもの:学習したインターフェースの単位あたり、より多くの能力。1つの実装がN個の呼び出し箇所とM個のテストに対して見返りを生む。

局所性(Locality) — 保守者が深さから得るもの:変更、バグ、知識、検証が呼び出し元全体に広がるのではなく、一箇所に集中する。一度修正すれば、どこでも修正されたことになる。

深い vs 浅い

ディープモジュール = 小さなインターフェース + 大きな実装:

┌─────────────────────┐
│   小さなインターフェース  │  ← メソッドが少なく、パラメータがシンプル
├─────────────────────┤
│                     │
│  深い実装             │  ← 複雑なロジックが隠蔽されている
│                     │
└─────────────────────┘

シャローモジュール = 大きなインターフェース + 小さな実装(避けること):

┌─────────────────────────────────┐
│       大きなインターフェース        │  ← メソッドが多く、パラメータが複雑
├─────────────────────────────────┤
│  薄い実装                         │  ← 単に通過させるだけ
└─────────────────────────────────┘

インターフェースを設計するときは、次のように問いかける:

  • メソッドの数を減らせないか?
  • パラメータを単純化できないか?
  • より多くの複雑さを内部に隠せないか?

原則(Principles)

  • 深さはインターフェースの特性であり、実装の特性ではない。 ディープモジュールは内部的に、小さくモック可能で交換可能な部品で構成されていても構わない — それらは単にインターフェースの一部ではないだけである。モジュールは、内部シーム(実装に対してプライベートで、自身のテストで使用される)と、インターフェースにある外部シームの両方を持つことができる。
  • 削除テスト。 モジュールを削除した場合を想像してみる。複雑さが消え去るなら、それは単なるパススルーだった。複雑さがN個の呼び出し元に再出現するなら、それは存在価値があったということだ。
  • インターフェースがテストの表面である。 呼び出し元とテストは同じシームを越える。インターフェースを越えてテストしたい場合、おそらくモジュールの形が間違っている。
  • 1つのアダプタは仮説上のシーム。2つのアダプタは本物のシーム。 何かが実際にそのシームをまたいで変化しない限り、シームを導入してはならない。

テスト容易性のための設計

優れたインターフェースはテストを自然なものにする:

  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. 小さな表面積。 メソッドが少ない = 必要なテストが少ない。パラメータが少ない = テストのセットアップがシンプル。

関係性(Relationships)

  • モジュールは正確に1つのインターフェースを持つ(呼び出し元とテストに提示する表面)。
  • 深さはモジュールの特性であり、そのインターフェースに対して測定される。
  • シームはモジュールのインターフェースが存在する場所である。
  • アダプタはシームに位置し、インターフェースを満たす。
  • 深さは呼び出し元にとってのレバレッジと、保守者にとっての局所性を生み出す。

採用されなかったフレーミング

  • 深さを実装行数とインターフェース行数の比率として捉える(Ousterhout):実装を水増しする動機を与える。代わりに、レバレッジとしての深さを採用する。
  • 「インターフェース」をTypeScriptの interface キーワードやクラスのpublicメソッドと捉える:狭すぎる — ここでのインターフェースは、呼び出し元が知る必要のあるすべての事実を含む。
  • 「バウンダリ」: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.

関連スキル