CommunityCodierung & Entwicklunggithub.com

mattpocock/codebase-design

Gemeinsame Fachsprache für das Design tiefer Module. Verwende dies, wenn der Benutzer eine Modul-Schnittstelle entwerfen oder verbessern, Vertiefungsmöglichkeiten finden, entscheiden möchte, wo eine Naht verläuft, Code testbarer oder KI-navigierbarer machen möchte, oder wenn eine andere Fähigkeit die Fachsprache für tiefe Module benötigt.

Was ist codebase-design?

Diese Fähigkeit (Skill) führt eine präzise, gemeinsame Fachsprache für das Design von **tiefen Modulen** ein – Module mit viel Verhalten hinter einer kleinen Schnittstelle. Sie ist für Entwickler und KI-Agenten gedacht, die Code entwerfen, umstrukturieren oder testbarer machen, sowie die Navigation durch eine Codebasis verbessern möchten. Die Fähigkeit definiert Kernbegriffe wie Modul, Schnittstelle, Tiefe, Naht und Adapter und hebt deren konsequente Verwendung hervor, anstelle von mehrdeutigen Begriffen wie Komponente, Dienst, API oder Grenze. Sie bietet visuelle Diagramme für tiefe vs. flache Module, praktische Prinzipien (z. B. den Löschtest), Entwurfsrichtlinien für Testbarkeit und klare Beziehungen zwischen den Begriffen. Sie bezieht sich auf ergänzende Dokumente (DEEPENING.md und DESIGN-IT-TWICE.md) für fortgeschrittene Techniken und lehnt irreführende Definitionen von Tiefe als Codezeilenverhältnis ab. Diese Fähigkeit ist sprachunabhängig und auf jede Codebasis anwendbar, in der modulare Gestaltung wichtig ist.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht codebase-design?

Entwerfe tiefe Module: viel Verhalten hinter einer kleinen Schnittstelle, platziert an einer sauberen Naht, testbar durch diese Schnittstelle. Verwende diese Sprache und diese Prinzipien überall dort, wo Code entworfen oder umstrukturiert wird. Das Ziel: Hebelwirkung für Aufrufer, Lokalität für Betreuer und Testbarkeit für alle.

Glossar

Verwende diese Begriffe exakt – ersetze sie nicht durch „Komponente“, „Dienst“, „API“ oder „Grenze“. Konsequente Sprache ist der springende Punkt.

Modul — alles mit einer Schnittstelle und einer Implementierung. Bewusst skalierungsneutral: eine Funktion, Klasse, ein Paket oder ein systemübergreifender Abschnitt. Vermeide: Einheit, Komponente, Dienst.

Schnittstelle — alles, was ein Aufrufer wissen muss, um das Modul korrekt zu verwenden: die Typsignatur, aber auch Invarianten, Reihenfolge-Einschränkungen, Fehlermodi, erforderliche Konfiguration und Leistungsmerkmale. Vermeide: API, Signatur (zu eng – beziehen sich nur auf die Typebene).

Implementierung — was sich in einem Modul befindet, sein Codekörper. Unterscheide sie vom Adapter: Ein Ding kann ein kleiner Adapter mit einer großen Implementierung sein (ein Postgres-Repo) oder ein großer Adapter mit einer kleinen Implementierung (ein In-Memory-Fake). Verwende „Adapter“, wenn die Naht das Thema ist; sonst „Implementierung“.

Tiefe — Hebelwirkung an der Schnittstelle: die Menge an Verhalten, die ein Aufrufer (oder Test) pro Einheit Schnittstelle, die er lernen muss, ausüben kann. Ein Modul ist tief, wenn eine große Menge an Verhalten hinter einer kleinen Schnittstelle sitzt, und flach, wenn die Schnittstelle fast so komplex ist wie die Implementierung.

Naht (Michael Feathers) — ein Ort, an dem du Verhalten ändern kannst, ohne an diesem Ort zu bearbeiten; der Ort, an dem die Schnittstelle eines Moduls lebt. Wo die Naht platziert wird, ist eine eigene Designentscheidung, die von dem, was dahinter liegt, zu unterscheiden ist. Vermeide: Grenze (überladen mit dem DDD-Bounded Context).

Adapter — ein konkretes Ding, das eine Schnittstelle an einer Naht erfüllt. Beschreibt die Rolle (welchen Slot es füllt), nicht die Substanz (was darin steckt).

Hebelwirkung — was Aufrufer von der Tiefe bekommen: mehr Fähigkeit pro Einheit Schnittstelle, die sie lernen. Eine Implementierung zahlt sich über N Aufrufstellen und M Tests aus.

Lokalität — was Betreuer von der Tiefe bekommen: Änderungen, Fehler, Wissen und Überprüfung konzentrieren sich an einem Ort, anstatt sich über Aufrufer zu verteilen. Einmal repariert, überall repariert.

Tief vs. flach

Tiefes Modul = kleine Schnittstelle + viel Implementierung:

┌─────────────────────┐
│   Kleine Schnittst. │  ← Wenige Methoden, einfache Parameter
├─────────────────────┤
│                     │
│  Tiefe Implement.    │  ← Komplexe Logik versteckt
│                     │
└─────────────────────┘

Flaches Modul = große Schnittstelle + wenig Implementierung (vermeiden):

┌─────────────────────────────────┐
│       Große Schnittstelle       │  ← Viele Methoden, komplexe Parameter
├─────────────────────────────────┤
│  Dünne Implementierung          │  ← Leitet nur weiter
└─────────────────────────────────┘

Frage beim Entwerfen einer Schnittstelle:

  • Kann ich die Anzahl der Methoden reduzieren?
  • Kann ich die Parameter vereinfachen?
  • Kann ich mehr Komplexität im Inneren verstecken?

Prinzipien

  • Tiefe ist eine Eigenschaft der Schnittstelle, nicht der Implementierung. Ein tiefes Modul kann intern aus kleinen, testbaren, austauschbaren Teilen bestehen – sie sind nur nicht Teil der Schnittstelle. Ein Modul kann interne Nähte (privat in seiner Implementierung, von eigenen Tests verwendet) sowie die externe Naht an seiner Schnittstelle haben.
  • Der Löschtest. Stell dir vor, das Modul zu löschen. Wenn die Komplexität verschwindet, war es ein Durchgang. Wenn die Komplexität bei N Aufrufern wieder auftaucht, hat es seinen Wert verdient.
  • Die Schnittstelle ist die Testoberfläche. Aufrufer und Tests überschreiten dieselbe Naht. Wenn du an der Schnittstelle vorbei testen möchtest, hat das Modul wahrscheinlich die falsche Form.
  • Ein Adapter bedeutet eine hypothetische Naht. Zwei Adapter bedeuten eine echte Naht. Führe keine Naht ein, es sei denn, etwas variiert tatsächlich über sie hinweg.

Entwurf für Testbarkeit

Gute Schnittstellen machen das Testen natürlich:

  1. Abhängigkeiten akzeptieren, nicht erzeugen.

    // Testbar
    function processOrder(order, paymentGateway) {}
    
    // Schwer zu testen
    function processOrder(order) {
      const gateway = new StripeGateway();
    }
    
  2. Ergebnisse zurückgeben, keine Seiteneffekte erzeugen.

    // Testbar
    function calculateDiscount(cart): Discount {}
    
    // Schwer zu testen
    function applyDiscount(cart): void {
      cart.total -= discount;
    }
    
  3. Kleine Oberfläche. Weniger Methoden = weniger benötigte Tests. Weniger Parameter = einfachere Testeinrichtung.

Beziehungen

  • Ein Modul hat genau eine Schnittstelle (die Oberfläche, die es Aufrufern und Tests präsentiert).
  • Tiefe ist eine Eigenschaft eines Moduls, gemessen an seiner Schnittstelle.
  • Eine Naht ist der Ort, an dem die Schnittstelle eines Moduls lebt.
  • Ein Adapter sitzt an einer Naht und erfüllt die Schnittstelle.
  • Tiefe erzeugt Hebelwirkung für Aufrufer und Lokalität für Betreuer.

Abgelehnte Definitionen

  • Tiefe als Verhältnis von Implementierungszeilen zu Schnittstellenzeilen (Ousterhout): belohnt das Aufblähen der Implementierung. Wir verwenden stattdessen Tiefe als Hebelwirkung.
  • „Schnittstelle“ als das TypeScript-Schlüsselwort interface oder die öffentlichen Methoden einer Klasse: zu eng – die Schnittstelle umfasst hier jede Tatsache, die ein Aufrufer wissen muss.
  • „Grenze“: überladen mit dem DDD-Bounded Context. Sage Naht oder Schnittstelle.

Tiefer gehen

  • Vertiefen eines Clusters unter Berücksichtigung seiner Abhängigkeiten – siehe DEEPENING.md: Abhängigkeitskategorien, Nahtdisziplin und „Ersetzen statt Schichten“-Testen.
  • Erkundung alternativer Schnittstellen – siehe DESIGN-IT-TWICE.md: parallele Sub-Agenten starten, um die Schnittstelle auf mehrere radikal unterschiedliche Weisen zu entwerfen und dann hinsichtlich Tiefe, Lokalität und Nahtplatzierung zu vergleichen.

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.

Verwandte Skills