Desarrollo guiado por especificaciones: curso acelerado

13 conceptos · Acordar el qué antes de generar el cómo

Le pides a una IA que construya algo. Te devuelve código que parece correcto. Lo ejecutas. Falla. O peor: funciona, pero resuelve un problema ligeramente distinto del que tenías en la cabeza. Entonces explicas de nuevo. Arregla esa parte y, en silencio, deshace algo que había hecho bien dos mensajes antes. Una hora después tienes un montón de código en el que no confías del todo y que no puedes cambiar de forma limpia.

Ese ciclo tiene nombre: vibe coding. Le das a la IA una idea vaga y esperas que adivine bien. Para un prototipo desechable está bien. Para cualquier cosa que quieras conservar, desplegar o entregar a otra persona, es una trampa.

El desarrollo guiado por especificaciones (SDD) es la salida. En vez de describir lo que quieres y esperar, lo escribes, con suficiente claridad para que tú y la IA estén de acuerdo antes de que exista código. Ese acuerdo escrito es la especificación. El código pasa a ser lo que produce la especificación, no al revés.

Este curso cubre la disciplina de punta a punta. Al final podrás ejecutar una construcción completa guiada por especificación de tres maneras: en claude.ai (la app web, tu herramienta principal aquí), en Claude Code y en OpenCode. La misma disciplina se transfiere a las tres.

En SDD, la especificación es la fuente de verdad y el código es un resultado de construcción. Cada concepto de este curso es una forma de escribir una especificación mejor, acordarla antes o mantenerla fiel a medida que el proyecto crece.

Así es como la codificación agentic ya funciona en la práctica

No tienes que creerlo por fe. El análisis de Anthropic de 2026 sobre unas 400.000 sesiones de codificación agentic encontró una división clara del trabajo: las personas toman la mayoría de las decisiones de planificación (qué construir), y el agente toma la mayoría de las decisiones de ejecución (cómo construirlo). Y el predictor más fuerte del éxito de una sesión no fue la habilidad para programar; fue la experiencia de dominio: con qué precisión la persona enmarcó el trabajo, qué le pidió al agente que verificara y si pudo devolverlo al rumbo cuando se desviaba. SDD es la disciplina que te vuelve bueno en la mitad que sigue siendo tuya. Consulta Agentic coding and persistent returns to expertise, de Anthropic.

La división qué/cómo, medida en unas 400.000 sesiones (Anthropic, 2026). SDD es la forma de mejorar en la mitad de planificación.

Prerrequisito: AI Prompting in 2026

Ese curso te enseñó a hablar con la IA: dar contexto, pedir con claridad y revisar el trabajo. Este curso enseña qué hacer antes de pedir cualquier cosa: cómo convertir una idea borrosa en una especificación escrita, lo bastante precisa como para construir a partir de ella. Encaja de forma natural con el Agentic Coding Crash Course, el compañero que ya conociste para profundizar en las herramientas de codificación.

No necesitas ser programador para esto​

SDD es una disciplina de pensamiento, no una habilidad de programación. La practicas casi por completo en lenguaje común, dentro de una ventana de chat normal. El resultado es un documento escrito con claridad y después un resultado funcional construido a partir de él, ya sea una app, un script, un generador de informes o una automatización. Si puedes escribir un brief claro para un colega capaz, puedes escribir una especificación. (Consulta Code You Never Write para entender por qué ahora es una habilidad general, no solo de desarrolladores).

El estudio lo vuelve concreto: la formación en programación apenas cambió si una sesión tenía éxito; la experiencia de dominio sí. No se te pide escribir código; se te pide conocer tu problema lo suficiente como para escribirlo: las reglas, los casos límite, qué significa "terminado". La especificación es donde entra tu experiencia. Un contador que puede expresar cada regla de conciliación construye mejor que un desarrollador que no entiende los libros, porque la especificación lleva el conocimiento y el agente aporta el código.

---

Tres herramientas, una disciplina​

Todo lo de abajo funciona en tres herramientas. Empezamos con claude.ai porque no necesita instalación (puedes hacer trabajo real guiado por especificación en el navegador hoy mismo) y porque el ciclo chat-documento hace visible el pensamiento. Los mismos movimientos se asignan limpiamente a los dos agentes de codificación.

	claude.ai (principal)	Claude Code	OpenCode
Qué es	La app de chat web/desktop	El agente de codificación de Anthropic (terminal/IDE)	Agente de codificación open source, cualquier modelo
Dónde vive la especificación	Un Artifact (documento editable junto al chat) en un Project (workspace guardado)	Archivos en tu repo (CLAUDE.md, specs/)	Archivos en tu repo (AGENTS.md, specs/)
Mejor para	Pensar, redactar, no programadores, empezar	Construir software real, end-to-end	Lo mismo, con elección de modelo y control de costo
Alternativas	ChatGPT (Projects + Canvas) y Gemini (Gems + Canvas) ejecutan la misma disciplina	(ninguna)	(ninguna)

Qué cubre este curso​

Parte	Tema	Lo que aprendes
1	El cambio	Por qué falla el vibe coding, qué es realmente una especificación y los tres niveles de SDD
2	El método	La constitución y después las cuatro fases: Research → Specify → Clarify → Build
3	Las tres formas	Ejecutar el ciclo en claude.ai, Claude Code y OpenCode
4	Un ejemplo completo	Una función, de principio a fin, en claude.ai y después en Claude Code
5	Criterio	Cuándo SDD compensa, cuándo es excesivo y cómo mantener viva una especificación

La columna vertebral de 15 minutos (si solo tienes unos minutos)

¿Es nuevo para ti y tienes poco tiempo? Lee el Concepto 1 (por qué falla el vibe coding), el Concepto 2 (la especificación es el producto), el Concepto 7 (Clarify mediante entrevista), el bloque de cuatro prompts al final de la Parte 2 y el ejemplo trabajado de la Parte 4. Esa es la lectura mínima viable; todo lo demás la profundiza después. Cuando quieras que la disciplina realmente se vuelva tuya, la escalera de Práctica al final es donde ejecutas el ciclo completo sobre algo real. (Esta división es en sí misma un movimiento de SDD: la columna vertebral es la especificación; el resto es el plan).

---

Parte 1: El cambio​

Tres ideas reencuadran cómo trabajas con IA. Entiéndelas y el resto es mecánica.

1. Vibe coding frente a desarrollo guiado por especificaciones​

La diferencia es cuándo haces el pensamiento.

En vibe coding, piensas mientras la IA construye; descubres lo que realmente quieres reaccionando a lo que te entrega. Se siente rápido: algo aparece en pantalla de inmediato. Pero cada ida y vuelta pierde un poco de contexto, la IA rellena huecos con suposiciones razonables pero equivocadas, y el resultado rara vez encaja con el resto de tu proyecto. El costo aparece después, de golpe, cuando intentas cambiarlo o confiar en él.

En el desarrollo guiado por especificaciones, piensas primero y lo escribes. La IA no empieza a construir hasta que ambos están de acuerdo sobre qué significa "terminado". Después, la construcción es casi mecánica: ejecuta un acuerdo, no adivina uno.

Dos ciclos: el vibe coding gira entre prompt, código y "casi, pero no"; SDD adelanta la especificación y después ejecuta un ciclo breve de construir y verificar contra ella.

Es el mismo movimiento que aprendiste en prompting (contexto primero, luego la petición), pero con más riesgo: la IA ahora escribe código dentro de tu proyecto, no solo responde una pregunta.

Regla práctica: si te molestaría tirar el resultado a la basura, ya pasaste el punto en que el vibe coding es seguro. Escribe la especificación.

2. La especificación es el producto; el código es un resultado de construcción​

Este es el giro mental que da nombre a SDD. Durante décadas, la especificación sirvió al código: escribías un brief, construías la cosa y descartabas el brief. SDD lo invierte. La especificación es el artefacto duradero que mantienes; el código se genera a partir de ella y se vuelve a generar cuando cambia la especificación. "Volver a generar" significa volver a ejecutar el ciclo de construcción sobre la especificación actualizada y revisar el resultado, no presionar un botón mágico de compilación: la especificación guía a un agente imperfecto que sigues supervisando.

La inversión: la forma antigua trata la especificación como andamiaje para el código; SDD convierte la especificación en la fuente de verdad y el código en un resultado que puede volver a derivarse.

Una buena especificación responde tres preguntas, en orden:

1. Por qué: ¿qué problema resolvemos y para quién? (Lo que la mayoría de sesiones de vibe coding nunca declara).
2. Qué: ¿qué debe ser verdad cuando esto esté terminado? Comportamientos, entradas, salidas, reglas, casos límite y, explícitamente, qué queda fuera de alcance.
3. Qué no construir: los límites. Esta sola sección evita la mayoría de fallos de "hizo demasiado / hizo lo incorrecto".

Observa lo que falta: el cómo. Una especificación describe comportamiento, no implementación. "Los usuarios pueden restablecer una contraseña olvidada mediante un enlace enviado por correo que vence en 30 minutos" es especificación. "Usar un JWT y una tabla tokens de Postgres" es implementación, y pertenece al plan, una fase posterior. Mezclar ambos demasiado pronto es el error más común de principiante: bloqueas una decisión técnica antes de acordar el comportamiento que se supone que debe entregar.

La prueba para cada línea de una especificación

Pregunta: "¿Podría una persona competente construir lo incorrecto y aun así cumplir técnicamente esta línea?" Si la respuesta es sí, la línea es demasiado vaga; ajústala. Una especificación no está terminada cuando no queda nada por añadir, sino cuando no queda nada que pueda malinterpretarse.

3. Los tres niveles de SDD​

SDD no es todo o nada. Hay tres niveles, y eliges según cuánto importe el trabajo.

Nivel	Qué significa	Cuándo usarlo
Spec-First	Escribes la especificación una vez, al inicio, y después construyes desde ella. La especificación puede derivar después.	La mayoría de funciones. Es el valor predeterminado.
Spec-Anchored	La especificación sigue siendo la fuente de verdad; la actualizas cuando cambia el comportamiento y vuelves a derivar desde ella.	Cualquier cosa que mantendrás durante meses.
Spec-as-Source	La especificación es la fuente; el código se regenera por completo desde ella, tratado como una salida que se puede volver a derivar y que sigues ejecutando y revisando.	Equipos y herramientas maduros, de alta disciplina.

Para este curso, empieza en Spec-First y crece hacia Spec-Anchored. Spec-as-Source es hacia donde va el campo, pero te lo ganas dominando los dos primeros. La disciplina es idéntica en todos los niveles; solo cambia cuán estrictamente mantienes sincronizada la especificación.

---

Parte 2: El método​

El flujo tiene una base (la constitución) y cuatro fases (Research → Specify → Clarify → Build):

El método de un vistazo: la constitución está por encima de cuatro fases (Research, Specify, Clarify, Build), y cualquier hueco encontrado al construir te devuelve a corregir la especificación.

4. La constitución: las reglas por encima de cada especificación​

Antes de cualquier función individual, escribes un documento corto con reglas persistentes para todas: la constitución. En los agentes de codificación es el archivo de reglas (CLAUDE.md / AGENTS.md); en claude.ai, tus Project instructions. La misma idea en todas partes: principios, restricciones y convenciones que quieres que sigan cada especificación y cada build.

Una advertencia honesta, porque cambia cómo la usas: una constitución es contexto persistente, no ley aplicada. El agente la carga en cada sesión y la sigue de forma más fiable cuanto más específica y concisa es, pero "cargada" no significa "garantizada". Para reglas que nunca deben romperse (no tocar datos de producción, nunca confirmar secretos), no dependas solo de la regla escrita; respáldalas con pruebas, hooks de pre-commit o de herramienta, checks de CI, permisos más estrictos o una persona revisando el diff. La constitución fija la intención; esos mecanismos la aplican.

Una constitución son principios, no una enciclopedia. Responde "¿qué siempre es cierto aquí?", no "¿cómo funciona la función X?". Mantenla ajustada; la IA la relee constantemente, así que la hinchazón cuesta y entierra las reglas que importan. Buenas líneas de constitución se ven así:

# Constitution — Smart Notes

## Principles

- Plain language over cleverness. A new contributor should understand any file in 5 minutes.
- Prefer well-established libraries over custom code. Research before reinventing.
- Every feature ships with its spec in `specs/`. The spec is the source of truth.

## Constraints

- Stack: keep it to what's already here. Propose, don't add, new dependencies.
- Never touch `published/` or anything in `src/generated/`.

## Definition of done

- Behaviour matches the spec, edge cases included.
- A human has reviewed the diff against the spec before merge.

Una constitución demasiado estricta envenena todo lo posterior

Una constitución marca el tono de todo lo posterior: si exige testing de nivel enterprise, presupuestos de rendimiento y proceso pesado para un proyecto de fin de semana, cada fase posterior hereda ese peso y una app de tareas se convierte en una catedral. Ajusta la constitución al riesgo; siempre puedes subir el nivel después.

Puedes verlo ocurrir. Dale a un habit-tracker de fin de semana una constitución que exige 90% de cobertura de pruebas, un presupuesto de rendimiento y un registro escrito de decisiones para cada cambio, y la primera función saldrá con un benchmark harness, tres capas de abstracción y un decision log: una semana de proceso para un botón que añade una fila a una lista. Nadie pidió eso; lo pidió la constitución, y cada fase posterior heredó el peso.

Pero el fallo opuesto es igual de común: una constitución tan vaga que no dice nada. Tres versiones del mismo proyecto:

Demasiado ligera (inútil)	Demasiado estricta (asfixiante)	Justa
"Escribe código limpio. Sé consistente. Usa buenas prácticas."	12 reglas sobre % de cobertura, presupuestos de rendimiento, formato de mensajes de commit y pasos de revisión, todo para una app de fin de semana	Las 6-8 líneas anteriores: principios que la IA no puede inferir, restricciones que de verdad muerden, un "done" claro

La prueba para cada regla es la misma que para cada línea de una especificación: ¿quitarla permitiría que la IA cometiera un error? "Escribe código limpio" falla, porque la IA ya intenta hacerlo, así que la línea no hace nada. "Nunca toques published/" pasa, porque la IA no podría haberlo sabido por sí sola.

5. Fase 1: investigar antes de escribir​

No puedes especificar lo que no entiendes. Antes de escribir una línea de especificación, haz que la IA mapee el territorio: el problema, los usuarios, las restricciones y, en un proyecto existente, cómo funciona el código actual y dónde debe encajar lo nuevo.

El movimiento potente aquí es investigación paralela: en vez de un intercambio largo, haz que la IA investigue varias preguntas a la vez y vuelva con un informe. En un chat pides un documento estructurado de hallazgos; en los agentes de codificación lo haces literalmente, con subagentes que investigan un área cada uno en su propia ventana de contexto y devuelven un resumen (manteniendo limpia tu conversación principal, la disciplina de contexto del Agentic Coding Crash Course).

El resultado no es código y todavía no es una especificación. Es un documento corto de hallazgos: qué existe, las opciones, las incógnitas, y alimenta la especificación. Un prompt que funciona en cualquiera de las tres herramientas:

Research what's involved in building [feature]. Investigate these separately and report each on its own: (1) how this kind of thing is usually done, (2) the main approaches and their trade-offs, (3) anything in our existing project it has to fit, (4) the failure modes and edge cases I should worry about. Give me a one-page findings doc: what exists, the options, and what's still unknown. Don't propose a final design or write any code yet.

6. Fase 2: escribir la especificación (el qué y el porqué, nunca el cómo)​

Ahora escribe la especificación, apoyada en la investigación. No empieces desde una página en blanco: redáctala con la IA y luego hazla precisa. Las tres preguntas del Concepto 2 (por qué, qué y qué no construir) se expanden a seis secciones concretas. Una especificación viable tiene, como mínimo:

• Objetivo: el porqué, en dos o tres frases.
• Escenarios de usuario: recorridos de tipo "cuando un usuario hace X, recibe Y".
• Requisitos funcionales: los "debe" verificables, cada uno lo bastante específico como para hacer fallar un build que lo ignore.
• Casos límite y reglas: entrada vacía, enorme, duplicada, mal formada, no autorizada.
• Fuera de alcance: lo que esto explícitamente no hace. No lo omitas.
• Criterios de aceptación: la lista que dice "terminado" (la definición de terminado de la constitución sigue aplicándose encima).

Anatomía de una especificación: seis secciones que describen comportamiento y, deliberadamente, ningún CÓMO (eso pertenece al plan).

Redáctala con un prompt como este y luego ajústala a mano:

Using the research above and our constitution, draft spec.md for [feature]. Include: goal (the why), user scenarios, functional requirements, edge cases & rules, out-of-scope, and acceptance criteria. Describe behaviour only, no databases, frameworks, or file layout. Make each requirement specific enough that a build which ignored it would visibly fail.

Qué significa "ajustar a mano". La prueba de precisión del Concepto 2, haciendo trabajo real. Mira cómo un requisito pasa de algo que la IA podría cumplir mal a algo que solo puede cumplir correctamente:

Antes: "Los usuarios pueden restablecer su contraseña."

Después: "Un usuario que ha cerrado sesión puede solicitar un restablecimiento de contraseña por correo electrónico. El enlace funciona una sola vez, vence después de 30 minutos, y un enlace usado o vencido muestra un mensaje de 'solicita un enlace nuevo'. La respuesta nunca revela si un correo electrónico está registrado."

La primera línea permitiría un build que envía por correo una contraseña en texto plano a cualquiera que lo pida. La segunda solo puede pasar si hace lo que realmente querías. Cada detalle que omites, la IA lo decide por ti; decide aquí, con palabras, los que importan.

Mantener la especificación libre de implementación es lo que te permite cambiar de opinión sobre herramientas después sin reescribir tu intención.

Omite esa disciplina y la elección de herramienta se convierte en requisito por accidente. Una especificación dice "guardar uploads en S3"; el plan y el código siguen; un mes después, un acuerdo de compliance exige almacenamiento en los propios servidores de la empresa. El comportamiento que a todos les importaba (los uploads siguen siendo duraderos y recuperables) nunca quedó escrito, solo quedó escrito el proveedor, así que cambiarlo implica un refactor en vez de un cambio de una línea en el plan.

7. Fase 3: aclarar por entrevista (hacer que la IA te pregunte a ti)​

Este es el paso de mayor valor y el que más se omite. Antes de construir, invierte las preguntas: en vez de instruir a la IA, haz que te entreviste a ti para revelar todo lo que la especificación dejó ambiguo. Un prompt hace la mayor parte del trabajo:

Before we build anything, interview me about this spec. Ask one question at a time, focusing on ambiguities, missing edge cases, and unstated assumptions. Keep going until you could hand this spec to a stranger and trust they'd build exactly what I mean. Don't write any code yet.

Te sorprenderá cuántas cosas "obvias" nunca se dijeron realmente. Cada ambigüedad que resuelves aquí, con palabras, es una que no resolverás después eliminando código incorrecto. Este es el lugar más barato de todo el proceso para corregir un error: corregirlo en la especificación cuesta una frase; corregirlo después de implementar cuesta un rebuild.

Sáltalo y las preguntas se responderán de todos modos, solo que más tarde, en código. Un equipo especifica "los usuarios pueden subir una foto de perfil", todos asienten y se envía. En un día: alguien sube un TIFF de 40 MB (nunca se indicó límite de tamaño o tipo), dos usuarios sobrescriben las fotos de otros (no había regla de unicidad) y un archivo roto se muestra en blanco en todo el sitio (sin fallback). Tres supuestos no declarados, cada uno una pregunta que la entrevista habría hecho en una sola frase, cada uno ahora convertido en bug.

8. Fase 4: construir desde la especificación​

La especificación está acordada. Ahora construyes desde ella, y la cantidad de proceso que añades escala con el cambio. No hay una pipeline fija que ejecutar siempre: haz la menor planificación que el cambio necesite y luego supervisa la construcción contra la especificación.

• Un cambio que podrías describir en una frase (un typo, una regla, un campo nuevo): simplemente pídelo. Salta el plan. Forzar proceso pesado sobre un arreglo de una línea es el exceso del mismo error.
• Un cambio donde el enfoque es incierto o toca algunos archivos: planifica primero. Haz que el agente proponga el enfoque y revísalo antes de cualquier código.
• Un cambio multiarchivo o arquitectónico: el ciclo completo, planificar y luego construir y verificar, con el trabajo dividido en pasos pequeños y verificables.

Dos cosas se mantienen constantes en cualquier tamaño: revisas el enfoque antes del código y verificas el resultado contra la especificación. Verify nunca es el paso que se omite.

¿Quién divide el trabajo en tareas? Lo hace el agente. Esta es la parte que cambió. No escribes a mano una lista de tareas. Claude Code y OpenCode planifican y descomponen el trabajo en su propia checklist rastreada, y avanzan por ella marcando cada elemento como terminado. Tu trabajo está en revisar esa descomposición y comprobar cada paso contra la especificación, no en escribir la lista. (En claude.ai, que no tiene herramienta de tareas, tú mismo capturas el plan y las tareas como Artifacts: ese es el único lugar donde el viejo "escribe un archivo de tareas" sigue encajando).

Plan (cuando el cambio lo merece):

Based on the agreed spec, propose a technical plan: stack, structure, and the key decisions, each with its trade-off. Match our constitution and reuse what already exists rather than adding new dependencies. Don't write code yet; I'll review the plan first.

Build (supervisado):

Implement the agreed plan in small, checkable steps. Do one step at a time, and after each, check it against the spec and stop for me to confirm before the next. Commit after each so every step has a clean rollback point.

Planifica con un modelo fuerte, implementa con uno más barato

El pensamiento caro es el plan. Una vez acordado el enfoque, construir es "seguir los pasos", y un modelo más barato o rápido lo hace bien. En los agentes de codificación esto es una configuración; en claude.ai haces la planificación en tu chat más capaz y conservas la especificación y el plan como handoff. (La misma división Plan/Execute del Agentic Coding Crash Course).

Cierra el ciclo: verifica contra la especificación

Que el código se ejecute no es lo mismo que haga lo acordado. Convierte tus criterios de aceptación en checks reales (pruebas automatizadas donde puedas escribirlas, un recorrido manual donde no puedas o una lista breve de preguntas de revisión) y ejecútalos después de cada paso. Si un check falla porque la especificación era vaga y no porque el código estuviera mal, corrige primero la especificación y luego el código. Si omites esto, SDD se degrada silenciosamente en aquello que debía prevenir: documentación pulida junto a código que nadie verificó.

Parte 2 en una pantalla​

Todo el método, copiable. Captura la checklist; guarda los prompts en un snippet.

¿Mi especificación está terminada?

• Objetivo: el porqué, en 2-3 frases
• Escenarios de usuario: "cuando un usuario hace X, recibe Y"
• Requisitos funcionales: cada uno lo bastante específico como para que ignorarlo haga fallar el build
• Casos límite y reglas: vacío, enorme, duplicado, mal formado, no autorizado
• Fuera de alcance: lo que esto explícitamente no hace
• Criterios de aceptación: la checklist que dice "terminado"
• Sin CÓMO: sin base de datos, framework o layout de archivos (eso es el plan)

Los cuatro prompts, en orden:

RESEARCH:  Research what's involved in building [feature]. Investigate separately and
           report each on its own: (1) how this is usually done, (2) the main approaches
           and trade-offs, (3) what in our existing project it must fit, (4) failure modes
           and edge cases. One-page findings doc. No design or code yet.

SPECIFY:   Using the research and our constitution, draft spec.md for [feature]: goal,
           user scenarios, functional requirements, edge cases & rules, out-of-scope,
           acceptance criteria. Behaviour only — no tech choices. Make each requirement
           specific enough that a build ignoring it would visibly fail.

CLARIFY:   Before we build anything, interview me about this spec, one question at a
           time — ambiguities, missing edge cases, unstated assumptions — until there's
           nothing left to misread. No code yet.

BUILD:     Right-size it. Tiny change: just ask. Otherwise: have the agent propose a
           plan and review it, then let it build in small steps, checking each against
           the spec and committing as you go. Turn acceptance criteria into checks.

---

Parte 3: Las tres formas​

La misma constitución, las mismas cuatro fases, tres lugares para ejecutarlas. Empezamos con claude.ai (nada que instalar), luego los dos agentes de codificación.

Las herramientas cambian; la disciplina no

La mecánica específica de esta parte, atajos (Shift+Tab, Tab), slash commands (/init, /undo), nombres de modelos y funciones de producto (Projects, Artifacts, Canvas, Gems) está vigente a junio de 2026 y puede cambiar. La disciplina de cuatro fases que ejecutan no cambia.

Una disciplina, tres hogares: el mismo ciclo se ejecuta en claude.ai, Claude Code y OpenCode; solo cambia dónde vive la especificación.

9. Forma 1: claude.ai, el método principal​

En la app web, tus dos bloques de construcción son Projects (un workspace persistente con custom instructions y knowledge subido) y Artifacts (documentos editables que viven junto al chat). SDD se asigna directamente a ellos.

Configura una vez, la constitución:

1. Crea un Project para tu trabajo (por ejemplo, "Smart Notes").
2. Coloca la constitución en las custom instructions del Project. Sube investigación, documentos existentes o capturas a Project knowledge para que cada chat del proyecto pueda verlos.

Ejecuta las cuatro fases; cada una produce un Artifact:

• Research → pide a Claude que investigue y produzca un Artifact de hallazgos. (No hay subagentes en la app web, así que pide varias preguntas cubiertas en un documento estructurado).
• Specify → pide a Claude que redacte spec.md como Artifact. Edítalo directamente en el panel Artifact hasta que esté bien.
• Clarify → pega el prompt de entrevista del Concepto 7. Responde las preguntas; haz que Claude incorpore las respuestas de vuelta en el Artifact de la especificación.
• Build → pide un Artifact plan.md, luego un Artifact tasks.md, y después implementa tarea por tarea. Cada archivo de código es su propio Artifact, que puedes previsualizar y descargar.

Por qué importa un Project: la constitución y la especificación quedan cargadas en cada chat, así que puedes abrir una conversación nueva para implementar sin volver a explicar el proyecto. Los Artifacts son tus archivos de especificación; cópialos a un repo cuando pases a un agente de codificación.

ChatGPT y Gemini pueden ejecutar la misma disciplina

Si prefieres otro asistente web, la disciplina se transfiere aunque la mecánica cambie. ChatGPT: Projects para la constitución, Canvas como documentos editables de spec/plan. Gemini: un Gem para la constitución, Canvas para los documentos. El ciclo (constitución, luego Research → Specify → Clarify → Build) es el mismo; solo cambian los botones y cuán persistente es cada memoria de "proyecto". claude.ai es nuestro valor predeterminado porque Artifacts + Projects se asignan de forma más limpia a archivos de especificación, pero nada aquí es exclusivo de Claude.

Antes de pegar cualquier cosa en una herramienta de navegador

Una ventana de chat es fácil, y ese es exactamente el riesgo. No subas código fuente privado, datos de clientes, secretos, credenciales o material confidencial de negocio a ningún asistente web salvo que la política de tu organización lo permita. Para trabajo sensible, ejecuta un agente basado en repo dentro de tu entorno aprobado y usa ejemplos sanitizados y ficticios (como hace la función Smart Notes de abajo). La disciplina es la misma; el límite de datos no.

10. Forma 2: Claude Code, la disciplina en tu repo​

Cuando tu proyecto es software real, Claude Code elimina el copy-paste: la especificación, el plan y las tareas viven como archivos en tu repo, junto al código que generan. Las funciones nativas siguientes son todo lo que necesitas, sin frameworks extra. Lo que añade sobre el ciclo de chat es maquinaria integrada para cada fase:

• La constitución es un archivo que Claude lee en cada sesión. CLAUDE.md se carga al inicio de cada conversación, así que no vuelves a pegar nada, pero trátalo como guía persistente, no como garantía dura (respalda reglas de "nunca" con hooks o pruebas, según el Concepto 4). Ejecuta /init y luego recórtalo hasta dejar reglas reales.
• Plan mode es tu puerta Specify/Clarify, aplicada por la herramienta. Shift+Tab en plan mode pone a Claude en modo de solo lectura: puede estudiar tu código y redactar la especificación, pero no puede escribir una línea hasta que apruebes. Eso es "acordar antes de construir", integrado en la herramienta.
• Los subagentes hacen investigación paralela sin contaminar tu contexto. Cada uno investiga un área en su propia ventana y devuelve solo un resumen, así que la Fase 1 se mantiene rápida y tu sesión principal ligera.
• El agente mantiene su propia lista de tareas; tú la supervisas. Una vez que apruebas el plan, Claude divide el trabajo en su propia checklist rastreada y la ejecuta marcando cada elemento como hecho. No escribes esa lista; tu trabajo es revisar la descomposición y, después de cada paso, ejecutar los checks relevantes contra la especificación y hacer commit antes del siguiente, para que cada paso tenga un punto limpio de rollback. Ese ritmo de commit después de cada paso es un workflow que tú diriges (y puedes hornear en la constitución); si debe ocurrir siempre, aplícalo con un hook.

Como los cuatro artefactos son archivos planos, tu especificación ahora está bajo control de versiones: puedes hacer diff, revisarla en una pull request y ver exactamente cuándo debía cambiar el comportamiento. Ese es el salto de "una especificación que escribí una vez" a "una especificación que gobierna el repo".

11. Forma 3: OpenCode, cualquier modelo​

Todo lo del Concepto 10 también aplica a OpenCode: el archivo de reglas (AGENTS.md) como constitución (OpenCode también lee un CLAUDE.md existente cuando no hay AGENTS.md), modo Plan (Tab) como puerta de solo lectura, subagentes para investigación y un /undo respaldado por git entre pasos de construcción. Igual que en Claude Code, el agente rastrea su lista de tareas y trabaja en ella mientras tú revisas la descomposición y compruebas cada paso contra la especificación; Tab cambia a modo Build cuando apruebas. Lo único que OpenCode añade es elección de modelo, que encaja con la división natural de SDD: las fases de especificación y plan recompensan un modelo de razonamiento fuerte, mientras que construir una lista de tareas clara y acordada funciona bien con uno barato como deepseek-v4-flash. Tú decides dónde va cada dólar de "pensamiento". (Los detalles de configuración de ambos agentes están en el Agentic Coding Crash Course).

---

Parte 4: Un ejemplo completo​

12. Una función, de principio a fin, dos veces​

Ejecutemos todo el ciclo con una función pequeña y real: un "resumen semanal" que envía por correo a cada usuario un resumen de sus notas cada lunes. Toca varios archivos (un job programado, la consulta de notas, el mailer), así que por la regla de right-sizing del Concepto 8 merece el ciclo completo. Lo hacemos dos veces: primero en claude.ai, donde el pensamiento es visible, y luego en Claude Code, donde el ciclo se ejecuta contra archivos reales en un repo.

En claude.ai

Fase 0: Constitución (ya configurada en el Project). Principios: lenguaje claro, preferir bibliotecas existentes, cada función se envía con una especificación, nunca tocar published/.

Fase 1: Research. Prompt:

Research what's involved in a "weekly digest email" for our notes app. Cover: how we'd select which notes to include, scheduling options, email-sending approaches, and the main failure modes (no notes that week, send failures, time zones). Give me a one-page findings doc. Don't propose a final design yet.

Claude devuelve un Artifact de hallazgos. Lo hojeas; la pregunta de zona horaria es una que no habías considerado.

Fase 2: Specify. Prompt:

Using those findings and our constitution, draft spec.md for the weekly digest. Include goal, user scenarios, functional requirements, edge cases, out-of-scope, and acceptance criteria. Describe behaviour only, no tech choices yet.

Recibes un Artifact de especificación. Está bien, pero es genérico en algunos lugares.

Fase 3: Clarify. Prompt:

Before we plan anything, interview me about this spec, one question at a time, until there's nothing left to misread.

La entrevista revela decisiones que nunca habías declarado: los resúmenes usan el lunes local del usuario, no UTC; una semana con cero notas no envía nada en vez de un correo vacío; los usuarios dados de baja se omiten. Respondes; Claude incorpora cada respuesta en el Artifact de la especificación. Este es el momento en que SDD se gana su lugar: tres bugs futuros acaban de morir como frases.

Fase 4: Build.

Now write plan.md: the technical approach for this spec, given our existing stack. Then tasks.md: an ordered, checkable task list.

Revisas el plan (reutiliza tu mailer existente, lo cual coincide con la constitución), lo apruebas y luego implementas tarea por tarea, comprobando cada una contra la especificación y guardando a medida que avanzas. Cuando una tarea revela que la especificación guardaba silencio sobre algo (por ejemplo, el asunto del correo), actualizas primero la especificación y luego continúas. La especificación sigue siendo cierta.

La misma función, en Claude Code

Mismas cuatro fases, mismos prompts; lo que cambia es que cada artefacto es un archivo y la herramienta aplica las puertas que en el navegador te imponías tú mismo.

• Research: en vez de un solo documento de hallazgos, inicia subagentes, uno por área, para que tu sesión principal siga ligera. Los hallazgos aterrizan en specs/weekly-digest/research.md.
• Specify: entra en plan mode con Shift+Tab (solo lectura): la regla "no construyas todavía", ahora aplicada por la herramienta, no por tu fuerza de voluntad.
• Build: Claude planifica el trabajo en su propia lista de tareas rastreada y construye a través de ella; tú revisas cada paso contra la especificación y haces commit después de cada uno, así git log se lee como esa lista de tareas y cada paso es un punto limpio de rollback.

La única diferencia real es dónde termina la especificación: en claude.ai vivía en un Artifact que copias hacia adelante; en Claude Code vive en specs/, bajo control de versiones junto al código que produjo. (OpenCode es idéntico: cambia CLAUDE.md por AGENTS.md y Shift+Tab por Tab).

El resultado no es solo código que funciona; es código que funciona más una especificación que lo explica y lo gobierna, lista para que la siguiente persona (o tu siguiente yo) la cambie con seguridad.

Ver la forma de los artefactos: un spec.md, plan.md y tasks.md compactos

El método es abstracto hasta que ves qué sale de él. Aquí hay versiones recortadas de los tres artefactos, escritas para que veas la forma. En claude.ai creas los tres como Artifacts; con un agente de codificación mantienes spec.md y plan.md como archivos, mientras que la lista de tareas suele ser la propia del agente (aquí se escribe para que una buena sea visible). Los reales son más largos; lo que importa es la forma.

# spec.md — Weekly Digest

## Goal

Email each user a once-a-week summary of their own notes so they
re-engage without opening the app. Reduce silent churn.

## User Scenarios

- A user with notes this week gets a Monday-morning digest listing them.
- A user with no notes this week gets nothing (not an empty email).
- An unsubscribed user gets nothing, ever.

## Functional Requirements

FR-1 Digest sends on the user's local Monday at 8:00am.
FR-2 Include only notes created or edited in the prior 7 days.
FR-3 Zero qualifying notes → no email is sent.
FR-4 Unsubscribed users are skipped.
FR-5 A send failure is retried once, then logged; it never blocks others.

## Edge Cases & Rules

- Time zone missing → fall back to UTC.
- 50+ notes → list the 10 most recent, then "and N more."

## Out of Scope

- Digest customization, frequency options, non-email channels.

## Acceptance Criteria

- [ ] A user in Asia/Karachi receives the digest at their local Monday 8am.
- [ ] An empty week sends no email (verified in logs).
- [ ] Unsubscribed users receive nothing.
- [ ] One simulated send failure retries once, then logs, others still send.

# plan.md — Weekly Digest

## Approach

Reuse the existing mailer service (constitution: prefer what exists).
A scheduled job runs hourly, selects users whose local time is Mon 08:00,
builds the digest from the notes query, and hands it to the mailer.

## Key Decisions

- Scheduling: hourly cron + per-user timezone check (no per-user timers).
- Templating: reuse existing email template system.
- Failure handling: wrap each send; retry-once lives in the job, not the mailer.

## Touch Points

- new: jobs/weekly_digest.\* | reuse: services/mailer, models/note
- no schema change required

# tasks.md — Weekly Digest

1. Note-selection query: notes per user from the last 7 days. [FR-2]
2. Eligibility check: local Monday 08:00 + subscribed. [FR-1, FR-4]
3. Digest builder: top 10 + "and N more"; skip if empty. [FR-3, edge]
4. Wire to mailer with retry-once + logging. [FR-5]
5. Tests for each acceptance criterion. [Verify]

Observa los hilos: cada tarea cita el requisito que satisface, y la última tarea es verificación, derivada directamente de los criterios de aceptación.

---

Parte 5: Criterio​

13. Cuándo SDD compensa y cuándo es excesivo​

SDD es una disciplina, y la disciplina tiene costo: espera que Specify y Clarify se sientan lentos, decenas de minutos de pensamiento donde el vibe coding ya estaría mostrándote código, y entiende que esa brecha es exactamente el intercambio que estás haciendo (los principiantes abandonan el método en el momento en que peor se siente, justo antes de que compense). Gastarlo en un arreglo de una línea es tan incorrecto como omitirlo en un sistema de pagos. La habilidad es saber cuál es cuál.

Usa SDD cuando…	Sáltalo (solo vibe) cuando…
El trabajo toca varios archivos, módulos o datos	Es un script de una sola vez o un ajuste mínimo
Alguien más (o tu yo futuro) lo mantendrá	Tirarás el resultado hoy
Equivocarse es caro (dinero, datos, confianza)	El costo de adivinar mal es "presionar undo"
Los requisitos son borrosos y hay que fijarlos	La tarea está totalmente clara en una frase
Varias personas deben acordar qué significa "done"	Estás explorando para aprender qué quieres

Pasar "haz este botón azul" por todo el proceso de constitución-a-implementación es absurdo. Pero en cuanto una tarea implica state, permisos, modelos de datos, dinero o expectativas de otra persona, la estructura empieza a pagarse sola, y paga más cuanto más vive la cosa.

El umbral está bajo a propósito: el trabajo diminuto y desechable queda a la izquierda, pero la mayoría de lo que conservas cae a la derecha, donde una especificación compensa.

Hay un segundo beneficio más allá de acertar a la primera: te ayuda a desbloquearte. En los datos de sesiones de Anthropic, cuando un build se torcía, los usuarios menos experimentados se rendían y abandonaban sesiones problemáticas varias veces más que los demás; lo que la experiencia compraba sobre todo era la capacidad de devolver al agente al rumbo. Una especificación ya acordada es ese volante: cuando algo se rompe, tienes un punto fijo contra el que depurar en vez de un recuerdo vago de lo que querías. El movimiento de recuperación es concreto: cuando el agente se desvía de la especificación a mitad del build, vuelve a anclarlo pegando el requisito específico que ignoró (el FR), reduciendo la tarea a solo esa cosa y apuntándolo de nuevo a los criterios de aceptación.

Mantén viva la especificación (la parte que todos olvidan). Una especificación solo es fuente de verdad si sigue siendo verdadera. Cuando cambia el comportamiento (una regla nueva, una función eliminada, un caso límite corregido), cambia primero la especificación y luego vuelve a derivar el código. Este es el movimiento que convierte Spec-First en Spec-Anchored, y es la diferencia entre una especificación que se vuelve más valiosa con el tiempo y una que se vuelve una mentira en tu repo en menos de un mes.

Así se ve el drift en la práctica: alguien ajusta directamente en código el asunto del correo de resumen y lo envía. La especificación todavía describe el asunto anterior. Tres semanas después, un nuevo compañero lee la especificación, "corrige" el código para que coincida con ella y rompe silenciosamente lo que funcionaba. Nadie mintió; la especificación simplemente dejó de ser verdadera, y descubrirlo costó un bug. El arreglo es barato y aburrido: el cambio entra en spec.md en el mismo commit que el código, siempre.

Qué cambia cuando tienes muchas especificaciones. Una especificación es un documento; una carpeta con docenas es un sistema. Con un directorio completo specs/, la pregunta viva deja de ser "¿esta especificación es clara?" y pasa a ser "¿estas especificaciones siguen de acuerdo?". Las funciones interactúan, así que un cambio en una puede propagarse a otras, y cuando dos especificaciones apuntan a decisiones en conflicto, la constitución es lo que lo resuelve. Mantener consistente todo el conjunto de especificaciones a medida que crece es el salto real de "puedo especificar una función" a "dirijo un repo con SDD".

---

Práctica​

Leer SDD no es aprender SDD. La disciplina solo se vuelve tuya cuando has ejecutado el ciclo completo sobre algo real y has sentido cómo la fase Clarify atrapa un error que de otro modo habrías enviado. Haz esto en orden. Cada uno sube el riesgo, y cada uno está deliberadamente más allá de la línea de "solo vibe", para que la estructura tenga que ganarse su lugar.

Para cada proyecto, produce los mismos cuatro artefactos (constitución, spec.md, plan.md, tasks.md) más el resultado funcional. La única prueba de éxito es la del Concepto 2: ¿podría una persona desconocida construir lo correcto solo desde tu especificación, sin hacerte una sola pregunta?

Calentamiento: sentir la entrevista (claude.ai, ~30 min). Elige la cosa real más pequeña que has querido construir: un planificador de estudio, una herramienta CSV-to-summary, un habit tracker. Crea un Project, pega una constitución de tres líneas y ejecuta las cuatro fases. Una regla: no omitas el Concepto 7. Haz que Claude te entreviste antes de cualquier código. Cuenta cuántas decisiones salen que nunca pensaste declarar. Ese número es la razón de existir de SDD.

Proyecto 1: una función con reglas reales (claude.ai, ~1 hr). Especifica y construye una función "tag and filter" para Smart Notes (la app del ejemplo trabajado): los usuarios añaden tags a notas y filtran por ellos. Suena trivial hasta que lo especificas, y ese es el punto. Oblígate a fijar los casos límite en la especificación: ¿qué pasa sin tags? ¿Tags duplicados? ¿Un filtro que no coincide con nada? ¿Sensibilidad a mayúsculas? ¿Renombrar un tag en uso? Done when tu especificación responde las cinco antes de escribir una línea de implementación.

Proyecto 2: moverlo a un repo (Claude Code u OpenCode, ~2 hrs). Saca el Proyecto 1 de la ventana de chat y ejecuta el mismo ciclo en un agente de codificación. Coloca la constitución en CLAUDE.md / AGENTS.md, conserva spec.md, plan.md y tasks.md como archivos en el repo, y usa plan mode como tu puerta specify/clarify. Implementa una tarea por vez, haciendo commit después de cada una. Done when git log muestra un commit limpio por tarea y la especificación vive bajo control de versiones junto al código que produjo.

Proyecto 3: mantener viva la especificación (el difícil, ~1 hr). Ahora cambia de opinión. Añade un requisito nuevo al Proyecto 2: por ejemplo, los tags pueden tener colores, o el filtrado admite modos "any of" y "all of". Resiste la tentación de decirle al agente que lo añada sin más. En vez de eso: edita primero spec.md, vuelve a ejecutar Clarify sobre la sección cambiada, actualiza el plan y las tareas, y luego implementa. Done when el diff de spec.md y el diff del código cuentan la misma historia. Este es el movimiento que convierte Spec-First en Spec-Anchored, y es el que casi nadie practica.

Proyecto 4: trabajar dentro de código que no escribiste (Claude Code u OpenCode, ~2 hrs). Un proyecto nuevo es el caso fácil. Clona cualquier proyecto open source pequeño que nunca hayas visto, o toma el repo de otra persona, y añade una función modesta usando SDD. Esta vez la Fase 1 carga el peso: antes de especificar nada, haz que el agente investigue cómo está estructurado el código existente, dónde debe encajar tu función y qué convenciones debe respetar; usa subagentes para que cada uno mapee un área y reporte. Tu especificación debe incluir una sección "encaja con el sistema existente" que nombre los patrones que estás siguiendo. Done when tu función se lee como si siempre hubiera sido parte del código base, no como algo atornillado encima, y tu especificación explica por qué encaja.

Proyecto 5: SDD sin código (claude.ai, ~45 min). Demuéstrate que esto es una disciplina de pensamiento, no de programación (Concepto "not a programmer"). Elige un proceso repetible, no una app: un informe semanal de estado armado desde notas crudas, una pipeline de reutilización de contenido, una rutina de triage de inbox, una rúbrica de calificación aplicada a entregas. Ejecuta exactamente el mismo ciclo (constitución, research, spec, clarify, build), donde "build" produce el proceso y sus prompts, no código fuente. Done when tú (o un compañero) pueden ejecutar el proceso desde la especificación y obtener un resultado consistente cada vez, sin improvisación.

Proyecto 6: la prueba del desconocido, de verdad (capstone, ~1.5 hrs). Hasta aquí lo revisaste tú, que eres el revisor más débil posible; sabes lo que querías decir. Así que salte de la ecuación. Escribe una especificación para una función y entrégala a una sesión de IA fresca y vacía (un chat nuevo sin memoria de tu conversación) o a un par, y haz que la construyan con cero preguntas permitidas. Donde construyan algo incorrecto, la culpa es de la especificación, no de ellos: corrige la especificación, no el código, e inténtalo de nuevo. Done when un lector frío construye lo que realmente querías en el primer intento. Supera esto y tendrás la habilidad real: escribir intención con suficiente precisión para que sobreviva al salir de tu cabeza.

---

Hacia dónde lleva esto​

Ahora tienes toda la disciplina: acordar el qué antes de generar el cómo, mantener la especificación como fuente de verdad y ejecutar el ciclo constitución → Research → Specify → Clarify → Build en cualquiera de las tres herramientas que encaje con el momento.

Esta es la capa de pensamiento bajo todo lo demás en el libro. Conociste las herramientas de codificación que ejecutan este ciclo, Claude Code y OpenCode, en el Agentic Coding Crash Course, y viste la disciplina funcionando en el Cowork Crash Course; vuelve a cualquiera de los dos para profundizar en la mecánica. Desde aquí, las pistas Mode ponen este ciclo a trabajar: cada curso de construcción que tomes, Python in the AI Era, Build AI Agents, AI Searchable Context y Building a Digital FTE, es este mismo ciclo aplicado a sistemas cada vez más grandes.

Recuerda la tesis de todo el libro: General Agents build Custom Agents. Spec-Driven Development es cómo apuntas un agente general a un problema difícil y recuperas un sistema confiable en vez de una pila de suposiciones.

---

Flashcards Study Aid

---

Pon a prueba tu comprensión

Comprueba lo que aprendiste. Cada sesión muestra un conjunto nuevo de 18 preguntas, así que obtienes preguntas nuevas cada vez que la repites.

Checking access...