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

Tras casi un año usando agentes de codificación IA a diario, lo que más me molestaba no era el código alucinado ni las APIs incorrectas. Era la inconsistencia. La misma tarea, formulada de forma 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 atrás.

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 inmediato.

Capa 1, CLAUDE.md se carga automáticamente en cada sesión. Contiene 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 concreta. Propósito, requisitos, criterios de éxito, restricciones técnicas y límites de alcance. Nada sobre detalles de implementación.

Capa 3, plan.md desglosa 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 bruscamente. Lo comprobé 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 resolvió. 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 bastante corto para que el modelo le preste atención completa.

CLAUDE.md funciona mejor cuando se mantiene conciso

Como este archivo se carga en cada sesión, debe contener únicamente lo que aplica de forma universal. Comandos de build, versiones del stack, organización de carpetas, convenciones de nomenclatura. Añade un límite en tres niveles: cosas que hacer siempre, cosas sobre las que preguntar primero, cosas que nunca hacer.

El enfoque que mejor funcionó fue empezar con lo mínimo y añadir reglas de forma incremental cada vez que veía al agente repetir un error. Intentar escribir un CLAUDE.md exhaustivo desde el principio llevaba a un archivo inflado que desencadenaba la misma bajada de cumplimiento que trataba de evitar.

Algunos errores concretos: no pongas claves de API ni fragmentos de código aquí porque quedan 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 centran 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. Cinco secciones son suficientes: 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 bien lo seguía ciegamente generando conflictos con los patrones existentes, o bien lo ignoraba por completo.

Una alternativa a escribir specs manualmente: haz que el agente te entreviste. Establece dos reglas: una pregunta a la vez, y opción múltiple siempre que sea posible. Las specs resultantes tenían menos lagunas que las que escribía yo solo.

Guarda las specs completadas en docs/specs/YYYY-MM-DD-tema.md y hazles commit en Git. Esto da al agente acceso al historial de specs mediante git diff, y 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 descuidada

El brainstorming y las preguntas y respuestas durante la escritura de una spec consumen una parte significativa de la ventana de contexto. Pasar directamente a la implementación desde 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 una a una. La mejora en precisión fue perceptible dentro de la primera semana.

Tres hábitos que consolidaron este funcionamiento: 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 alcanza aproximadamente el 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 no ha llegado al nivel 1 todavía. Envían prompts sueltos esperando lo mejor, y cuando algo falla no hay forma de diagnosticar por qué.

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 puedes dar hoy es crear un CLAUDE.md para tu proyecto y escribir un SPEC.md antes de tu próxima funcionalidad.