AGENTS.md y CLAUDE.md: Cómo escribir un archivo de configuración que tu agente realmente utilice

Escribir un buen archivo de configuración es la acción de mayor apalancamiento y menor esfuerzo en el desarrollo agéntico. Estableces el contexto una vez y todas las sesiones se benefician: el agente deja de adivinar tu comando de tests, deja de reformatear según sus propios defaults y deja de editar el directorio que le indicaste como fuera de límites. Esta página es la técnica concreta detrás de la habilidad de "context & configuration" AI-Native — una de las 17 habilidades AI-native que evaluamos a lo largo de los niveles. Mantener memoria durable del proyecto en CLAUDE.md / AGENTS.md es una señal definitoria de un Desarrollador Agéntico de Nivel 3, así que vale la pena hacerlo bien.

La idea central es la misma en todas las herramientas, aunque los mecanismos difieran: un archivo de configuración transporta lo que un agente no puede inferir del código en sí. El modelo ya conoce tu lenguaje. No sabe que tus tests necesitan un flag específico, que migraste fuera de una librería hace tres meses, o que infra/ es código generado que nunca debe editarse a mano. Esa brecha es lo que el archivo rellena.

El panorama: una filosofía, muchos archivos

Cada agente importante lee un archivo de contexto de proyecto. Comparten la filosofía y difieren en nombre de archivo y mecánica de carga. Este es el mapa para 2026:

File	Tool(s)	Status
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 tools	Estándar abierto entre herramientas
CLAUDE.md	Claude Code	Formato nativo de Claude Code
GEMINI.md	Gemini CLI	Formato nativo de Gemini
.github/copilot-instructions.md	GitHub Copilot	Instrucciones de repositorio de Copilot
.cursor/rules (antes .cursorrules)	Cursor	Formato de reglas de Cursor

La conclusión: AGENTS.md es el estándar emergente de fuente única de verdad — una especificación abierta que ya leen ~20 herramientas. La advertencia es que Claude Code no lee AGENTS.md de forma nativa; solo lee CLAUDE.md. Por eso el patrón canónico de fuente única es mantener AGENTS.md como referencia y conectar con Claude mediante un CLAUDE.md mínimo que lo importe:

@AGENTS.md

<!-- Claude-specific notes can go below -->

Un symlink también funciona (ln -s AGENTS.md CLAUDE.md), pero en Windows es preferible el @import — los symlinks allí requieren permisos de administrador. Así mantienes un solo archivo y ambos ecosistemas lo leen.

Qué poner realmente dentro

El análisis de GitHub sobre más de 2.500 repositorios ("How to write a great AGENTS.md") encontró que las configuraciones que realmente ayudan a los agentes comparten seis secciones. En orden aproximado de prioridad:

1. Commands — colocados al principio, con comandos ejecutables exactos y sus flags (npm test, npm run build, pytest -v), no solo nombres de herramientas. Esta es la sección de mayor ROI: los agentes ya saben que pytest existe; no conocen los flags requeridos de tu proyecto. Ponla cerca del inicio.
2. Testing practices — cómo testeas, qué ejecutar antes de hacer commit, expectativas de cobertura.
3. Project structure — dónde viven las cosas, para que el agente deje de buscarlas a ciegas.
4. Code style — muestra un fragmento de código real, no tres párrafos de prosa.
5. Git workflow — nombrado de ramas, convenciones de commits, reglas de PR.
6. Boundaries — lo que el agente nunca debe tocar (directorios generados, secretos, código vendorizado, migraciones).

Observa el orden de apalancamiento. "Commands with flags" es el primero por una razón: es lo que el modelo más consistentemente no puede adivinar y con más frecuencia falla. Si solo escribes bien una cosa, que sea esa.

Incluir / excluir: el test línea por línea

Los docs de memoria de Anthropic trazan una línea explícita de dos columnas. Úsala como filtro para cada línea que estés tentado de añadir.

Include	Exclude
Comandos Bash que el agente no puede adivinar	Todo lo que se puede inferir del código
Reglas de estilo que difieren de los defaults	Convenciones estándar del lenguaje que el modelo ya conoce
Instrucciones de testing / runner de tests preferido	Docs de API detalladas (enlaza en su lugar)
Etiqueta del repositorio (nombrado de ramas, convenciones de PR)	Información que cambia frecuentemente
Decisiones arquitectónicas específicas del proyecto	Explicaciones largas y tutoriales
Particularidades del entorno de desarrollo (variables de entorno requeridas)	Descripciones archivo por archivo del código base
Gotchas no obvios	Prácticas evidentes como "escribe código limpio"

Hay un test que colapsa toda la tabla en un hábito:

El test por línea: "¿Eliminar esta línea causaría que el agente cometiera errores? Si no, elimínala."

Aplica ese test a cada línea. "Usa TypeScript" — el agente puede ver los archivos .ts; elimínala. "Ejecuta las migraciones de base de datos con npm run db:migrate, nunca edites migrations/ a mano" — no podría haberlo adivinado, y equivocarse corrompe el estado; consérvala.

Escribe al nivel de altitud correcto

La guía de ingeniería de contexto de Anthropic destila una buena autoría en cuatro principios.

1. Especificidad / verificabilidad. Escribe reglas lo suficientemente concretas para contrastarlas con la salida del agente. Las guías vagas no pueden verificarse, por lo que no pueden seguirse de forma confiable.

• "Usa 2 espacios de indentación" — no "Formatea el código correctamente."
• "Ejecuta npm test antes de hacer commit" — no "Testea tus cambios."
• "Los handlers de API viven en src/api/handlers/" — no "Mantén los archivos organizados."

2. Altitud correcta. Apunta entre la lógica rígidamente codificada y las instrucciones vagas: "lo suficientemente específico para guiar el comportamiento, lo suficientemente flexible para ser una heurística sólida." Demasiado rígido y se rompe en el primer caso borde; demasiado vago y no guía nada.

3. Mínimo pero suficiente. Mínimo no significa corto. Significa dar suficiente contexto por adelantado para que el agente no tenga que adivinar ni redescubrir — y nada más allá de eso. Elimina el relleno, conserva el detalle que soporta el peso.

4. Estructura. Usa secciones etiquetadas — encabezados Markdown o etiquetas XML. Un archivo escaneable es un archivo que el agente (y tus compañeros de equipo) realmente analizan.

Mantén la ligereza

La razón real para mantenerse ligero es el presupuesto de tokens. El archivo de configuración se carga completo en cada sesión. No se recupera bajo demanda; se antepone al contexto al inicio. Por tanto, el exceso de contenido tiene un costo directo y medible: un CLAUDE.md inflado reduce de forma medible la adherencia a las instrucciones. El propio enunciado de Anthropic es contundente — los archivos CLAUDE.md inflados hacen que Claude ignore tus instrucciones reales. Cada línea basura que añades debilita tus buenas líneas.

Los objetivos son concretos:

• Anthropic apunta a menos de ~200 líneas como meta orientativa para CLAUDE.md.
• Codex impone un límite estricto de 32 KiB en AGENTS.md (project_doc_max_bytes); los archivos sobredimensionados se truncan, por lo que cualquier contenido más allá del límite silenciosamente no carga.

Y una trampa que vale la pena nombrar: los imports no ahorran presupuesto. Un archivo @imported sigue cargando en el contexto al inicio — has dividido el archivo, no reducido la huella. Para reducir realmente lo que carga en cada sesión, externaliza el contenido relevante condicionalmente:

• Path-scoped rules para aspectos transversales que afectan muchos archivos — solo cargan cuando el agente trabaja en esa ruta.
• Skills para procedimientos bajo demanda — solo cargan cuando se invocan.
• Links para material de referencia largo o detallado — apunta a él en lugar de incrustarlo.

El principio es el mismo que el test por línea aplica, pero a nivel de sección: si solo es relevante a veces, no debería estar en el archivo que siempre carga.

DESIGN.md: una convención de equipo, no un estándar

Un DESIGN.md es la aplicación de libro de texto de "mantén la configuración ligera, enlaza el detalle." Es un documento separado de diseño/arquitectura — las decisiones clave, el modelo de dominio, los patrones arquitectónicos, el por qué está construido así — que tu AGENTS.md @imports o referencia en lugar de incrustar. Eso mantiene la configuración que siempre carga corta mientras el contexto profundo queda a un salto de distancia.

Sé honesto sobre su estatus, sin embargo: a diferencia de AGENTS.md y CLAUDE.md, no existe ninguna fuente primaria que establezca DESIGN.md como un archivo de configuración de agente estándar. Es una potente convención de equipo, no un estándar documentado. Úsalo porque funciona para tu equipo, no porque una especificación lo exija.

Alcance y jerarquía

Ambos ecosistemas apilan archivos de lo general a lo específico, pero resuelven la precedencia de forma diferente.

CLAUDE.md tiene cuatro alcances, cargando de general a específico:

1. Managed policy — establecida por tu organización / IT, aplica a toda la organización.
2. User — ~/.claude/CLAUDE.md, aplica a todos tus proyectos.
3. Project — ./CLAUDE.md, incluido en git y compartido con el equipo.
4. Local — ./CLAUDE.local.md, en gitignore, para tus anulaciones personales.

En monorepos, los archivos del directorio padre se cargan automáticamente y los del directorio hijo bajo demanda. Los imports usan la sintaxis @path/to/file (relativa o absoluta), anidan hasta 4 niveles de profundidad, y el parser omite los bloques de código para que una ruta dentro de un bloque delimitado no se trate como import.

AGENTS.md resuelve ganando el más cercano. Codex recorre desde la raíz de Git hacia abajo hasta tu directorio de trabajo actual y concatena los archivos que encuentra, primero la raíz. Como los archivos más cercanos aparecen después, prevalecen — gana el archivo más cercano. En un monorepo mantienes un AGENTS.md por paquete, y el más cercano al código que se está editando tiene precedencia. Por encima de todo: una instrucción explícita en el chat invalida todos los archivos.

Y el puente entre herramientas de antes une los dos sistemas: mantén AGENTS.md como referencia canónica, añade un CLAUDE.md que haga @AGENTS.md, y tu jerarquía se comparte entre herramientas sin duplicación.

Orientativo, no vinculante

Aquí está el matiz que te salva de una falsa sensación de seguridad: estos archivos son contexto orientativo, no cumplimiento determinista. Guían al agente; no lo vinculan.

Las palabras de énfasis como IMPORTANT y YOU MUST mejoran de forma medible la adherencia — pero no la garantizan. Para requisitos que deben ocurrir cada vez (ejecutar el formateador, bloquear un commit que falla los tests, nunca escribir en main), el respaldo determinista son los hooks (en Claude Code), no un texto más enfático en la configuración.

La regla general: usa la configuración para guías y heurísticas; recurre a los hooks en el momento en que "el agente generalmente hace esto" no es suficiente y necesitas "el agente siempre hace esto."

Mantenlo como código

Un archivo de configuración es un artefacto vivo, no una escritura única. Trátalo como el resto del repositorio.

• Arranca con /init. Deja que la herramienta genere un primer borrador desde tu base de código, luego refínalo a mano — la versión generada es un punto de partida, no el archivo final.
• Revísalo cuando las cosas vayan mal. Cada vez que el agente haga algo torpe, pregúntate si una línea faltante o engañosa en la configuración lo causó.
• Poda regularmente. Vuelve a aplicar el test por línea a todo el archivo. Las líneas que eran esenciales el trimestre pasado pueden ser peso muerto ahora.
• Prueba los cambios por comportamiento. No confíes en que una edición ayudó — observa si el comportamiento del agente realmente cambió. Si no puedes ver la diferencia, la línea probablemente no está haciendo trabajo.
• Inclúyelo en git. Una configuración compartida y versionada significa que todo el equipo contribuye y se beneficia, y los cambios aparecen en revisión.

El hábito más valioso es el bucle de auto-mejora: cuando el agente comete un error, añade una sola regla de una línea para que no se repita. En pocas semanas ese bucle converge tu configuración exactamente en los gotchas que tu proyecto realmente tiene — nada más, nada menos.

Un AGENTS.md inicial

Aquí tienes un esqueleto real, listo para copiar y pegar, con las seis secciones de alto ROI rellenas con placeholders realistas. Sustituye con tus especificaciones y elimina todo lo que no supere el test por línea.

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

Para una fuente única de verdad entre herramientas, coloca un `CLAUDE.md` de una línea junto a él con `@AGENTS.md`, y enlaza tus notas de arquitectura más profundas (un `DESIGN.md`, tus ADRs) en lugar de pegarlas.

## Por dónde seguir

Un archivo de configuración ligero y específico es uno de los comportamientos concretos que separa a los desarrolladores asistidos por IA de los genuinamente AI-native. [Encuentra tu nivel AI-native](/quiz) en tres minutos — evalúa exactamente este tipo de oficio — y cuando estés listo para conectar tu cadena de herramientas, empieza desde [el stack recomendado de ProCoders](/stack).