AGENTS.md

En el Radar compartido: Trial (valoración de la edición aportada).

Cómo funciona

Funciona como punto de entrada al contexto del proyecto. Describe estructura, comandos y convenciones, enlazando documentación extensa cuando hace falta.

Ejemplo de uso

Un archivo raíz puede indicar: «Ejecuta npm run check antes de terminar; modifica las fuentes, no dist/; consulta docs/arquitectura.md para cambios de dominio». Las reglas específicas pueden vivir cerca del código si el cliente admite esa jerarquía.

## Comprobaciones

- Ejecuta `npm run check` antes de terminar.
- Consulta `docs/arquitectura.md` para cambios de dominio.
- Modifica las fuentes; `dist/` es una salida generada.

Plantilla completa

# AGENTS.md

## Proyecto

API de originación de créditos (Java 21, Spring Boot, PostgreSQL, Kafka).
Arquitectura hexagonal: `dominio/` no depende de `infraestructura/` (lo comprueba ArchUnit).

## Comandos

- Compilar y probar: `./mvnw -q verify`
- Solo un módulo: `./mvnw -q test -pl solicitudes`
- Levantar dependencias locales: `docker compose up -d postgres kafka`

## Convenciones

- Importes con `Dinero` (BigDecimal + moneda); nunca `double`.
- Endpoints que crean recursos exigen `Idempotency-Key`.
- Eventos con transactional outbox; no publiques en Kafka dentro del caso de uso.

## No tocar

- `db/migrations/` ya aplicadas: crea una nueva.
- Código generado en `target/` y clientes en `generated/`.

## Antes de terminar

- `./mvnw -q verify` en verde.
- Si cambias un contrato público (OpenAPI o evento), actualiza `docs/contratos/` y avisa en el resumen.

## Más contexto

- Decisiones: `docs/adr/README.md`
- Despliegue: `docs/despliegue.md`

Jerarquía

Los agentes compatibles leen el AGENTS.md más cercano al archivo en el que trabajan, además del raíz. En un monorepo:

AGENTS.md                    # reglas comunes
services/pagos/AGENTS.md     # reglas específicas de pagos
apps/web/AGENTS.md           # convenciones del frontend

Ante conflicto, prevalece el más cercano; las instrucciones explícitas del usuario en la conversación prevalecen sobre ambos.

Por qué un estándar

Antes de AGENTS.md cada herramienta tenía su archivo, y los repositorios acumulaban copias que se contradecían. Un formato común, leído por Codex, Cursor, GitHub Copilot, Gemini CLI, Jules, Aider y otros, permite mantener una sola fuente. Para herramientas con formato propio, ver instrucciones compartidas.

Buenas prácticas

• Breve y concreto: lo que una persona nueva necesitaría saber el primer día para no romper nada.
• Comandos copiables y probados (un job de CI puede ejecutarlos para detectar que han dejado de funcionar).
• Enlaces a documentación detallada en lugar de copiarla.
• Revisión en pull request y responsable explícito.
• Recuerda que el contenido llega al contexto del modelo: no incluyas nada que no deba salir del repositorio.

Criterios de implementación

Comprobar los comandos en CI, asignar responsables y retirar instrucciones obsoletas. No incluir secretos: el archivo aporta orientación, no impone aislamiento ni permisos.