Tabla de Contenidos

7. AGENTS.md

Qué es AGENTS.md en dos líneas está en Conceptos básicos, y cómo se genera el primero, en OpenCode y Claude Code. Aquí, qué entra en él, dónde va todo lo demás y cómo se escriben las referencias para que funcionen igual en las dos herramientas.

1. Qué es AGENTS.md

AGENTS.md es un markdown en la raíz del repositorio con las instrucciones fijas del proyecto: lo que le contarías a un compañero nuevo el primer día. Se carga entero en todas las sesiones, encaje o no con la tarea. Es un estándar abierto: el mismo fichero lo leen Claude Code, OpenCode, Codex, Cursor, Copilot o Gemini CLI.

Pequeño: el detalle va en skills

Como se paga en cada petición, AGENTS.md tiene que ser pequeño: solo lo imprescindible y un índice. El detalle se reparte en skills, una por tema, y el agente carga solo la que necesita para la tarea. 

AGENTS.md
.opencode
└── skills
    ├── producto
    │   └── SKILL.md
    ├── tecnologia
    │   └── SKILL.md
    ├── arquitectura
    │   ├── SKILL.md
    │   ├── cliente.md
    │   └── servidor.md
    └── despliegue
        ├── SKILL.md
        ├── desarrollo.md
        └── produccion.md

Las que tiene que haber como mínimo:

Si hay varias arquitecturas, el SKILL.md se queda con lo común y cada una va en un fichero de apoyo dentro de la skill: cliente.md, servidor.md, movil.md. Con el despliegue igual: desarrollo.md y produccion.md con lo propio de cada entorno. 

---
name: arquitectura
description: Carpetas, patrones y nombres del proyecto. Usar antes de crear
  cualquier clase o fichero.
---

# Arquitectura

- Un paquete por funcionalidad (`pedidos`, `clientes`), no por capa.
- Los controladores solo validan y delegan: la lógica va en los servicios.

Lee además `servidor.md` si tocas `servidor/` y `cliente.md` si tocas `cliente/`.

AGENTS.md dice cuándo usar cada una: 

# Pedidos

API REST de pedidos con cliente web. Compilar y probar: `./mvnw verify`.

## Skills del proyecto

Antes de empezar, lee la skill que necesite la tarea:

- `.claude/skills/producto/SKILL.md`: antes de escribir o revisar una especificación.
- `.claude/skills/tecnologia/SKILL.md`: antes de añadir una dependencia.
- `.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero.
- `.claude/skills/despliegue/SKILL.md`: antes de tocar el despliegue.

La skill sola no basta. El agente la carga solo si decide que encaja con la tarea, y muchas veces no lo decide: en las pruebas de Vercel no llegó a usarse en más de la mitad de los casos. El índice de AGENTS.md está siempre en contexto, así que convierte esa decisión en una instrucción. Y como da la ruta del fichero, funciona también en un agente que no sepa de skills.

Cómo generar un primer AGENTS.md con /init y cómo mantenerlo: /init en OpenCode.

CLAUDE.md: no usarlo

Existe también CLAUDE.md, el fichero propio de Claude Code. No lo uses: si en una carpeta hay CLAUDE.md, Claude Code lee solo ese y deja de leer el AGENTS.md de esa misma carpeta, sin avisar. El equipo que usa otra herramienta ve unas normas y el que usa Claude Code ve otras.

Como basta con que alguien cree un CLAUDE.md para que el AGENTS.md deje de valer, se añade una regla de arquitectura que lo impida: un test que falla si aparece alguno en el repositorio. 

class SinClaudeMdTest {

    @Test
    void noHayNingunClaudeMd() throws IOException {
        try (Stream<Path> ficheros = Files.walk(Path.of("."))) {
            List<Path> claudeMd = ficheros
                    .filter(f -> !f.startsWith("./target") && !f.startsWith("./.git"))
                    .filter(f -> f.getFileName().toString().equalsIgnoreCase("CLAUDE.md"))
                    .toList();

            assertThat(claudeMd)
                    .as("Las instrucciones van en AGENTS.md, no en CLAUDE.md")
                    .isEmpty();
        }
    }
}

2. Cómo se organiza AGENTS.md

La sección 1 dice que AGENTS.md es un índice pequeño. Aquí va qué entra en él, dónde va todo lo demás y cómo se escriben las referencias para que funcionen igual en Claude Code y en OpenCode.

Qué entra

El agente obedece lo que pone el fichero: en el estudio de ETH Zurich, cuando AGENTS.md nombra una herramienta, el agente la usa en casi todas las tareas, y si no la nombra, casi nunca. Pero el fichero encarece cada tarea más de un 20 %, y solo mejora el resultado cuando cuenta lo que no es estándar. Así que entra solo lo que vale para todas las tareas y no se deduce del código:

Fuera: la descripción general del proyecto, el árbol de carpetas, la lista de dependencias y las reglas de estilo. Las tres primeras el agente las saca del propio código, y en el estudio no le ayudaron a encontrar antes los ficheros que tenía que tocar. El estilo lo impone el formateador, no un párrafo.

No dejes tal cual el AGENTS.md que genera /init. Mete justo lo que sobra: descripción, arquitectura y dependencias. Los ficheros generados por el modelo salen peor que los escritos a mano. Úsalo de borrador y recorta. 

# Pedidos

API REST de pedidos con cliente web.

## Órdenes
- Compilar y probar: `./mvnw verify`
- Solo los tests del servidor: `./mvnw -pl servidor test`

## Convenciones
- Los importes son `BigDecimal` con escala 2; nunca `double`.
- Los errores de negocio heredan de `ErrorDeNegocio`; los controladores no lanzan `RuntimeException`.
- Cada requisito de `specs/` tiene al menos un test que cita su identificador (`R-12`).

## Límites
- No modifiques una migración ya aplicada: crea una nueva.
- Pregunta antes de añadir una dependencia o de cambiar un requisito de `specs/`.

## Skills del proyecto
Explora primero el código que toca la tarea. Después lee la skill que necesite:
- `.claude/skills/producto/SKILL.md`: antes de escribir o revisar una especificación.
- `.claude/skills/tecnologia/SKILL.md`: antes de añadir una dependencia.
- `.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero.
- `.claude/skills/despliegue/SKILL.md`: antes de tocar el despliegue.

Cabe en una pantalla, y así tiene que seguir: menos de 200 líneas, mejor menos de 60. Cada instrucción de más hace que el modelo cumpla peor todas las demás, no solo la nueva.

Dónde va lo demás

Qué es Dónde va Ejemplo
Lo que vale en todas las tareas AGENTS.md raíz «Los importes son BigDecimal»
Lo que vale solo en una carpeta AGENTS.md de esa carpeta servidor/src/test/AGENTS.md: «los tests de integración crean los pedidos con PedidoFactory; no se mockea el repositorio»
El detalle que solo hace falta en algunas tareas Una skill arquitectura, despliegue
Un procedimiento que se lanza para una tarea concreta Una skill revisar-pr
Lo que tiene que cumplirse siempre Un test, el linter o un hook SinClaudeMdTest, el formateador

Cómo se escriben las referencias

Cada referencia lleva la ruta entre comillas invertidas y cuándo leerla. Nunca con @:

Referencia Claude Code OpenCode
`.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero. La lee cuando la tarea lo pide La lee cuando la tarea lo pide
@.claude/skills/arquitectura/SKILL.md La carga entera al arrancar, en todas las sesiones No la entiende: es texto
Ver la skill de arquitectura. No sabe cuándo leerla No sabe cuándo leerla
El @ anula el índice. En Claude Code, @ruta importa el fichero al arrancar, así que un índice escrito con @ carga todas las skills en cada sesión: lo mismo que meterlas en AGENTS.md. El ejemplo de la documentación de OpenCode usa @ y en Claude Code hace justo eso.

La condición se escribe con las palabras con las que se pedirá la tarea («antes de escribir o revisar una especificación»), sin «MUST» ni mayúsculas. En la prueba de Vercel, «explora primero el proyecto y luego usa la skill» acertó más que «debes usar la skill»: con la orden tajante, el agente leía la documentación primero, seguía sus ejemplos sin mirar el proyecto y se dejaba cambios.

Lo mismo vale para la description de cada skill (el frontmatter): las skills se activan casi por palabra clave. En la medición de Scott Spence, con la palabra en el prompt se activaban casi siempre; con una forma genérica de pedirlo, entre un 20 y un 40 % de las veces.

Fuentes