Guía de inicio de mattpocock Skills: haz que la IA aprenda TDD y depuración estructurada

Introducción al proyecto

mattpocock/skills es un paquete de “habilidades de metodología de ingeniería” para herramientas de programación con IA. Su punto de partida es muy simple: las herramientas de programación con IA son rápidas, pero eso no significa que sean fiables.

Matt Pocock descubrió, tras muchas prácticas, que la programación con IA falla con mucha frecuencia por cuatro patrones:

• Desalineación de requisitos: tú crees que la IA lo entiende, pero en realidad se desvía
• Salida demasiado redundante: la IA usa 20 palabras para explicar algo que cabría en 1
• El código no funciona: sin un ciclo de realimentación, la IA escribe a ciegas en una caja negra
• La arquitectura se degrada rápido: la IA acelera el desarrollo, pero también acelera el incremento de entropía del software

Estos cuatro problemas no son bugs de la herramienta, sino la ausencia de metodología. mattpocock/skills ataca la causa: comprime décadas de experiencia de ingeniería en un conjunto de habilidades (Skills) componibles, para que la IA imponga la misma disciplina de ingeniería en cualquier modelo.

Dificultad / Duración / Resultados

Dificultad: Nivel principiante — no necesitas experiencia con TDD; solo saber usar la línea de comandos y una herramienta de programación con IA
Duración: unos 30 minutos para recorrer todo el flujo de principio a fin
Resultados: construir un flujo de trabajo completo de alineación de requisitos → TDD impulsado por pruebas → depuración estructurada → reflexión sobre la arquitectura

Perfil de lectores objetivo

• Desarrolladores backend / full-stack con 1 a 5 años de experiencia
• Ya has usado Claude Code, Codex u herramientas similares de programación con IA
• Sientes que el código generado por IA “se puede usar pero es inestable” y quieres establecer un ritmo de desarrollo controlado
• Te interesa TDD, pero no has encontrado una forma adecuada de empezar

Dependencias principales y entorno

Estructura completa del proyecto (árbol)

skills/
├── CLAUDE.md                          # Especificación de normas para el directorio de Skills
├── README.md                          # Visión general y documentación de uso
├── skills/
│   ├── engineering/
│   │   ├── diagnose/
│   │   │   └── SKILL.md               # Flujo de depuración estructurada
│   │   ├── grill-with-docs/
│   │   │   └── SKILL.md               # Entrevista en profundidad con documentación
│   │   ├── improve-codebase-architecture/
│   │   │   └── SKILL.md               # Diagnóstico para mejora de arquitectura
│   │   ├── setup-matt-pocock-skills/
│   │   │   └── SKILL.md               # Punto de entrada para inicializar configuración
│   │   ├── tdd/
│   │   │   ├── SKILL.md               # Flujo de trabajo de TDD por cortes verticales
│   │   │   ├── tests.md               # Ejemplos de pruebas buenas / malas
│   │   │   ├── mocking.md             # Mejores prácticas para Mock
│   │   │   ├── refactoring.md         # Cuándo decidir refactorizar
│   │   │   ├── deep-modules.md        # Principios de diseño para módulos profundos
│   │   │   └── interface-design.md    # Diseño de interfaces que se puedan testear
│   │   ├── to-issues/
│   │   │   └── SKILL.md               # Descomponer requisitos en GitHub Issues
│   │   ├── to-prd/
│   │   │   └── SKILL.md               # Generación de PRD
│   │   ├── triage/
│   │   │   └── SKILL.md               # Máquina de estados para el enrutado de Issues
│   │   └── zoom-out/
│   │       └── SKILL.md               # Lectura con perspectiva global del código
│   ├── productivity/
│   │   ├── caveman/
│   │   │   └── SKILL.md               # Modo de comunicación comprimida (ahorra 75% de tokens)
│   │   ├── grill-me/
│   │   │   └── SKILL.md               # Entrevista en profundidad sobre requisitos
│   │   └── write-a-skill/
│   │       └── SKILL.md               # Guía para escribir Skills personalizadas
│   └── misc/
│       ├── git-guardrails-claude-code/
│       │   └── SKILL.md               # Barandillas de seguridad para Git
│       └── scaffold-exercises/
│           └── SKILL.md               # Andamiaje de directorios para ejercicios
└── .claude-plugin/
    └── plugin.json                    # Metadatos del plugin

Pasos guiados

Paso 1: instala mattpocock Skills

En cualquier herramienta de programación con IA que admita Skills, ejecuta el siguiente comando para completar la instalación:

npx skills@latest add mattpocock/skills

El script de instalación te guiará para elegir qué Skills activar y a qué herramienta de IA se vinculan esas Skills. Paso clave: confirma la opción /setup-matt-pocock-skills; esta será la entrada de inicialización para todas las Skills posteriores.

Paso 2: inicializa la configuración

Una vez completada la instalación, en la herramienta de programación con IA ejecuta:

/setup-matt-pocock-skills

Esta Skill te preguntará, una tras otra:

1. Issue Tracker: qué herramienta usas para gestionar Issues (GitHub / Linear / archivo local)
2. Triage Labels: qué palabras usar cuando etiquetes un Issue (/triage usará esta información)
3. Ruta de guardado de documentación: dónde se colocarán los ADR y los documentos generados

Tras completar la configuración, se generará un CONTEXT.md en la raíz del proyecto, que funcionará como un “diccionario compartido de lenguaje” entre tú y la IA. Este archivo es muy importante: unifica la forma en que se usan los términos en el proyecto; a partir de él, la IA basará todas sus posteriores nominaciones y comentarios.

Paso 3: alinea requisitos con /grill-me

Cuando tengas un requisito nuevo o un diseño que quieras que la IA prepare, no empieces directamente. Primero ejecuta:

/grill-me

La IA te hará preguntas una por una, enumerando cada rama del árbol de decisiones. Por ejemplo, si vas a “agregar funcionalidad de reembolsos al módulo de pagos”, la IA te preguntará:

• ¿El reembolso es total o parcial?
• ¿Cuáles son las condiciones para activar el reembolso (iniciado por el usuario / automático por riesgo / manual por soporte)?
• ¿Cómo se maneja el inventario después del reembolso?
• ¿Se debe persistir el registro de reembolsos?

Cada pregunta vendrá con una recomendación de respuesta, tú solo necesitas confirmarla o corregirla. Este proceso es como una entrevista estructurada: asegura que la IA entienda realmente lo que quieres hacer, y no se desvíe por interpretación literal.

Paso 4: prueba por cortes verticales con /tdd

Después de alinear requisitos, pasas a la fase de desarrollo. Aquí está la parte más central de mattpocock/skills — prohibidos los cortes horizontales.

¿Qué es un corte horizontal? Primero escribir todas las pruebas, y luego escribir todo el código. Este es el gran punto ciego de TDD; la IA es especialmente propensa a hacerlo, y el resultado es que las pruebas “prueban una conducta imaginada”, no la conducta real.

La forma correcta: hacer solo un corte vertical a la vez.

RED:   Escribe una prueba que describa el primer comportamiento → la prueba falla
GREEN: Escribe el código mínimo para que pase la prueba → prueba pasa
REFACTOR: Refactoriza (opcional)

Repite este ciclo. Cada vez que la IA termina una prueba, ya “ha visto” esa parte de la implementación, por lo que la prueba valida comportamiento real, no comportamiento previsto.

Miremos un ejemplo concreto: supongamos que queremos implementar una funcionalidad de checkout para un carrito.

// Primera ronda: solo probamos “el carrito puede agregar un producto”
import { describe, it, expect } from 'vitest';
import { Cart } from './cart';

describe('Cart', () => {
  it('allows adding an item', () => {
    const cart = new Cart();
    cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
    expect(cart.items).toHaveLength(1);
  });
});

// cart.ts — implementación mínima para que pase la prueba
export interface CartItem {
  id: string;
  name: string;
  price: number;
}

export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }
}

// Segunda ronda: probamos “el carrito puede calcular el total”
it('calculates total price', () => {
  const cart = new Cart();
  cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
  cart.addItem({ id: 'book-2', name: 'React 实战', price: 79 });
  expect(cart.totalPrice()).toBe(138);
});

// cart.ts — agrega el método totalPrice
export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }

  totalPrice(): number {
    return this.items.reduce((sum, item) => sum + item.price, 0);
  }
}

Cada ronda es: prueba falla → pasa con el código mínimo → siguiente ronda. Ese es el ritmo central de los cortes verticales.

Paso 5: depuración estructurada con /diagnose

Cuando el código falla, no le pidas directamente a la IA “arreglarme el bug”. Primero establece un ciclo de realimentación ejecutando:

/diagnose

/diagnose obliga a la IA a completar un ciclo de depuración en seis fases:

¿Por qué es importante este flujo? Porque la forma más común de depurar con IA es “adivinar y cambiar, mirar el resultado; si no, volver a adivinar”. Sin un ciclo de realimentación, esto equivale a lanzar dardos en la oscuridad. /diagnose convierte la depuración en una disciplina de ingeniería, no en magia.

Un escenario típico: supón que tu interfaz de pagos de repente devuelve errores 500:

// Fase 1: construir un ciclo de realimentación — escribe una prueba fallida que aísle la interfaz
import { describe, it, expect } from 'vitest';
import { createHonoServer } from './server';
import fetch from 'node-fetch';

describe('Payment API', () => {
  it('returns 200 for valid checkout', async () => {
    const app = createHonoServer();
    const response = await fetch('http://localhost:3000/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ id: 'book-1', quantity: 1 }],
        userId: 'user-123',
      }),
    });
    expect(response.status).toBe(200); // ahora falla; en realidad devuelve 500
  });
});

En la fase 3 se generará una lista de hipótesis:

1. Si se trata de “timeout del servicio de inventario que causa una excepción no capturada”, entonces mockear el servicio de inventario para que responda con éxito elimina el 500
2. Si se trata de “la transacción de base de datos no se confirma”, entonces revisar que se llame a transaction.commit() revela el problema
3. Si se trata de “un error al parsear el formato de la pasarela de pagos”, entonces validar que el mock de datos de la pasarela reproduce el problema

La IA valida una hipótesis a la vez, en lugar de apilar todos los cambios.

Paso 6: construye una Skill personalizada con /write-a-skill

Cuando acumules un conjunto de flujos de trabajo propios en un proyecto, puedes encapsularlo como una Skill para que la IA la invoque cuando trabajes en ese proyecto:

/write-a-skill

La IA te preguntará, en orden:

1. ¿Qué dominio cubre esta Skill?
2. ¿Cuáles son los escenarios de uso concretos?
3. ¿Necesita incluir scripts o solo comandos?
4. ¿Hay materiales de referencia?

Luego genera una estructura estándar:

my-custom-skill/
├── SKILL.md              # Archivo de instrucciones principales (obligatorio)
├── REFERENCE.md          # Documentación detallada (divide si supera 100 líneas)
├── EXAMPLES.md           # Ejemplos de uso
└── scripts/
    └── helper.ts         # Script de utilidades (opcional)

El campo description de SKILL.md es la única entrada que “ve” la IA para detectar esta Skill; tiene requisitos de formato estrictos:

---
name: my-custom-skill
description: Genera un cliente de API seguro para tipos a partir de un JSON Schema e inyecta datos Mock.
              Use when user mentions "API client", "generate types", or "mock data".
---

La primera frase de description dice “qué hace”; la segunda dice “en qué escenarios se activa”. Usa disparadores para guiar a la IA a cargarla automáticamente.

Solución de problemas (preguntas frecuentes)

1. La IA no ejecuta pruebas y escribe código directamente

Síntoma: llamas a /tdd, pero la IA salta directamente a la implementación y omite la fase RED.

Cómo diagnosticar:

• Verifica que en CONTEXT.md ya estén definidos el framework de pruebas del proyecto y las convenciones de test
• Al empezar /tdd, indica explícitamente “escribe solo una prueba, no otro código”
• Si la IA sigue saltándose la fase, escribe manualmente en la conversación: “primero escribe una prueba fallida” para llevarla de vuelta a RED

Causa raíz: la IA interpreta TDD de forma literal; cree que “escribir pruebas” ya equivale a TDD, y no entiende que “que fallen las pruebas” es la señal en sí.

---

2. Trampa del corte horizontal — escribir todas las pruebas de una vez

Síntoma: la IA genera 10 archivos de prueba de una sola vez en /tdd y luego escribe toda la implementación de una sola vez.

Cómo diagnosticar:

• Intervención directa: dile a la IA “solo escribe el primer test y luego impleméntalo”
• Añade en CONTEXT.md una advertencia de antipatrón: “prohibido el corte horizontal; cada vez, solo un corte vertical”

Causa raíz: la IA se deja llevar por la ilusión de “solucionar todo de golpe”; el corte horizontal le da sensación de completitud, pero el resultado es frágil.

---

3. El ciclo de depuración no tiene señal de realimentación

Síntoma: llamas a /diagnose, pero la IA solo modifica código repetidamente, sin crear una señal de fallo repetible.

Cómo diagnosticar:

• Si la Fase 1 no pasa, no entres en la Fase 2. Dile explícitamente a la IA: “aún no hay una señal de fallo repetible; sigue construyendo el ciclo de realimentación”
• Intenta construir señales end-to-end con node-fetch y peticiones HTTP reales, en lugar de mockear todo el módulo

Causa raíz: el ciclo de realimentación es el núcleo de la depuración; sin él, todas las acciones posteriores son movimientos a ciegas.

---

4. Falla la descripción de la Skill — no se activa automáticamente

Síntoma: escribiste una Skill personalizada, pero la IA no la carga.

Cómo diagnosticar:

• Revisa si esa Skill está registrada en plugin.json
• Confirma que el description incluye disparadores (palabras que el usuario realmente dirá)
• Asegúrate de que el name y description de SKILL.md cumplen los requisitos (YAML frontmatter)

Causa raíz: la carga de Skills depende del emparejamiento de palabras clave dentro del description; si no es preciso, no se activará.

---

5. La entrevista de /grill-me se convierte en un informe en un solo sentido

Síntoma: al ejecutar /grill-me, la IA solo recibe la información que le das y no pregunta de forma proactiva.

Cómo diagnosticar:

• Cuando la IA haga preguntas, explica que está entrando en modo entrevista; sigue respondiendo y no lo cortes
• Si la IA se queda en silencio durante más de 3 rondas, di manualmente: “sigue preguntando, tengo más información”
• La causa suele ser que la IA cree que “ya entendió”, pero en realidad solo entendió literalmente

Causa raíz: la IA tiende a converger rápidamente hacia un estado de “parece entendido”, en lugar de enumerar todas las ramas.

---

6. CONTEXT.md demasiado grande provoca explosión de tokens

Síntoma: a medida que el proyecto avanza, CONTEXT.md crece y crece, y la IA empieza a sufrir desbordes de contexto o responde más lento.

Cómo diagnosticar:

• Refactoriza CONTEXT.md de forma periódica: conserva “los términos generales ya estables” y mueve “registros de decisiones temporales” a la carpeta docs/adr/
• /improve-codebase-architecture puede ayudar a identificar qué contenido debería extraerse desde CONTEXT.md

Causa raíz: CONTEXT.md es un archivo que crece dinámicamente; si no se mantiene, se convertirá en un segundo monorepo.

Lecturas adicionales / Direcciones avanzadas

Extensión de la metodología: Matt Pocock, como defensor del “TypeScript de gimnasia tipográfica”, su curso Total TypeScript es un complemento excelente para entender el desarrollo guiado por tipos.

De TDD a mejora de arquitectura: cuando tu base de código haya pasado por varias rondas de refactor con TDD, puedes usar /improve-codebase-architecture para hacer un diagnóstico de arquitectura. Se basa en el lenguaje de dominio del CONTEXT.md y en los registros de decisiones dentro de docs/adr/ para identificar “módulos superficiales” (interfaces complejas pero con poca funcionalidad) y oportunidades de refactor.

Ecosistema de Skills personalizadas: la filosofía de diseño de mattpocock/skills es “pequeño y componible”. No necesariamente tienes que instalar todas las Skills que ofrece: puedes instalar solo /tdd y /diagnose, e ir introduciendo gradualmente en el desarrollo diario. En la comunidad también hay otros desarrolladores que han construido conjuntos de Skills con este marco; merece la pena prestarles atención.