SDD HARNESS — Hablar el mismo idioma antes de la primera línea

Un wizard de 5 fases para que los agentes construyan lo que tenía en la cabeza · Herramienta interna · Specification-Driven Development

Cliente

Side project / herramienta interna — RBT Studio

Rol

Diseño y desarrollo del skill

Periodo

Mayo 2026 · en uso activo

Stack

Claude Code · skill, Specification-Driven Development, Arquitectura multi-agente, TDD

Cada vez que arrancaba un proyecto nuevo con agentes, el punto de partida era distinto: a veces directo al código, a veces una spec improvisada en un mensaje. El resultado era el mismo — specs inconsistentes de un proyecto a otro, y una desconexión entre lo que yo tenía en la cabeza y lo que los agentes acababan construyendo.

El problema: Lo que había era o demasiado poco o demasiado

Los skills de planificación más simples no tenían fondo real: una plantilla de spec sin nada detrás que asegurara que el código resultante la cumplía. Los más completos iban al otro extremo — procesos pesados pensados para equipos grandes que, en un proyecto propio o de cliente mediano, son fricción pura: mucha ceremonia, poca agilidad.

Cómo se abordó

1. Buscar primero, construir después. Antes de escribir nada busqué soluciones existentes —otros skills de planificación estructurada— y ninguna encajaba. Los más simples no tenían fondo real: una plantilla de spec sin nada detrás que asegurara que el código resultante cumplía esa spec. Los más completos iban al otro extremo: procesos pesados, pensados para equipos grandes, que en un proyecto propio o de cliente mediano se convertían en fricción pura. Necesitaba algo en medio.
2. Tratarlo como un sistema Lean, no como gestión de proyectos disfrazada. La decisión de diseño clave. En vez de una plantilla de documento único, lo estructuré como un wizard de 5 fases, cada una con una responsabilidad concreta y una salida clara que alimenta a la siguiente: SPEC (qué y por qué), ARCHITECT (cómo y qué decisiones), SCAFFOLD (estructura base), HARNESS AGENTS (coordinación) y HANDOFF (entrega y contexto).
3. TDD como la única disciplina no negociable. El punto de apoyo del sistema es TDD: cada fase de implementación exige que los tests pasen antes de darse por buena, lo que actúa como ancla real contra la deriva — tanto la mía como la de los agentes. Es la diferencia entre «creo que esto cumple la spec» y «esto cumple la spec porque los tests lo confirman». Añadir más fases o más ceremonia habría reintroducido la fricción que quería evitar; quitar la disciplina de tests habría vuelto al punto de partida.

wizard de 5 fases: SPEC → ARCHITECT → SCAFFOLD → HARNESS AGENTS → HANDOFF → TDD como ancla en cada fase

Solución: Un sistema Lean con una disciplina no negociable

Cinco fases secuenciales, cada una con una responsabilidad concreta y una salida clara que alimenta a la siguiente, generando los artefactos de documentación antes de tocar código de implementación. Añadir más fases habría reintroducido la fricción; quitar la disciplina de tests habría vuelto al punto de partida — buenas intenciones sin verificación.

Decisiones de producto

• mi rol: Diseño y desarrollo del skill
• las 5 fases: SPEC qué y por qué
  ARCHITECT cómo y qué decisiones
  SCAFFOLD estructura base
  HARNESS AGENTS coordinación
  HANDOFF entrega y contexto
• el ancla: TDD. Cada fase de implementación exige que los tests pasen antes de darse por buena — la diferencia entre "creo que esto cumple la spec" y "esto cumple la spec porque los tests lo confirman".
• estado: Creado en mayo de 2026, en uso activo. La PRD completa de Job Search OS salió de este proceso.

Resultados

No hay una métrica única que resuma el impacto, pero el cambio en cómo trabajo es claro. Hay seguridad de que nada se pierde entre la idea inicial y el proyecto terminado, porque cada fase deja un artefacto que la siguiente puede consultar. Hay un mismo idioma entre yo y los agentes: con spec y arquitectura explícitas antes de implementar, no queda ambigüedad que cada agente interprete a su manera. Y hay menos rework, porque el enfoque TDD detecta los errores de interpretación pronto y no al final. Ya lo he usado para arrancar proyectos reales — la PRD completa de Job Search OS salió de este proceso, pivotando de una idea inicial de CRM manual a un Career Operating System event-driven con una arquitectura mucho más sólida de la que habría salido empezando directo por el código.

• 5 fases — cada una con un artefacto que la siguiente puede consultar
• 1 ancla — TDD — la única disciplina no negociable del sistema
• En uso — desde mayo de 2026, en proyectos propios y de cliente

"La estructura correcta no está ni en la plantilla mínima ni en el proceso exhaustivo, sino en un sistema Lean con fases bien delimitadas y una única disciplina no negociable que hace de ancla."

Qué se aprendió

1. Seguridad de que nada se pierde entre la idea inicial y el proyecto terminado — cada fase deja un artefacto trazable.
2. Mismo idioma entre yo y los agentes. Con spec y arquitectura explícitas antes de implementar, no queda ambigüedad que cada agente interprete a su manera.
3. Menos rework. El enfoque TDD detecta los errores de interpretación pronto, no al final — por ejemplo, pivotar de un CRM manual a un Career Operating System event-driven antes de escribir código.

Herramienta interna, en uso activo desde mayo de 2026.