AGENTS.md con Claude Code

Estado actual

Claude Code usa CLAUDE.md como su archivo de instrucciones nativo. A febrero 2026, no lee AGENTS.md de forma nativa (hay un feature request abierto con 2,800+ votos).

Esto no impide usarlo. Hay 3 workarounds probados por la comunidad.

Workaround 1: File reference (recomendado)

Crea un CLAUDE.md que importa el contenido de AGENTS.md:

# CLAUDE.md

@AGENTS.md

La directiva @AGENTS.md le dice a Claude Code que cargue el contenido completo del archivo como contexto. Asi mantienes una unica fuente de verdad en AGENTS.md que funciona con todas las herramientas.

Agregar instrucciones especificas de Claude

Puedes combinar la referencia con instrucciones propias de Claude Code:

# CLAUDE.md

@AGENTS.md

## Claude-specific

### Skills disponibles
- /commit - Commits atomicos con mensajes descriptivos
- /review - Review de codigo

### Sub-agentes
Usar agente `Explore` para busquedas amplias en el codebase.
Usar agente `Plan` para disenar implementaciones.

### MCP Servers
- Playwright MCP para testing e2e
- Chrome DevTools para depuracion

Este es el bridge pattern: instrucciones universales en AGENTS.md + extensiones especificas en CLAUDE.md.

Workaround 2: Symlink

ln -s AGENTS.md CLAUDE.md

Simple y funcional en Linux y macOS. El problema: no puedes agregar instrucciones especificas de Claude. Si solo usas Claude Code, es suficiente. Si necesitas extensiones, usa el workaround 1.

Workaround 3: Hook de sesion

Para un enfoque mas automatizado, usa hooks de Claude Code:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/load-agents-md.sh"
          }
        ]
      }
    ]
  }
}

Script .claude/hooks/load-agents-md.sh:

#!/bin/bash
echo "=== AGENTS.md ==="
find "$CLAUDE_PROJECT_DIR" -name "AGENTS.md" -type f | while read -r file; do
  echo "--- $file ---"
  cat "$file"
done

Esto inyecta el contenido de todos los AGENTS.md al inicio de cada sesion.

El bridge pattern en detalle

La estrategia recomendada es usar ambos archivos con roles complementarios:

Archivo	Contenido
AGENTS.md	Instrucciones universales (comandos, stack, boundaries, estilo)
CLAUDE.md	Referencia a AGENTS.md + extensiones Claude (skills, MCP, sub-agentes)

proyecto/
├── AGENTS.md          # Fuente de verdad (funciona con todas las herramientas)
├── CLAUDE.md          # @AGENTS.md + extensiones Claude Code
├── .cursorrules       # Symlink a AGENTS.md (si usas Cursor)
└── src/

Ventajas

• Una fuente de verdad: cambias AGENTS.md y todas las herramientas lo reciben
• Extensibilidad: cada herramienta puede tener su archivo con extensiones propias
• Sin duplicacion: no mantienes el mismo contenido en 3 archivos

Diferencias entre CLAUDE.md y AGENTS.md

Caracteristica	AGENTS.md	CLAUDE.md
Compatibilidad	25+ herramientas	Solo Claude Code
Skills	No	Si (/commit, /review)
Sub-agentes	No	Si (Explore, Plan)
Config global	No	Si (~/.claude/CLAUDE.md)
MCP integration	No	Si
Jerarquico	Si (anidado en subdirectorios)	Si (proyecto + global)

Que poner en cada archivo

En AGENTS.md (universal)

• Descripcion del proyecto
• Comandos de build, test, lint
• Tech stack con versiones
• Estructura del proyecto
• Convenciones de codigo
• Boundaries (always/ask/never)
• Flujo de Git

En CLAUDE.md (solo Claude Code)

• @AGENTS.md (referencia)
• Skills disponibles
• Configuracion de sub-agentes
• MCP servers configurados
• Prioridades de Claude Code (seguridad, performance, etc.)
• Preferencias de comportamiento (idioma, formato de respuesta)

Ejemplo completo

AGENTS.md

Task management API. Hono 4 + TypeScript + SQLite.

## Commands
- Dev: `bun dev` (port 8787)
- Test: `bun test`
- Build: `bun run build`
- Lint: `bunx biome check src/`

## Architecture
- `src/domain/` - entities, value objects
- `src/routes/` - HTTP handlers
- `src/services/` - business logic

## Boundaries
### Never
- Never commit .env or .dev.vars
- Never use any as type
- Never skip failing tests

CLAUDE.md

@AGENTS.md

## Prioridades
1. Seguridad: validar inputs, no exponer secretos
2. Testing: todo codigo nuevo requiere tests
3. Mantenibilidad: funciones < 30 lineas, archivos < 150 lineas

## Idioma
Responder siempre en espanol. Codigo en ingles.

Resumen

• Claude Code no lee AGENTS.md nativamente (aun)
• Bridge pattern (recomendado): CLAUDE.md con @AGENTS.md + extensiones Claude
• Symlink: simple pero sin extensiones (ln -s AGENTS.md CLAUDE.md)
• Hook: automatiza la carga de AGENTS.md al inicio de sesion
• Instrucciones universales en AGENTS.md, extensiones de Claude en CLAUDE.md
• Una fuente de verdad, sin duplicacion

---

← Capitulo 6: Optimizacion de Tokens | Capitulo 8: AGENTS.md con OpenSpec →