Obliga a un bloque de suposiciones antes de cualquier tarea no trivial
El bloque de cuatro líneas que elimina el retrabajo de la IA.
El modo de fallo más común de un agente de codificación no es un error de sintaxis. Es que el agente llene en silencio un requisito ambiguo con una suposición plausible pero equivocada y luego construya cincuenta archivos encima. Para cuando te das cuenta, el error ya es estructural. La solución no es un mejor prompt para la tarea en sí. Es una regla permanente que obliga al agente a mostrar sus suposiciones antes de escribir cualquier código.
El modo de fallo: adivinar en silencio
Los requisitos casi nunca están completos. Cuando dices "agrega caché", el agente tiene que decidir: dónde cachear, cómo invalidar, por usuario o global, qué TTL. Un buen ingeniero humano pregunta. Un agente, optimizado para ser útil y producir salida, adivina y sigue adelante. Cada conjetura es razonable por separado. Apiladas, se alejan de lo que realmente querías, y la desviación es invisible hasta que lees el diff.
El costo es asimétrico. Detectar una suposición equivocada en una oración en inglés es casi gratis. Detectarla después de que el agente reestructuró tu módulo es caro y desmoralizante.
El mecanismo: un bloque de suposiciones
Agrega una regla a tu CLAUDE.md, AGENTS.md o prompt de sistema que se dispare en cualquier tarea no trivial:
## Before non-trivial work
Before writing code for any non-trivial task, output an ASSUMPTIONS block:
- **Requirements** — what I'm inferring about the desired behavior
- **Architecture** — where this fits, what it touches, what I'll change
- **Scope** — what's in, what's explicitly out
End with: "Correct me now or I proceed."
Then wait for my reply before touching files.La clave es la última línea. Convierte una conjetura implícita en un checkpoint explícito que tú tienes que aprobar. Lees cuatro viñetas, detectas la inferencia equivocada y rediriges en una oración.
Por qué esto supera a "solo pregunta más"
Decirle a un agente que "pregunte si tiene dudas" rinde poco porque el agente rara vez siente dudas. Tiene una respuesta segura para cada ambigüedad. Un bloque de suposiciones evita la seguridad por completo: no le pide al agente que detecte incertidumbre, lo obliga a enumerar sus propias inferencias donde tú puedes verlas. Tú aportas el juicio sobre cuál inferencia está equivocada.
| Enfoque | Qué hace el agente | Dónde aparecen los errores |
|---|---|---|
| Sin regla | Adivina en silencio, procede | En el diff final, tras el trabajo |
| "Pregunta si dudas" | Casi nunca se dispara; se siente seguro | Igual en el diff |
| Bloque de suposiciones | Lista cada inferencia, espera | En cuatro viñetas, antes del código |
Movidas avanzadas
- Acótalo a "no trivial". No quieres un bloque de suposiciones para "renombra esta variable". Define el umbral en la regla para que se dispare en features y refactors, no en one-liners.
- Haz del bloque una plantilla. Encabezados fijos (Requirements / Architecture / Scope) lo hacen fácil de ojear y obligan al agente a cubrir puntos ciegos que de otro modo saltaría.
- Conserva la línea "correct me now or I proceed". Sin una compuerta explícita, los agentes tratan el bloque como narración y siguen de largo igual.
- Reúsalo como especificación. El bloque de suposiciones aprobado sirve como registro de diseño ligero. Pégalo en la descripción del PR para que los revisores vean las decisiones tomadas.
Recursos
- Anthropic — Claude Code best practices
- Documentación de Anthropic — Manage Claude's memory (CLAUDE.md)
- AGENTS.md — un formato abierto y simple para instrucciones de agentes
- Anthropic — Building effective agents
¿Desarrollas sistemas de IA o en la nube? Yeda AI audita y refuerza pipelines de LLM y agentes en producción. Hablemos · Lee el blog