Tag: Claude Code

Hooks vs permissions en Claude Code: dónde va el guardrail

Abrí mi propio .claude/settings.local.json mientras preparaba este post. Buscaba un ejemplo bonito de hooks vs permissions en Claude Code para ilustrar la diferencia. Encontré otra cosa.

364 reglas allow. Cero reglas deny. Cero ask. Y "defaultMode": "bypassPermissions".

La primera regla de la lista es Bash(*).

Bash(*) equivale a Bash: matchea todos los comandos. Las otras 185 reglas de Bash de la lista ya no afinan nada, porque no queda nada que afinar. Y las 178 restantes —WebFetch, PowerShell, Skill— tampoco protegen: una regla allow nunca dice que no, solo evita que te pregunten. Con bypassPermissions puesto, ni eso: no iba a preguntar de todas formas. Una allowlist de 364 líneas que no le dice que no a nada.

Lo mejor viene ahora. En el .claude/settings.json versionado del mismo repositorio sí hay dos hooks PreToolUse, con matchers Bash y Read|Glob. Funcionan perfectamente. Son hooks de guía y observabilidad — le dicen a Claude por dónde buscar antes de lanzarse a hacer grep por todo el repo — no de seguridad.

Capa de hooks montada. Capa de permisos abierta de par en par.

Hace poco escribí, en el post donde probé la blocklist típica y pasaron 16 de 20 comandos destructivos, esta frase exacta: "Revisa el tuyo con una pregunta concreta: ¿hay alguna regla comodín tipo Bash(*) que anule a todas las demás? Si la hay, tu allowlist es decorativa."

Hooks vs permissions: las dos capas, y cuál manda

Claude Code tiene dos sitios donde puedes decir "esto no".

El sistema de permisos: configuración declarativa con reglas allow, deny y ask. Los hooks: scripts tuyos que se ejecutan antes de la llamada a la herramienta y pueden bloquearla. Las dos son piezas del agent harness, esa capa que rodea al modelo y decide qué puede tocar de verdad.

El sistema de permisos de Claude Code es configuración declarativa —reglas allow, deny y ask en settings.json— que se evalúa antes de ejecutar la herramienta. Un hook PreToolUse es un script tuyo que Claude Code ejecuta antes de la llamada y que puede bloquearla saliendo con código 2. La diferencia que decide dónde va tu guardrail: los permisos no pueden fallar, el hook sí.

Casi todo el que se preocupa por la seguridad monta un hook. Es lo divertido: escribes código, haces pattern matching, devuelves exit 2 y te sientes ingeniero de seguridad. Si nunca has montado uno, empieza por Claude Code hooks: guardrails, logging y automatización para tus agentes, el tutorial del cómo.

Este post va del dónde. Y el dónde importa porque las dos capas no tienen la misma autoridad.

Un hook solo puede restringir, nunca ampliar

Un hook PreToolUse es una válvula de un solo sentido. Cierra, no abre.

La documentación de permisos de Claude Code no deja margen a interpretación. Traduzco las dos frases que lo zanjan:

"Las decisiones de un hook no saltan las reglas de permisos. Claude Code evalúa las reglas deny y ask sea cual sea lo que devuelva un hook PreToolUse: una regla deny que coincida bloquea la llamada, y una regla ask que coincida sigue preguntando incluso cuando el hook ha devuelto allow o ask."

"Un hook que bloquea también tiene precedencia sobre las reglas allow. Un hook que sale con código 2 detiene la llamada antes de que se evalúen las reglas de permisos, así que el bloqueo se aplica incluso cuando una regla allow habría dejado pasar la llamada."

Puede vetar lo que tus permisos habrían permitido. No puede rescatar lo que ya han denegado. Si diseñas la seguridad pensando que el hook es "el sitio donde yo decido", la estás montando sobre la capa con menos autoridad.

La propia documentación sugiere el patrón combinado: para ejecutar todos los comandos Bash sin prompts salvo unos pocos, pon "Bash" en allow y registra un hook PreToolUse que rechace esos concretos. Es un patrón legítimo. Fíjate en para qué lo propone: ergonomía. No suelo de seguridad.

El hook falla abierto. La regla `deny` no puede fallar.

Un hook es un proceso. Y a los procesos les pasan cosas. Esto es lo que ocurre según cómo termine:

Esto es lo que dice la documentación de hooks según cómo termine el proceso:

exit 2 → bloquea. Imprima JSON o no; ni un permissionDecision de allow puede anularlo. El mensaje de bloqueo es la razón del JSON si la hay, y si no, el stderr.
exit 0 con JSON válido → manda la decisión del JSON y el exit code se ignora.
Cualquier otro exit code, un script que no existe, JSON inválido o un timeout → error no bloqueante. En palabras de la doc: "the action proceeds". La llamada continúa por el flujo normal de permisos y en el transcript aparece un aviso <hook name> hook error.

Lee otra vez la tercera.

El día que renombras el script, cambias de máquina, se te cuela una coma en el JSON o el proceso se pasa del timeout, tu "guardrail de seguridad" deja pasar el comando. No para el mundo: escribe un aviso y sigue.

Incluida la salida 1, la de fallo de toda la vida en Unix: si tu hook revienta con exit 1, el comando pasa.

En PreToolUse el timeout por defecto es de 600 s. Y todos los hooks que matchean corren en paralelo, así que tampoco hay un orden de ejecución en el que apoyarte.

Una regla deny no tiene ninguna de esas formas de fallar: no hay proceso, ni exit code, ni ruta a un binario que pueda cambiar. Es configuración que se evalúa antes de ejecutar nada. Si una herramienta está denegada en cualquier nivel, ningún otro nivel puede permitirla — ni --allowedTools en la línea de comandos.

Falla cerrado por construcción. Por eso el suelo va ahí.

El sistema de permisos entiende de shell. Tu `grep` no.

Cuando escribes un hook con grep haces pattern matching sobre un string. Claude Code no: parsea el comando.

Los separadores que reconoce son &&, ||, ;, |, |&, & y los saltos de línea. Cada subcomando debe coincidir por separado. Y las reglas deny y ask matchean más allá de una asignación de variable de entorno.

Dos comandos y las dos capas, lado a lado:

safe-cmd && rm -rf /
FOO=bar rm -rf tmp/

Comando	Hook con `grep`	Regla de permisos
`safe-cmd && rm -rf /`	`[[ "$cmd" == safe-cmd* ]]` → pasa: el string empieza por `safe-cmd`	`Bash(safe-cmd *)` no da permiso: cada subcomando se matchea por separado
`FOO=bar rm -rf tmp/`	`grep -E '^rm '` → no matchea: el comando empieza por `FOO`	`Bash(rm *)` en `deny` sí coincide: matchea pasada la asignación

Dos comandos. Dos fallos del hook ingenuo. Cero de las reglas.

Y hay más parseo que no vas a reimplementar bien. Antes de matchear se despojan los wrappers conocidos: timeout, time, nice, nohup, stdbuf, los builtins command y builtin, y el noglob de zsh. Por eso Bash(npm test *) también cubre timeout 30 npm test.

Claude Code hasta rechaza tus patrones frágiles por ti: una regla como Bash(command:rm *) sería esquivable con un comando compuesto, así que la ignora y emite un warning al arrancar. Lo correcto es Bash(rm *).

Los agujeros que sí existen

Los permisos no son magia. Hay tres sitios donde te toca poner de tu parte.

Los runners de entorno no están en la lista de wrappers que se despojan: direnv exec, devbox run, mise exec, npx, docker exec. Ejecutan sus argumentos como comando, así que Bash(devbox run *) cubre también devbox run rm -rf .. La regla correcta lleva runner + comando interno, Bash(devbox run npm test), una por cada uno. Tedioso y correcto.

Los patrones sobre argumentos son frágiles: Bash(curl http://github.com/ *) no cubre las variaciones. Deniega curl y wget y usa WebFetch con WebFetch(domain:github.com).

Las redirecciones se comprueban como escritura de archivo: el destino de >, >> y 2> se valida contra tus reglas Edit. Bash(git commit *) permite el comando, no el destino. /dev/null no se comprueba.

Nada de esto lo arregla un hook. Enumerar strings peligrosos es el diseño equivocado, lo escribas en un middleware o en un PreToolUse.

La sintaxis que casi nadie escribe bien

Regla	Qué matchea
`Bash(npm run build)`	exactamente `npm run build`
`Bash(npm run *)`	`npm run build`, `npm run test --watch`, y el escueto `npm run`
`Bash(ls *)`	`ls -la` y `ls` — pero no `lsof`
`Bash(ls*)`	`ls -la` y `lsof`
`Read(./.env)`	leer el `.env` del directorio actual
`Read(./secrets/**)`	glob estilo gitignore
`WebFetch(domain:example.com)`	peticiones a ese dominio

El espacio antes del * es toda la diferencia entre ls y lsof. El sufijo :* equivale al wildcard final — Bash(ls:*) ≡ Bash(ls *) — pero solo se reconoce al final del patrón: en Bash(git:* push) los dos puntos son un carácter literal.

Y el * va después del subcomando. Bash(git log *) permite solo git log; Bash(git *) permite todo git. Claude Code te avisa al arrancar si lo escribes antes.

Queda la precedencia, que mucha gente asume al revés: se evalúa deny, luego ask, luego allow. La primera coincidencia en ese orden decide, y la especificidad de la regla no altera el orden. Una deny amplia como Bash(aws *) bloquea todo lo que coincida, incluida una allow más estrecha como Bash(aws s3 ls).

Dicho de otra forma: una regla deny no admite excepciones de allowlist. Si necesitas una excepción, no la pongas en deny.

Hooks vs permissions en Claude Code: qué va en cada capa

	`permissions`	Hooks `PreToolUse`
Naturaleza	Configuración declarativa	Proceso que ejecutas
Modo de fallo	No puede fallar: no hay nada que ejecutar	Falla abierto: error, timeout o JSON inválido → la acción continúa
Autoridad	`deny` es absoluto en todos los niveles	Solo restringe; nunca amplía
Entiende shell	Sí: separadores, wrappers, asignaciones, redirecciones	Solo lo que tú programes
Superficie	Toda herramienta con regla	Solo lo que cubra tu matcher
Para qué sirve	Suelo de seguridad, lo irreversible, secretos	Contexto, logging, reescritura, reglas que dependen del estado del proyecto
Ejemplo	`Bash(rm *)`, `Read(./.env)`	Registrar cada comando, avisar si el working tree está sucio, guiar la búsqueda

El JSON que deberías tener

{
  "permissions": {
    "defaultMode": "default",
    "deny": [
      "Bash(rm *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(docker *)",
      "Bash(npm publish *)"
    ],
    "allow": [
      "Bash(npm run build)",
      "Bash(npm test *)",
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(ls *)",
      "WebFetch(domain:github.com)"
    ],
    "disableBypassPermissionsMode": "disable"
  }
}

Bash(rm *) en deny cubre FOO=bar rm -rf tmp/ sin que hagas nada. Bash(npm test *) en allow cubre timeout 30 npm test gracias al despojado de wrappers. Y deny bloquea aunque más abajo haya una allow que coincida: no hay forma de escribir la excepción, y esa es justo la propiedad que querías.

Este es el tipo de decisión que trabajo en el curso Construye con IA: de la idea al producto con Claude Code: antes de darle capacidades a un agente, dejar por escrito qué no puede hacer.

Entonces, ¿para qué el hook?

Para lo que los permisos no saben expresar. Contexto: la hora, la rama, si el working tree está sucio. Observabilidad: registrar cada llamada. Guía: decirle por dónde buscar antes de que haga grep por todo el repo, que es lo que hacen los dos hooks de mi repo. Reescritura y guía de comandos. Decisiones que dependen del estado del proyecto, no del string del comando.

Con un límite que conviene tener delante. En PreToolUse el matcher se compara contra el nombre de la herramienta. "*", "" u omitido matchean todo. Si solo contiene letras, dígitos, _, -, espacios, , y |, es un string exacto o una lista: Bash, Edit|Write. Cualquier otro carácter lo convierte en una expresión regular de JavaScript sin anclar: ^Bash.

Consecuencia práctica: un matcher "Bash" no cubre PowerShell, ni Write, ni Edit, ni las herramientas MCP (mcp__servidor__tool). Si tu guardrail vive solo ahí, toda esa superficie está descubierta y no te vas a enterar.

Qué hacer hoy

Abre tu .claude/settings.local.json y cuenta las reglas deny. Si el número es cero, ya tienes plan para esta tarde.

Escribe cinco. Solo cinco, y que sean lo irreversible: los secretos y el borrado.

Read(./.env) — que no lea tus claves.
Read(./secrets/**) — ni el resto de secretos.
Bash(rm *) — el borrado, que además cubre FOO=bar rm -rf tmp/.
Bash(curl *) — la exfiltración por red.
Bash(wget *) — la otra mitad de lo mismo.

Luego quita bypassPermissions y ponle "disableBypassPermissionsMode": "disable". Y si trabajas con equipo, todo eso va en managed settings: la precedencia más alta, no lo anula ningún otro nivel ni los argumentos de línea de comandos.

Un último detalle que resume el post. Poner disableAllHooks solo en tus settings de usuario no basta: los settings de proyecto del repositorio tienen precedencia sobre los tuyos y pueden volverlo a false. Ni siquiera desactivar los hooks se decide desde donde viven los hooks.

La autoridad está en la configuración. Tu script es la capa de encima.

Mi settings.local.json ya tiene reglas deny. Tardé cuatro minutos. Llevaba meses con Bash(*) en la primera línea y un hook precioso que no protegía absolutamente nada.

Si quieres ver esta capa montada en proyectos reales, con los settings completos y los hooks que sí aportan, lo trabajamos dentro de Dominicode Labs.

Comportamiento verificado contra la documentación oficial de Claude Code en septiembre de 2026.

Preguntas frecuentes

¿Puedo usar un hook para permitir algo que una regla deny bloquea?

No. Claude Code evalúa las reglas deny y ask sea cual sea lo que devuelva el hook. Una regla deny que coincida bloquea la llamada aunque el hook haya devuelto allow, y una regla ask sigue preguntando igual.

Al revés sí funciona: un hook que sale con exit 2 detiene la llamada antes de que se evalúen los permisos, así que bloquea aunque una regla allow la hubiera dejado pasar. El hook solo restringe.

¿Qué pasa si mi hook de seguridad falla o el script no existe?

El comando se ejecuta. Cualquier exit code que no sea 0 o 2, un script inexistente, un JSON inválido o un timeout se tratan como error no bloqueante: la acción continúa por el flujo normal de permisos y en el transcript aparece un aviso <hook name> hook error.

Por eso un hook no es un buen suelo de seguridad. Una regla deny es configuración, no hay proceso que pueda reventar.

¿Basta con poner Bash en deny para bloquear todos los comandos?

Sí, y hace algo más de lo que esperas. Bash(*) es equivalente a Bash y matchea todos los comandos. Como regla deny, ambas formas eliminan la herramienta del contexto de Claude: el modelo ni siquiera la ve.

Lo que no puedes es denegar Bash entero y luego abrir excepciones con reglas allow más estrechas. Una regla deny no admite excepciones de allowlist.

¿Por qué mi regla `Bash(ls *)` no permite `lsof`?

Porque el espacio antes del asterisco forma parte del patrón. Bash(ls *) matchea ls -la y el escueto ls, pero no lsof. Si quieres cubrir los dos, la regla es Bash(ls*), sin espacio.

Mismo cuidado con el subcomando: el * va después. Bash(git log *) permite solo git log; Bash(git *) te abre todo git.

¿Cómo evito que alguien active bypassPermissions en mi equipo?

Con permissions.disableBypassPermissionsMode a "disable", y su equivalente permissions.disableAutoMode para el modo auto. En tus settings de usuario ya sirven, pero puestos en managed settings son inanulables: ese nivel tiene la precedencia más alta y no lo tumba ningún otro, ni los argumentos de línea de comandos.

¿Dónde pongo las reglas: `settings.json` o `settings.local.json`?

.claude/settings.json se versiona y lo comparte todo el equipo. .claude/settings.local.json es tuyo y solo tuyo: Claude Code lo añade a tus git excludes la primera vez que lo escribe, así que no se sube. Si lo creaste tú a mano, añádelo al .gitignore.

La precedencia va de mayor a menor: managed settings, argumentos de línea de comandos, settings.local.json del proyecto, settings.json del proyecto y ~/.claude/settings.json de usuario. Con una salvedad que ya conoces: si algo está denegado en cualquiera de esos niveles, ningún otro puede permitirlo.

Así que el suelo compartido va en el settings.json versionado, donde lo hereda todo el equipo. Tus atajos personales, en el local.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

September 9, 2026

Revisar código generado por IA: el método Revisión por Contrato

Una noche estuve casi dos horas revisando una pull request.

No la escribí yo. La escribió el agente, en dos minutos.

Y ahí me quedé, con el diff abierto a las tantas, leyendo línea por línea un código que no había escrito, buscando el fallo que sabía que estaba en alguna parte.

Dos minutos de generación. Ciento diez de revisión.

Revisar código generado por IA se había comido entero el tiempo que la IA me iba a ahorrar.

Nos vendieron que la IA nos iba a quitar trabajo, y es verdad a medias, que es la peor forma de ser verdad. Te quitó el trabajo de escribir. Te dio el trabajo de auditar.

Antes escribías cuatrocientas líneas en dos horas. Ahora las lees en dos horas.

Por qué revisar código generado por IA cansa más que escribirlo

Revisar código generado por IA cansa más que escribirlo porque no sigues un razonamiento: verificas cuatrocientas afirmaciones independientes, una a una, sin ningún hilo que las sostenga.

Cuando escribes esas cuatrocientas líneas, el modelo mental se construye contigo. Entender es un subproducto gratis de haberlas escrito.

Cuando las revisas, tienes que reconstruir ese modelo desde fuera, deduciendo la intención a partir del resultado. Y ahí está el detalle:

Del otro lado no había ningún modelo mental.

Tu compañero, cuando escribió aquella función rara, tenía un motivo. Malo o bueno, pero un motivo, y podías preguntárselo. El agente produjo el token más probable dadas las circunstancias. Estás reconstruyendo una intención que nunca existió.

Por eso cansa distinto, y por eso no mejora con la práctica: no hay nada que aprender, solo cuatrocientas comprobaciones que hacer.

Y lo peor no es el tiempo. Es que nunca sabes del todo si se te ha colado algo, porque en la línea 230 aflojaste y lo sabes. O lo lees entero con la misma atención en la 400 que en la 12, o lo mergeas con el nudo en el estómago. No hay tercera.

Y ya sabes cuál de las dos gana casi siempre: en cinco proyectos de gran escala, el 64,7% de las pull requests se aprueba sin un solo comentario.

El problema no era el agente

Yo estuve meses culpando al modelo. Cambié de herramienta tres veces y escribí prompts cada vez más largos, con más reglas, más ejemplos y más mayúsculas.

Mejoraba un poco. Nunca lo suficiente.

Hasta que caí en lo que estaba delante desde el principio: el problema no era el agente, era que yo era la única verificación del sistema. Entre el código generado y producción no había nada más que mis ojos cansados.

Eso no lo arregla un modelo mejor. Un modelo mejor te da código correcto más a menudo, pero no cambia quién tiene que comprobarlo.

De hecho, cada mejora en la velocidad de generación empeora tu situación. Si el agente pasa de cuatrocientas líneas a ochocientas en el mismo rato, tú no has ganado nada: has doblado la cola de revisión. La única parte del proceso que no escala eres tú, y todo el mundo está optimizando las otras.

Por qué tu spec no lo arregló

Aquí es donde la mayoría me dice que ya probó lo de escribir specs y lo dejó.

Yo también. Y no es que las specs sean inútiles: es que escribiste la spec para el agente, no para la verificación.

Mira tus criterios de aceptación de la última vez. “El endpoint debe ser rápido.” “Maneja bien los errores.” “No rompas nada.” Frases que ninguna máquina puede rechazar. Una spec que nadie comprueba es documentación, y la documentación no ha frenado un bug en la historia de esta profesión.

Un contrato es una especificación contra la que algo puede fallar. Fallar de verdad: salir con código distinto de cero, poner el CI en rojo, parar la cosa antes de que llegue a ti.

Es la misma diferencia que ya conoces entre un README que dice “recuerda formatear antes de commitear” y un hook que no te deja commitear sin formatear. Los dos expresan la misma norma. Uno confía en que alguien se acuerde.

Tu spec era un README muy bien escrito. Lo que necesitas es el hook.

Así que coge cualquier línea de cualquier spec tuya y pregúntate esto:

¿Puedo escribir algo que compruebe esto sin mí?

Si la respuesta es sí, tienes una cláusula. Si es no, tienes una intención. Las intenciones no se tiran —orientan al agente y algo aportan—, pero no cuentan: no van a rechazar nada y no puedes apoyarte en ellas para dejar de leer el diff entero.

Cuando pasas tu spec entera por esa pregunta suele salir algo incómodo: de veinte líneas, diecisiete eran intenciones.

Si al hacer el recuento te sale un número parecido, el problema no es que escribas mal specs: son los siete fallos típicos que hacen que una spec no aguante delante de un agente, y casi todos se arreglan con la misma pregunta.

Ahí está tu tiempo de revisión. Y convertir esas diecisiete es lo que llamo Revisión por Contrato: tres piezas en un orden que importa.

La Revisión por Contrato es un método para revisar código generado por IA sin leer el diff entero. Consta de tres piezas: conviertes las intenciones de tu spec en cláusulas que una máquina puede rechazar (contrato), declaras por escrito dónde el agente no puede escribir (carril) y dejas que un conjunto de comandos ejecutables emita el resultado (veredicto). Lo que tú revisas después es el veredicto y el contrato, no las cuatrocientas líneas.

1. Contrato: qué se construye

La conversión desde tu spec actual es bastante mecánica:

Spec (describe)	Contrato (se puede incumplir)
“El endpoint debe ser rápido”	p95 < 200 ms en el test de carga del CI
“Maneja bien los errores”	Todo path de error devuelve un tipo del enum `AppError`
“No rompas nada”	La suite existente pasa sin cambios en sus asserts
“Sigue las convenciones”	`lint` y `typecheck` en verde, sin excepciones nuevas

Hay dos contratos, y confundirlos es el error más común. El AGENTS.md es el contrato permanente del repositorio: lo que es cierto para cualquier tarea que se haga aquí. La spec es el contrato de esta tarea concreta, nace con el issue y muere con la pull request. Si metes lo de la tarea en el AGENTS.md, envejece fatal y en dos meses nadie se fía de lo que dice.

Para la parte de la tarea tengo publicada la skill que uso yo, sdd-creator: obliga al agente a escribir spec.md, plan.md y tasks.md antes de tocar código, y funciona igual en Claude Code, Codex, Cursor o Gemini.

Aquí vamos con el AGENTS.md, que es el que más rinde por línea escrita. Esta es la primera mitad:

# AGENTS.md

API de facturación interna. Emite y consulta facturas para el equipo de
operaciones. No es público: todo el tráfico entra por el gateway.

## Stack

- **Lenguaje:** TypeScript 7, Node 24 LTS
- **Framework:** Fastify 5
- **Gestor de paquetes:** pnpm — derivado de `pnpm-lock.yaml`. No uses otro.

## Convenciones

- Los handlers no hablan con Prisma. Pasan por un servicio en `src/services/`.
- Todo error de dominio es un `AppError`. No se lanzan strings ni `Error` pelado.
- Los tests van junto al fichero que prueban, como `*.test.ts`.

## Definición de terminado

Una tarea está terminada cuando:

1. El bucle corto pasa en verde.
2. El bucle largo pasa en verde.
3. Cada criterio de aceptación de la spec tiene evidencia: qué comando lo
   demuestra y cuál fue su salida.
4. El diff no contiene nada que la spec no pidiera.

Las convenciones no las inventes: ábrete tres ficheros del repo y escribe lo que ya se hace. Una convención impuesta desde fuera que el código existente incumple es la peor línea que puedes meter ahí, porque el agente la seguirá y su código no se parecerá a nada de lo que hay alrededor.

Y el punto 4 merece párrafo propio, porque es el que casi nadie escribe y el que más caro sale.

Le pides al agente que arregle un bug del IVA. Arregla el bug. Y de paso renombra dos variables, extrae un helper, actualiza un comentario y reordena los imports de tres ficheros. Puede que hasta sean mejoras, pero ninguna de esas líneas está cubierta por ningún contrato: nadie las pidió, nadie definió cuándo estarían bien, y ahora están en tu diff obligándote a leerlas.

Código de más es código sin contrato. Esa línea sola recorta el diff medio de una forma que se nota la primera semana.

2. Carril: por dónde no puede salirse

Piensa en la última vez que un agente te dejó algo raro. Ajustó el assert de un test que fallaba. Añadió una dependencia entera para no escribir tres líneas. Metió un as any. Marcó un test lento como skip. Tocó un fichero de despliegue.

Ninguno de esos es un fallo de razonamiento. En todos entendió perfectamente lo que le pediste.

La mayoría de los desastres que te va a dar un agente no son de lógica. Son de alcance.

No hace trampas: hace lo que le pediste por el camino más corto que encontró. Le pediste que los tests pasaran. No le pediste que el código funcionara. Casi siempre coinciden, por eso vivimos tranquilos. Cuando dejan de coincidir, el camino corto es tocar el test.

Y de aquí sale lo que de verdad importa:

Si el agente puede modificar la cosa que lo comprueba, no tienes verificación. Tienes teatro.

Los tests, el linter, el CI — todo eso son ficheros del repositorio, dentro de su radio de acción. Salvo que digas lo contrario, el que recibe el veredicto tiene permiso de escritura sobre quien lo emite. Ningún juzgado funcionaría así.

## Límites

Sin permiso explícito, el agente no toca:

- `prisma/migrations/` ni el esquema. Una migración se revisa a mano, siempre.
- `.github/workflows/`, `Dockerfile` ni nada de despliegue.
- `package.json`: no se añaden ni se actualizan dependencias. Si hace falta
  una, para y pregunta.
- `.env`, `.env.*` ni ningún fichero con credenciales.
- Los asserts de los tests que ya existen. Añadir tests nuevos, sí. Cambiar
  los que ya estaban, no.
- `src/lib/money.ts`. Es aritmética de céntimos y ya nos ha mordido dos veces.

El “para y pregunta” es una salida y hace falta: un límite sin salida se convierte en un agente bloqueado o, peor, en un agente que se lo salta.

La línea de los asserts es la que protege al verificador. No prohíbe tocar los tests: prohíbe cambiar los que ya estaban. Añadir cobertura nueva puede y debe; aflojar la existente para que su trabajo pase, no.

Y la última línea es la que hace creíbles a todas las demás. money.ts no está ahí por una regla general, sino porque ese fichero ya mordió dos veces. Las cuatro primeras las copias de cualquier plantilla; esa la escribes tú. Tu repo tiene dos o tres. Ya sabes cuáles son.

Ahí está el cambio de postura que ordena todo lo demás: dejas de pedirle al agente que se porte bien y montas un sitio donde portarse mal se detecta solo. Un prompt es una petición y depende de que el modelo esté teniendo un buen día. Un límite es una propiedad del sitio donde trabaja.

Eso sí, sé honesto con lo que es un fichero markdown: una señal, no una valla. Los límites de verdad viven en tres capas — declarado (el AGENTS.md), impedido (permisos y hooks que rechazan escrituras fuera del alcance) y detectado (CI y protección de rama). La primera cuesta diez minutos y quita la inmensa mayoría de las desviaciones. Si alguien te vende que un markdown le pone puertas a un proceso con acceso de escritura a tu disco, desconfía.

3. Veredicto: quién dice que está bien

Un veredicto no es una opinión. Una opinión es lo que da un linter cuando sugiere, o lo que das tú a las once de la noche cuando dices “bueno, tiene buena pinta”.

Un veredicto es un proceso que termina en dos estados y ninguno más. No admite matices y no cambia según lo cansado que estés.

Y no lo emite una cosa. Lo emiten cinco:

Capa	Pregunta que responde
Build	¿Esto compila?
Tipos	¿Las piezas encajan entre sí?
Lint	¿Se parece al resto del código de esta casa?
Tests	¿El comportamiento sigue siendo el que era?
Criterios de aceptación	¿Hace lo que la spec pidió?

Las cuatro primeras ya las tienes: están en tu repo desde antes de que existieran los agentes. La quinta es la que casi nadie tiene, y es la que convierte un montón de comandos sueltos en un harness, porque conecta el contrato con algo que se ejecuta.

Un aviso sobre la palabra “harness”, que se usa para dos cosas distintas: aquí es el conjunto de comandos que verifica el código que tu agente escribe. Si lo que quieres es probar el agente en sí —tools falsas, presupuesto de tokens, trazas reproducibles en CI—, eso es otro montaje y lo explico en el test harness para agentes de IA.

Esa quinta capa es la que tengo automatizada en ai-workflow-kit —v2.5.0 en npm a septiembre de 2026—, que se instala con npx ai-workflow-kit. El plan de la tarea lleva una casilla por paso, y cada casilla lleva detrás el comando que la demuestra: verify la marca solo cuando ese comando sale con código cero. Lo que queda escrito en el fichero es lo que se demostró, no lo que el agente dijo que había hecho.

El harness tiene dos velocidades, y esa decisión que parece técnica es la que decide si el sistema se usa o se abandona. El bucle corto lo ejecuta el agente después de cada cambio y tiene que bajar de sesenta segundos; si tarda más, hace tandas más largas entre comprobaciones y cuando algo falla ya no sabes cuál de los quince cambios lo rompió. El bucle largo se ejecuta una vez, antes de abrir la PR.

Y no, no puedes meterlo todo en el corto por si acaso. Un bucle corto de ocho minutos no es exhaustivo: es un bucle que nadie ejecuta. Los sesenta segundos son el umbral por debajo del cual la gente no busca la forma de esquivarlo.

## Verificación

Estos comandos están ejecutados y comprobados. Son el harness: si uno falla,
el trabajo no está hecho.

### Bucle corto — después de cada cambio

    pnpm typecheck      # 4s
    pnpm lint           # 6s
    pnpm test:unit      # 18s

### Bucle largo — antes de abrir la PR

    pnpm build          # 40s
    pnpm test           # 2m 10s
    pnpm test:e2e       # 3m 30s

### Rojos conocidos

- `pnpm test:e2e` falla 2 de 34 en `emision-factura.e2e.ts` desde el cambio
  del proveedor de firma. Es anterior al agente. Si falla cualquier otro,
  lo rompiste tú.

Si te llevas una sola línea técnica de este post, que sea esta: nunca metas en el harness un comando que no hayas ejecutado.

El agente lee el fichero, ve pnpm test:integration, lo lanza, el comando no existe, el error es raro y decide seguir adelante. Él cree que está verificado. Tú crees que está verificado. Nadie ha comprobado nada. Has empeorado tu punto de partida y encima duermes mejor.

Los tiempos anotados al lado de cada comando tampoco son decoración: son lo que te permite saber dentro de seis meses si el bucle corto sigue siendo corto. Los harness no se rompen de golpe, se degradan un comando cada vez.

Y los rojos conocidos son lo que más me costó aceptar. ¿Qué haces con un comando importante que hoy falla? La tentación es dejarlo fuera hasta arreglarlo. No lo hagas: ponlo y documenta que está en rojo. Un harness honesto con dos rojos vale más que uno verde de mentira. Además, si el agente sabe qué estaba roto antes de empezar, distingue lo que rompió él de lo que ya estaba roto, en vez de ponerse a investigarlo y a veces a “arreglarlo”.

Qué cambia el martes por la mañana

Le pides una feature y el agente rompe el contrato — pongamos que dos tests existentes fallan.

Sin harness, eso te llega como una PR de cuatrocientas líneas y tú descubriéndolo en el minuto cuarenta. O peor, no descubriéndolo.

Con harness, el bucle corto se pone rojo a los veintiocho segundos y el agente sabe exactamente qué rompió, porque el rojo tiene nombre y no está en la lista de rojos conocidos. La mayoría de las veces lo arregla solo. Y cuando no puede, lo que te llega no es un diff: es una frase — no puedo cumplir esta cláusula sin tocar lo que dijiste que no tocara.

Mi tiempo medio de revisión pasó de una hora cincuenta a veinte minutos. A cuatro PRs por semana son seis horas a la semana. No lo redondeo a “cinco veces más rápido” porque los porcentajes bonitos son lo primero que hace desconfiar: es un número mío, medido en mi repo. Tú tendrás el tuyo.

Pero los veinte minutos siguen ahí, y aquí es donde muchos esperan que diga “y ya no revisas nada”. Lo que cambió es en qué se te van:

Miras el veredicto. Qué pasó, qué falló, qué se saltó. Treinta segundos.
Lees el contrato, no la implementación. Cuarenta líneas. Y la pregunta ya no es “¿está bien este código?” sino “¿pedí lo correcto?”, que es muchísimo mejor pregunta y que solo puedes responder tú.
Lees el diff, pero apuntando a las zonas donde el contrato no llega: si el nombre encaja con el dominio, si la solución es la adecuada para este proyecto. Ahí es donde viven los fallos que un code review no puede ver —N+1, fugas de recursos, race conditions—, y por eso ese tercer paso no lo puedes borrar del proceso.

Ese tercer punto es tu trabajo de verdad, y es el que la IA no te va a quitar. Nunca fue leer cuatrocientas líneas buscando un null. Era decidir si lo que se construyó tenía sentido.

Qué hacer hoy

Cuatro cosas, por orden. Ninguna te lleva más de una tarde.

Pasa tu última spec por la prueba de una línea. Cuenta cláusulas e intenciones. Ese número explica tu tiempo de revisión mejor que cualquier otra cosa.
Ejecuta tus comandos de verificación, uno a uno, apuntando lo que tarda cada uno. De ahí salen tu bucle corto, tu bucle largo y tus rojos conocidos.
Escribe el AGENTS.md con esas secciones: stack, convenciones, definición de terminado, límites y verificación. Media página. El punto 4 de la definición de terminado no te lo saltes.
Añade una línea de carril que sea tuya. El fichero que ya te mordió. Esa es la que hace creíbles a las otras cinco.

El AGENTS.md no hace falta que lo escribas mirando a una pantalla en blanco: lo tienes entero, con las cinco secciones y los comentarios de por qué está cada línea, en el ebook gratuito de El método Revisión por Contrato. Treinta páginas, sin coste.

Si prefieres ver el AGENTS.md, el harness y los límites montados sobre un proyecto real en vez de partir de una plantilla, ese es justo el recorrido de Construye con IA: de la idea al producto con Claude Code.

Un apunte que te ahorra una tarde: AGENTS.md es un estándar abierto, no algo que traigan todas las herramientas. En su lista de compatibilidad, consultada el 6 de septiembre de 2026, están Codex, Cursor, el agente de codificación de Copilot, Gemini CLI o Zed. Claude Code es la excepción, y conviene saberlo porque es de las más usadas: lee CLAUDE.md. Se arregla con un fichero de una línea que importe el otro con @AGENTS.md. Compruébalo en tu versión, que esto es de lo poco aquí que puede cambiar en tres meses.

Si quieres el marco completo alrededor de esto —cómo se escribe la spec de la tarea, no solo el contrato del repo— lo desarrollo en el libro de Spec-Driven Development, en papel o en ebook.

Empieza por el punto 2. Es el más aburrido de los cuatro y es el que sostiene los otros tres.

Preguntas frecuentes

¿Cómo se revisa código generado por IA sin leer todo el diff?

Necesitas tres cosas antes de que la pull request llegue a ti: un contrato con cláusulas que una máquina pueda rechazar, límites escritos sobre qué ficheros el agente no toca, y un harness de comandos ejecutables que emita un veredicto binario. Con eso, tu revisión se reduce a tres pasos: mirar el veredicto (treinta segundos), leer el contrato para comprobar que pediste lo correcto (unas cuarenta líneas) y leer el diff solo en las zonas que el contrato no cubre —nombres, encaje con el dominio, si la solución es la adecuada para este proyecto—. En mi repo eso bajó el tiempo medio de revisión de una hora cincuenta a veinte minutos.

¿Esto no es simplemente tener buenos tests?

Los tests son una de las cinco capas, no el mecanismo. Puedes tener una suite excelente y seguir revisando cuatrocientas líneas a mano, porque los tests responden “¿el comportamiento sigue siendo el que era?” y no responden “¿esto hace lo que la spec pidió?” ni “¿el agente se salió de su terreno?”. La pieza que casi nadie tiene es la quinta: criterios de aceptación con un comando detrás. Y si quieres que el test defina el contrato antes de que el agente escriba nada, eso es TDD con IA y encaja encima de esto, no en su lugar.

Mi repo no tiene tests. ¿Esto me sirve de algo?

Sí, y probablemente más. Empieza por lo que ya existe aunque no lo llames harness: el build, el type checker y el linter ya emiten veredictos hoy. Escribe el AGENTS.md con esos tres comandos y los límites, y añade tests después, uno por tarea. La alternativa —esperar a tener cobertura para empezar— es como la gente se queda un año sin hacer nada.

¿No es más fácil poner todo esto en el prompt?

Funciona. Casi siempre. El problema es el casi. El prompt vive en una conversación y muere con ella. El fichero vive en el repositorio: se escribe una vez y se aplica a todas las tareas que vengan detrás, incluidas las que lance otra herramienta o cualquiera que entre al repo después de ti.

¿Esto no ralentiza al agente?

Al contrario, aunque el bucle corto sume segundos. Sin verificación el agente entrega rápido y falso, y el coste aparece luego en tu revisión y en los arreglos. Con verificación, el error llega a los veintiocho segundos, con nombre, y lo arregla él. La velocidad que importa no es la de generar código: es la de llegar a algo que se pueda mergear.

¿Sirve si mi stack no es TypeScript?

La estructura es la misma en Python, Go o Java — stack, convenciones, definición de terminado, límites y verificación. Lo que cambian son los comandos concretos, y esos salen de tu proyecto, no de un ejemplo. Copia la forma y rellénala con lo tuyo.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

September 8, 2026

Arquitectura de subagentes IA: por qué falla el mega-prompt
El año pasado construí un agente que pretendía ser el ingeniero de software definitivo. Fue mi primer intento serio de arquitectura de subagentes IA — y la forma en la que fallé me enseñó por qué un solo agente nunca debería hacerlo todo.

Su System Prompt ocupaba casi 3.000 palabras. Le instruí para ser arquitecto de software, experto en seguridad, programador senior de TypeScript, tester meticuloso y redactor técnico. Además, le configuré 28 herramientas distintas: leer archivos, escribir código, ejecutar comandos bash, consultar 3 bases de datos y hacer peticiones HTTP.

Al principio parecía impresionante. En la primera tarea sencilla respondió bien.

Pero a la cuarta tarea compleja, el sistema colapsó por completo:
- Confundía las reglas de testing con las de documentación.
- Para cambiar una sola línea de CSS llamaba a herramientas de base de datos.
- Consumía 100.000 tokens en cada paso solo leyendo la lista gigante de herramientas disponibles.
Ese día entendí una verdad fundamental del desarrollo con IA: en lugar de construir un único agente que intente hacerlo todo, necesitas un equipo de subagentes con tareas concretas y contextos aislados.

Por qué los Mega-Prompts fallan en la práctica

No es una limitación de que el modelo "sea tonto"; es el resultado de cómo funcionan los Transformers:

1. Degradación por ruido de herramientas (Tool Noise)

Cuantas más herramientas (tools) le expones a un modelo en un único turno, mayor es la probabilidad de que elija la herramienta equivocada o invente parámetros incompatibles.

Con pocas herramientas bien definidas, la precisión de selección se mantiene alta. Cuando la lista crece a decenas de herramientas mezclando responsabilidades distintas (leer archivos, escribir código, consultar bases de datos, hacer peticiones HTTP), esa precisión cae de forma abrupta — es el mismo problema que un desarrollador tendría memorizando 30 comandos de CLI casi idénticos.

2. Dispersión de atención (Attention Drift)

Si tu prompt contiene 50 reglas diferentes ("no uses any", "usa el prefijo on en eventos", "escribe tests en Vitest", "documenta en JSDoc"), el mecanismo de atención del LLM diluye la importancia de cada una.

Cuando el contexto se llena de logs y código, las reglas del medio del prompt simplemente dejan de tener peso estadístico.

3. Contaminación de contexto

Si un agente pasa 20 minutos investigando archivos y leyendo logs de error, esos 80.000 tokens de "ruido exploratorio" se quedan atascados en la memoria para siempre.

Cuando luego le pides que escriba la solución final, su respuesta estará condicionada por todo ese texto basura previo.

La solución: Arquitectura de Subagentes en 3 capas

La solución no es hacer prompts más largos ni añadir más mayúsculas al texto. Es aplicar el principio de Responsabilidad Única que llevamos décadas usando en ingeniería de software.

En Dominicode organizamos el trabajo en tres tipos de subagentes especializados:
```
                  ┌───────────────────────┐
                  │    AGENTE ORQUESTADOR │
                  │  (Planifica y delega) │
                  └──────────┬────────────┘
                             │
            ┌────────────────┼────────────────┐
            ▼                ▼                ▼
     ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
     │ RESEARCHER  │  │ IMPLEMENTER │  │  REVIEWER   │
     │ (Read-only) │  │(Write + TDD)│  │ (Auditoría) │
     └─────────────┘  └─────────────┘  └─────────────┘
```
1. El Investigador (Researcher — Solo Lectura)
- Herramientas permitidas: Búsqueda en archivos, lectura de código, búsqueda web.
- Herramientas prohibidas: Edición de archivos, ejecución de comandos destructivos.
- Misión: Explora el codebase, localiza las funciones relevantes y devuelve un resumen limpio de 50 líneas con los hallazgos. Su memoria sucia de 60.000 tokens se descarta al terminar; solo el resumen pasa al siguiente agente.
2. El Implementador (Implementer — Escritura + TDD)
- Herramientas permitidas: Edición precisa de archivos, ejecución de tests.
- Misión: Recibe el resumen del Researcher y la especificación técnica. Su único objetivo es crear el test, escribir el código mínimo para pasarlo y verificar que compila. No pierde tiempo buscando archivos porque el Researcher ya le dio las rutas exactas.
3. El Revisor (Reviewer — Auditor de Calidad)
- Herramientas permitidas: Lectura de diffs de git, linter.
- Misión: Revisa los cambios antes de hacer commit. Evalúa si se respetan los estándares de tipado, si hay regresiones de rendimiento y si se cumplió la especificación original.
Cómo se comunican los subagentes sin saturar tokens: El patrón Artifact

El error habitual al montar sistemas multiagente es hacer que el Agente A le hable al Agente B en un chat conversacional interminable ("Hola Agente B, ¿cómo estás? He encontrado esto…"). Eso gasta tokens en cortesías inútiles.

El patrón más eficiente es la comunicación mediante artefactos en disco:
1. El Researcher escribe sus hallazgos en un archivo local: scratch/research_findings.md.
2. El Orchestrator lee ese archivo y lanza al Implementer pasándole únicamente la ruta del archivo.
3. El Implementer ejecuta los cambios y escribe el resumen de modificaciones en scratch/changes_summary.md.
Cada subagente arranca con una ventana de contexto limpia, consumiendo solo los tokens necesarios para su tarea concreta.

Este flujo de trabajo desacoplado es el que explicamos a fondo en el curso Construye con IA: de la idea al producto con Claude Code, donde mostramos cómo estructurar entornos reales multiagente que no se degradan con el tiempo.

Ejemplo práctico: Definiendo un subagente en TypeScript

Si estás creando tus propios agentes con código propio, no necesitas frameworks gigantes. Puedes instanciar agentes especializados restringiendo las tools y el system prompt:
```
import { generateText, tool, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";

// Agente especializado solo en investigación.
// Modelo de ejemplo: sustituye por la versión vigente de Claude en tu build.
export async function spawnResearcherAgent(query: string, codebaseDir: string) {
  const result = await generateText({
    model: anthropic("claude-sonnet-5"),
    system: `Eres un agente de investigación técnica de solo lectura.
    Tu objetivo es explorar el código en "${codebaseDir}", localizar las funciones clave
    y responder con un informe conciso. NUNCA propongas escribir código ni modificar archivos.`,
    prompt: `Investiga: ${query}`,
    tools: {
      searchFiles: tool({
        description: "Busca patrones en el repositorio",
        inputSchema: z.object({ pattern: z.string() }),
        execute: async ({ pattern }) => {
          // Lógica de búsqueda grep/ripgrep
          return { matches: ["src/auth/service.ts:45", "src/auth/jwt.ts:12"] };
        },
      }),
      readFile: tool({
        description: "Lee un archivo específico",
        inputSchema: z.object({ path: z.string() }),
        execute: async ({ path }) => Bun.file(path).text(),
      }),
    },
    stopWhen: stepCountIs(8),
  });

  return result.text; // Salida limpia lista para pasar al Implementador
}
```
Al limitar el rol a lectura y 2 herramientas, la tasa de error baja notablemente y el coste por ejecución se reduce al mínimo.

Qué hacer hoy con tu proyecto

Si tienes un archivo de prompt de 5 páginas o un agente que intenta resolver todo el ciclo de vida de tu software:
1. Separa la lectura de la escritura: Crea un agente explorador con herramientas de solo lectura y un agente constructor que solo toque archivos cuando ya sabe exactamente qué cambiar.
2. Usa especificaciones previas: Antes de lanzar a los subagentes, asegúrate de tener una base firme con Spec-Driven Development (SDD) para que ningún agente tenga que improvisar requisitos sobre la marcha.
3. Pasa datos, no conversaciones: Haz que tus subagentes se comuniquen a través de archivos estructurados en lugar de historiales de chat kilométricos.
En Dominicode Labs compartimos arquitecturas reales de subagentes que usamos a diario para automatizar la creación de cursos, la refactorización de código y el mantenimiento de proyectos en producción.

Deja de pedirle milagros a un mega-prompt. Diseña un sistema de subagentes donde cada uno haga una sola cosa, pero la haga con precisión quirúrgica.
August 24, 2026
OpenSpec y Claude Code: integración paso a paso del flujo OPSX
El lunes le pedí a Claude Code que añadiera paginación a un listado. Lo hizo bien.

El miércoles abrí una sesión nueva en el mismo proyecto y le pedí un filtro. Se inventó otra forma de paginar, distinta a la del lunes, y reescribió la que ya funcionaba.

No fue culpa del modelo. El contexto de Claude Code vive en la sesión: cierras la terminal y se evapora.

OpenSpec con Claude Code resuelve eso: lo acordado vive en archivos versionados dentro del repo y el agente los lee antes de tocar código.

Tutorial de integración OpenSpec Claude Code, paso a paso: instalación, inicialización y el flujo OPSX de principio a fin.

Aviso rápido: OpenSpec no es OpenAPI

Comparten cuatro letras y nada más.

OpenSpec es un framework open source de spec-driven development para asistentes de código, de Fission-AI. No describe endpoints REST. Si has llegado buscando Swagger, este no es tu post.

Lo que hace es meter una capa de especificación entre tú y el agente: propuesta, diseño, tareas y spec del cambio. Todo en Markdown, todo dentro del repo, todo bajo control de versiones.

Paso 1: instalar (y el error de scope que arrastran los tutoriales viejos)
```
npm install -g @fission-ai/openspec@latest
```
Fíjate bien en el scope, porque esto:
```
# ❌ NO es OpenSpec
npm install -g openspec
```
instala otro paquete distinto, sin relación con el framework. Es el fallo más repetido en tutoriales de hace unos meses, y luego pasas media hora preguntándote por qué openspec init no hace lo que dice la documentación.

Instala siempre el paquete con scope @fission-ai/.

Paso 2: inicializar OpenSpec en Claude Code

Desde la raíz del repo:
```
cd tu-proyecto
openspec init
```
El init te pregunta qué herramienta usas. Selecciona Claude Code.

Y aquí el detalle que casi nadie explica bien: para Claude Code te crea las dos cosas.
```
.claude/skills/openspec-*/SKILL.md    ← una skill por cada acción del flujo
.claude/commands/opsx/<id>.md         ← los slash commands
openspec/config.yaml                  ← la configuración del proyecto
```
Las skills las carga Claude Code solo, sin que tú hagas nada. Los comandos son la puerta de entrada manual cuando quieres disparar una fase concreta. No eliges entre unas y otros: conviven.

El config.yaml guarda además tus preferencias entre ejecuciones de init y update. Si mañana actualizas OpenSpec, no te vuelve a preguntar todo.

Paso 3: llena el config.yaml antes de pedir nada

Este paso parece opcional. No lo es.

openspec/config.yaml no es un README que el agente abre si le apetece. Su contenido se inyecta en cada petición de planificación. Va dentro del prompt, siempre.

Dedica cinco minutos a describir de verdad tres cosas: el stack real con sus versiones, las convenciones que sigues (naming, estructura de carpetas, patrón de tests) y lo que está prohibido en el proyecto — esa librería que ya migraste, ese patrón que odias.

La diferencia se nota en la primera propuesta. Con el config vacío recibes una propuesta genérica de manual. Con el config bien puesto recibes una que usa tus carpetas, tus nombres y tu forma de testear.

Un apunte honesto: no inventes claves en el YAML. Completa las que el propio init deja generadas y, si necesitas un campo que no existe, mira la doc oficial.

Es la misma lógica que trabajamos en el curso Construye con IA: el resultado de un agente depende mucho menos del prompt del momento que del contexto estable que le dejaste montado antes.

Paso 4: el flujo OPSX de principio a fin

En Claude Code los comandos van con dos puntos: /opsx:<id>. Este detalle importa y ahora verás por qué.

/opsx:explore — pensar sin comprometerte
```
/opsx:explore
```
Fase de planificación pura. Exploras el problema, discutes enfoques, descartas caminos. No genera artefactos ni te ata a nada.

Es el comando que más se omite en los tutoriales y el que más rentabilidad da. Cuando saltas directo a propose, el agente propone algo — y lo propone bien argumentado, con lo cual te lo crees. En explore es donde descubres que el problema real era otro, antes de tener cuatro archivos que revisar.

/opsx:propose — generar la propuesta
```
/opsx:propose añadir filtros por categoría al listado de productos
```
Aquí se materializa el trabajo:
```
openspec/changes/<nombre-del-cambio>/
├── proposal.md    ← qué se va a hacer y por qué
├── design.md      ← cómo, a nivel técnico
├── tasks.md       ← el desglose ejecutable
└── specs/         ← la delta spec del cambio
```
Y ahora tu parte: leerlo. Este es el punto exacto donde el flujo funciona o no funciona. Corriges asunciones, ajustas el diseño, partes tareas demasiado grandes. Cuesta minutos ahora y ahorra horas después.

/opsx:apply — implementar contra la spec
```
/opsx:apply
```
El agente implementa tarea por tarea, referenciando la spec acordada. La diferencia con pedirle código a pelo es que ya no hay margen de interpretación.

/opsx:update y /opsx:sync — mantener la spec viva

Antes de archivar, el perfil por defecto trae dos comandos más que casi nadie menciona: /opsx:update revisa los artefactos de un cambio si algo se movió a mitad de camino, y /opsx:sync fusiona la delta spec del cambio dentro de las specs generales del proyecto, para que la spec principal quede al día sin tocarla a mano.

/opsx:archive — cerrar el cambio
```
/opsx:archive
```
Mueve el cambio a openspec/changes/archive/ y actualiza la fuente de verdad del proyecto. A partir de ahí eso ya no es un cambio pendiente: es cómo funciona tu sistema.

El perfil extendido (y dónde vive /opsx:verify)

El perfil por defecto (core) trae los seis comandos que acabas de ver: explore, propose, apply, update, sync y archive. Si necesitas control más granular, cambias de perfil:
```
openspec config profile
openspec update
```
Eso desbloquea /opsx:new, /opsx:continue, /opsx:ff, /opsx:bulk-archive, /opsx:onboard y, el que más se echa en falta, /opsx:verify: contrasta la implementación contra la spec acordada. No es un test runner, es la comprobación de que no se coló nada que nadie pidió y que no falta nada que sí se pidió.

Empieza sin el perfil extendido. Actívalo cuando el ciclo base (explore → propose → apply → archive) te sepa corto.

Delta specs: por qué esto sirve en un proyecto que ya existe

Aquí está la decisión de diseño que hace a OpenSpec usable en el mundo real.

La spec de un cambio no describe tu sistema entero. Describe solo lo que se mueve:
```
## ADDED Requirements

### Requirement: Filtrado por categoría
El listado DEBE permitir filtrar productos por categoría.

#### Scenario: Usuario selecciona una categoría
- WHEN el usuario selecciona la categoría "Audio"
- THEN el listado muestra solo productos de esa categoría

## MODIFIED Requirements

## REMOVED Requirements
```
Escenarios en Markdown plano con sintaxis WHEN/THEN. Sin Gherkin, sin herramientas extra, sin plugins.

Piensa en la alternativa: especificar entera una aplicación con tres años de historia para poder añadir un filtro. No lo hace nadie, y por eso la mayoría de intentos de SDD en brownfield mueren en la segunda semana. Con deltas, la unidad de trabajo es el cambio, no el sistema.

Si quieres el marco completo detrás de esto — cómo se escribe una spec que un agente pueda ejecutar sin rellenar huecos por su cuenta — lo desarrollo en el libro de Spec-Driven Development. Y para el reverso de la moneda, ya escribí sobre por qué una spec falla con un agente de IA.

La sintaxis cambia según la herramienta

Dato práctico que ahorra confusión cuando copias comandos de un tutorial grabado con otro editor:

Herramienta Sintaxis

Claude Code /opsx:propose

Cursor /opsx-propose

GitHub Copilot /opsx-propose

Amazon Q @opsx-propose

Codex $openspec-propose

Mismo flujo, distinto prefijo. Si el comando no autocompleta en tu editor, casi siempre es esto.

Si vienes de un tutorial de hace unos meses

El flujo pre-OPSX está muerto. Pasó de fases cerradas a acciones, y la traducción es esta:

Antes Ahora

/openspec:proposal /opsx:propose

openspec/project.md openspec/config.yaml

changes/active/ openspec/changes/

Si tienes un proyecto con la estructura antigua, no lo migres a mano. Vuelve a ejecutar openspec init y deja que la herramienta reconstruya lo suyo.

Qué hacer hoy con esto

Abre un proyecto que ya tengas — uno real, con código feo dentro — y no empieces por una feature grande.

Instala, ejecuta openspec init, dedica cinco minutos de verdad al config.yaml y lanza un /opsx:explore sobre el próximo cambio pequeño que tenías pendiente. Sigue hasta /opsx:archive. Media hora, un ciclo completo.

Lo que vas a notar no es velocidad. Es que la siguiente sesión de Claude Code arranca sabiendo lo que se decidió en la anterior. Eso es lo que compras aquí.

Dos avisos para terminar. Esto no sustituye a revisar el código: sustituye a discutir el mismo diseño tres veces. Y no todo cambio merece el ciclo completo — un fix de dos líneas no necesita una propuesta, y sobre eso escribí en cuándo NO usar spec-driven development.

Si quieres ver este flujo aplicado a proyectos completos, con los casos donde se rompe y cómo se arregla, lo trabajamos dentro de Dominicode Labs.

Preguntas frecuentes

¿OpenSpec es lo mismo que OpenAPI?

No. OpenSpec es un framework open source de spec-driven development para asistentes de código, creado por Fission-AI. OpenAPI es una especificación para describir APIs REST. Comparten cuatro letras y nada más.

¿Por qué mi instalación de OpenSpec no funciona?

Lo más probable es que hayas instalado el paquete equivocado. El comando correcto es npm install -g @fission-ai/openspec@latest, con el scope @fission-ai. El paquete llamado openspec a secas es otro proyecto distinto, y es el error que arrastran muchos tutoriales antiguos.

¿OpenSpec sirve en un proyecto que ya existe o solo en proyectos nuevos?

Sirve en proyectos existentes, y esa es su mejor característica. La spec de cada cambio es una delta: solo describe lo que se añade, se modifica o se elimina, con las secciones ADDED, MODIFIED y REMOVED Requirements. No necesitas especificar tu sistema entero para empezar.

¿Se puede usar OpenSpec con Cursor o Copilot en vez de Claude Code?

Sí. El flujo es el mismo y lo que cambia es el prefijo de los comandos. Claude Code usa /opsx:propose con dos puntos, Cursor y Copilot usan /opsx-propose con guion, Amazon Q usa @opsx-propose y Codex usa $openspec-propose. Lo seleccionas al ejecutar openspec init.

¿Puedo saltarme el comando explore e ir directo a propose?

Puedes, pero es donde más gente pierde tiempo. El comando explore es la fase de planificación sin compromiso y sirve para descartar enfoques antes de generar propuesta, diseño, tareas y spec. Si vas directo a propose, acabas revisando cuatro artefactos de una solución que quizá resuelve el problema equivocado.

¿Qué hago si seguí un tutorial con el flujo antiguo de OpenSpec?

Ese flujo ya no es válido. El comando /openspec:proposal pasó a /opsx:propose, el archivo openspec/project.md pasó a openspec/config.yaml y la carpeta changes/active/ pasó a openspec/changes/. Lo más limpio es volver a ejecutar openspec init en el proyecto en lugar de renombrar archivos a mano.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
August 21, 2026

Integrar OpenSpec con Claude Code: el flujo OPSX paso a paso

El lunes le pedí a Claude Code que añadiera paginación a un listado. Lo hizo bien.

El miércoles abrí una sesión nueva en el mismo proyecto y le pedí un filtro. Se inventó otra forma de paginar, distinta a la del lunes, y reescribió la que ya funcionaba.

No fue culpa del modelo. El contexto de Claude Code vive en la sesión: cierras la terminal y se evapora.

OpenSpec con Claude Code resuelve eso. OpenSpec es un framework open source de spec-driven development creado por Fission-AI que guarda lo acordado — propuesta, diseño, tareas y spec — en archivos Markdown versionados dentro del repo, para que Claude Code los lea antes de tocar código. En esta guía lo instalamos, lo inicializamos con openspec init y recorremos el flujo OPSX completo sobre un proyecto que ya existe.

OpenSpec no es OpenAPI: la diferencia en una tabla

Comparten cuatro letras y nada más.

	OpenSpec	OpenAPI
Qué es	Framework de spec-driven development para asistentes de código	Especificación para describir APIs REST
Quién lo mantiene	Fission-AI	OpenAPI Initiative (Linux Foundation)
Formato	Markdown dentro del repo	YAML o JSON
Para qué sirve	Que un agente implemente lo acordado	Que un cliente sepa llamar a tu API

Si has llegado buscando Swagger, este no es tu post.

Cómo instalar OpenSpec para Claude Code (y el error de scope de npm)

OpenSpec se instala como CLI global. Requiere Node.js 20.19.0 o superior, y la versión actual es la 1.8.0.

npm install -g @fission-ai/openspec@latest

Fíjate bien en el scope, porque esto:

# ❌ NO es OpenSpec
npm install -g openspec

instala otro paquete distinto: openspec a secas es la versión 0.0.0 publicada el 9 de abril de 2019, sin relación alguna con el framework y sin una sola actualización desde entonces. Es el fallo más repetido en tutoriales, y luego pasas media hora preguntándote por qué openspec init no hace lo que dice la documentación.

Instala siempre el paquete con scope @fission-ai/.

Qué crea `openspec init` en un proyecto con Claude Code

Desde la raíz del repo:

cd tu-proyecto
openspec init

El init te pregunta qué herramienta usas. Selecciona Claude Code.

Y aquí el detalle que casi nadie explica bien: para Claude Code te crea las dos cosas.

.claude/skills/openspec-*/SKILL.md    ← una skill por cada acción del flujo
.claude/commands/opsx/<id>.md         ← los slash commands
openspec/config.yaml                  ← la configuración del proyecto

Las skills las carga Claude Code solo, sin que tú hagas nada. Los comandos son la puerta de entrada manual cuando quieres disparar una fase concreta. No eliges entre unas y otros: conviven.

El config.yaml guarda además tus preferencias entre ejecuciones de init y update. Si mañana actualizas OpenSpec, no te vuelve a preguntar todo.

Qué poner en `openspec/config.yaml` (y por qué no es opcional)

openspec/config.yaml es el archivo donde defines el schema por defecto, el contexto del proyecto y las reglas por artefacto. No es documentación que el agente abre si le apetece: es entrada del modelo. La doc oficial lo dice sin rodeos — "When generating any artifact, your context and rules are injected into the AI prompt".

Sus claves de nivel superior son cuatro:

Clave	Para qué
`schema`	El schema por defecto de los artefactos
`context`	La información de tu proyecto. Aparece en todos los artefactos
`rules`	Restricciones por artefacto. Solo aparecen en el artefacto que coincide
`operations`	Guía opcional para `apply` y `archive`

Ese matiz de context y rules importa: el contexto viaja siempre, las reglas solo cuando toca. Así que lo que quieras que el agente tenga presente en cada decisión va en context.

Dedica cinco minutos a describir de verdad tres cosas ahí: el stack real con sus versiones, las convenciones que sigues (naming, estructura de carpetas, patrón de tests) y lo que está prohibido en el proyecto — esa librería que ya migraste, ese patrón que odias.

La diferencia se nota en la primera propuesta. Con el config vacío recibes una propuesta genérica de manual. Con el config bien puesto recibes una que usa tus carpetas, tus nombres y tu forma de testear. El detalle de cada clave está en la doc de customization.

Es la misma lógica que trabajamos en el curso Construye con IA: el resultado de un agente depende mucho menos del prompt del momento que del contexto estable que le dejaste montado antes.

El flujo OPSX paso a paso en Claude Code

En Claude Code los comandos van con dos puntos: /opsx:<id>. Este detalle importa y ahora verás por qué.

`/opsx:explore` — pensar sin comprometerte

/opsx:explore

Fase de planificación pura. Exploras el problema, discutes enfoques, descartas caminos. No genera artefactos ni te ata a nada.

Es el comando que más se omite en los tutoriales y el que más rentabilidad da. Cuando saltas directo a propose, el agente propone algo — y lo propone bien argumentado, con lo cual te lo crees. En explore es donde descubres que el problema real era otro, antes de tener cuatro archivos que revisar.

`/opsx:propose` — generar la propuesta

/opsx:propose añadir filtros por categoría al listado de productos

Aquí se materializa el trabajo:

openspec/changes/<nombre-del-cambio>/
├── proposal.md    ← qué se va a hacer y por qué
├── design.md      ← cómo, a nivel técnico
├── tasks.md       ← el desglose ejecutable
└── specs/         ← la delta spec del cambio

Y ahora tu parte: leerlo. Este es el punto exacto donde el flujo funciona o no funciona. Corriges asunciones, ajustas el diseño, partes tareas demasiado grandes. Cuesta minutos ahora y ahorra horas después.

`/opsx:apply` — implementar contra la spec

/opsx:apply

El agente implementa tarea por tarea, referenciando la spec acordada. La diferencia con pedirle código a pelo es que ya no hay margen de interpretación.

`/opsx:archive` — cerrar el cambio

/opsx:archive

Mueve el cambio a openspec/changes/archive/ y consolida lo implementado en openspec/specs/, que es la fuente de verdad del proyecto — "Specs are the source of truth — they describe how your system currently behaves". A partir de ahí eso ya no es un cambio pendiente: es cómo funciona tu sistema.

Los otros dos del perfil por defecto

/opsx:update revisa los artefactos de planificación de un cambio y los mantiene coherentes entre sí, en cualquier dirección: si editas el diseño, la propuesta se ajusta.

/opsx:sync fusiona las delta specs en openspec/specs/ sin archivar el cambio. Útil cuando quieres consolidar antes de cerrar.

Los extendidos, y por qué `/opsx:verify` no te va a funcionar todavía

Aquí está el detalle que hace perder media hora a mucha gente: el perfil por defecto no trae verify.

El perfil core son los seis de arriba — propose, explore, apply, update, sync, archive. Los extendidos son otros seis: /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive y /opsx:onboard. Si escribes /opsx:verify recién instalado, no autocompleta y no pasa nada.

Para activarlos:

openspec config profile   # selecciona el perfil ampliado
openspec update           # aplica los cambios en el proyecto

Con el perfil ampliado activo, /opsx:verify contrasta la implementación contra la spec. No es un test runner: es la comprobación de que no se ha colado nada que nadie pidió y de que no falta nada que sí se pidió.

Empieza por los seis del perfil core. Los extendidos los necesitarás cuando tengas el ciclo rodado y lleves varios cambios a la vez.

Delta specs: por qué esto sirve en un proyecto que ya existe

Una delta spec es una spec que describe solo lo que cambia — lo añadido, lo modificado y lo eliminado — en vez de redescribir el sistema entero. Es lo que hace viable OpenSpec en un proyecto que ya existe.

Así se ve una:

## ADDED Requirements

### Requirement: Filtrado por categoría
El listado DEBE permitir filtrar productos por categoría.

#### Scenario: Usuario selecciona una categoría
- GIVEN el listado de productos cargado
- WHEN el usuario selecciona la categoría "Audio"
- THEN el listado muestra solo productos de esa categoría

## MODIFIED Requirements

### Requirement: Paginación del listado
El listado DEBE conservar el filtro activo al cambiar de página.

Dos cosas que conviene saber antes de copiar esto. Las etiquetas son literales y no se traducen: ADDED, MODIFIED, REMOVED, Requirement:, Scenario: y GIVEN/WHEN/THEN van en inglés aunque el cuerpo esté en español. Y solo incluyes las secciones que uses — si el cambio no elimina nada, no dejes un ## REMOVED Requirements vacío.

Sobre los escenarios: es vocabulario Gherkin, pero en Markdown plano. Sin ficheros .feature, sin Cucumber, sin plugins.

Piensa en la alternativa: especificar entera una aplicación con tres años de historia para poder añadir un filtro. No lo hace nadie, y por eso la mayoría de intentos de SDD en brownfield mueren en la segunda semana. Con deltas, la unidad de trabajo es el cambio, no el sistema.

Si quieres el marco completo detrás de esto — cómo se escribe una spec que un agente pueda ejecutar sin rellenar huecos por su cuenta — lo desarrollo en el libro de Spec-Driven Development.

Y para el reverso de la moneda, ya escribí sobre por qué una spec falla con un agente de IA.

La sintaxis cambia según la herramienta

Dato práctico que ahorra confusión cuando copias comandos de un tutorial grabado con otro editor:

Herramienta	Sintaxis
Claude Code	`/opsx:propose`
Cursor	`/opsx-propose`
GitHub Copilot	`/opsx-propose`
Amazon Q	`@opsx-propose`
Codex	`$openspec-propose`

Mismo flujo, distinto prefijo. Si el comando no autocompleta en tu editor, casi siempre es esto. La lista completa está en la tabla de herramientas soportadas, que cubre más de treinta.

Cómo migrar del flujo antiguo de OpenSpec al flujo OPSX

El flujo pre-OPSX está muerto. Pasó de fases cerradas a acciones, y la traducción es esta:

Antes	Ahora
`/openspec:proposal`	`/opsx:propose`
`openspec/project.md`	`openspec/config.yaml`
`changes/active/`	`openspec/changes/`

Si tienes un proyecto con la estructura antigua, no lo migres a mano: ejecuta openspec update, que regenera los ficheros de skills y comandos para las herramientas que tengas configuradas.

Qué hacer hoy con esto

Abre un proyecto que ya tengas — uno real, con código feo dentro — y no empieces por una feature grande.

Instala, ejecuta openspec init, dedica cinco minutos de verdad al config.yaml y lanza un /opsx:explore sobre el próximo cambio pequeño que tenías pendiente. Sigue hasta /opsx:archive. Media hora, un ciclo completo.

Dos avisos antes de que te lances. Esto no sustituye a revisar el código: sustituye a discutir el mismo diseño tres veces. Y no todo cambio merece el ciclo completo — un fix de dos líneas no necesita una propuesta, y sobre eso escribí en cuándo NO usar spec-driven development.

Si quieres ver este flujo aplicado a proyectos completos, con los casos donde se rompe y cómo se arregla, lo trabajamos dentro de Dominicode Labs.

Lo que vas a notar no es velocidad. Es que la siguiente sesión de Claude Code arranca sabiendo lo que se decidió en la anterior. Eso es lo que compras aquí.

Preguntas frecuentes

¿OpenSpec es lo mismo que OpenAPI?

No. OpenSpec es un framework open source de spec-driven development para asistentes de código, creado por Fission-AI. OpenAPI es una especificación para describir APIs REST. Comparten cuatro letras y nada más.

¿Por qué mi instalación de OpenSpec no funciona?

Lo más probable es que hayas instalado el paquete equivocado. El comando correcto es npm install -g @fission-ai/openspec@latest, con el scope @fission-ai. El paquete llamado openspec a secas es otro proyecto distinto, y es el error que arrastran muchos tutoriales antiguos.

¿OpenSpec sirve en un proyecto que ya existe o solo en proyectos nuevos?

Sirve en proyectos existentes, y esa es su mejor característica. La spec de cada cambio es una delta: solo describe lo que se añade, se modifica o se elimina, con las secciones ADDED, MODIFIED y REMOVED Requirements. No necesitas especificar tu sistema entero para empezar.

¿Se puede usar OpenSpec con Cursor o Copilot en vez de Claude Code?

Sí. El flujo es el mismo y lo que cambia es el prefijo de los comandos. Claude Code usa /opsx:propose con dos puntos, Cursor y Copilot usan /opsx-propose con guion, Amazon Q usa @opsx-propose y Codex usa $openspec-propose. Lo seleccionas al ejecutar openspec init.

¿Puedo saltarme el comando explore e ir directo a propose?

Puedes, pero es donde más gente pierde tiempo. El comando explore es la fase de planificación sin compromiso y sirve para descartar enfoques antes de generar propuesta, diseño, tareas y spec. Si vas directo a propose, acabas revisando cuatro artefactos de una solución que quizá resuelve el problema equivocado.

¿Por qué no me funciona el comando /opsx:verify?

Porque no viene en el perfil por defecto. OpenSpec usa el perfil core, que trae seis comandos: propose, explore, apply, update, sync y archive. El comando verify pertenece al perfil ampliado, junto a new, continue, ff, bulk-archive y onboard. Para activarlo ejecuta openspec config profile y después openspec update.

¿Qué comandos trae OpenSpec por defecto?

El perfil core incluye seis: propose para generar la propuesta, explore para planificar sin compromiso, apply para implementar, update para mantener coherentes los artefactos de planificación, sync para fusionar las delta specs en openspec/specs/ y archive para cerrar el cambio.

¿Qué hago si seguí un tutorial con el flujo antiguo de OpenSpec?

Ese flujo ya no es válido. El comando /openspec:proposal pasó a /opsx:propose, el archivo openspec/project.md pasó a openspec/config.yaml y la carpeta changes/active/ pasó a openspec/changes/. Lo más limpio es ejecutar openspec update en el proyecto, que regenera skills y comandos, en lugar de renombrar archivos a mano.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

August 17, 2026

Por qué Spec-Driven Development (SDD) triplica tu velocidad cuando programas con agentes de IA
Hace unas semanas estaba viendo trabajar a un desarrollador senior con bastante experiencia. Usaba una de las mejores herramientas de IA del mercado.

Su flujo era este: escribía un prompt en el chat ("Agrégame la autenticación con OAuth y guarda el token en cookies HTTP-only"), la IA generaba 150 líneas de código, el código fallaba, le volvía a pedir que corrigiera el error, la IA cambiaba tres archivos sin avisar, se rompía el tipo de una interfaz… y de repente llevaba dos horas haciendo el famoso "prompt ping-pong".

Tenía la sensación de ir rapidísimo porque la IA escribía texto a toda velocidad. Pero al final de la jornada, la mitad de su tiempo lo había pasado arreglando las suposiciones que la IA había tenido que inventar porque nadie se las definía.

El problema no era la IA. El problema es que estaba intentando construir una casa pidiéndole al albañil que pusiera ladrillos sin enseñarle los planos. Aquí es donde Spec-Driven Development (SDD) transforma la forma en que los desarrolladores senior trabajan con los agentes de IA.

El espejismo del "Vibe Coding" sin rumbo

Nos han vendido que programar con IA consiste en hablarle en lenguaje natural como si fuera un colega y dejar que el LLM deduzca todo lo demás.

Para un script de 20 líneas o un prototipo que vas a tirar mañana, funciona. Para software en producción con arquitecturas reales, es una trampa.

Cuando no defines las reglas del juego antes de pedir código, obligas al agente de IA a tomar decenas de decisiones implícitas:
- ¿Qué nombres le da a las variables y modelos?
- ¿Cómo maneja los casos de borde y errores?
- ¿Qué contrato sigue la API?
- ¿Qué dependencias o utilidades existentes en el proyecto debe reutilizar?
Si el agente adivina mal una sola de esas cosas, el código generado es basura técnica que tendrás que mantener tú. Como explicamos en nuestro artículo sobre por qué tu spec falla con un agente de IA, la falta de claridad en las restricciones es la causa número uno de código roto.

¿Qué es Spec-Driven Development (SDD)?

Spec-Driven Development no es burocracia ni escribir documentación de 50 páginas que nadie lee.

SDD consiste en invertir el flujo de trabajo: en lugar de usar la IA para que redacte código directamente desde tu cabeza, utilizas la IA para definir una especificación estructurada y verificable ANTES de escribir la primera línea de código.

En nuestro workflow de producción, una especificación SDD se divide en tres piezas muy concretas:

1. spec.md (La Especificación Funcional y Técnica)

Define el QUÉ y el POR QUÉ.
- Contexto del problema y objetivo.
- Requisitos funcionales explícitos.
- Contratos de datos, tipos e interfaces.
- Reglas de negocio y lo que NO debe hacer el sistema.
2. plan.md (La Arquitectura e Impacto)

Define el CÓMO.
- Qué archivos se modifican, cuáles se crean y cuáles se eliminan.
- Estrategia de testing y verificación.
- Modificaciones en dependencias o firmas de API.
3. tasks.md (El Plan de Ejecución)

Define el ORDEN.
- Lista de tareas atómicas e independientes que el agente de IA puede ejecutar paso a paso sin perder contexto ni alucinar.
Eso sí, ten en cuenta que no siempre necesitas cargar con toda la estructura: en nuestra guía sobre cuándo NO usar Spec-Driven Development detallamos los escenarios donde un enfoque más directo resulta más eficiente.

El cambio mental: De programador a Director de Arquitectura

Mira lo que ocurre cuando le das a un agente (como Claude Code, AGY o Cursor) una especificación bien acotada:
```
# Spec: Interceptor de Telemetría HTTP
## Requisitos
- Interceptar todas las peticiones salientes HttpClient.
- Añadir el header X-Correlation-ID usando un UUID v4 si no existe previamente.
- Si la petición responde con status 401, reintentar una sola vez tras renovar el token vía AuthService.refreshToken().
- NO interceptar peticiones hacia /api/v1/auth/login.

## Contrato
- Firma de error devuelta: ApiErrorResponse { code: string; message: string; timestamp: number }.
```
Cuando un agente lee este archivo antes de tocar el código:
1. El contexto entra limpio: El LLM no necesita adivinar el nombre del header ni la estrategia de reintento.
2. Las respuestas son deterministas: El código generado encaja al primer intento con la arquitectura de tu aplicación.
3. El tiempo de revisión tiende a cero: En lugar de leer 300 líneas de diff intentando adivinar qué pretendía hacer la IA, solo verificas que el código cumple los puntos de la spec.
Cómo empezar con SDD hoy mismo

No necesitas instalar un framework complejo ni cambiar la estructura de tu empresa.

La próxima vez que vayas a pedirle una funcionalidad a tu agente de IA, haz esto:
1. Escribe un archivo .md rápido en tu proyecto describiendo qué quieres lograr, qué archivos se verán afectados y cuáles son los tipos/interfaces involucrados.
2. Pásale la spec al agente y pídele: "Revisa esta especificación. Identifica ambigüedades o contradicciones antes de proponer cambios".
3. Una vez alineados en la especificación, pídele que genere la solución siguiendo las tareas definidas.
Te aseguro una cosa: escribir esa spec te llevará 4 minutos. Te ahorrará 45 minutos de depuración descontrolada.

Programar rápido con IA no consiste en teclear prompts más deprisa. Consiste en pensar con claridad antes de pedir el código.

Si quieres llevar tus habilidades al siguiente nivel, explora los Cursos de Dominicode donde profundizamos en arquitecturas modernas y herramientas de desarrollo. Además, en Dominicode Labs acompañamos a developers a construir productos reales y workflows autónomos asistidos por IA.

Preguntas frecuentes

¿SDD reemplaza a TDD (Test-Driven Development)?

No, se complementan. SDD define el contrato y las expectativas de alto nivel antes de construir, mientras que TDD asegura la corrección del código a nivel unitario durante la implementación.

¿Cuánto tiempo lleva escribir una especificación SDD?

Para una tarea típica de feature, redactar una spec básica toma entre 3 y 8 minutos. Ese pequeño esfuerzo inicial ahorra habitualmente horas de refactorización y depuración.

¿Qué herramientas son ideales para trabajar con Spec-Driven Development?

SDD es agnóstico a la herramienta, pero brilla especialmente con agentes CLI como Claude Code y AGY, o entornos con contexto profundo como Cursor y Windsurf.

¿Es necesario usar SDD para correcciones de bugs pequeñas?

Para bugs triviales o cambios de una sola línea no es necesario crear una spec completa. SDD es más valioso en tareas que involucran múltiples archivos, lógica de negocio o contratos de interfaz.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
August 12, 2026

Marcas de agua en Claude Code: ¿pueden detectar tu código?

Un compañero me mandó el titular por Telegram a las siete de la mañana. Debajo, una sola línea: "¿Entonces pueden saber que este commit lo escribí con Claude Code?".

Es la pregunta correcta. Y la respuesta corta es incómoda: hoy nadie te lo puede demostrar, porque el detector público de las marcas de agua de Claude todavía no existe.

La respuesta larga es más interesante. Va de por qué estas marcas funcionan razonablemente bien sobre prosa y se deshacen casi solas dentro de un repositorio de código.

La familia de marcas de agua más documentada en la literatura no es un carácter oculto ni un metadato: es un sesgo estadístico introducido durante la generación, en la elección misma de las palabras, que deja una firma detectable sin alterar el significado. Anthropic no ha confirmado que la suya funcione así. Solo dice que va "tejida dentro del propio texto".

He leído la documentación entera. Esto es lo que dice, y lo que no.

Documentación de Anthropic actualizada el 11 de agosto de 2026. Última revisión de este post: 12 de agosto de 2026.

Qué ha anunciado Anthropic exactamente

Cuatro hechos, sin adornos.

Anthropic ha firmado el Código de Buenas Prácticas del Artículo 50(2) del Reglamento Europeo de IA sobre transparencia del contenido generado por IA. Esto no es marketing: es cumplimiento normativo.
Los modelos Claude lanzados a partir del 2 de agosto de 2026 salen con marcado machine-readable desde el primer día. Para los modelos anteriores hay un periodo transitorio y Anthropic dice que está trabajando en incorporarlo.
El alcance cubre Claude Platform (la API), Claude, Claude Code, Claude Cowork y Claude Tag, además de Claude servido desde AWS, Google Cloud y Microsoft Foundry. Se aplica en todo el mundo, no solo en la Unión Europea. Con una salvedad que conviene retener para más adelante: la marca en el texto sí viaja por esas tres nubes, pero los metadatos de procedencia firmados "puede que no estén soportados en todas las plataformas, según las funcionalidades que ofrezca cada una".
La documentación no contempla ningún opt-out: el marcado se aplica a la salida de los modelos soportados, también cuando consumes la API.

Que Claude Code aparezca escrito con todas las letras en esa lista es lo que hace que este post exista.

Sobre el mecanismo, la documentación de Anthropic dice esto y nada más:

"Teje una marca de agua imperceptible directamente en el propio texto. No la verás, y no cambia el significado, la calidad ni la legibilidad de la respuesta de Claude."
("…it weaves an imperceptible watermark directly into the text itself. You won't see it, and it doesn't change the meaning, quality, or readability of Claude's response.")

Punto. No publican el algoritmo.

Cómo se mete una marca de agua dentro de un texto

La técnica estándar sesga la elección de tokens: en cada paso el modelo parte el vocabulario en una lista verde y una roja usando un hash secreto, y empuja suavemente la generación hacia la verde. El texto sigue siendo natural, pero contiene más tokens verdes de los que el azar explicaría.

Aclaración previa: Anthropic no ha publicado su algoritmo. Lo que viene ahora es cómo funciona la familia de técnicas conocida en la literatura académica —sobre todo el trabajo de Kirchenbauer et al., "A Watermark for Large Language Models" (2023)—, no una descripción de lo que hace Claude por dentro.

Lo explico porque es didáctico y porque es la familia plausible. No porque sea un dato confirmado.

Un modelo de lenguaje no escribe palabras: escribe tokens. En cada paso genera un vector de logits, una puntuación para cada token del vocabulario, y de ahí sale la distribución de la que se muestrea el siguiente. Si nunca has visto por dentro cómo se trocea el texto, en Tokens en español: por qué cuestan un 26 % más que en inglés lo explico con ejemplos reales.

La técnica clásica hace esto:

Toma los últimos tokens generados y calcula un hash con una clave secreta.
Usa ese hash como semilla para partir el vocabulario en dos: una lista verde y una lista roja.
Suma un pequeño sesgo a los logits de la lista verde antes de muestrear.
Repite en cada token.

El texto resultante es perfectamente natural. Pero contiene muchos más tokens "verdes" de los que el azar justificaría. Quien tenga la clave recalcula las listas y saca un valor estadístico de confianza.

La gracia del método es que el detector no necesita el modelo. Solo la clave y suficiente texto.

Ahí está la palabra que lo condiciona todo: suficiente.

Marca de agua no es lo mismo que detector de IA

Un detector de IA adivina a partir del estilo; un detector de marca de agua busca una firma concreta que el propio modelo insertó. Son dos tecnologías distintas, con tasas de error distintas, y confundirlas es el error que más circula esta semana.

	Detector de IA	Detector de watermark
Analiza estilo	Sí	No
Conoce la firma	No	Sí
Necesita clave	No	Posiblemente
Es probabilístico	Sí	Sí
Identifica proveedor	Difícil	Potencialmente

Un detector de IA clásico —los que llevan años suspendiendo a estudiantes por escribir demasiado bien— hace estadística sobre el estilo: perplejidad, longitud de frase, variedad léxica. Adivina. Un detector de watermark no adivina: busca una firma concreta que sabe que está ahí.

Anthropic dice que "está trabajando para permitir que usuarios y terceros detecten las marcas de agua incrustadas de Claude y los metadatos de procedencia" y que publicará los detalles más adelante. Traducido: hoy no hay detector público de la marca de agua de Claude, ni fecha.

De ahí sale la frase que más falta hace repetir esta semana: cualquier web que hoy te diga "este texto contiene el watermark de Claude" sin acceso al mecanismo de verificación de Anthropic, está vendiendo humo. Sin ese mecanismo no hay verificación posible. Hay marketing.

El problema de la baja entropía cuando escribes código

Una marca de agua estadística es más débil sobre código que sobre prosa porque el código tiene poca entropía: en cada punto hay muy pocas continuaciones válidas y casi ningún margen para elegir un token en lugar de otro equivalente.

Y esto no me lo invento yo. Kirchenbauer et al. le dedican una sección entera del paper, titulada "A caveat: The difficulty of watermarking low-entropy sequences", y la abren así: "El texto de baja entropía crea dos problemas para el marcado. El primero: tanto humanos como máquinas producen terminaciones parecidas, si no idénticas, ante prompts de baja entropía, lo que hace imposible distinguir unas de otras."

Lo que sí es inferencia mía es aplicárselo a Claude. Anthropic no ha publicado su algoritmo ni ninguna política específica sobre código.

Una marca de agua estadística necesita libertad de elección. Si el modelo tiene veinte formas igual de válidas de continuar una frase, puede empujar hacia la lista verde sin que se note. En prosa esto sobra: "rápido" o "veloz", "por tanto" o "así que".

El código no funciona así.

Después de const user = await this.userService. hay dos o tres continuaciones razonables y el resto son errores de compilación. La entropía se hunde. El modelo no puede elegir un nombre de método "más verde" si el método se llama como se llama en la interfaz, y no puede reordenar los argumentos porque la firma es la que es.

Cuanto más determinista es la salida, menos sitio hay donde esconder señal. Y el código es el texto más determinista que produce un modelo. Es la misma naturaleza probabilística que explico en por qué la IA se inventa cosas: ese margen de maniobra permite tanto la alucinación como la marca de agua. En código, el margen se estrecha.

Añade que la mayoría de los diffs que revisas en un PR son de veinte o treinta líneas. Anthropic no da ningún umbral, pero sí reconoce el límite: un pasaje muy corto deja "demasiado poco texto para una señal fiable".

El paper de Kirchenbauer sí da números. En sus experimentos detectan el 98,4 % de las generaciones al umbral z=4, que se alcanza a los 128 tokens. Y avisan, en la misma sección: "Las secuencias de alta entropía se detectan con relativamente pocos tokens, mientras que las de baja entropía requieren más tokens para ser detectadas."

Junta las dos frases y verás por qué el número engaña. Ciento veintiocho tokens son del orden de diez o quince líneas de TypeScript, bastante menos que un commit cualquiera. Parece buena noticia para quien quiera detectarte. No lo es: ese 98,4 % está medido sobre prosa periodística, y el código es exactamente el material de baja entropía que, según los propios autores, necesita bastantes más tokens. Cuántos más, no lo dice nadie. Echa tú la cuenta con el tamaño de tus commits.

Por qué tu flujo de trabajo real lava la marca

Formatear, refactorizar, renombrar y revisar código altera la secuencia de tokens, y eso es lo que deshace una marca estadística sin que nadie se lo proponga.

Separemos las dos mitades del argumento, porque solo una está documentada. La documentada: Anthropic dice que la marca puede dejar de detectarse si el texto "ha sido editado en profundidad, parafraseado, traducido o mezclado con otra escritura" ("heavily edited, paraphrased, translated, or mixed into other writing"). La mía: que tu flujo de trabajo normal, el de cualquier martes, cuenta como editar en profundidad.

Conviene citar también la otra mitad, porque Anthropic la dice y casi nadie la está recogiendo: la marca "viaja con el texto cuando se copia y pega en otro sitio, y puede sobrevivir a algunas ediciones". Es cierto y no contradice lo anterior. Copiar y pegar no toca la secuencia de tokens: la marca sigue ahí intacta. Lo que la rompe es cambiar el orden de esos tokens, y eso es precisamente lo que hacen el formateador, la extracción de método y el renombrado.

Lee las dos frases otra vez y piensa en cómo trabajas de verdad con Claude Code a diario.

Spec-Driven Development reduce la libertad del modelo

Cuando trabajas con una spec detallada —nombres de tipos, contratos, estructura de carpetas, criterios de aceptación— no le pides al modelo que invente. Le pides que transcriba una decisión que ya tomaste tú.

Si la marca funciona como creo —y esto sigue siendo inferencia mía—, cuanto más rigurosa sea la spec, menos libertad probabilística le queda al modelo y menos espacio hay donde incrustar señal. Un efecto secundario curioso de una metodología que adopté por razones completamente distintas, y que tienes desarrollada entera en el libro de Spec-Driven Development.

El efecto Prettier

Esto es más brutal todavía, y pasa cada día sin que lo pienses.

Guardas el archivo y el formateador reparte los saltos de línea a su manera. Extraes un método. Renombras data por invoiceLines porque el nombre no decía nada. Mueves el bloque a otro archivo. El linter reordena los imports. Pasa por code review y alguien cambia tres cosas.

Cada una de esas operaciones altera la secuencia de tokens. Y cualquier marca estadística de la familia que describí arriba depende, literalmente, del orden exacto de esos tokens. Que la de Claude funcione así es inferencia mía. Que editar en profundidad pueda dejarla indetectable lo dice Anthropic.

No es que estés intentando borrar nada. Es que hacer bien tu trabajo la borra. Auditar y refactorizar lo que genera el asistente en lugar de aceptarlo tal cual es justo el flujo que enseño en Construye con IA, y resulta que además tiene este efecto colateral.

Lo que sí aguanta: C2PA en los archivos que genera Claude

Hay un caso donde la marca sí resiste: los archivos. Cuando Claude genera un .svg, .png o .jpg entra un segundo mecanismo: incrusta metadatos de procedencia firmados criptográficamente con el estándar C2PA, de la Coalition for Content Provenance and Authenticity. Anthropic no dice que esto sustituya a la marca del texto; dice que esos formatos llevan además procedencia.

Otra liga. Una firma criptográfica no es probabilística: o valida o no valida. Y permite detectar si el archivo fue manipulado después.

Y aquí está el contraste que más importa: la marca de agua del texto no la puede verificar nadie fuera de Anthropic, pero el C2PA sí se verifica ya hoy con herramientas públicas como c2patool o contentcredentials.org. Uno es una promesa; el otro funciona esta tarde.

Un detalle técnico que conviene fijar: un .svg es un archivo de texto, XML, no un binario. Los metadatos viven dentro del propio documento. Y aplica a los archivos que Claude genera, no a los que ya tienes en el proyecto.

O sea: si le pides a tu agente los iconos SVG de la aplicación y los commiteas tal cual, esos archivos sí llevan procedencia verificable dentro del repo. Puedes comprobarlo tú mismo:

c2patool icono-generado.svg

Durarán hasta que alguien los pase por un optimizador, los convierta de formato o los vuelva a guardar: Anthropic avisa de que la conversión de formato, el re-guardado y las capturas de pantalla eliminan los metadatos.

Y hay una limitación más, la que dejé apuntada al principio: los metadatos firmados "puede que no estén soportados en todas las plataformas". Si consumes Claude a través de AWS, Google Cloud o Microsoft Foundry, la marca del texto viaja igual, pero la procedencia de los archivos depende de lo que ofrezca cada plataforma. Anthropic lo incluye entre las causas por las que un contenido marcado puede no dar señal: haberse producido "a través de una plataforma, funcionalidad o tipo de archivo donde ese tipo de marcado no estaba soportado".

Robusto, pero no indestructible.

El falso positivo: detectar la marca no prueba autoría

Todo lo anterior va de falsos negativos: la marca está y se pierde. Pero hay un problema en la dirección contraria, y lo reconoce la propia Anthropic.

Detectar una marca de Claude te dice que el contenido "puede haber sido procesado por Claude" ("may have been processed by Claude"). No que Claude lo escribiera. La documentación lo desarrolla sin rodeos: "Claude puede no ser el autor original. La gente usa Claude a menudo para corregir, traducir, resumir o convertir archivos."

Léelo despacio, porque cambia la conversación entera.

Si coges una función que escribiste tú y le pides a Claude que la refactorice, que le añada tipos o que te traduzca los comentarios al inglés, la salida sale marcada igual. La marca prueba paso por el modelo, no autoría del modelo.

Y el reverso también está escrito: "la ausencia de marca detectada no significa que el contenido no fuera generado o procesado por IA".

O sea que la señal falla en las dos direcciones. Quien pretenda usar una detección como prueba de que no escribiste tú el código está leyendo mal la herramienta, y ahora tienes la frase del fabricante para decírselo.

¿Qué otras IAs marcan el contenido que generan?

Anthropic no es la primera ni va sola. El Artículo 50(2) empuja a todo el sector en la misma dirección, pero cada uno ha llegado hasta un punto distinto.

Proveedor	Marca el texto	Marca archivos	¿Verificable hoy por ti?
Anthropic (Claude)	Sí, desde agosto de 2026	Sí, C2PA en `.svg`, `.png`, `.jpg`	Texto: no. Archivos: sí, C2PA
Google (Gemini)	Sí, SynthID-Text	Sí, SynthID en imagen, audio y vídeo	No: leer SynthID requiere la clave de Google
OpenAI (ChatGPT)	No	Sí, C2PA en imágenes y SynthID en audio	Solo lo que expone C2PA

Google llegó antes: SynthID-Text lleva desplegado en Gemini desde 2024 y fue el primer marcado de texto en producción a escala. Firmó el mismo Código de Buenas Prácticas el 24 de julio de 2026, una semana antes de que el Artículo 50 fuera aplicable, y anunció acuerdos con Apple, ElevenLabs, Kakao, NVIDIA y OpenAI para que el marcado sea interoperable entre proveedores.

Fíjate en la casilla que se repite: nadie tiene detector público de texto. Ni Anthropic ni Google. SynthID lleva dos años funcionando y sigue necesitando la clave privada de Google para leerse. Eso te dice más sobre el plazo real de Anthropic que cualquier promesa de documentación futura.

Y el caso de OpenAI merece un párrafo, porque es el más honesto sobre los incentivos del negocio: tenía el marcado de texto construido y lo aparcó en septiembre de 2024, cuando una encuesta interna reveló que cerca del 30 % de los usuarios de ChatGPT lo usarían menos si supieran que marca lo que escribe. Marca imágenes y audio, donde nadie protesta. Texto no.

Entonces, ¿debería preocuparte?

Respuesta corta: no, si escribes software y auditas lo que genera el asistente. Sí, si tu empresa firma contratos con cláusulas sobre uso de IA y nadie las ha leído.

La iniciativa es buena ingeniería y buena regulación. La web abierta se está llenando de texto sintético que se hace pasar por humano, y marcarlo en origen es mejor que dejarlo en manos de detectores que funcionan por corazonadas estilísticas.

Para quien escribe software, el código sigue siendo código.

Tu repositorio no es un canal de distribución de texto sintético. Es un artefacto de ingeniería que pasa por specs, revisión, formateo, refactor y tests. Mientras controles la arquitectura y audites lo que genera el asistente, es poco probable que una marca estadística sobreviva a ese recorrido. Y mientras no haya detector público, ni tú ni nadie puede comprobarlo.

Lo único que te recomiendo hacer hoy: si tu empresa firma contratos con cláusulas sobre uso de IA, sube el tema tú antes de que lo suba un cliente. No para justificarte —usar Claude Code no es hacer trampas—, sino para tener una política escrita en lugar de una improvisación en una llamada incómoda.

Si quieres seguir estas cosas con gente que las aplica en producción y no solo lee titulares, en Dominicode Labs es de lo que hablamos cada semana.

Preguntas frecuentes

¿Puede alguien saber hoy si usé Claude para escribir este código?

No. Anthropic no ha publicado ni el algoritmo ni un detector público, y no ha dado fecha. Dice que trabaja para que usuarios y terceros puedan detectar las marcas, y que compartirá los detalles en documentación técnica futura. Hasta entonces, cualquier herramienta que afirme lo contrario no puede demostrarlo.

¿La marca de agua afecta a la calidad del código que genera Claude?

Anthropic afirma que no cambia el significado, la calidad ni la legibilidad. En prosa es creíble: el sesgo se reparte entre alternativas equivalentes. En código las alternativas equivalentes escasean, así que —y esto es deducción mía, no dato publicado— cualquier esquema de marcado tendría mucho menos margen de actuación. No hay motivo para esperar peor código por esto.

¿Puedo desactivar la marca de agua?

La documentación de Anthropic no menciona ninguna opción para desactivarlo, tampoco para quien usa la API. Se aplica a Claude Platform, Claude, Claude Code, Claude Cowork y Claude Tag, incluido Claude servido a través de AWS, Google Cloud y Microsoft Foundry, y rige en todo el mundo.

¿La marca de agua sobrevive a copiar y pegar el código?

Sí. Anthropic dice que la marca "viaja con el texto cuando se copia y pega en otro sitio, y puede sobrevivir a algunas ediciones". Copiar y pegar no altera la secuencia de tokens, así que no hay motivo para que se pierda. Lo que sí puede romperla, según la propia documentación, es editar en profundidad, parafrasear, traducir o mezclar el texto con otra escritura.

¿Cómo compruebo si un archivo generado por Claude lleva metadatos C2PA?

Con c2patool desde la terminal (c2patool archivo.svg) o subiendo el archivo a contentcredentials.org. Esto es lo único verificable hoy sin depender de Anthropic, y solo aplica a archivos .svg, .png y .jpg generados por Claude. Los metadatos desaparecen si conviertes el formato, vuelves a guardar el archivo o haces una captura de pantalla.

¿Afecta la marca de agua a quién es dueño del código que genera Claude?

No. La marca es un mecanismo de transparencia sobre el origen del contenido, no un mecanismo de propiedad. La titularidad de lo que generas con Claude se rige por los términos de servicio de Anthropic y por el contrato que tengas con tu cliente o tu empresa, no por si el texto lleva firma estadística. Lo que sí conviene es que esa relación esté escrita antes de que alguien pregunte.

¿Los detectores de IA como GPTZero o Turnitin detectan la marca de agua de Claude?

No. Son mecanismos distintos. Un detector convencional analiza el estilo y estima una probabilidad; no conoce ninguna firma y se equivoca a menudo en las dos direcciones. Un detector de watermark busca una señal concreta que sabe cómo se incrustó. Que un detector clásico marque tu texto como generado por IA no significa que haya encontrado la marca de Anthropic, porque no puede.

Si detectan la marca, ¿significa que el código lo escribió Claude?

No, y lo dice Anthropic: detectar una marca de Claude indica que el contenido "puede haber sido procesado por Claude", no que Claude lo escribiera. Si le pasas tu propio código para que lo refactorice o te lo traduzca, la salida sale marcada igual. La marca prueba paso por el modelo, no autoría del modelo. Cualquiera que use una detección como prueba de que no escribiste tú el código está leyendo mal la señal.

¿Me afecta si no estoy en la Unión Europea?

Sí. El marcado nace del Código de Buenas Prácticas del Artículo 50(2) del Reglamento Europeo de IA, pero Anthropic lo aplica globalmente. Dónde esté tu empresa no cambia nada.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

August 12, 2026

Context Engineering: Cómo estructurar la memoria de tus agentes de IA para eliminar alucinaciones
Hace unas semanas estaba ayudando a un desarrollador senior a configurar su entorno de trabajo con herramientas de IA. Para asegurarse de que el agente no cometiera errores, pegó en la ventana del chat un bloque gigante de 12.000 tokens que incluía la documentación entera del proyecto, 15 reglas de linteo, 4 archivos de tipos y la estructura del árbol de carpetas.

Cuando le pidió a la IA que implementara un módulo simple, la IA ignoró por completo las reglas situadas en la mitad del texto y generó importaciones obsoletas.

El desarrollador exclamó frustrado: "¡Le di toda la información en el prompt y aun así alucina!".

El problema no era la falta de información; era el exceso de ruido mal estructurado. Context Engineering no es escribir mejores prompts (Prompt Engineering). Es la disciplina de diseñar la arquitectura de información que alimenta a la ventana de contexto de los modelos LLM para maximizar la atención del modelo y erradicar las alucinaciones.

El fenómeno "Lost in the Middle" y la curva de atención

Los modelos de lenguaje basados en la arquitectura Transformer no leen el texto de la misma manera que los humanos.

Cuando la ventana de contexto supera los miles de tokens, ocurre un fenómeno estudiado minuciosamente por investigadores conocido como "Lost in the Middle" (Perdido en el medio):
- La IA presta máxima atención a los primeros tokens del prompt (Primacy Bias), que corresponden habitualmente al System Prompt.
- La IA presta máxima atención a los últimos tokens recibidos (Recency Bias), que corresponden a la última instrucción del usuario.
- La información situada en el tercio central de la ventana de contexto sufre una caída drástica de atención, aumentando el riesgo de alucinaciones o instrucciones ignoradas.
```
Nivel de Atención del LLM
 ▲
1.0 ┼──────┐                                 ┌──────┐
    │      │                                 │      │
0.5 ┤      └───────────┐         ┌───────────┘      │
    │                  │         │                  │
0.0 ┴──────────────────┴─────────┴──────────────────┴──►
    [System Prompt]    [Zona Central]     [Último Prompt]
      (Alta Atención)  (PERDIDO EN EL MEDIO) (Alta Atención)
```
Prompt Engineering vs. Context Engineering
- Prompt Engineering: Se enfoca en el redactado del mensaje. "Escribe una función en TypeScript limpia y responde en formato JSON".
- Context Engineering: Se enfoca en la gestión dinámica del espacio de memoria. ¿Qué archivos se deben incluir? ¿En qué formato se presentan los datos? ¿Cómo se poda el historial de conversación cuando se sobrecarga?
Como demostramos en nuestro análisis sobre por qué tu spec falla con un agente de IA, entregar especificaciones ambiguas o mal estructuradas es la razón principal por la que los agentes generan código inservible.

4 Pilares de Context Engineering para Developers

1. Etiquetado Semántico con XML y Markdown

Los modelos LLM avanzados (como Anthropic Claude) han sido entrenados específicamente para interpretar etiquetas XML como delimitadores de contexto. En lugar de enviar texto plano continuo, envuelve la información en secciones etiquetadas:
```
<system_instructions>
  Eres un desarrollador Senior en TypeScript. Sigue estrictamente las reglas definidas en <coding_standards>.
</system_instructions>

<coding_standards>
  - Usa siempre tipos estrictos sin 'any'.
  - Utiliza el patrón Result para manejo de errores.
</coding_standards>

<context_files>
  <file path="src/types/user.ts">
    export interface User { id: string; email: string; }
  </file>
</context_files>

<user_request>
  Crea una función para validar el correo de la interfaz User.
</user_request>
```
2. Podado Dinámico de Contexto (Context Pruning)

No arrastres el historial de chat indefinidamente. Si llevas 20 mensajes iterando sobre una funcionalidad, el historial acumulado satura la memoria. Limpia el contexto generando un resumen del estado actual e inicia una sesión limpia con los artefactos actualizados.

Como analizamos al calcular el coste de subagentes al cambiar de modelo, reducir el volumen de tokens enviados reduce los costes y acelera la velocidad de respuesta.

3. Graph Engineering (Indexación de Dependencias)

En lugar de enviarle al agente archivos enteros de 1.000 líneas, utiliza herramientas de indexación que entreguen únicamente las firmas de funciones, interfaces y grafos de dependencias requeridos. Revisa nuestra guía completa de graph engineering para aprender a crear mapas de código precisos.

Y cuando ese contexto sale de tus propias notas, la unidad importa: una nota atómica se recupera entera y una nota-cajón llega partida. Lo desarrollé en Zettelkasten para developers.

4. Separación de Tareas mediante Subagentes

Delegar sub-tareas a subagentes independientes garantiza que cada subagente trabaje en su propia ventana de contexto de 2.000 tokens hiperenfocada, devolviendo únicamente el resultado consolidado al hilo principal.

Diseñar el contexto adecuado es lo que transforma a un asistente conversacional genérico en una herramienta de ingeniería precisa y predecible.

Si quieres aprender a dominar arquitecturas avanzadas de desarrollo asistido por IA, descubre los Cursos de Dominicode. Y si quieres aplicar estas técnicas en proyectos reales de producción junto a desarrolladores senior, súmate a Dominicode Labs.

Preguntas frecuentes

¿Por qué los modelos con ventanas de 1 millón de tokens siguen necesitando Context Engineering?

Aunque un modelo pueda "procesar" 1 millón de tokens técnicamente, la calidad del razonamiento y la precisión en la recuperación de datos disminuyen a medida que aumenta la ventana. Mantener la información acotada y estructurada garantiza la máxima precisión.

¿Cuál es la diferencia entre RAG (Retrieval-Augmented Generation) y Context Engineering?

RAG es una técnica específica de Context Engineering que utiliza búsquedas semánticas o vectoriales para seleccionar qué fragmentos de información recuperar de una base de datos. Context Engineering engloba la estrategia completa de empaquetado, podado, etiquetado y presentación de esos fragmentos al modelo.

¿Es mejor enviar código en formato JSON, XML o Markdown?

Markdown con bloques de código delimitados por tres acentos graves (“`) y etiquetas XML (<file>, <spec>) es la combinación óptima. Los modelos actuales reconocen esta estructura de forma nativa por la abundancia de repositorios de GitHub en sus datos de entrenamiento.

¿Cómo afecta el idioma del contexto a la precisión del modelo?

Los modelos de lenguaje procesan los tokens de instrucciones en inglés con una ligera ventaja de atención debido a la densidad de datos de entrenamiento. Sin embargo, para la lógica de negocio y comentarios del proyecto en español, mantener el contexto en español estructurado mediante etiquetas XML ofrece resultados excelentes sin pérdida de coherencia.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
August 10, 2026
Cómo crear skills y subagentes personalizados para automatizar tu flujo diario de desarrollo con IA
Cada mañana, durante semanas, me sorprendía a mí mismo haciendo exactamente lo mismo. Abría mi herramienta de IA y pasaba los primeros 10 minutos explicándole la arquitectura de mi proyecto, las normas de linteo de nuestro equipo, qué librerías no debía usar y cómo estructurar los tests unitarios.

Si cambiaba de conversación o abría un nuevo hilo para otra tarea, tenía que volver a escribirlo todo de nuevo.

Estaba tratando a los asistentes de inteligencia artificial como un becario que llega nuevo a la oficina cada dos horas y sufre amnesia. Ahí fue cuando me di cuenta de que el verdadero salto de productividad no está en perfeccionar los prompts, sino en construir skills y subagentes personalizados que encapsulen tu conocimiento y el de tu equipo en tu flujo de desarrollo con IA.

El problema del prompt de 500 líneas en la ventana de contexto

Muchos desarrolladores intentan solucionar este problema pegando gigantescos bloques de contexto en el system prompt o en archivos de instrucciones globales.

Eso crea dos problemas graves:
1. Degradación del contexto: Si sobrecargas la ventana inicial del modelo con reglas que solo aplican a una tarea específica (por ejemplo, cómo migrar la base de datos), el LLM pierde precisión al razonar sobre la tarea actual.
2. Coste descontrolado de tokens: Cada mensaje que envías vuelve a procesar todo ese system prompt gigante. Como analizamos en nuestro artículo sobre el coste de subagentes al cambiar de modelo, acumular tokens innecesarios encarece y ralentiza drásticamente la ejecución.
La solución arquitectónica correcta es separar el conocimiento en dos conceptos: Skills (habilidades bajo demanda) y Subagentes (agentes especializados con ventana de contexto aislada).

¿Qué es una Skill y cuándo usarla?

Una Skill es una carpeta de instrucciones y recursos que se activa solo cuando el agente la necesita para resolver una tarea concreta.

Piensa en una skill como el "manual de procedimientos" para una tarea específica:
- Crear una nueva spec arquitectónica.
- Configurar el tracking de analítica.
- Auditar la accesibilidad UI de una página.
```
---
name: angular-signals-migration
description: Guía paso a paso para migrar componentes de RxJS BehaviorSubject a Angular Signals en v22+
---

# Instrucciones de Migración
1. Reemplaza `BehaviorSubject<T>` por `signal<T>`.
2. Para valores derivados, utiliza `computed()`. No uses `effect()` para modificar estado.
3. Asegúrate de actualizar la plantilla eliminando el pipe `async`.
```
Cuando tu agente (como Claude Code o AGY) detecta que tu petición requiere migrar componentes, lee este SKILL.md bajo demanda, aplica las reglas y libera el espacio cuando termina.

¿Qué es un Subagente personalizado?

Un Subagente es un agente secundario que se lanza en una conversación en segundo plano completamente aislada.

Recibe un rol específico (por ejemplo: Code Reviewer, Database Debugger o SEO Auditor), un conjunto acotado de herramientas y su propia ventana de contexto. Cuando termina su labor, devuelve únicamente el resultado sintetizado al agente principal.

Al igual que explicamos en nuestro post sobre graph engineering, estructurar la información en nodos especializados evita que la IA se pierda en un laberinto de contexto irrelevante.

Ejemplo de definición de Subagente
```
---
name: code-reviewer-senior
description: Revisa pull requests buscando vulnerabilidades de seguridad, memory leaks y falta de tipos estrictos.
tools: read_file, grep_search
---

# Rol: Senior Code Reviewer
Eres un auditor de código ultrarreciso. Revisa las líneas modificadas en la PR y evalúa:
1. ¿Hay algún `any` implícito o explícito en TypeScript?
2. ¿Se están liberando los subs de observables no finitos?
3. Devuelve únicamente una lista de hallazgos críticos prioritarios.
```
Guía paso a paso para crear tu primera Skill

Para implementar skills en tu repositorio o configuración global de IA:

1. Estructura el directorio

Crea una carpeta dentro de .agents/skills/ (o la ruta de configuraciones de tu herramienta):
```
.agents/
  skills/
    db-migration/
      SKILL.md
      template.sql
```
2. Escribe el SKILL.md con Frontmatter claro

Define en la cabecera YAML el nombre y una descripción precisa de cuándo debe activarse la skill. El agente utilizará la descripción para saber cuándo consultar estas instrucciones.

3. Mantén los pasos de ejecución atómicos

Define un flujo paso a paso que el agente pueda verificar en cada etapa antes de continuar.

El resultado es inmediato: dejas de repetir las mismas explicaciones una y otra vez. Tu equipo comparte la misma carpeta de .agents/ en el repositorio Git, garantizando que todos los desarrolladores (y sus agentes de IA) sigan exactamente los mismos estándares.

Si deseas ver más sobre la integración de IA en tu organización, revisa nuestra guía sobre cómo formar a tu equipo de desarrollo en IA en 6 semanas.

Para seguir perfeccionando tu workflow, consulta los Cursos de Dominicode donde profundizamos en desarrollo asistido por IA. Y si buscas construir productos reales en comunidad, te esperamos en Dominicode Labs.

Preguntas frecuentes

¿En qué se diferencia una Skill de un Prompt tradicional?

Un prompt tradicional se envía manualmente en cada mensaje. Una Skill es modular, vive en el disco como archivo de código y es descubierta y cargada de forma autónoma por la IA solo cuando la tarea lo requiere.

¿Puedo compartir mis skills con otros miembros de mi equipo?

Sí, al almacenar la carpeta .agents/skills/ dentro del propio repositorio de Git, todo el equipo comparte automáticamente las mismas instrucciones y mejores prácticas del proyecto.

¿Los subagentes consumen más tokens que una conversación normal?

Inicialmente, lanzar un subagente consume tokens de inicialización, pero a medio y largo plazo ahorra miles de tokens porque evita arrastrar el historial de chat acumulado de la sesión principal.

¿Qué herramientas soportan el uso de Skills y Subagentes?

Herramientas avanzadas como Claude Code, Google Antigravity (AGY), Cursor y entornos habilitados con arquitecturas de agentes permiten definir e invocar skills y subagentes de forma nativa.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
August 7, 2026
Cómo conectar Claude Code a tus DBs y APIs mediante MCP (Model Context Protocol)
Durante mucho tiempo, la mayor limitación de los asistentes de desarrollo basados en IA no era su capacidad para escribir código, sino su ceguera ante el mundo real.

Le pedías a la IA que investigara un bug sutil en producción, y el modelo empezaba a inventar tablas que no existían, asumir tipos de columnas equivocados o sugerir llamadas a endpoints obsoletos. Tenías que hacer de "puente humano": copiar la respuesta del terminal, pegarla en el chat, pedirle una SQL, ejecutarla tú en tu cliente de base de datos y pegarle el resultado.

Ese trabajo manual se acabó. Model Context Protocol (MCP) es el estándar abierto propuesto por Anthropic que permite a asistentes como Claude Code conectarse de forma nativa a tus bases de datos, APIs de staging, repositorios y servicios internos.

¿Qué es exactamente Model Context Protocol (MCP)?

Piensa en MCP (Model Context Protocol) como el estándar USB-C para los modelos de lenguaje.

Antes de MCP, si querías que un LLM interactuara con Postgres, tu API GraphQL o un canal de Slack, tenías que escribir integraciones ad-hoc y wrappers frágiles para cada herramienta.

MCP unifica todo bajo una arquitectura cliente-servidor muy simple:
- Host (o Cliente MCP): Tu entorno de desarrollo o agente (por ejemplo, Claude Code, AGY o Cursor).
- Servidor MCP: Un proceso ligero que expone herramientas (tools), recursos (resources) y prompts hacia el cliente mediante un protocolo JSON-RPC estándar over stdio o HTTP/SSE.
Cuando el agente necesita saber qué tablas existen en tu base de datos, llama a la herramienta list_tables expuesta por tu servidor MCP, recibe la respuesta estructurada y actúa en consecuencia sin que tú tengas que mover un dedo.

Cómo configurar un servidor MCP en Claude Code

Conectar Claude Code a una base de datos o servicio externo es cuestión de minutos. Puedes usar servidores MCP creados por la comunidad o construir el tuyo propio.

1. Usar un servidor existente (Ejemplo: PostgreSQL / Supabase)

Puedes añadir un servidor MCP directamente a la configuración de tu entorno con un comando sencillo:
```
claude mcp add postgres npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@localhost:5432/mydb
```
A partir de ese momento, Claude Code tiene acceso a herramientas seguras como query para inspeccionar esquemas y ejecutar consultas de lectura cuando se lo pidas en lenguaje natural.

2. Crear tu propio servidor MCP personalizado en TypeScript

Si tienes una API interna o reglas de negocio propietarias, puedes construir tu propio servidor MCP en TypeScript con muy pocas líneas:
```
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "mi-api-interna", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 1. Listar herramientas disponibles para la IA
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "buscar_usuario_por_email",
    description: "Busca los datos de un usuario en el entorno de staging por su email",
    inputSchema: {
      type: "object",
      properties: { email: { type: "string" } },
      required: ["email"]
    }
  }]
}));

// 2. Ejecutar la lógica cuando la IA invoca la herramienta
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "buscar_usuario_por_email") {
    const { email } = request.params.arguments as { email: string };
    const user = await miApiStaging.getUser(email);
    return { content: [{ type: "text", text: JSON.stringify(user) }] };
  }
  throw new Error("Herramienta no encontrada");
});

const transport = new StdioServerTransport();
await server.connect(transport);
```
Seguridad: Evitando riesgos en producciones reales

Darle acceso a un agente de IA a tus bases de datos y servicios requiere precauciones claras:
1. Principio de mínimo privilegio: Configura tus servidores MCP con credenciales de solo lectura para entornos de desarrollo o staging.
2. Protección contra inyecciones: Tal como explicamos en nuestro análisis sobre inyección indirecta de prompts en agentes de IA, nunca permitas que datos no confiables provenientes de la base de datos o de usuarios modifiquen el comportamiento del agente sin sanitizar.
3. Control de contexto: Utiliza técnicas de graph engineering para estructurar los datos expuestos por tus herramientas MCP y evitar saturar la memoria del modelo.
El protocolo MCP cambia drásticamente la relación entre el desarrollador y la IA. Dejas de copiar y pegar respuestas del terminal para convertir a tu agente en un miembro activo del equipo que consulta métricas, ejecuta tests y verifica estados en tiempo real.

Si quieres llevar tus habilidades al siguiente nivel y dominar la integración de agentes con infraestructuras reales, explora los Cursos de Dominicode. Y si buscas construir proyectos con arquitecturas avanzadas de IA, entra en Dominicode Labs.

Preguntas frecuentes

¿MCP funciona solo con Claude Code o con cualquier cliente de IA?

MCP es un estándar abierto. Aunque fue creado por Anthropic, puede ser implementado por cualquier cliente, IDE o framework de agentes (como Cursor, Antigravity, VS Code o agentes personalizados).

¿Es seguro conectar una base de datos de producción a través de MCP?

Se recomienda conectar únicamente entornos de desarrollo, staging o réplicas de solo lectura. Para operaciones de escritura en producción, el servidor MCP debe solicitar siempre confirmación explícita del usuario antes de ejecutar cualquier cambio.

¿Qué diferencia hay entre una llamada a una API tradicional y un servidor MCP?

Una llamada a API tradicional requiere que tú programes la petición exacta en tu código. Un servidor MCP le enseña a la IA la firma de la herramienta para que el modelo decida de forma autónoma cuándo y cómo invocarla según el contexto de la conversación.

¿Dónde puedo encontrar servidores MCP listos para usar?

Existen repositorios oficiales y comunitarios con servidores MCP para PostgreSQL, GitHub, Slack, Puppeteer, Brave Search, Google Drive y decenas de servicios populares.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
August 6, 2026

Tag: Claude Code

Hooks vs permissions: las dos capas, y cuál manda

Un hook solo puede restringir, nunca ampliar

El hook falla abierto. La regla deny no puede fallar.

El sistema de permisos entiende de shell. Tu grep no.

Los agujeros que sí existen

La sintaxis que casi nadie escribe bien

Hooks vs permissions en Claude Code: qué va en cada capa

El JSON que deberías tener

Entonces, ¿para qué el hook?

Qué hacer hoy

Preguntas frecuentes

¿Puedo usar un hook para permitir algo que una regla deny bloquea?

¿Qué pasa si mi hook de seguridad falla o el script no existe?

¿Basta con poner Bash en deny para bloquear todos los comandos?

¿Por qué mi regla Bash(ls *) no permite lsof?

¿Cómo evito que alguien active bypassPermissions en mi equipo?

¿Dónde pongo las reglas: settings.json o settings.local.json?

Por qué revisar código generado por IA cansa más que escribirlo

El problema no era el agente

Por qué tu spec no lo arregló

1. Contrato: qué se construye

2. Carril: por dónde no puede salirse

3. Veredicto: quién dice que está bien

Qué cambia el martes por la mañana

Qué hacer hoy

Preguntas frecuentes

¿Cómo se revisa código generado por IA sin leer todo el diff?

¿Esto no es simplemente tener buenos tests?

Mi repo no tiene tests. ¿Esto me sirve de algo?

¿No es más fácil poner todo esto en el prompt?

¿Esto no ralentiza al agente?

¿Sirve si mi stack no es TypeScript?

Por qué los Mega-Prompts fallan en la práctica

1. Degradación por ruido de herramientas (Tool Noise)

2. Dispersión de atención (Attention Drift)

3. Contaminación de contexto

La solución: Arquitectura de Subagentes en 3 capas

1. El Investigador (Researcher — Solo Lectura)

2. El Implementador (Implementer — Escritura + TDD)

3. El Revisor (Reviewer — Auditor de Calidad)

Cómo se comunican los subagentes sin saturar tokens: El patrón Artifact

Ejemplo práctico: Definiendo un subagente en TypeScript

Qué hacer hoy con tu proyecto

Aviso rápido: OpenSpec no es OpenAPI

Paso 1: instalar (y el error de scope que arrastran los tutoriales viejos)

Paso 2: inicializar OpenSpec en Claude Code

Paso 3: llena el config.yaml antes de pedir nada

Paso 4: el flujo OPSX de principio a fin

/opsx:explore — pensar sin comprometerte

/opsx:propose — generar la propuesta

/opsx:apply — implementar contra la spec

/opsx:update y /opsx:sync — mantener la spec viva

/opsx:archive — cerrar el cambio

El perfil extendido (y dónde vive /opsx:verify)

Delta specs: por qué esto sirve en un proyecto que ya existe

La sintaxis cambia según la herramienta

Si vienes de un tutorial de hace unos meses

Qué hacer hoy con esto

Preguntas frecuentes

¿OpenSpec es lo mismo que OpenAPI?

¿Por qué mi instalación de OpenSpec no funciona?

¿OpenSpec sirve en un proyecto que ya existe o solo en proyectos nuevos?

¿Se puede usar OpenSpec con Cursor o Copilot en vez de Claude Code?

¿Puedo saltarme el comando explore e ir directo a propose?

¿Qué hago si seguí un tutorial con el flujo antiguo de OpenSpec?

OpenSpec no es OpenAPI: la diferencia en una tabla

Cómo instalar OpenSpec para Claude Code (y el error de scope de npm)

Qué crea openspec init en un proyecto con Claude Code

Qué poner en openspec/config.yaml (y por qué no es opcional)

El flujo OPSX paso a paso en Claude Code

/opsx:explore — pensar sin comprometerte

/opsx:propose — generar la propuesta

/opsx:apply — implementar contra la spec

/opsx:archive — cerrar el cambio

Los otros dos del perfil por defecto

Los extendidos, y por qué /opsx:verify no te va a funcionar todavía

Delta specs: por qué esto sirve en un proyecto que ya existe

La sintaxis cambia según la herramienta

Cómo migrar del flujo antiguo de OpenSpec al flujo OPSX

El hook falla abierto. La regla `deny` no puede fallar.

El sistema de permisos entiende de shell. Tu `grep` no.

¿Por qué mi regla `Bash(ls *)` no permite `lsof`?

¿Dónde pongo las reglas: `settings.json` o `settings.local.json`?

1. El Investigador (`Researcher` — Solo Lectura)

2. El Implementador (`Implementer` — Escritura + TDD)

3. El Revisor (`Reviewer` — Auditor de Calidad)

`/opsx:explore` — pensar sin comprometerte

`/opsx:propose` — generar la propuesta

`/opsx:apply` — implementar contra la spec

`/opsx:update` y `/opsx:sync` — mantener la spec viva

`/opsx:archive` — cerrar el cambio

El perfil extendido (y dónde vive `/opsx:verify`)

Qué crea `openspec init` en un proyecto con Claude Code

Qué poner en `openspec/config.yaml` (y por qué no es opcional)

`/opsx:explore` — pensar sin comprometerte

`/opsx:propose` — generar la propuesta

`/opsx:apply` — implementar contra la spec

`/opsx:archive` — cerrar el cambio

Los extendidos, y por qué `/opsx:verify` no te va a funcionar todavía

1. `spec.md` (La Especificación Funcional y Técnica)

2. `plan.md` (La Arquitectura e Impacto)

3. `tasks.md` (El Plan de Ejecución)