CommunityProgramación y desarrollogithub.com

Diseño de Codebase

Vocabulario compartido para diseñar módulos profundos. Úsalo cuando quieras diseñar o mejorar la interfaz de un módulo, encontrar oportunidades de profundización, decidir dónde colocar un seam, hacer el código más testeable o navegable por IA, o cuando otra habilidad necesite el vocabulario de módulo profundo.

¿Qué es Diseño de Codebase?

Esta habilidad proporciona un vocabulario preciso y principios para diseñar módulos profundos en el código, basándose en conceptos de John Ousterhout y Michael Feathers. Se enfoca en lograr módulos con una interfaz pequeña pero una implementación rica, lo que maximiza el apalancamiento para los llamadores y la localidad para los mantenedores. La habilidad es neutral en cuanto a escala y tecnología, aplicable a funciones, clases, paquetes o slices que cruzan capas, y se puede utilizar en cualquier flujo de trabajo de diseño o reestructuración de código. Soporta plataformas como Claude Code, Cursor y Codex, y su documentación incluye una guía detallada sobre los términos del glosario, principios de diseño, técnicas para mejorar la testabilidad y enlaces a recursos adicionales como DEEPENING.md y DESIGN-IT-TWICE.md.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Diseño de Codebase?

Diseña módulos profundos: mucho comportamiento detrás de una interfaz pequeña, colocada en un seam limpio, testeable a través de esa interfaz. Usa este lenguaje y estos principios dondequiera que se diseñe o reestructure código. El objetivo es apalancamiento para los llamadores, localidad para los mantenedores y testabilidad para todos.

Glosario

Usa estos términos exactamente — no sustituyas "componente", "servicio", "API" o "límite". El lenguaje consistente es el punto central.

Módulo — cualquier cosa con una interfaz y una implementación. Deliberadamente independiente de escala: una función, clase, paquete o slice que cruza capas. Evita: unidad, componente, servicio.

Interfaz — todo lo que un llamador debe saber para usar el módulo correctamente: la firma de tipos, pero también invariantes, restricciones de orden, modos de error, configuración requerida y características de rendimiento. Evita: API, firma (demasiado estrechos — se refieren solo a la superficie de tipos).

Implementación — lo que está dentro de un módulo, su cuerpo de código. Distinto de Adaptador: una cosa puede ser un adaptador pequeño con una implementación grande (un repositorio Postgres) o un adaptador grande con una implementación pequeña (un fake en memoria). Recurre a "adaptador" cuando el seam sea el tema; "implementación" en caso contrario.

Profundidad — apalancamiento en la interfaz: la cantidad de comportamiento que un llamador (o una prueba) puede ejercer por unidad de interfaz que tiene que aprender. Un módulo es profundo cuando una gran cantidad de comportamiento se encuentra detrás de una interfaz pequeña, y superficial cuando la interfaz es casi tan compleja como la implementación.

Seam (Michael Feathers) — un lugar donde puedes alterar el comportamiento sin editar en ese lugar; la ubicación donde vive la interfaz de un módulo. Dónde poner el seam es una decisión de diseño en sí misma, distinta de lo que hay detrás. Evita: límite (sobrecargado por el contexto delimitado de DDD).

Adaptador — una cosa concreta que satisface una interfaz en un seam. Describe el rol (qué hueco llena), no la sustancia (lo que hay dentro).

Apalancamiento — lo que los llamadores obtienen de la profundidad: más capacidad por unidad de interfaz que aprenden. Una implementación se amortiza a través de N sitios de llamada y M pruebas.

Localidad — lo que los mantenedores obtienen de la profundidad: el cambio, los bugs, el conocimiento y la verificación se concentran en un lugar en lugar de extenderse entre los llamadores. Arreglado una vez, arreglado en todas partes.

Profundo vs superficial

Módulo profundo = interfaz pequeña + mucha implementación:

┌─────────────────────┐
│   Interfaz Pequeña  │  ← Pocos métodos, parámetros simples
├─────────────────────┤
│                     │
│ Implementación      │  ← Lógica compleja oculta
│ Profunda            │
│                     │
└─────────────────────┘

Módulo superficial = interfaz grande + poca implementación (evitar):

┌─────────────────────────────────┐
│      Interfaz Grande            │  ← Muchos métodos, parámetros complejos
├─────────────────────────────────┤
│  Implementación Fina            │  ← Solo pasa a través
└─────────────────────────────────┘

Al diseñar una interfaz, pregúntate:

  • ¿Puedo reducir el número de métodos?
  • ¿Puedo simplificar los parámetros?
  • ¿Puedo ocultar más complejidad en el interior?

Principios

  • La profundidad es una propiedad de la interfaz, no de la implementación. Un módulo profundo puede estar compuesto internamente por partes pequeñas, simulables e intercambiables — simplemente no forman parte de la interfaz. Un módulo puede tener seams internos (privados a su implementación, usados por sus propias pruebas) así como el seam externo en su interfaz.
  • La prueba de eliminación. Imagina eliminar el módulo. Si la complejidad desaparece, era un paso a través. Si la complejidad reaparece en N llamadores, estaba ganando su lugar.
  • La interfaz es la superficie de prueba. Los llamadores y las pruebas cruzan el mismo seam. Si quieres probar más allá de la interfaz, probablemente el módulo tenga la forma incorrecta.
  • Un adaptador significa un seam hipotético. Dos adaptadores significan uno real. No introduzcas un seam a menos que algo realmente varíe a través de él.

Diseñando para la testabilidad

Las buenas interfaces hacen que las pruebas sean naturales:

  1. Acepta dependencias, no las crees.

    // Testeable
    function procesarPedido(pedido, pasarelaPago) {}
    
    // Difícil de testear
    function procesarPedido(pedido) {
      const pasarela = new PasarelaStripe();
    }
    
  2. Devuelve resultados, no produzcas efectos secundarios.

    // Testeable
    function calcularDescuento(carrito): Descuento {}
    
    // Difícil de testear
    function aplicarDescuento(carrito): void {
      carrito.total -= descuento;
    }
    
  3. Área de superficie pequeña. Menos métodos = menos pruebas necesarias. Menos parámetros = configuración de prueba más simple.

Relaciones

  • Un Módulo tiene exactamente una Interfaz (la superficie que presenta a los llamadores y las pruebas).
  • La Profundidad es una propiedad de un Módulo, medida contra su Interfaz.
  • Un Seam es donde vive la Interfaz de un Módulo.
  • Un Adaptador se sienta en un Seam y satisface la Interfaz.
  • La Profundidad produce Apalancamiento para los llamadores y Localidad para los mantenedores.

Enfoques rechazados

  • Profundidad como ratio de líneas de implementación a líneas de interfaz (Ousterhout): recompensa inflar la implementación. Usamos profundidad-como-apalancamiento en su lugar.
  • "Interfaz" como la palabra clave interface de TypeScript o los métodos públicos de una clase: demasiado estrecho — la interfaz aquí incluye todos los hechos que un llamador debe conocer.
  • "Límite": sobrecargado con el contexto delimitado de DDD. Di seam o interfaz.

Profundizando más

  • Profundizar un clúster dadas sus dependencias — consulta DEEPENING.md: categorías de dependencia, disciplina de seam y pruebas de reemplazar-no-apilar.
  • Explorando interfaces alternativas — consulta DESIGN-IT-TWICE.md: inicia subagentes paralelos para diseñar la interfaz de varias formas radicalmente diferentes, luego compara en profundidad, localidad y colocación del 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.

Skills relacionados