Crea tres archivos de especificaciones antes de usar Claude Code y Codex

Después de casi un año usando agentes de codificación con IA todos los días, lo que más me molestaba no era el código alucinado ni las APIs incorrectas. Era la inconsistencia. La misma tarea, formulada de manera ligeramente distinta, producía un resultado limpio un día y un desastre al siguiente. Las sesiones largas lo empeoraban: el agente olvidaba acuerdos tomados veinte mensajes antes.

La causa era estructural. No tenía ningún marco para comunicar la intención al agente entre sesiones. Cada conversación empezaba desde cero y derivaba en direcciones impredecibles.

Tres capas que cambiaron el resultado

Dividir las instrucciones en tres archivos, cada uno con un rol distinto, resolvió el problema de inconsistencia casi de un día para otro.

Capa 1, CLAUDE.md se carga automáticamente en cada sesión. Tiene las constantes del proyecto: comandos de compilación, versiones del stack, estructura de carpetas, convenciones de código y límites de comportamiento (hacer siempre X, preguntar antes de Y, nunca hacer Z).

Capa 2, SPEC.md captura el qué y el por qué de una funcionalidad específica. Propósito, requisitos, criterios de éxito, restricciones técnicas y límites de alcance. Nada sobre detalles de implementación.

Capa 3, plan.md descompone una spec en tareas ejecutables de dos a cinco minutos, con rutas de archivo explícitas, orden TDD y puntos de commit.

Por qué meter todo en un solo archivo no funciona

La investigación sobre el seguimiento de instrucciones en LLMs describe esto como la “Maldición de las Instrucciones”. A medida que aumenta el número de directivas en un único contexto, el cumplimiento de cada directiva individual cae drásticamente. Lo verifiqué directamente: un archivo único con reglas del proyecto, specs de funcionalidades y listas de tareas hacía que el agente ignorara aproximadamente la mitad de las instrucciones hacia el final del documento.

Separar por rol lo solucionó. El agente lee las reglas universales desde la capa 1, la intención de la funcionalidad desde la capa 2, y los pasos de ejecución desde la capa 3. Cada archivo se mantiene lo suficientemente corto para que el modelo le preste atención completa.

CLAUDE.md funciona mejor cuando se mantiene liviano

Como este archivo se carga en cada sesión, solo debe tener lo que aplica de forma universal. Comandos de build, versiones del stack, organización de carpetas, convenciones de nomenclatura. Agrégale un límite en tres niveles: cosas que hacer siempre, cosas sobre las que preguntar primero, cosas que nunca hacer.

El enfoque que mejor me funcionó fue empezar con lo mínimo e ir agregando reglas de forma incremental cada vez que veía al agente repetir un error. Intentar escribir un CLAUDE.md completo desde el principio generaba un archivo inflado que terminaba provocando la misma caída de cumplimiento que quería evitar.

Algunos errores concretos: no pongas claves de API ni fragmentos de código aquí porque se vuelven obsoletos rápido. No dupliques reglas que ya aplica tu linter. Y mueve cualquier cosa específica de una sola funcionalidad a la capa 2.

Los archivos de spec se enfocan en el qué y el por qué, no en el cómo

La diferencia respecto a un PRD tradicional es que estas specs están estructuradas para ser consumidas por un agente. Con cinco secciones alcanza: propósito, requisitos, criterios de éxito, restricciones técnicas y límites de alcance.

Deja las decisiones de implementación al agente. Puede analizar el código existente y elegir el enfoque adecuado. Cuando intenté dictar el cómo, el agente o lo seguía a ciegas generando conflictos con los patrones existentes, o lo ignoraba por completo.

Una alternativa a escribir specs manualmente: pedile al agente que te entreviste. Establecé dos reglas: una pregunta a la vez, y opción múltiple siempre que sea posible. Las specs resultantes tenían menos vacíos que las que escribía yo solo.

Guardá las specs completadas en docs/specs/YYYY-MM-DD-tema.md y haceles commit en Git. Esto le da al agente acceso al historial de specs mediante git diff, y le proporciona a los revisores un registro de la intención detrás de los cambios de código.

La separación de sesiones es la práctica más olvidada

El brainstorming y las preguntas y respuestas durante la escritura de una spec consumen una parte importante de la ventana de contexto. Pasar directamente a la implementación en la misma sesión hace que el agente vaya perdiendo acceso al contexto anterior de forma gradual.

Reestructuré el trabajo en tres sesiones: la sesión 1 produce SPEC.md, la sesión 2 crea plan.md, la sesión 3 en adelante ejecuta tareas de a una. La mejora en precisión fue notable dentro de la primera semana.

Tres hábitos que consolidaron este flujo: escribir rutas de archivo explícitas en cada tarea para que el agente deje de adivinar, fijar el orden TDD (test primero, implementación, verificación, commit) en plan.md, e iniciar una nueva sesión cuando el uso del contexto llega aproximadamente al 50%.

El modelo de madurez apunta hacia la spec como fuente de verdad

El equipo de Martin Fowler definió recientemente un modelo de madurez para el desarrollo de software basado en agentes con tres niveles. Nivel 1: escribir una spec, implementar, descartar la spec. Nivel 2: mantener la spec como documento vivo junto al código. Nivel 3: la spec se convierte en la única fuente de verdad, y el código es un artefacto generado.

La mayoría de equipos e individuos que conozco todavía no llegó al nivel 1. Mandan prompts sueltos esperando lo mejor, y cuando algo falla no hay forma de diagnosticar por qué. Eso funciona para tareas pequeñas, pero se rompe a medida que crece la complejidad.

Pasar del nivel 1 al nivel 2 requiere un solo hábito: hacer commit de los archivos de spec en Git. Pasar del nivel 2 al nivel 3 significa actualizar la spec antes de modificar el código. El paso más pequeño que podés dar hoy es crear un CLAUDE.md para tu proyecto y escribir un SPEC.md antes de tu próxima funcionalidad.