Mapa de la ruta
🧭 Por qué existen las skills
Los 4 problemas que matan los proyectos con agentes
🔥 Grilling: alineación
Deja de adivinar lo que quieres
📖 Lenguaje ubicuo
1 palabra en lugar de 20
✅ Código que funciona
Red, green, refactor: con el agente a tu lado
🏗️ Arquitectura saludable
Salir de la bola de barro sin refactorizar todo
🔄 Flujo de trabajo completo
De la idea al PR mergeado
Contenido detallado
🧭 Por qué existen las skills
Los 4 problemas que matan los proyectos con agentes — y cómo las skills abordan cada uno.
Paquete estructurado (SKILL.md + scripts + refs) que el agente carga bajo demanda para realizar un trabajo específico.
Sin skills, repites el contexto en cada sesión. Con skills, el conocimiento queda versionado, se puede probar y reutilizar.
SKILL.md, frontmatter, activadores, referencias, scripts y alcance único.
Brecha entre lo que pediste y lo que entendió el agente: genera retrabajo silencioso.
Es la causa #1 de «el agente no funciona». Reconocerla a tiempo evita horas de código equivocado.
Ambigüedad, premisas implícitas, falta de ejemplos, alcance difuso.
El exceso de palabras, la repetición y el ruido en el prompt degradan la precisión del agente.
El lenguaje ubicuo condensa la intención. 1 término bien definido vale 20 líneas de explicación.
Presupuesto de tokens, ruido frente a señal, terminología compartida.
Código generado sin pruebas activas: parece funcionar, pero falla en casos límite.
El TDD con un agente transforma «espero que funcione» en «demuestra que funciona».
Red/green/refactor, vertical slice, prueba de regresión.
Codebase sin límites claros: cualquier cambio rompe cosas en otras partes.
Los agentes amplifican el acoplamiento deficiente. Las skills de arquitectura combaten la entropía.
Acoplamiento, límites, ADRs, mejora progresiva.
Sistema de skills de Matt Pocock — grill, ubiqua, tdd, arquitetura — encadenadas en el workflow.
Entender el mapa antes que los detalles acelera la adopción y evita el uso aislado.
Composición, orden de uso, slash commands, agentic OS.
🔥 Grilling: alineación con el agente
Deja de adivinar lo que quieres: deja que el agente pregunte primero.
Técnica en la que el agente hace preguntas incisivas antes de programar: extrae requisitos ocultos.
Evita semanas de retrabajo. 30min de grilling ahorran 5h de código equivocado.
Cuestionamiento adversarial, premisas, alcance, criterios de aceptación.
/grill-me ataca la idea en bruto; /grill-with-docs confronta el plan con CONTEXT.md y los ADRs del proyecto.
Usar el modo equivocado desperdicia el grilling. Cada uno tiene su propio activador.
Idea en bruto, plan maduro, documento de referencia, ADR.
Desencadenantes: funcionalidad ambigua, decisión arquitectónica, conflicto de equipo, pre-PRD.
Saber CUÁNDO grilling aporta valor evita usarlo cuando no hace falta.
Heurísticas de desencadenantes, costo/beneficio, momento adecuado.
Transcripción anotada de una sesión /grill-me que transforma una idea vaga en un PRD práctico.
Ver en la práctica qué es una buena pregunta frente a una respuesta evasiva.
Drill-down, contraejemplo, materialización de premisas.
Grilling superficial, preguntas retóricas, un agente que siempre está de acuerdo: señal de una sesión desperdiciada.
Detectarlo pronto evita la ilusión de alineación.
Sycophancy, preguntas cerradas, anclaje.
Un Grilling terminado se convierte en PRD mediante /to-prd, sin perder contexto.
Conecta la alineación con la ejecución. Se acabó eso de «hice grilling y lo perdí todo».
PRD, criterios de aceptación, vertical slices, handoff.
📖 Lenguaje ubicuo: CONTEXT.md + ADRs
1 palabra en lugar de 20 — terminología compartida entre tú y el agente.
Vocabulario compartido entre dominio, código y agente: mismo término, mismo significado.
Reduce la traducción mental. "Materialization cascade" equivale a un párrafo de explicación.
DDD, bounded context, glosario vivo, conceptos del dominio.
Documento raíz con dominio, conceptos, fronteras y términos — leído por el agente en todo contexto.
Sin CONTEXT.md, el agente vuelve a aprender tu dominio en cada sesión.
Secciones obligatorias, glosario, límites, ejemplos.
Registro breve e inmutable de cada decisión arquitectónica: contexto, opciones, elección y consecuencias.
Evita repetir una decisión antigua sin saberlo. El agente respeta las restricciones documentadas.
Decisión, contexto, alternativas, estado, consecuencia.
Caso real de Matt: término acuñado una vez en el CONTEXT.md y reutilizado en decenas de prompts.
Ver el beneficio concreto de la compactación mediante vocabulario.
Compresión semántica, reutilización de términos, intención densa.
Rutina de actualizar CONTEXT.md y los ADR en cada PR relevante: no dejar que se convierta en arqueología.
Un documento desactualizado es peor que no tener documento.
Docs-as-code, drift, gates de PR.
Métricas que comparan antes y después de adoptar un lenguaje ubicuo: tokens, tiempo de sesión, bugs.
Justificar la adopción ante el equipo con números, no opiniones.
Consumo de tokens, lead time, retrabajo, NPS de desarrolladores.
✅ Código que funciona: TDD + Diagnose
Red, green, refactor: con el agente a tu lado. Y cuando algo falla, /diagnose.
TDD usado como contrato entre tú y el agente: prueba antes que código.
Sin empezar por la prueba, el agente «alucina» el comportamiento. Con una prueba, el comportamiento se puede verificar.
Contrato ejecutable, ciclo de retroalimentación, criterios objetivos.
Slash command que orquesta el ciclo TDD con el agente: genera una prueba, la ejecuta, implementa y refactoriza.
Estandariza la calidad. Cada feature nace con una prueba aprobada.
Ciclo, gates y automatización de la refactorización.
Entregar valor mínimo end-to-end cada vez — UI, API, base de datos — en vez de trabajar en capas horizontales.
Permite TDD real. Cada slice se puede probar por separado.
Slice, walking skeleton, MVP, incremento comprobable.
Una skill que guía la investigación sistemática de un bug: reproduce, minimiza, plantea hipótesis y prueba.
Un bug intermitente sin método se convierte en un bucle infinito. /diagnose impone disciplina.
Hipótesis, observación, aislamiento, falsificación.
Secuencia obligatoria: reproducir el bug, reducir el caso y formular una hipótesis antes de tocar el código.
Omitir un paso genera una corrección que oculta el bug.
MCVE, bisect, falsificación.
Prueba escrita a partir de la reproducción minimizada: garantiza que el bug no vuelva.
Sin una prueba de regresión, pagas por el mismo bug 3 veces al año.
Captura, fixture, pruebas de mutación.
🏗️ Arquitectura saludable
Salir de la bola de barro sin refactorizar todo — mejora progresiva guiada por un agente.
Señales: cambiar 1 línea rompe 3 features distantes, nadie sabe dónde está algo, miedo a hacer cambios.
El diagnóstico va antes del tratamiento. Si no identificas los síntomas, tratas el síntoma equivocado.
Acoplamiento, cohesión, límites, shotgun surgery.
Una skill que escanea el código, identifica hotspots y propone mejoras priorizadas.
Sustituye la "refactorización de big bang" por intervenciones quirúrgicas.
Hotspot, priorización, cambio seguro.
Una skill que abstrae del archivo actual al sistema completo: rompe la visión de túnel.
Una buena decisión local puede ser mala a nivel global. Alejarse obliga a adoptar una visión sistémica.
Macro frente a micro, pensamiento sistémico, impacto en cascada.
Áreas del código donde invertir en modelado genera un retorno desproporcionado.
El tiempo es limitado. Profundizar en el lugar equivocado = pulir los bordes.
Dominio central, ROI del modelado, ventaja.
Usar los documentos de la ruta 1.3 para orientar dónde y cómo mejorar — el agente sigue las restricciones documentadas.
Refactorizar sin rumbo se convierte en gusto personal. Rumbo documentado y auditable.
Restricciones, conformidad, trazabilidad.
Walkthrough de codebase que pasa de estar en el "barro" a estar "saludable" mediante pequeños pasos guiados por las skills.
Inspira valor: no hace falta detenerlo todo para arreglarlo.
Strangler fig, boy scout rule, ramas cortas.
🔄 Flujo de trabajo completo
De la idea al PR mergeado — todas las skills de la ruta en orden de uso.
Comando que instala todas las skills de Matt en tu Claude Code y prepara el entorno.
Todo comienza aquí. Sin configuración, el resto de la ruta no funciona.
Bootstrap, dependencias, verificación.
Flujo: idea → /grill-me → /to-prd. El resultado es un PRD listo para dividir en partes.
Conecta los módulos 1.2 y 1.6: sin este puente, el grilling se convierte en una charla perdida.
PRD, criterios de aceptación, handoff documental.
/to-prd estructura el documento; /to-issues lo divide en issues comprobables para su ejecución.
Una issue bien dividida = un sprint sin ambigüedades.
División en partes, INVEST, criterios de aceptación.
Una skill que decide qué rol (PM, dev, reviewer) asume el agente según el estado del issue.
Evita que el agente actúe como desarrollador cuando debería estar revisando, y viceversa.
Máquina de estados, persona, gates de transición.
Cada issue priorizada se convierte en un ciclo /tdd — prueba, código, refactorización — hasta que todo pase.
Es donde la teoría se convierte en merge. Sin TDD aquí, la calidad se desploma.
Definición de terminado, controles de CI, slice completo.
Etapa final: revisión automática + humana, actualización de CONTEXT.md/ADR, merge.
Sin cerrar con documentación y revisión, el ciclo se «filtra» y la arquitectura vuelve a degradarse.
Revisiones, actualización de documentación y política de merge.