El estándar AGENTS.md para agentes de código con IA

AGENTS.md es un documento operativo para agentes de código con IA. Le dice al agente cómo trabajar en este árbol: dónde está el mapa, qué comandos ejecutar, cómo este repo hace git, y qué debe hacer siempre, preguntar primero o no hacer nunca.

No es un segundo README. Un README presenta el proyecto a las personas. No es una guía de estilo. Los linters y el código ya poseen los estándares de programación.

El formato es Markdown simple. No hay esquema obligatorio, frontmatter YAML ni configuración JSON. El convenio abierto está en agents.md: el nombre de archivo es AGENTS.md, gana el archivo más cercano a los archivos que se editan, los comandos listados se ejecutan, y un mensaje en el chat anula siempre el archivo.

En diciembre de 2025 el formato se donó a la Agentic AI Foundation (AAIF), un directed fund bajo la Linux Foundation, junto al Model Context Protocol de Anthropic. Un archivo, muchos agentes.

Apunte a unas 200 líneas en la raíz. Eso alcanza para el mapa, las reglas de git y los límites. Es lo bastante corto para cargarlo en cada sesión.

Qué contiene el archivo

Cinco bloques. Conserve este orden.

Panorama — qué es este árbol, en unas pocas frases.

Mapa y dónde leer más — las carpetas que importan, y un puntero al índice del conocimiento duradero. Señale. No pegue la wiki.

Comandos — los comandos exactos de install, test y lint. Si lo escribe, el agente lo intentará.

Flujo de git — cómo este repo publica. Nombres de rama, si abrir un pull request o hacer push a main, el modo de los mensajes de commit. Git es específico del repo, a diferencia de los estándares de código.

Límites — Always do. Ask first. Never do.

Ejemplo: un AGENTS.md raíz

Un monorepo de facturación ficticio. Los nombres son ilustrativos. Conserve los bloques.

Raíz del repositorio — monorepo de facturación ficticio

# AGENTS.md

## Project overview
Billing platform monorepo: a Node API (`apps/api`), a React dashboard (`apps/web`), and shared libraries under `packages/`. Root rules apply unless a nested AGENTS.md says otherwise.

## Map
- `apps/api` — invoice and payment API
- `apps/web` — operator dashboard
- `packages/` — shared types and clients
- `infra/` — Terraform for staging and production
- Durable product knowledge: `docs/INDEX.md`. Open that map when you need a service, runbook, or decision.

## Commands
pnpm install
pnpm test
pnpm lint
pnpm --filter @acme/api test
docker compose up -d   # before API integration tests

## Git workflow
- Open a pull request against `main`. Do not push commits to `main`.
- Branch names: `feat/<short-name>` or `fix/<short-name>`
- Commit messages: imperative mood, complete sentences.

## Boundaries

### Always do
- Run `pnpm test` and `pnpm lint` before you consider a change done.
- Read `docs/INDEX.md` before inventing a service name or a runbook step.

### Ask first
- Changing auth, billing webhooks, or CI workflows.
- Adding a nested `AGENTS.md`.
- Touching `infra/` production modules.

### Never do
- Commit `.env`, API keys, or customer payment data.
- Invent an undocumented payment provider.

Archivos anidados

Gana el AGENTS.md más cercano a los archivos que se editan. Anidar es raro a propósito. La mayoría de los subdirectorios siguen el archivo raíz. No anide otra copia para cubrir carpetas.

Añada un archivo anidado solo cuando ese subárbol rompe de verdad una regla de la raíz. El archivo anidado es un delta. No reitera pnpm, git ni never-commit-secrets.

infra/AGENTS.md — un delta, no una segunda copia de la raíz

# AGENTS.md — infra/

Root git, pnpm, and Never-secrets still apply. This file is only the delta.

## Ask first
- `terraform plan` or `terraform apply` against staging.

## Never do
- Run `terraform apply` against the production workspace.
- Edit Terraform state by hand.

Qué dejar fuera

Estilo que un linter puede imponer. Póngalo en el linter.

El CONTRIBUTING.md humano, salvo las líneas de git que el agente ejecutará. Si esas líneas son reglas operativas, también pertenecen a AGENTS.md.

Si una herramienta todavía lee CLAUDE.md, haga que ese archivo apunte a AGENTS.md. No copie las reglas operativas.

El conocimiento duradero del producto — personas, servicios, decisiones — pertenece al mapa de conocimiento, no al archivo operativo. Véase Organizar conocimiento para agentes de IA.

Los procedimientos largos pertenecen a un documento o skill enlazado. Una línea en AGENTS.md basta: para X, lea Y. No haga de los skills el eje del archivo.

Manténgalo vivo

Cuando un agente repite un error, añada una línea de límite. Cuando una línea queda obsoleta, bórrela. El presupuesto de 200 líneas es cómo se nota la hinchazón.

Resumen

Escriba un AGENTS.md raíz de unas 200 líneas. Dele un mapa, reglas de git y Always / Ask first / Never. Anide otro archivo solo cuando un subdirectorio rompe de verdad esas reglas. El chat sigue anulando el archivo.

Dylan Engelbrecht actualiza este knowledge hub a medida que evoluciona la práctica con agentes. Trate estos artículos como referencia viva — práctica actual, no una instantánea congelada.