Crea tres archivos de especificaciones antes de asignar trabajo a Claude Code o Codex

Si lleváis más de una semana usando agentes de codificación con IA, probablemente os habéis topado con esto: la misma tarea genera código limpio el lunes y basura el martes. El prompt apenas cambió. El repositorio tampoco. Pero el resultado es completamente distinto.

Pasé cerca de un año persiguiendo ese problema. Probé prompts más elaborados, instrucciones más detalladas, distintos modelos. Nada resolvía la causa raíz. El problema real era que no tenía ninguna forma estructurada de comunicar intención. Dependía del prompt para transportarlo todo: reglas del proyecto, requisitos de la funcionalidad, pasos de la tarea, convenciones de código. Es demasiado peso para una sola entrada.

La solución resultó ser dividir las instrucciones en tres archivos en tres capas distintas. Desde ese cambio, la brecha de calidad entre sesiones prácticamente ha desaparecido.

Por qué un solo archivo se rompe

La investigación sobre el seguimiento de instrucciones en LLMs describe un patrón conocido 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 en picado. Lo comprobé directamente: cuando metía reglas del proyecto, especificaciones de funcionalidades y listas de tareas en un solo archivo CLAUDE.md, el agente ignoraba aproximadamente la mitad de las instrucciones hacia el final del documento.

Tiene sentido si pensáis en cómo funciona la atención. Un documento largo lleno de preocupaciones mezcladas obliga al modelo a decidir en tiempo real qué importa más. Y toma malas decisiones. La solución es separar la información por rol para que cada capa permanezca enfocada.

Capa 1: CLAUDE.md como constitución del proyecto

CLAUDE.md (o su equivalente para vuestro agente) se carga automáticamente en cada sesión. Eso lo convierte en el lugar equivocado para instrucciones específicas de una funcionalidad. Debe contener únicamente cosas que sean ciertas en todo el proyecto:

• Comandos de compilación y versiones del stack tecnológico
• Estructura de carpetas y convenciones de nomenclatura
• Tres niveles de reglas de comportamiento: “hacer siempre”, “preguntar antes” y “nunca hacer”

Aprendí a no saturar este archivo con todo lo que se me ocurriera desde el principio. En cambio, observé dónde el agente cometía errores repetidos y añadí reglas de forma incremental. Ese enfoque funcionó mucho mejor que cualquier especificación inicial exhaustiva.

Algunas cosas que conviene mantener fuera de CLAUDE.md: claves de API (caducan), fragmentos de código (divergen del código real), reglas de estilo que ya aplica un linter, y cualquier cosa específica de una sola funcionalidad. Eso pertenece a la siguiente capa.

Capa 2: SPEC.md para el qué y el por qué

Un archivo de especificaciones describe una funcionalidad. Responde qué hace la funcionalidad, por qué existe, cuáles son los criterios de éxito, cuáles son las restricciones técnicas y dónde están los límites. Eso es todo. Cinco secciones.

La diferencia crítica respecto a un PRD tradicional: los archivos de especificaciones están estructurados para ser consumidos por el agente, no para reuniones de revisión humana. Y omiten deliberadamente el “cómo”. El agente debe deducir la implementación analizando el repositorio existente, no siguiendo instrucciones de codificación paso a paso desde la especificación.

Hay dos formas de escribir una buena especificación. Podéis redactarla vosotros mismos usando la estructura de cinco secciones anterior. O podéis hacer que el agente os entreviste. El enfoque de entrevista funciona sorprendentemente bien si aplicáis dos reglas: una pregunta a la vez, y preferir preguntas de opción múltiple sobre preguntas abiertas. La especificación resultante tiende a cubrir casos límite que yo habría pasado por alto escribiéndola solo.

Guardad las especificaciones completadas en docs/specs/YYYY-MM-DD-tema.md y haced commit. Esto crea un rastro que el agente puede seguir con git diff, y da a los revisores de código una forma de distinguir decisiones intencionales de accidentales.

Capa 3: plan.md para tareas ejecutables

El archivo de plan es la capa más concreta. Divide la especificación en tareas que duran entre dos y cinco minutos cada una, con rutas de archivo explícitas y un orden de ejecución fijo. Anclo cada plan a un ciclo TDD: escribir primero el test, implementar el código mínimo para que pase, confirmar que el test pasa y hacer commit.

Las rutas de archivo explícitas importan más de lo que esperaba. Sin ellas, el agente adivina dónde deben ir los archivos, y esas suposiciones divergen entre sesiones. Fijar las rutas elimina esa varianza.

La separación de sesiones que lo hizo funcionar

Aquí está la parte que tardé meses en descubrir. Incluso con tres archivos bien organizados, la calidad seguía degradándose cuando escribía la especificación y ejecutaba la implementación en la misma sesión. El motivo es sencillo: la lluvia de ideas y las preguntas y respuestas durante la escritura de la especificación consumen una gran parte de la ventana de contexto. Para cuando comienza la implementación, el agente ya está olvidando decisiones anteriores.

La solución es simple. Sesión 1: escribir SPEC.md y guardarlo. Sesión 2: generar plan.md a partir de la especificación. Sesión 3 en adelante: ejecutar tareas de una en una. También cambio a una nueva sesión cuando la ventana de contexto está aproximadamente a la mitad de su capacidad. La mejora en precisión fue inmediatamente perceptible.

Hacia dónde va esto

El equipo detrás del Manifiesto Ágil publicó un modelo de madurez para el desarrollo de software basado en agentes que encaja con este enfoque por capas:

• Nivel 1: Escribir una especificación, implementar y luego descartar la especificación.
• Nivel 2: Mantener la especificación viva como documento evolutivo que crece con el código.
• Nivel 3: La especificación se convierte en la única fuente de verdad, y el código es un artefacto generado.

La mayoría de los desarrolladores con los que hablo aún no han alcanzado el Nivel 1. Siguen operando en un modo donde el prompt es la única entrada y el código es la única salida. Eso funciona para tareas pequeñas, pero se desmorona a medida que crece la complejidad.

La transición del Nivel 1 al Nivel 2 es solo un hábito: hacer commit de vuestros archivos de especificaciones en Git. La transición del Nivel 2 al Nivel 3 es un cambio de flujo de trabajo: cuando necesitéis modificar el código, actualizad primero la especificación y regenerad.

Podéis empezar hoy mismo. Cread un CLAUDE.md con los fundamentos de vuestro proyecto, escribid un SPEC.md para vuestra próxima funcionalidad antes de tocar ningún código, y observad qué ocurre. La diferencia se acumula rápido.