Saltar al contenido

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)
  1. Por qué una línea no le basta a un agente de IA
  2. Objetivo: qué cambia y para quién
  3. Restricciones: lo que el agente no puede adivinar
  4. Criterios de aceptación: cómo sabes que terminó
  5. Un ejemplo completo: antes y después
  6. Dónde guardar la especificación: issue o SPEC.md
  7. Revisa la especificación antes y el trabajo después
  8. Errores comunes
  9. Preguntas frecuentes
  10. 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.

un prompt de una línea contra una especificación de diezuna líneaagrega una barra de envíogratis al carritoel agente adivina:· 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· cuándo terminódiez líneas# Barra de envío gratis## Objetivo## Restricciones## Criterios de aceptación## Fuera de alcanceel agente sabe qué hacer y cuándo pararel mismo cambio, pedido de dos formas

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.

las tres partes de una especificación1 · objetivo¿qué cambia?barra de envío gratisen el carrito lateralpara quien comprauna o dos frases2 · restricciones¿qué no tocar?solo components/cart/umbral de lib/shippingsin dependencias nuevaslo que no está en el repo3 · criterios¿cuándo terminó?subtotal 600: faltan 399subtotal ≥ 999: gratisnpm test pasapasa o fallasin la tercera, el agente para cuando el trabajo parece listotres partes, unas diez líneasmontos ilustrativos; tienda de ejemplo en Next.js

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

VagoVerificableCómo se revisa
Que se vea bienEl texto se ve completo a 375 px, sin scroll lateralCaptura a 375 px
Que funcioneCon subtotal 600 y umbral 999 se lee "Te faltan $399.00 para el envío gratis"Test unitario
Que sea accesibleEl texto vive en un elemento con aria-live="polite"Test o axe
Sin romper nadaNingún test existente se borra ni se saltaDiff de los archivos de test
Que compilenpm run typecheck sale con código 0Có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.

criterios de aceptación: vagos contra verificablesvagoverificablecómo se revisaque se vea bientexto visible a 375 px sin scroll lateralcaptura a 375 pxque funcionesubtotal 600: «Te faltan $399.00»test unitarioque sea accesibleel texto vive en aria-live="polite"test o axesin romper nadaningún test se borra ni se saltagit diff de testsque compilenpm run typecheck sale con código 0código de salidasi nadie lo puede revisar desde fuera, es un deseo, no un criteriocada criterio pasa o fallaejemplo ilustrativo de una tienda en Next.js

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.
  1. El título nombra el cambio; sirve también como nombre de la rama y del pull request.
  2. Objetivo describe lo que ve quien compra y dónde, sin decir cómo construirlo.
  3. La primera restricción limita el cambio a una carpeta y sus tests, así el diff queda pequeño y fácil de revisar.
  4. La segunda dice de dónde sale el umbral. Sin ella, lo más probable es un 999 escrito dentro del componente.
  5. La tercera elige entre dos caminos válidos (la utilidad existente o una nueva) y descarta dependencias.
  6. Los dos primeros criterios dan valores concretos y el texto exacto, así se convierten directamente en tests.
  7. El tercero cubre accesibilidad: un lector de pantalla anuncia el cambio cuando sube el subtotal.
  8. El cuarto cierra la trampa de los tests borrados y nombra los dos comandos que deben pasar.
  9. Fuera de alcance le 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óndeCuándo convieneQué pierdes
En el promptCambios de una sesión, que nadie más revisaDesaparece al cerrar la sesión
Un issueEl equipo lo discute, se asigna y se enlaza desde el pull requestEl agente necesita que se lo pegues o que tenga acceso al issue
SPEC.md en la ramaEl agente lo lee con @SPEC.md y el revisor lo tiene junto al códigoHay que borrarlo o archivarlo al hacer merge
AGENTS.md o CLAUDE.mdReglas que valen para todas las tareasNo 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);
  1. Lee el archivo que le pasas (por defecto SPEC.md) y lo parte en líneas; acepta finales de línea de Windows.
  2. El bucle agrupa cada línea bajo su encabezado ## ; la primera línea de cada grupo es el propio encabezado.
  3. parts lista las tres secciones obligatorias, con su nombre en español o en inglés.
  4. 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.
  5. criteria toma las casillas - [ ] (o ya marcadas, - [x]) de la sección de criterios, y falla si no hay ninguna.
  6. vague busca 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.
  7. Imprime OK con el número de criterios o un FAIL por 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.md empieza 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.md dentro de la rama.
  • check-spec.mjs pasa 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

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 19 de noviembre de 2026

← Blog