implement y code-review: construir cada ticket con TDD y revisarlo en dos ejes

Con los tickets listos (lo vimos en to-spec y to-tickets), toca construir. implement es la skill que lo hace: toma un ticket o un spec, lo programa con tdd en las costuras pactadas y termina con code-review, una revisión del diff en dos ejes que corren por separado: ¿cumple los estándares del repositorio? y ¿hace lo que pedía el spec? Las tratamos juntas porque implement no se considera terminado hasta que pasa por code-review.

Es la séptima parte de la guía de las skills de Matt Pocock (repositorio mattpocock/skills, licencia MIT). Incluimos también implement-spec, la variante que construye un spec entero con subagentes en paralelo.

implement: corto a propósito

El SKILL.md de implement tiene seis instrucciones:

1. Implementa el trabajo descrito en el spec o los tickets.
2. Si recibes la referencia de un ticket, búscalo en el issue tracker y di su título antes de empezar. Si es ambigua, pregunta.
3. Llama a tdd donde sea posible, en las costuras pactadas.
4. Ejecuta el chequeo de tipos a menudo, los ficheros de test sueltos a menudo y la suite completa una vez al final.
5. Al terminar, llama a code-review.
6. Haz commit en la rama actual.

Es corta porque delega: el método está en tdd y el control de calidad en code-review. Así puedes cambiar cualquiera de las dos sin tocar implement.

El flujo recomendado con varios tickets es un /implement por ticket con /clear entre uno y otro. Cada ticket se escribió para caber en una ventana de contexto limpia, así que el contexto del anterior es desechable.

implement-spec: el spec completo con subagentes

Cuando prefieres orquestar en lugar de llevar cada ticket a mano, /implement-spec construye el spec entero en una sola ejecución:

• Lee los tickets como un grafo de tareas, no como una lista: siempre hay una frontera de tickets listos.
• Crea una rama de integración y, para cada ticket listo, lanza un subagente implementador con contexto limpio, en su propio worktree y su propia rama, que usa tdd.
• Cuando un implementador termina, un subagente de merge integra su trabajo. Si eso libera tickets nuevos, lanza más implementadores.
• Al final pasa un único code-review sobre la rama de integración y corrige lo que salga con un implementador nuevo.
• Si el tracker cierra trabajo con PR, abre un borrador tras el primer merge y lo marca listo al acabar. Después limpia los worktrees.

La comunicación entre subagentes es mínima y por punteros de contexto: rutas al spec, a los tickets, a notas de investigación y a commits anteriores, sin copiar información que ya está ahí.

code-review: dos ejes que no se mezclan

code-review revisa el diff entre HEAD y un punto fijo que tú das (un SHA, una rama, una etiqueta, main, HEAD~5) en dos ejes:

• Standards: ¿el código cumple los estándares documentados del repositorio?
• Spec: ¿el código implementa fielmente el issue o spec que lo originó?

Por qué dos ejes y no uno

Un cambio puede pasar un eje y suspender el otro:

• Código que sigue todos los estándares pero implementa otra cosa: Standards bien, Spec mal.
• Código que hace justo lo que pedía el issue pero rompe las convenciones: Spec bien, Standards mal.

Si un único revisor mira las dos cosas, una tapa a la otra. Por eso cada eje corre en un subagente con contexto propio, en paralelo, y el informe final los presenta bajo ## Standards y ## Spec sin mezclarlos ni reordenarlos. Ni siquiera elige "el peor fallo" global: da el peor de cada eje.

El proceso

1. Fijar el punto de comparación: comprueba que existe (git rev-parse) y que el diff no está vacío, antes de lanzar nada. Usa git diff <punto>...HEAD con tres puntos, para comparar con la base común.
2. Encontrar el spec: referencias a issues en los commits (#123, Closes #45), una ruta que le pases, un fichero en docs/, specs/ o .scratch/, o te pregunta. Sin spec, el eje Spec se salta y lo dice.
3. Encontrar los estándares: todos los ficheros que documentan cómo se escribe código, siempre CODING_STANDARDS.md o CONTRIBUTING.md si existen.
4. Lanzar los dos subagentes a la vez, cada uno con un límite de 400 palabras.
5. Agregar con un resumen de una línea: hallazgos por eje y el peor de cada uno.

La línea base de malos olores

Aunque tu repositorio no documente nada, el eje Standards siempre lleva una lista fija de malos olores de Fowler (*Refactoring*, capítulo 3), cada uno con su arreglo: nombre misterioso, código duplicado, envidia de funcionalidades, grupos de datos, obsesión por los primitivos, switches repetidos, cirugía de escopeta, cambio divergente, generalidad especulativa, cadenas de mensajes, intermediario y legado rechazado.

Dos reglas los mantienen bajo control: un estándar documentado del repositorio siempre gana a la línea base, y cada mal olor es siempre un juicio ("posible envidia de funcionalidades"), nunca una infracción dura. Lo que ya comprueba una herramienta (linter, formateador) se ignora.

Cómo se combinan

/implement 02            → tdd en las costuras pactadas
                         → typecheck y tests sueltos durante el trabajo
                         → suite completa al final
                         → code-review contra el punto fijo
                              ├─ Standards (subagente)
                              └─ Spec: el ticket 02 (subagente)
                         → commit

El refactor que tdd deja fuera del bucle rojo-verde vuelve aquí: los malos olores del eje Standards son la lista de refactors candidatos. Y como el eje Spec lee el ticket original, detecta tanto lo que falta como el alcance de más (*scope creep*): comportamiento que nadie pidió.

Si quieres solo la revisión, code-review funciona suelta: "revisa desde main" sobre cualquier rama o PR. Para una revisión automática en cada PR de GitHub hay herramientas dedicadas como Open Code Review; code-review está pensada para ejecutarse dentro de tu sesión de agente.

Errores frecuentes

• No dar un punto fijo. Sin él, code-review te lo pide. Ten claro desde dónde revisas.
• Esperar que arregle lo que encuentra. code-review informa; los arreglos los hace implement (o un implementador nuevo en implement-spec).
• Meter en CLAUDE.md reglas de estilo. El revisor es quien hace cumplir los estándares; el implementador tiene más presión de contexto. Lo vemos en la parte 13 con retro.
• Lanzar implement-spec sin tickets con dependencias. Sin grafo, no hay frontera que paralelizar.

Preguntas frecuentes

¿implement crea ramas o PR? No: hace commit en la rama actual. implement-spec sí crea una rama de integración y, si procede, un PR en borrador.

¿Cuánto cuesta implement-spec? Depende del número de tickets: lanza un subagente por ticket más los de merge y revisión. En specs grandes es la opción más rápida, no la más barata.

¿code-review sirve para PR de otras personas? Sí, con la rama del PR y su issue como spec.

Siguiente paso

Prueba /code-review sobre tu rama actual con main como punto fijo y mira si los dos ejes coinciden. En la parte 8 de la guía pasamos a la salud del código con improve-codebase-architecture y codebase-design.