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, cómo se escriben las referencias para que funcionen igual en las dos herramientas y qué forma la memoria del proyecto que AGENTS.md indexa: los cuatro documentos, ADR.md y el AGENTS.md de cada módulo.

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.

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:

• producto: para qué sirve el producto, qué valor aporta y sus capacidades principales.
• tecnologia: el stack, los frameworks, las decisiones técnicas y las restricciones del sistema completo.
• arquitectura: organización de directorios, patrones de arquitectura y convenciones de nombres.
• despliegue: cómo se despliega la aplicación, lo común a todos los entornos.

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.

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

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();
        }
    }
}

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.

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:

• Una frase con qué es el proyecto.
• Órdenes para compilar, probar y comprobar, si no son las habituales.
• Convenciones que se apartan de lo normal: las que el agente no adivinaría leyendo el código.
• Límites: lo que no se hace nunca y lo que se pregunta antes.
• El índice de skills, con cuándo leer cada una.

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.

# 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.

• AGENTS.md por carpeta: Claude Code y OpenCode lo cargan cuando el agente trabaja con ficheros de esa carpeta. Solo se crea si sus normas difieren de las de la raíz, y no puede contradecirla: cada herramienta los junta en un orden distinto, así que no está claro cuál gana.
• Lo que tiene que cumplirse siempre no va en AGENTS.md: ahí es una petición, no una garantía. Si de verdad no puede fallar, un test que lo compruebe, como el de la regla de ''CLAUDE.md''.

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

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.

AGENTS.md es el índice. Lo que indexa es la memoria del proyecto: todo lo que el agente necesita saber y no está en el código. Tiene tres piezas, y cada una responde a una pregunta distinta:

Son los de siempre; cc-sdd los llama steering y los genera con /kiro-steering en .kiro/steering/ (la memoria del proyecto en Kiro). En este curso van como las cuatro skills de la sección 1, que es lo mismo con otro nombre:

Los cuatro documentos dicen qué se hace, no por qué. Sin el porqué, el agente propone otra vez la alternativa que ya se descartó, o deshace una decisión sin saber que lo era. Las decisiones van en ADR.md (Architecture Decision Record): un único fichero en la raíz, entradas cortas, de la más reciente a la más antigua.

# Decisiones de arquitectura

## [2026-11-07] Los importes son BigDecimal
**Contexto:** los totales de los pedidos salían con céntimos de diferencia según el orden de las líneas.
**Decisión:** todos los importes son `BigDecimal` con escala 2 y redondeo `HALF_UP`.
**Alternativas descartadas:** `double`, por los errores de redondeo; `long` en céntimos, porque obliga a convertir en cada cálculo con porcentajes.
**Consecuencias:** ningún importe se declara `double`; el test de arquitectura `ImportesBigDecimalTest` lo comprueba.

## [2026-10-20] Un paquete por funcionalidad
**Contexto:** con un paquete por capa, cada cambio tocaba cinco carpetas.
**Decisión:** un paquete por funcionalidad (`pedidos`, `clientes`), con sus controladores, servicios y repositorios dentro.
**Alternativas descartadas:** paquetes por capa, por el motivo del contexto.
**Consecuencias:** un paquete no importa clases internas de otro: solo su fachada.

Cada entrada lleva contexto, decisión, alternativas descartadas y consecuencias: qué problema había, qué se eligió, qué se dejó fuera y por qué, y qué queda prohibido a partir de ahora. Nada más.

• Cuándo se escribe: al terminar el diseño de una funcionalidad, si se eligió entre varias opciones; y cada vez que el agente propone algo y se le dice que no por una razón que vale para el futuro.
• Cuándo lo lee el agente: antes de diseñar. En AGENTS.md va con las demás referencias: `ADR.md`: antes de tomar una decisión de diseño o de proponer un cambio de arquitectura.
• Un solo fichero hasta pasar de 20 o 30 entradas: así el agente lo lee de golpe y lo busca fácil. Una carpeta con un fichero por decisión solo compensa cuando ya no cabe.

Un proyecto grande se parte en módulos (carpetas, bundles, paquetes), y cada uno tiene normas que solo valen ahí. La tabla de la sección 2 ya lo dice: van en un AGENTS.md dentro de la carpeta del módulo, que Claude Code y OpenCode cargan cuando el agente trabaja con sus ficheros.

# Módulo: facturacion

**Responsabilidad:** emite las facturas de los pedidos entregados y lleva su numeración.
**Entidades propias:** `Factura`, `LineaFactura`, `SerieFactura`.
**Depende de:** `pedidos`, `clientes`. **Nadie importa desde aquí salvo:** `informes`.
**Convenciones locales:** la numeración es correlativa por serie y año; se asigna en `SerieFactura.siguiente()`, nunca en el servicio.
**Trampas conocidas:** una factura emitida no se modifica; para corregirla se emite una rectificativa (`FacturaRectificativa`).
**Decisiones relacionadas:** ADR.md, «Los importes son BigDecimal».

Tres cosas que cuidar:

• Solo lo específico del módulo: responsabilidad, entidades que posee, qué módulos puede usar y quién puede usarlo, convenciones locales y trampas conocidas. Si repite el stack o la arquitectura general, en dos semanas dice otra cosa que la memoria global.
• Corto: entre 30 y 80 líneas. Si crece más, está entrando documentación de usuario o explicación de código que ya se lee en el código.
• Se llama AGENTS.md, como el de la raíz, y por lo mismo: lo leen todas las herramientas. Y no puede contradecirlo (sección 2).

Con esto la jerarquía queda clara: los cuatro documentos dicen el qué y el cómo general, ADR.md dice el porqué y cada AGENTS.md de módulo dice lo local.

• AGENTS.md: el estándar, con ejemplos y la lista de herramientas que lo leen.
• AGENTS.md outperforms skills in our agent evals: la prueba de Vercel. Índice en AGENTS.md: 100 %; skill sola: 53 %; skill con instrucción explícita: 79 %. La skill no llegó a usarse en el 56 % de los casos.
• AGENTS.md vs Agent Skills evals: lectura crítica de la prueba de Vercel. Lo que decide es dónde está el aviso de cargar la documentación (siempre en contexto o a decisión del modelo), no el formato.
• Measuring Claude Code skill activation: otra medición. Sin ayuda, las skills se activan solas la mitad de las veces; cuando se activan, siempre es la correcta.
• A complete guide to AGENTS.md: AGENTS.md mínimo y el detalle en ficheros enlazados por tema; qué no meter en él.
• agents-md-best-practices: skill que parte un AGENTS.md grande en un índice y un fichero por tema.
• infrahub-sdk-python PR #609: caso real. Un CLAUDE.md de 317 líneas pasa a un AGENTS.md de 77 más un AGENTS.md por carpeta; después el repositorio añadió skills para sus procedimientos.
• Writing a good CLAUDE.md: por qué cada instrucción de más empeora el cumplimiento del resto, y la carpeta de documentos enlazada desde el índice.
• Evaluating AGENTS.md: estudio de ETH Zurich. Los ficheros de contexto encarecen más de un 20 % cada tarea y en general no mejoran el resultado; sí ayudan cuando cuentan prácticas no estándar del proyecto.
• Claude Code: memory: menos de 200 líneas; los procedimientos y lo que vale solo para una parte del código, a skills; @ruta no ahorra contexto porque carga el fichero al arrancar.
• Steering Claude Code: el fichero de instrucciones como índice que apunta a otros ficheros.
• OpenCode: rules: OpenCode no sigue solo las rutas que aparecen en AGENTS.md; hay que decirle cuándo leer cada fichero.