Escribir una sola vez las reglas, convenciones y procedimientos del proyecto, en un lugar que el agente lee solo, sin que se lo recuerdes.
La idea que sobrevive a las herramientas
Lo que repetís tres veces, escribilo. Lo que no admite excepción, automatizalo.
El modelo sabe cómo se escribe software en general. No sabe cómo se escribe software acá. Esa diferencia —la convención de nombres, dónde van los tests, qué librería está prohibida y por qué— no está en sus pesos y nunca va a estar.
Hay dos formas de estándar y conviene no mezclarlas. Las reglas son permanentes y aplican siempre: van en el archivo de instrucciones del proyecto, que el agente carga al arrancar. Los procedimientos son condicionales y aplican a una tarea concreta: van en algo que se cargue solo cuando esa tarea aparece, para no ocupar espacio el resto del tiempo.
Y hay un tercer nivel que la gente descubre tarde: lo que tiene que pasar siempre, sin excepción, no va en un texto. Pedirle al modelo que “siempre corra el linter” es una sugerencia, y a veces la va a cumplir. Si es sin excepción, tiene que ser un comando determinista que se ejecuta pase lo que pase, sin pasar por el modelo.
El error más común acá es escribir el archivo de instrucciones como si fuera documentación para humanos. No lo es. Son órdenes ejecutables: cortas, concretas, sin ambigüedad y sin párrafos de introducción.
Cómo funciona, paso a paso
Hasta acá el porqué. Esto es la máquina: qué pasa en cada etapa y, sobre todo, cuál es la decisión que te toca a vos en cada una. Si en algún paso no decidís nada, ese paso lo está decidiendo la herramienta por vos.
01
Declaración
Qué pasa
Las reglas se escriben en un archivo que vive en el repositorio, no en tu cabeza ni en el prompt que escribís cada mañana. Quien clona el proyecto —persona o agente— las hereda sin que nadie se las cuente.
Qué decidís vos
Qué es regla y qué es preferencia tuya. Todo lo que declares como regla se va a aplicar donde parezca encajar, incluso donde vos nunca quisiste.
02
Carga
Qué pasa
Hay reglas que entran en la ventana en cada pedido y otras que se cargan solo cuando la tarea las toca. Las primeras cuestan lugar siempre; las segundas cuestan un acierto: alguien tiene que decidir bien cuándo aplican.
Qué decidís vos
Qué merece estar siempre presente. Un archivo de instrucciones de trescientas líneas se paga en cada mensaje, incluso en el que solo pedía un typo.
03
Alcance
Qué pasa
Una regla puede valer para todo el repositorio o solo para una carpeta. En un monorepo esa diferencia es lo que evita que la convención del backend se aplique al front.
Qué decidís vos
Dónde empieza y dónde termina cada regla. Una regla sin alcance declarado se aplica a todo, que casi nunca es lo que querías.
04
Aplicación
Qué pasa
Hay dos maneras de que una regla se cumpla. Escrita en el prompt se cumple casi siempre. Ejecutada por una herramienta —un formateador, un linter, un hook— se cumple siempre.
Qué decidís vos
Cuáles pasan a ser mecánicas. Toda regla que puedas convertir en comprobación deja de depender de que el agente se acuerde.
05
Conflicto
Qué pasa
Cuando dos reglas chocan, algo tiene que decidir cuál gana. La mayoría de los arneses le dan la razón a la más específica —la de la carpeta por sobre la del repositorio— y ponen tu mensaje arriba de todo, pero ese orden es de ellos, no es una ley. Si una regla solo funciona cuando le gana a otra, decilo adentro de la regla.
Qué decidís vos
Resolver el choque en el archivo, no en el chat. Si tenés que aclararlo cada vez, la contradicción sigue viva.
06
Erosión
Qué pasa
Una regla que ya nadie cumple pero sigue escrita es peor que no tenerla: enseña que el archivo se puede ignorar, y a partir de ahí se ignora entero.
Qué decidís vos
Borrar lo que murió. Es la parte del mantenimiento que no la hace ninguna herramienta.
Señales de que te falta
Repetís la misma corrección de estilo en cada sesión.
Dos features parecidas quedaron resueltas de dos formas distintas.
Le explicás el mismo procedimiento cada vez que aparece esa tarea.
Le pediste “siempre hacé X” y a veces no lo hace.
Errores comunes al cubrirla
Escribir el archivo de instrucciones como prosa larga. Nadie lo lee y el agente lo diluye.
Meter todo en las instrucciones permanentes. Lo que aplica a una tarea puntual ocupa contexto en las otras mil.
Confiarle al prompt algo que es innegociable, en vez de a un comando determinista.
Ninguna es obligatoria. Lo obligatorio es cubrir la disciplina; estas son formas conocidas de hacerlo.
AGENTS.md
Estándar abierto, Agentic AI FoundationArchivo
Un archivo en el repositorio con las reglas del proyecto, que el agente carga solo al arrancar. Un formato abierto que leen un par de docenas de agentes, de Codex y Gemini CLI a Cursor, Copilot y Devin.
Problema, mecanismo y encaje
El dolor concreto
Repetir en cada conversación “usá pnpm”, “los tests van acá”, “no toques esa carpeta” es desperdicio puro, y se pierde cuando cambia el equipo.
Cómo funciona
El agente lee el archivo al iniciar y lo antepone al contexto. Los equivalentes propios de cada herramienta —CLAUDE.md en Claude Code, y otros— son adaptadores alrededor del mismo conocimiento del proyecto: el contenido es portable, mientras que el nombre del archivo, las reglas de carga y la precedencia entre varios son cosa del arnés. Es la cobertura más barata que existe y la más subestimada: cuesta una tarde y no depende de instalar nada.
Cuándo conviene
Siempre, y es lo primero que hay que hacer. El error típico es escribirlo como documentación para humanos: son órdenes ejecutables, cortas y sin ambigüedad.
Agent Skills
Anthropic, estándar abiertoPaquete
Procedimientos empaquetados como carpeta —instrucciones, scripts, recursos— que el agente carga solo cuando aparece la tarea que los necesita.
Problema, mecanismo y encaje
El dolor concreto
El agente resuelve la misma tarea distinto cada vez, y la forma correcta de hacerla en tu equipo no está en sus pesos.
Cómo funciona
Un directorio con un SKILL.md en la raíz: instrucciones, más una descripción de cuándo aplican, más los scripts y archivos que el procedimiento necesite. La carga es progresiva —el agente solo tiene el nombre y la descripción hasta que una tarea coincide, y ahí lee el resto—, así que lo que te cuesta una skill inactiva es su descripción, no su contenido.
Cuándo conviene
Cuando un procedimiento se repite y tiene una forma correcta. Es la diferencia entre pedir un resultado y enseñar un método.
También ayuda en
Skills for Real Engineers
Matt PocockPaquete
Control
Colección de procedimientos armada alrededor de las fallas concretas del desarrollo asistido.
Hooks
Patrón del ecosistemaPatrón
Control
Comandos deterministas que se ejecutan en momentos definidos, sin pasar por el modelo.
Claude Code
AnthropicArnés
Capacidad
Agente de terminal con permisos declarados, hooks, subagentes y skills; también en escritorio, web e IDE.
Codex CLI
OpenAIArnés
Capacidad
Agente de terminal de OpenAI, con soporte de procedimientos y servicios externos.
OpenSpec
Fission AIFlujo de trabajo
Método
Desarrollo guiado por especificación en archivos: lo que ya está acordado, separado de lo que se está proponiendo.
Gentle AI
Gentleman ProgrammingFlujo de trabajo
Método
Instalador reproducible de configuraciones, desarrollo por fases guiado por especificación, y revisión con presupuesto.
gstack
Garry TanFlujo de trabajo
Método
Más de veinte procedimientos que reparten roles de producto —producto, diseño, QA, release— sobre un ciclo de sprint.