mattpocock/codebase-design

Vocabulário compartilhado para projetar módulos profundos. Use quando o usuário quiser projetar ou melhorar a interface de um módulo, encontrar oportunidades de aprofundamento, decidir onde colocar uma junta, tornar o código mais testável ou navegável por IA, ou quando outra habilidade precisar do vocabulário de módulo profundo.

O que é codebase-design?

Esta habilidade fornece um vocabulário e princípios precisos para projetar *módulos profundos* – módulos com uma interface pequena e uma implementação rica, colocados em uma junta limpa e testáveis através dessa interface. Ela define termos como Módulo, Interface, Implementação, Profundidade, Junta, Adaptador, Alavancagem e Localidade, e explica como esses conceitos se relacionam para criar código com alta coesão e baixo acoplamento. A habilidade é agnóstica em relação à escala e se aplica a funções, classes, pacotes e fatias que abrangem camadas, sendo útil para desenvolvedores que trabalham com TypeScript, Python, Rust, Go, Java ou C#. O fluxo de trabalho envolve analisar a interface atual de um módulo, aplicar o teste de exclusão, explorar alternativas de design (como descrito em DESIGN-IT-TWICE.md) e aprofundar o módulo movendo complexidade para dentro da implementação (conforme DEEPENING.md). A habilidade suporta a criação de módulos que oferecem alavancagem para chamadores e localidade para mantenedores, resultando em código mais fácil de testar, modificar e navegar por agentes de IA.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Projeto de Código (Codebase Design)

Projete módulos profundos: muito comportamento por trás de uma interface pequena, colocada em uma junta limpa, testável através dessa interface. Use esta linguagem e estes princípios sempre que o código estiver sendo projetado ou reestruturado. O objetivo é alavancagem para os chamadores, localidade para os mantenedores e testabilidade para todos.

Glossário

Use estes termos exatamente — não substitua por "componente", "serviço", "API" ou "fronteira". Uma linguagem consistente é o ponto principal.

Módulo — qualquer coisa com uma interface e uma implementação. Deliberadamente agnóstico em relação à escala: uma função, classe, pacote ou fatia que atravessa camadas. Evite: unidade, componente, serviço.

Interface — tudo o que um chamador precisa saber para usar o módulo corretamente: a assinatura de tipo, mas também invariantes, restrições de ordenação, modos de erro, configuração necessária e características de desempenho. Evite: API, assinatura (muito estreitos — referem-se apenas à superfície de tipo).

Implementação — o que está dentro de um módulo, seu corpo de código. Distinto de Adaptador: uma coisa pode ser um pequeno adaptador com uma grande implementação (um repositório Postgres) ou um grande adaptador com uma pequena implementação (um fake em memória). Use "adaptador" quando a junta for o tópico; "implementação" caso contrário.

Profundidade — alavancagem na interface: a quantidade de comportamento que um chamador (ou teste) pode exercer por unidade de interface que precisa aprender. Um módulo é profundo quando uma grande quantidade de comportamento está por trás de uma interface pequena, e raso quando a interface é quase tão complexa quanto a implementação.

Junta (Michael Feathers) — um lugar onde você pode alterar o comportamento sem editar naquele lugar; a localização onde a interface de um módulo reside. Onde colocar a junta é uma decisão de projeto em si, distinta do que fica por trás dela. Evite: fronteira (sobrecarregado com o contexto limitado do DDD).

Adaptador — uma coisa concreta que satisfaz uma interface em uma junta. Descreve o papel (qual slot ele preenche), não a substância (o que está dentro).

Alavancagem — o que os chamadores obtêm da profundidade: mais capacidade por unidade de interface que aprendem. Uma implementação retorna o investimento em N locais de chamada e M testes.

Localidade — o que os mantenedores obtêm da profundidade: mudança, bugs, conhecimento e verificação concentram-se em um lugar em vez de se espalhar pelos chamadores. Corrija uma vez, corrigido em todos os lugares.

Profundo vs Raso

Módulo profundo = interface pequena + muita implementação:

┌─────────────────────┐
│   Interface Pequena │  ← Poucos métodos, parâmetros simples
├─────────────────────┤
│                     │
│  Implementação      │  ← Lógica complexa oculta
│  Profunda           │
│                     │
└─────────────────────┘

Módulo raso = interface grande + pouca implementação (evite):

┌─────────────────────────────────┐
│       Interface Grande          │  ← Muitos métodos, parâmetros complexos
├─────────────────────────────────┤
│  Implementação Fina             │  ← Apenas repassa
└─────────────────────────────────┘

Ao projetar uma interface, pergunte:

  • Posso reduzir o número de métodos?
  • Posso simplificar os parâmetros?
  • Posso ocultar mais complexidade internamente?

Princípios

  • Profundidade é uma propriedade da interface, não da implementação. Um módulo profundo pode ser internamente composto de partes pequenas, simuláveis e trocáveis — elas simplesmente não fazem parte da interface. Um módulo pode ter juntas internas (privadas à sua implementação, usadas por seus próprios testes) além da junta externa em sua interface.
  • O teste de exclusão. Imagine excluir o módulo. Se a complexidade desaparecer, era um repasse. Se a complexidade reaparecer em N chamadores, o módulo estava valendo a pena.
  • A interface é a superfície de teste. Chamadores e testes cruzam a mesma junta. Se você quiser testar além da interface, o módulo provavelmente tem o formato errado.
  • Um adaptador significa uma junta hipotética. Dois adaptadores significam uma junta real. Não introduza uma junta a menos que algo realmente varie através dela.

Projetando para testabilidade

Interfaces boas tornam o teste natural:

  1. Aceite dependências, não as crie.

    // Testável
    function processOrder(order, paymentGateway) {}
    
    // Difícil de testar
    function processOrder(order) {
      const gateway = new StripeGateway();
    }
    
  2. Retorne resultados, não produza efeitos colaterais.

    // Testável
    function calculateDiscount(cart): Discount {}
    
    // Difícil de testar
    function applyDiscount(cart): void {
      cart.total -= discount;
    }
    
  3. Pequena área de superfície. Menos métodos = menos testes necessários. Menos parâmetros = configuração de teste mais simples.

Relacionamentos

  • Um Módulo tem exatamente uma Interface (a superfície que apresenta a chamadores e testes).
  • Profundidade é uma propriedade de um Módulo, medida em relação à sua Interface.
  • Uma Junta é onde a Interface de um Módulo reside.
  • Um Adaptador está em uma Junta e satisfaz a Interface.
  • Profundidade produz Alavancagem para chamadores e Localidade para mantenedores.

Enquadramentos rejeitados

  • Profundidade como proporção de linhas de implementação para linhas de interface (Ousterhout): recompensa o preenchimento da implementação. Usamos profundidade como alavancagem.
  • "Interface" como a palavra-chave interface do TypeScript ou métodos públicos de uma classe: muito estreito — interface aqui inclui todo fato que um chamador precisa saber.
  • "Fronteira": sobrecarregado com o contexto limitado do DDD. Diga junta ou interface.

Aprofundando

  • Aprofundando um cluster dadas suas dependências — veja DEEPENING.md: categorias de dependência, disciplina de junta e teste de substituir em vez de em camadas.
  • Explorando interfaces alternativas — veja DESIGN-IT-TWICE.md: crie subagentes paralelos para projetar a interface de várias maneiras radicalmente diferentes, depois compare com base em profundidade, localidade e posicionamento da junta.

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.

Habilidades Relacionadas