Tu Primer AGENTS.md

El minimo viable

Un AGENTS.md efectivo no necesita ser largo. Empieza con lo esencial:

# AGENTS.md

This is a React component library for accessible data visualization.
Uses pnpm workspaces. TypeScript strict mode.

## Commands

- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`

## Code style

- Use functional components with TypeScript
- Tests alongside source: `component.test.tsx`
- Prefer named exports over default exports

Eso es todo. 15 lineas que le ahorran al agente minutos de exploracion y errores de suposicion.

Paso a paso

1. Crear el archivo

touch AGENTS.md

Ubicalo en la raiz del repositorio, al mismo nivel que package.json o Cargo.toml.

2. Descripcion del proyecto (1-2 oraciones)

Esta es la linea mas importante. Ancla todas las decisiones del agente:

E-commerce API built with Express 5, TypeScript, and PostgreSQL.
Follows hexagonal architecture with domain, application, and infrastructure layers.

Mal ejemplo (demasiado vago):

A web project.

3. Comandos ejecutables

Los agentes necesitan comandos con flags exactos, no solo nombres de herramientas:

## Commands

- Install: `bun install`
- Dev: `bun dev` (port 3000)
- Build: `bun run build`
- Test all: `bun test`
- Test single file: `bun test path/to/file.test.ts`
- Lint: `bunx biome check src/`
- Lint fix: `bunx biome check --write src/`
- Type check: `bunx tsc --noEmit`

Tip: incluye comandos por archivo, no solo del proyecto completo. Los agentes trabajan con archivos individuales y ejecutar bun test completo cuando solo cambiaste un archivo es desperdicio.

4. Tech stack con versiones

## Tech stack

- Runtime: Node.js 22
- Language: TypeScript 5.7 (strict)
- Framework: Hono 4
- Database: PostgreSQL 17, Drizzle ORM
- Testing: Vitest 3
- Linting: Biome 2
- Package manager: bun

No digas “React project”. Di “React 19 con TypeScript, Vite 6 y Tailwind CSS 4”.

5. Commitear

git add AGENTS.md
git commit -m "feat: agregar AGENTS.md con instrucciones para agentes IA"

AGENTS.md es parte del codigo. Se versiona, se revisa en PRs y se actualiza cuando cambian las convenciones.

Verificar que funciona

Con cualquier agente

Pide al agente que resuma las instrucciones que tiene:

Resume las instrucciones de AGENTS.md que estas siguiendo

Si el agente las conoce, veras tu contenido reflejado. Si no, el agente no esta leyendo el archivo (revisa la ubicacion).

Con Codex

codex --ask-for-approval never "Summarize current instructions"

Con Claude Code

Claude Code lee CLAUDE.md nativamente. Para que lea AGENTS.md, necesitas el bridge pattern (cubierto en el Capitulo 7).

Estructura recomendada del archivo

AGENTS.md
├── Descripcion (1-2 oraciones)
├── Commands (build, test, lint, dev)
├── Tech stack (con versiones)
├── Project structure (directorios clave)
├── Code style (convenciones, ejemplos)
└── Boundaries (que no tocar)

Cada seccion se cubre en profundidad en el Capitulo 3.

Errores comunes al empezar

Error	Por que falla	Correccion
Archivo vacio	El agente lo ignora	Minimo: descripcion + comandos
Solo nombres de herramientas (“Vitest”)	El agente no sabe los flags	Incluir comando completo: bunx vitest run
Instrucciones vagas (“escribe buen codigo”)	No es accionable	Ser especifico: “funciones < 30 lineas”
Copiar el README completo	Ruido, desperdicio de tokens	Incluir solo lo relevante para agentes

Resumen

• Empieza minimo: descripcion + comandos + stack es suficiente
• Ubicalo en la raiz del repo, al mismo nivel que package.json
• Incluye comandos con flags exactos, no solo nombres de herramientas
• Especifica versiones del tech stack
• Commitealo: es parte del codigo y se versiona con el proyecto

---

← Capitulo 1: Introduccion | Capitulo 3: Secciones Esenciales →