El problema
Seamos honestos: ya no queremos leer código. No queremos verificar todo lo que hacen los agentes ni tener en la cabeza cada detalle técnico del proyecto.
Pero si nadie controla a los agentes, convertirán cualquier proyecto en un caos inmantenible que ni un humano ni un agente podrán desenredar. Es solo cuestión de tiempo.
La idea
HUMAN-INTENT.md es un archivo en la raíz de tu repositorio. Contiene tu intención: la arquitectura del proyecto, las reglas de desarrollo y las decisiones de producto.
No es documentación del código. Es la ley que el código debe obedecer.
Las reglas
-
Lo escribes tú — y solo tú
Los agentes nunca editan este archivo. Cada línea es una decisión tomada por un humano.
-
Sus instrucciones son ley para el agente
Lo que dice HUMAN-INTENT.md prevalece sobre todo lo demás. Si el código contradice el archivo, el código está equivocado.
-
Define la arquitectura, las reglas y el producto
Intención, no recetas. El agente ya conoce todos los patrones; tu trabajo es fijar qué debe cumplirse — y por qué.
Por qué funciona
Es imposible seguir el ritmo de los agentes: hay más código del que nadie está dispuesto a leer. Controlar cada línea es inútil. Controlar la intención, no.
HUMAN-INTENT.md sube el control un nivel: vigilas un archivo con tus decisiones en lugar de miles de líneas de código. Mientras el archivo sea ley, el proyecto sigue tu intención — incluso si nadie lee el código.
Cómo empezar
- Crea HUMAN-INTENT.md en la raíz de tu repositorio.
- Anota las decisiones que ya has tomado: arquitectura, reglas de desarrollo, producto.
- Dile a tu agente que lea el archivo y lo trate como ley — referéncialo desde AGENTS.md o CLAUDE.md.
- Cada vez que tomes una nueva decisión, añádela al archivo. Nunca dejes que un agente escriba en él.
- Revisa este archivo, no el código.