Especificación para agentes de IA: una línea contra diez
En la práctica/ 14 min de lectura
Un prompt de una línea deja que el agente adivine. Una especificación de diez líneas le da objetivo, restricciones y criterios de aceptación que puede comprobar.
- IA
- Claude Code
En este artículo (10)
- Por qué una línea no le basta a un agente de IA
- Objetivo: qué cambia y para quién
- Restricciones: lo que el agente no puede adivinar
- Criterios de aceptación: cómo sabes que terminó
- Un ejemplo completo: antes y después
- Dónde guardar la especificación: issue o SPEC.md
- Revisa la especificación antes y el trabajo después
- Errores comunes
- Preguntas frecuentes
- Checklist
Una especificación para agentes de IA es un texto corto que dice qué construir (el objetivo), qué no tocar (las restricciones) y cómo saber que terminó (los criterios de aceptación). Con una línea, el agente adivina todo lo demás; con unas diez líneas, construye lo que pediste y puede comprobarlo él mismo.
Aquí tienes las tres partes, un ejemplo completo antes y después con una tienda en Next.js, dónde guardar la especificación y un script en Node que revisa que no le falte nada. Las recomendaciones que atribuimos a la documentación de Claude Code salen de su página de buenas prácticas, leída el 19 de noviembre de 2026; el resto es práctica.
Por qué una línea no le basta a un agente de IA
Escribe "agrega una barra de envío gratis al carrito" y un agente de código hará algo razonable. El problema es que hay muchas cosas razonables y solo una es la que tenías en mente. Con esa línea, el agente tiene que decidir por su cuenta dónde va la barra, de dónde sale el umbral, cómo se formatea el dinero, qué archivos puede tocar, qué no debe tocar y, sobre todo, cuándo terminó.
La documentación de Claude Code lo explica así: el agente lee tu código muy bien y encuentra por su cuenta la estructura, las convenciones y el framework de tests. Lo que no puede encontrar es lo que nunca estuvo en el repo: una decisión de una reunión, una preferencia entre dos caminos válidos o lo que para ti significa "listo". Por eso recomienda nombrar el archivo, describir el síntoma y decir desde el principio cómo se ve el resultado correcto. Su ejemplo: en lugar de "fix the login bug", describir cuándo falla, dónde mirar y pedir primero un test que reproduzca el fallo.
Hay un segundo motivo. Según la misma página, Claude tiende a leer las peticiones de forma conservadora y a construir lo mínimo que las cumple, porque no puede ver cuánto esperabas. Si quieres los estados vacíos y de error, o el flujo completo, tienes que decirlo. Una especificación es el lugar donde lo dices una sola vez.
No hace falta para todo. Si estás explorando ("¿qué mejorarías de este archivo?"), un prompt vago está bien y corriges sobre la marcha. La especificación vale la pena cuando el cambio toca varios archivos, cuando hay reglas que el código no muestra o cuando vas a dejar al agente trabajando solo. Si lo que tienes es un fallo, un buen reporte de bug para la IA ya es una especificación: el error, los pasos para reproducirlo y el resultado esperado.
Desliza la figura para verla completa
Objetivo: qué cambia y para quién
El objetivo son una o dos frases que describen el resultado, no la implementación. "En el carrito lateral, mostrar cuánto le falta al cliente para el envío gratis" dice qué ve la persona y dónde. No dice qué componente crear ni qué hook usar: eso lo puede decidir el agente leyendo el código.
Dos pruebas rápidas para un buen objetivo. La primera: alguien que no estuvo en la conversación entiende qué va a cambiar en la pantalla o en el sistema. La segunda: no mezcla dos cambios. Si tu objetivo tiene un "y además", probablemente son dos especificaciones y dos ramas.
Desliza la figura para verla completa
Restricciones: lo que el agente no puede adivinar
Las restricciones son los límites del cambio: qué archivos puede tocar, qué utilidades existentes debe usar, qué dependencias no se agregan y qué queda fuera de alcance. Para decidir qué escribir, la documentación de Claude Code propone dos preguntas: ¿lo podría encontrar leyendo el código? ¿De verdad iría a buscarlo? Si las dos respuestas son sí, déjalo fuera.
En el ejemplo, "formatea con formatMoney de lib/money.ts" sí va, porque hay otras formas válidas de formatear dinero y el agente podría escribir la suya. "El proyecto usa TypeScript" no va: lo ve en el primer archivo que abre. Lo mismo con las preferencias: si te importa cuál de dos enfoques razonables elige, dilo, porque eso no está en el código.
Una sección de "Fuera de alcance" ahorra muchas sorpresas. "El cálculo real del envío en el checkout queda fuera" evita que el agente, con buena intención, también arregle eso.
Ojo con lo que pones aquí. La documentación distingue entre instrucciones que el modelo lee y decide si seguir (el prompt, CLAUDE.md, una skill) y reglas que la herramienta aplica siempre (hooks, reglas de denegación). Una especificación es del primer tipo. Si una regla no puede tener excepciones, como no tocar nunca un directorio generado, ponla en un hook o en los permisos. Y si es una regla de todo el proyecto, no de esta tarea, va en el archivo de instrucciones: aquí explicamos cómo escribir AGENTS.md y combinarlo con CLAUDE.md.
Criterios de aceptación: cómo sabes que terminó
Esta es la parte que más se olvida y la que más cambia el resultado. La documentación de Claude Code lo dice sin rodeos: el agente para cuando el trabajo parece terminado, y si no tiene nada que ejecutar para saber si de verdad lo está, "parece" es todo lo que tiene. Su recomendación es darle algo que responda pasa o falla: un test, el código de salida de un build, un linter, un script que compare con un resultado esperado o una captura de pantalla junto al diseño.
Un criterio de aceptación sirve si alguien que no escribió el código puede revisarlo desde fuera y llegar a la misma respuesta. "Que se vea bien" no cumple. "El texto se ve completo a 375 px de ancho, sin scroll lateral" sí.
| Vago | Verificable | Cómo se revisa |
|---|---|---|
| Que se vea bien | El texto se ve completo a 375 px, sin scroll lateral | Captura a 375 px |
| Que funcione | Con subtotal 600 y umbral 999 se lee "Te faltan $399.00 para el envío gratis" | Test unitario |
| Que sea accesible | El texto vive en un elemento con aria-live="polite" | Test o axe |
| Sin romper nada | Ningún test existente se borra ni se salta | Diff de los archivos de test |
| Que compile | npm run typecheck sale con código 0 | Código de salida |
Los montos de la tabla son ilustrativos. La cuarta fila merece atención: "los tests pasan" se puede cumplir borrando el test que falla. Ya lo vimos en el agente de IA que pasó los tests porque los borró. Por eso conviene que la especificación diga también qué no puede cambiar en los tests, y que revises ese diff antes que el resto.
Desliza la figura para verla completa
Un ejemplo completo: antes y después
Antes, el prompt de una línea:
agrega una barra de envío gratis al carrito
Después, la misma petición como especificación. Son diez líneas de contenido, contando el título, más los encabezados de sección. Las rutas son de una tienda de ejemplo en Next.js y los montos son ilustrativos:
# Barra de envío gratis en el carrito
## Objetivo
En el carrito lateral, mostrar cuánto le falta al cliente para el envío gratis.
## Restricciones
- Toca solo components/cart/ y sus tests.
- El umbral sale de FREE_SHIPPING_MIN en lib/shipping.ts; no lo escribas en el componente.
- Formatea con formatMoney de lib/money.ts. Sin dependencias nuevas.
## Criterios de aceptación
- [ ] Subtotal 600 y umbral 999: se lee "Te faltan $399.00 para el envío gratis".
- [ ] Subtotal igual o mayor que el umbral: se lee "Tu envío es gratis".
- [ ] El texto vive en un elemento con aria-live="polite".
- [ ] Ningún test existente se borra ni se salta; npm test y npm run typecheck pasan.
## Fuera de alcance
- El cálculo real del envío en el checkout.
- El título nombra el cambio; sirve también como nombre de la rama y del pull request.
Objetivodescribe lo que ve quien compra y dónde, sin decir cómo construirlo.- La primera restricción limita el cambio a una carpeta y sus tests, así el diff queda pequeño y fácil de revisar.
- La segunda dice de dónde sale el umbral. Sin ella, lo más probable es un
999escrito dentro del componente. - La tercera elige entre dos caminos válidos (la utilidad existente o una nueva) y descarta dependencias.
- Los dos primeros criterios dan valores concretos y el texto exacto, así se convierten directamente en tests.
- El tercero cubre accesibilidad: un lector de pantalla anuncia el cambio cuando sube el subtotal.
- El cuarto cierra la trampa de los tests borrados y nombra los dos comandos que deben pasar.
Fuera de alcancele dice al agente dónde parar.
Con el archivo listo, el prompt para empezar es corto. La @ seguida de la ruta incluye el archivo en el mensaje:
Lee @SPEC.md. Antes de editar, dime qué archivos vas a tocar y cómo vas a comprobar cada criterio de aceptación. Al terminar, pega la salida de npm test y de npm run typecheck.
La primera parte pide un plan antes de tocar código; si quieres que el agente no pueda editar hasta que lo apruebes, usa plan mode en Claude Code. La última parte pide evidencia: la documentación recomienda pedir el comando que se ejecutó y su salida, porque "todos los tests pasan" por sí solo dice muy poco.
Dónde guardar la especificación: issue o SPEC.md
Depende de quién más la tiene que leer y de cuánto va a durar.
| Dónde | Cuándo conviene | Qué pierdes |
|---|---|---|
| En el prompt | Cambios de una sesión, que nadie más revisa | Desaparece al cerrar la sesión |
| Un issue | El equipo lo discute, se asigna y se enlaza desde el pull request | El agente necesita que se lo pegues o que tenga acceso al issue |
SPEC.md en la rama | El agente lo lee con @SPEC.md y el revisor lo tiene junto al código | Hay que borrarlo o archivarlo al hacer merge |
AGENTS.md o CLAUDE.md | Reglas que valen para todas las tareas | No es para una tarea: se carga en cada sesión |
La documentación de Claude Code propone un flujo para cuando no tienes claro qué quieres: pedirle al agente que te entreviste hasta poder escribir la especificación y que la guarde en SPEC.md. Su ejemplo es sobre límites de peticiones en una API; adaptado al nuestro:
Quiero agregar una barra de envío gratis al carrito, pero no lo he pensado del todo. Entrevístame hasta que puedas escribir la especificación y luego escríbela en SPEC.md.
El agente pregunta por lo que no has decidido (qué pasa con descuentos, qué queda fuera) hasta que las respuestas forman una especificación. Después, la documentación recomienda abrir una sesión nueva para construir, así el trabajo empieza con un contexto limpio y una definición de terminado por escrito. Si trabajas en una rama por tarea, como en este flujo de git con agentes, el SPEC.md viaja con la rama.
Revisa la especificación antes y el trabajo después
Una especificación incompleta se nota tarde, cuando el diff ya está hecho. Este script en Node, sin dependencias, la revisa antes de empezar: comprueba que estén las tres partes con contenido y que los criterios de aceptación no sean deseos.
// Usage: node check-spec.mjs SPEC.md
import { readFileSync } from "node:fs";
const file = process.argv[2] ?? "SPEC.md";
const lines = readFileSync(file, "utf8").split(/\r?\n/);
const problems = [];
// Group the lines under their "## " heading.
const sections = {};
let current = "";
for (const line of lines) {
if (line.startsWith("## ")) current = line.slice(3).trim();
(sections[current] ??= []).push(line);
}
// The three parts, with Spanish or English headings, and not empty.
const parts = [["Objetivo", "Goal"], ["Restricciones", "Constraints"], ["Criterios de aceptación", "Acceptance criteria"]];
for (const names of parts) {
const body = names.flatMap((n) => sections[n]?.slice(1) ?? []);
if (!body.some((l) => l.trim())) problems.push(`missing or empty section: ## ${names.join(" / ")}`);
}
// Every acceptance criterion is a checkbox, and none of them is a wish.
const criteria = parts[2].flatMap((n) => sections[n] ?? []).filter((l) => /^- \[[ x]\] /i.test(l));
if (criteria.length === 0) problems.push("no acceptance criteria (- [ ] ...)");
const vague = /\b(bien|correctamente|bonito|limpio|properly|correctly|nice|clean)\b/i;
for (const c of criteria) if (vague.test(c)) problems.push(`vague criterion: ${c}`);
console.log(problems.length ? problems.map((p) => `FAIL ${p}`).join("\n") : `OK ${file}: ${criteria.length} criteria`);
process.exit(problems.length ? 1 : 0);
- Lee el archivo que le pasas (por defecto
SPEC.md) y lo parte en líneas; acepta finales de línea de Windows. - El bucle agrupa cada línea bajo su encabezado
##; la primera línea de cada grupo es el propio encabezado. partslista las tres secciones obligatorias, con su nombre en español o en inglés.- Para cada parte junta las líneas sin el encabezado y falla si no hay ninguna con texto: una sección vacía cuenta como ausente.
criteriatoma las casillas- [ ](o ya marcadas,- [x]) de la sección de criterios, y falla si no hay ninguna.vaguebusca palabras que no se pueden revisar desde fuera, como "bien" o "correctamente". Es una lista corta a propósito: agrega las que veas en tus especificaciones.- Imprime
OKcon el número de criterios o unFAILpor problema, y sale con código 1 si hay alguno, así lo puedes usar en un hook o en CI.
Lo corrimos con Node 22 sobre la especificación de arriba, sobre su versión en inglés y sobre una especificación vaga escrita a mano:
$ node check-spec.mjs SPEC.md
OK SPEC.md: 4 criteria
$ node check-spec.mjs SPEC.vaga.md
FAIL missing or empty section: ## Restricciones / Constraints
FAIL vague criterion: - [ ] Que se vea bien en móvil.
FAIL vague criterion: - [ ] Que funcione correctamente.
Al terminar el agente, revisa el trabajo contra la especificación, no contra tu memoria de lo que pediste. La documentación sugiere un prompt para un revisor que no vio la conversación; en español sería: "usa un subagente para revisar el diff contra SPEC.md, comprueba que cada requisito esté implementado y que los casos límite listados tengan tests, reporta los huecos que afecten la corrección y omite el estilo". Y advierte que no quites lo de omitir el estilo: un revisor al que le pides problemas siempre encuentra alguno, y si arreglas todos terminas con capas de más.
Errores comunes
- Describir la implementación en lugar del resultado. "Crea un hook useFreeShipping" fija un camino; "mostrar cuánto falta para el envío gratis" deja que el agente elija según el código.
- Repetir lo que el repo ya dice. El framework, la estructura de carpetas o el estilo de código los encuentra por su cuenta. Cada línea de más compite con las que importan.
- Criterios que no se pueden revisar. "Que funcione bien" no pasa ni falla. Escribe el valor, el texto o el comando.
- Aceptar "los tests pasan" sin más. Pide que ningún test se borre ni se salte, y revisa ese diff primero.
- Olvidar lo que queda fuera. Sin esa sección, el agente puede "mejorar" algo que no le pediste.
- Usar la especificación para reglas absolutas. Si algo no puede pasar nunca, va en un hook o en los permisos, no en un texto que el modelo interpreta.
- Construir en la misma sesión donde discutiste la idea. Una sesión nueva con
@SPEC.mdempieza con el contexto limpio. - No actualizarla. Si a mitad del trabajo cambias de opinión, cambia primero la especificación; si no, el revisor compara contra algo que ya no es cierto.
Preguntas frecuentes
¿Qué diferencia hay entre una especificación y un prompt?
Una especificación es un prompt con estructura y con una definición de terminado. La diferencia práctica es que se puede guardar, revisar con otra persona y usar después para comparar el resultado. Un prompt suelto desaparece con la sesión.
¿Qué tan larga debe ser?
Lo suficiente para que el agente no adivine lo que importa. Para un cambio como el del ejemplo, unas diez líneas bastan. Si pasa de una página, revisa si estás describiendo la implementación o si en realidad son dos tareas.
¿La escribo yo o la escribe la IA?
Las dos funcionan. Si ya sabes lo que quieres, escríbela tú. Si no, pide al agente que te entreviste y la escriba en SPEC.md, como sugiere la documentación de Claude Code, y léela antes de construir: es tu definición de terminado, no la suya.
¿Sirve con otros agentes además de Claude Code?
Sí. Un archivo Markdown con objetivo, restricciones y criterios no depende de ninguna herramienta. Lo que cambia es cómo se lo pasas: con @, pegándolo o desde un issue al que el agente tenga acceso.
Checklist
- El objetivo cabe en una o dos frases y describe el resultado.
- Las restricciones solo dicen lo que el agente no puede leer en el repo.
- Hay una sección de lo que queda fuera de alcance.
- Cada criterio de aceptación pasa o falla, con valores, textos o comandos.
- Un criterio prohíbe borrar o saltar tests existentes.
- Las reglas sin excepciones están en hooks o permisos, no en la especificación.
- La especificación vive en un issue o en
SPEC.mddentro de la rama. check-spec.mjspasa antes de empezar.- Pides evidencia (comandos y salidas) y revisas el diff contra la especificación.
La guía en PDF trae la plantilla en blanco y dos especificaciones llenas, listas para copiar.
¿Viste esto en Instagram? Comenta SPEC en el Reel y te mando la guía.
Escrito por

Publicado el 19 de noviembre de 2026