Cómo escribir agentes de Claude Code que no te mientan

Le pediste a Claude Code que implementara este diseño y verificara que coincide con el mockup de Figma. Te respondió: Listo. Todas las secciones coinciden, el espaciado es correcto, los colores son los que toca. Abriste la página. La mitad del espaciado estaba mal. El estado hover no existía. Los botones tenían un tono incorrecto. El modelo no mintió con mala intención — predijo que querías escuchar verificado, así que generó exactamente esa secuencia de tokens. No hubo ningún paso de verificación. Nunca podría haberlo — verificar requiere comparar contra un ground truth, y un único agente en un único contexto no tiene manera de salirse de su propia respuesta y comprobarse a sí mismo.

Dos reglas han convertido mis flujos de trabajo llenos de alucinaciones en pipelines fiables: un agente, una especialización, y todo lo que pueda ejecutarse como comando de shell debe ejecutarse como comando de shell. Esto no es teoría. Es lo que hago cada día con Claude Code, y estos son los patrones que realmente marcan la diferencia.

Por qué los agentes generalistas mienten

Los LLM son predictores del siguiente token. Cuando un prompt pide dos roles — construye X y verifica X — el modelo termina el primer rol y luego predice cómo sería la salida del segundo, sin ejecutarlo realmente. La auto-verificación es estructuralmente débil: mismo contexto, mismo modelo, los mismos puntos ciegos. El pass en la verificación está correlacionado con el pass en la construcción — fallan juntos.

El modelo no sabe que está mintiendo. Desde su perspectiva, narrar verifiqué todo con cuidado es una continuación coherente de haber escrito el código. Es la misma razón por la que los prompts de ¿estás seguro? no atrapan alucinaciones: el modelo tiene la misma confianza en el segundo intento. La confianza no está correlacionada con la corrección — está correlacionada con lo plausible que suena la siguiente frase.

La solución no son mejores prompts. Ten cuidado, vuelve a revisar, no alucines — estas instrucciones no sirven para nada. La solución es estructural: especializa el agente para que físicamente no pueda fingir, y enruta el trabajo cuantitativo a través del shell para que la respuesta venga del estado real, no de la probabilidad de tokens.

Regla 1: un agente, una especialización

Divide el trabajo en agentes separados con contextos separados. Cada agente tiene una sola responsabilidad y un conjunto de herramientas acotado. Todo el flujo se convierte en una carrera de relevos en lugar de un único agente dando vueltas:

• Agente builder: recibe la spec y escribe el código. Ese es su único trabajo. Tiene Read, Edit, Write, Bash.
• Agente reviewer: recibe la spec más el diff y comprueba los criterios de aceptación. Contexto limpio. Sin conocimiento de cómo se escribió el código, solo de lo que salió. Tiene Bash, Read, Grep, Glob — sin herramientas de escritura.
• Agente de analytics: responde preguntas sobre datos construyendo y ejecutando queries. Solo Bash. No puede llegar a la respuesta sin ejecutar un comando real.
• Orchestrator: la sesión principal que despacha cada agente en turno y nunca le pide a uno que haga el trabajo del otro.

Ejemplo concreto: implementación de UI más una verificación visual contra un mockup de Figma. El builder escribe los componentes y hace commit del diff. Luego el orchestrator invoca al reviewer con la URL del diseño, el diff y criterios de aceptación explícitos. El reviewer ejecuta Playwright, toma screenshots, los difiere contra la referencia y devuelve PASS o FAIL con las rutas reales de los screenshots y los pixel diffs. El builder nunca se acerca al paso de verificación — y precisamente por eso la verificación es real.

El anti-patrón es el mega-agente: un único prompt que dice implementa esta UI y asegúrate de que coincide con el mockup. Te lo garantizo: reportará que todo coincide. No coincidirá. El relato de lo verifiqué es simplemente la secuencia de tokens más probable después de lo implementé.

Regla 2: shell antes que prompt, siempre

Todo lo cuantitativo, todo lo que toca estado real, todo donde la respuesta puede estar mal de una forma que parece correcta — pásalo por sh. El trabajo del agente es construir y ejecutar el comando, luego leer su salida. El agente no es la fuente de verdad. La salida del shell lo es.

• Contar: wc -l logs.txt es verdad. Hay aproximadamente 47 líneas de log de parte del modelo es una alucinación.
• Analytics: psql -c "SELECT count(*) FROM events WHERE created_at > now() - interval '30 days'". No estima el volumen.
• Tests: pnpm test --reporter=json | jq '.numFailedTests'. No resume qué falló.
• Estado de Git: git rev-list --count main..HEAD, git diff --stat. No cuenta los commits ni describe los cambios.

Una vez que interiorizas esto, empiezas a detectar cada momento en que el agente estaba a punto de inventarse un número. Parece que hay unos 200 registros... — no. Ejecuta SELECT count(*). La mayoría de los tests pasan... — no. Ejecuta el test suite, parsea el JSON. El modelo es excelente construyendo el comando. Es poco fiable siendo el comando.

Modos de fallo que he sufrido en persona

No son hipotéticos. Cada uno de estos me costó tiempo real antes de cambiar el patrón:

• Verificación fantasma. El agente dijo comprobé las 14 secciones contra el mockup. No abrió el mockup. No tomó ningún screenshot. La comprobación era un paso alucinado en el relato.
• Números incorrectos con total confianza. Pedí los monthly active users de los datos de analytics. Me dio un número equivocado por un factor de ~3×. El modelo interpoló a partir de filas de muestra en lugar de ejecutar la query real.
• Cambios de archivos inventados. El agente dijo actualicé config/feature-flags.json. No lo había hecho. Solo lo había pretendido. git diff estaba vacío.
• Ejecuciones de tests falsas. Todos los tests pasan. No se ejecutó ningún test. El agente nunca invocó el test runner — predijo cómo habría sido la salida del runner.

Los cuatro se resuelven con las mismas dos reglas: divide el agente, empuja al shell. El reviewer no tiene Write, así que no puede falsificar ediciones de archivos. El agente de analytics solo tiene Bash, así que no puede devolver un número que no venga de una query. La imposibilidad estructural gana a las buenas intenciones siempre.

Cómo estructurar esto en Claude Code

Claude Code admite sub-agents definidos en .claude/agents/*.md. Cada archivo de agente declara un nombre, una descripción, un conjunto de herramientas permitidas y un system prompt. El orchestrator (tu sesión principal) los despacha usando la herramienta Agent. Esta es la clase de definición que uso para el reviewer — corta, acotada y físicamente incapaz de escribir código:

---
name: reviewer
description: Reviews a diff against acceptance criteria. Cannot edit code.
tools: Bash, Read, Grep, Glob
---

You are a strict code reviewer. You receive:
- A diff (already produced by the builder)
- Acceptance criteria

Your job:
1. Run the build, the tests, the linter — through Bash.
2. Read the changed files directly.
3. Compare the actual behavior to the criteria.
4. Report PASS or FAIL with concrete evidence (command output, file excerpts).

You must NOT:
- Trust the builder's summary
- Assume anything was verified just because it was claimed
- Mark something PASS without running the actual check

Fíjate en el conjunto de herramientas: Bash, Read, Grep, Glob. Sin Write, sin Edit, sin Agent. El reviewer puede ejecutar comandos, leer archivos, buscar patrones — y nada más. Si intenta hacer pasar un diff alucinado por verificado, la forma de sus llamadas a herramientas lo deja en evidencia: no hubo comprobaciones reales. Puedes auditar las llamadas y ver exactamente qué se inspeccionó.

El patrón de orquestación: la sesión principal llama al Builder → espera → ejecuta git diff ella misma para capturar el cambio real → llama al Reviewer con la spec y el diff → lee el veredicto del Reviewer. La sesión principal nunca le pide a un agente que haga ambas cosas. Las restricciones de herramientas son más fuertes que las instrucciones en el prompt: no falsifiques la verificación es un deseo. No tener Write es un hecho.

Anti-patrones a desterrar

Cosas que veo en prompts y que no hacen nada — o peor, dan una falsa sensación de seguridad:

• Ten cuidado y revisa tu trabajo. No genera ningún comportamiento adicional. El modelo ya produce lo que parece trabajo cuidadoso.
• Asegúrate de verificar de verdad. La palabra de verdad no añade semántica sobre la que el modelo pueda actuar. Va a afirmar que verificó de verdad.
• No alucines. Un meme del prompt engineering. La alucinación no es un interruptor que el modelo pueda apagar.
• Fiarse del agente con números pequeños. Los números pequeños son donde miente con más confianza. No existe un umbral de honestidad.
• Añadir más reglas al prompt para forzar la honestidad. Las correcciones estructurales (dividir + shell) ganan a los ajustes de prompt siempre. Si una regla necesita aplicarse, codifícala en el acceso a herramientas, no en español.

Si tu estrategia para atrapar alucinaciones es redactar las instrucciones con más énfasis, no tienes una estrategia. Tienes una esperanza.

El modelo mental

Un agente no es un compañero. Es una función: prompt → tokens. La función es excelente escribiendo código y pésima introspectando si hizo lo correcto. Trata sus afirmaciones sobre su propio trabajo como una hipótesis. El diff, el exit code, el screenshot, el row count — esa es la evidencia. El resumen al final del turno es la superficie más propensa a mentir de todo el sistema.

La especialización es tu seguro contra la deriva narrativa. El shell es tu único ground truth. El builder escribe. El reviewer comprueba. Bash decide.

Conclusión

Si te quedas con una sola cosa: no dejes que un único agente produzca y juzgue su propia salida, y no dejes que ningún agente responda una pregunta cuantitativa sin ejecutar un comando. Todo lo demás se deriva de estas dos reglas. Configura el acceso a herramientas de forma agresiva, audita las llamadas a herramientas en lugar de los resúmenes, y la superficie de alucinación se reduce de todas partes a unos pocos lugares concretos que ya sabes dónde buscar.