Community코딩 & 개발github.com

mattpocock/codebase-design

딥 모듈 설계를 위한 공유 용어집입니다. 사용자가 모듈의 인터페이스를 설계하거나 개선하고, 심층화 기회를 찾고, 경계(seam) 위치를 결정하고, 코드를 더 테스트 가능하거나 AI 탐색 가능하게 만들고자 할 때 또는 다른 스킬이 딥 모듈 용어를 필요로 할 때 사용합니다.

codebase-design란 무엇인가요?

이 스킬은 모듈을 깊게(deep) 설계하는 원칙과 공유 용어를 제공합니다. 핵심은 작은 인터페이스 뒤에 많은 행동(behavior)을 숨겨 호출자(caller)에게는 레버리지(leverage)를, 유지보수자(maintainer)에게는 지역성(locality)을, 모두에게는 테스트 용이성을 제공하는 것입니다. Module, Interface, Implementation, Depth, Seam, Adapter, Leverage, Locality 등 정확한 용어를 사용하여 코드 설계 논의의 일관성을 유지합니다. 모든 AI 에이전트 플랫폼에서 사용할 수 있는 언어-독립적인 원칙이며, 인터페이스의 깊이를 측정하고, 테스트 가능성을 높이며, 경계(seam)를 올바르게 배치하는 방법을 가이드합니다. 특히 설계 대안을 탐색하기 위해 병렬 에이전트를 실행하는 DESIGN-IT-TWICE.md와 의존성 분석을 위한 DEEPENING.md 같은 보조 문서와 함께 사용됩니다.

지원 대상~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에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

코드베이스 설계

딥 모듈(deep modules) 설계: 작은 인터페이스 뒤에 많은 행동을 숨기고, 깔끔한 경계(seam)에 배치하며, 그 인터페이스를 통해 테스트 가능하게 만듭니다. 코드를 설계하거나 재구성할 때마다 이 언어와 원칙을 사용하세요. 목표는 호출자에게 레버리지(leverage), 유지보수자에게 지역성(locality), 모두에게 테스트 용이성입니다.

용어집

다음 용어를 정확히 사용하세요 — 'component', 'service', 'API', 'boundary'로 대체하지 마세요. 일관된 언어가 핵심입니다.

Module — 인터페이스와 구현을 가진 모든 것. 의도적으로 규모와 무관: 함수, 클래스, 패키지, 또는 계층을 넘나드는 조각. 피할 것: unit, component, service.

Interface — 호출자가 모듈을 올바르게 사용하기 위해 알아야 하는 모든 것: 타입 시그니처뿐만 아니라 불변 조건, 순서 제약, 오류 모드, 필수 설정, 성능 특성까지 포함합니다. 피할 것: API, signature (너무 좁음 — 타입 수준 표면만 가리킴).

Implementation — 모듈 내부, 코드 본문. Adapter와 구분: 어떤 것은 큰 구현을 가진 작은 어댑터(PostgreSQL 저장소)일 수 있고, 작은 구현을 가진 큰 어댑터(인메모리 페이크)일 수 있습니다. 경계(seam)가 주제일 때는 'adapter'를, 그 외에는 'implementation'을 사용하세요.

Depth — 인터페이스에서의 레버리지: 호출자(또는 테스트)가 배워야 하는 인터페이스 단위당 발휘할 수 있는 행동의 양. 작은 인터페이스 뒤에 많은 행동이 있으면 깊고(deep), 인터페이스가 구현만큼 복잡하면 얕습니다(shallow).

Seam (Michael Feathers) — 그 자리에서 편집하지 않고 행동을 변경할 수 있는 곳; 모듈의 인터페이스가 위치한 지점. 경계를 어디에 둘지는 그 자체로 설계 결정이며, 그 뒤에 무엇이 올지와는 별개입니다. 피할 것: boundary (DDD의 bounded context와 중복됨).

Adapter — 경계(seam)에서 인터페이스를 충족하는 구체적인 것. 역할(무엇을 채우는지)을 설명하며, 내용(내부가 무엇인지)은 설명하지 않습니다.

Leverage — 호출자가 깊이(depth)로부터 얻는 것: 배운 인터페이스 단위당 더 많은 능력. 하나의 구현이 N개의 호출 지점과 M개의 테스트에서 보답합니다.

Locality — 유지보수자가 깊이(depth)로부터 얻는 것: 변경, 버그, 지식, 검증이 호출자들로 퍼지지 않고 한 곳에 집중됩니다. 한 번 고치면 모든 곳에서 고쳐집니다.

깊음(Deep) vs 얕음(Shallow)

깊은 모듈 = 작은 인터페이스 + 많은 구현:

┌─────────────────────┐
│   작은 인터페이스    │  ← 적은 메서드, 간단한 파라미터
├─────────────────────┤
│                     │
│  깊은 구현          │  ← 숨겨진 복잡한 로직
│                     │
└─────────────────────┘

얕은 모듈 = 큰 인터페이스 + 적은 구현 (피할 것):

┌─────────────────────────────────┐
│       큰 인터페이스             │  ← 많은 메서드, 복잡한 파라미터
├─────────────────────────────────┤
│  얇은 구현                     │  ← 그냥 통과만 시킴
└─────────────────────────────────┘

인터페이스를 설계할 때 물어보세요:

  • 메서드 수를 줄일 수 있나요?
  • 파라미터를 단순화할 수 있나요?
  • 더 많은 복잡성을 내부에 숨길 수 있나요?

원칙

  • 깊이(Depth)는 구현이 아닌 인터페이스의 속성입니다. 깊은 모듈은 내부적으로 작고, 목킹 가능하며, 교체 가능한 부품들로 구성될 수 있습니다 — 그저 인터페이스의 일부가 아닐 뿐입니다. 모듈은 내부 경계(internal seams) (구현에 비공개이며 자체 테스트에서 사용됨)와 외부 경계(external seam) (인터페이스에 있음)를 모두 가질 수 있습니다.
  • 삭제 테스트. 모듈을 삭제한다고 상상해보세요. 복잡성이 사라지면 통과(pass-through)였던 것입니다. 복잡성이 N개의 호출자에 걸쳐 다시 나타나면 그만한 가치가 있었던 것입니다.
  • 인터페이스는 테스트 표면입니다. 호출자와 테스트는 같은 경계(seam)를 가로지릅니다. 인터페이스를 지나쳐 테스트하고 싶다면 모듈 모양이 잘못된 것입니다.
  • 어댑터 하나는 가상의 경계(seam)입니다. 어댑터 두 개는 진짜 경계입니다. 실제로 변하는 것이 없으면 경계를 도입하지 마세요.

테스트 용이성을 위한 설계

좋은 인터페이스는 테스트를 자연스럽게 만듭니다:

  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. 작은 표면적. 메서드가 적을수록 필요한 테스트도 적습니다. 파라미터가 적을수록 테스트 설정이 간단해집니다.

관계

  • Module은 정확히 하나의 Interface를 가집니다 (호출자와 테스트에 제공하는 표면).
  • Depth는 Module의 속성이며, 해당 Interface에 대해 측정됩니다.
  • Seam은 Module의 Interface가 위치하는 곳입니다.
  • Adapter는 Seam에 위치하며 Interface를 충족합니다.
  • Depth는 호출자에게 Leverage를, 유지보수자에게 Locality를 제공합니다.

거부된 프레임

  • 구현 줄 수 대 인터페이스 줄 수 비율로서의 깊이(Depth) (Ousterhout): 구현을 부풀리도록 유도합니다. 우리는 레버리지로서의 깊이(leverage)를 사용합니다.
  • TypeScript interface 키워드 또는 클래스의 public 메서드로서의 'Interface': 너무 좁음 — 인터페이스는 여기서 호출자가 알아야 하는 모든 사실을 포함합니다.
  • 'Boundary': DDD의 bounded context와 중복됨. Seam 또는 Interface라고 말하세요.

더 깊이 들어가기

  • 의존성이 주어진 클러스터 심화(deepening) — DEEPENING.md 참조: 의존성 범주, 경계(seam) 규율, 교체-하지말고-계층화(replace-don't-layer) 테스트.
  • 대안 인터페이스 탐색 — DESIGN-IT-TWICE.md 참조: 병렬 하위 에이전트를 실행하여 인터페이스를 근본적으로 다른 여러 방식으로 설계한 다음, 깊이(Depth), 지역성(Locality), 경계(seam) 배치를 기준으로 비교합니다.

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.

관련 스킬