AGENTS.md

Qué escribir

Escribe las convenciones que necesitaría alguien que acaba de llegar al equipo: cómo se organiza el código, los nombres, qué utilidades y bibliotecas usar, y cómo se gestionan los errores y las pruebas.

• Omite lo que cualquier ingeniero con experiencia ya sabe, como “Escribe código legible”. HeyDeer y los agentes de programación ya siguen las prácticas habituales.
• Escribe una convención por viñeta, bajo unos pocos encabezados.
• Indica las rutas, funciones y bibliotecas a las que se refiere cada convención.
• Añade el motivo cuando no sea evidente, para que HeyDeer pueda valorar los casos que la convención no detalla.
• Deja en REVIEW.md o en las instrucciones de revisión las pautas que solo sirven para la revisión, como lo que HeyDeer no debe tocar. Si HeyDeer debe verificar un requisito en cada pull request al que se aplique, ponlo en una comprobación del repositorio.

AGENTS.md

# Conventions

## Structure

- API handlers live in src/api/, one file per resource.
- Background jobs live in src/jobs/ and are idempotent, because
  the queue can run a job twice.

## Helpers

- Retries use retry() from src/lib/retry.ts, which adds backoff.
- Read the current time through now() from src/lib/clock.ts, so
  tests can set it.

## Errors and tests

- Return client errors through AppError with a stable code, such
  as new AppError('INVOICE_NOT_FOUND', 404).
- Each new API handler has a test in tests/api/ that runs against
  a real database.

Archivos en la raíz y anidados

Añade AGENTS.md a la raíz del repositorio. Un directorio que necesite sus propias convenciones puede tener su propio archivo, como src/payments/AGENTS.md.

Para cada archivo que lee HeyDeer, se aplican los archivos AGENTS.md desde la raíz del repositorio hasta el directorio de ese archivo. Un archivo más profundo se suma a los superiores y prevalece cuando se contradicen.

src/payments/AGENTS.md

# Payments

- Every call to chargeCard() passes an idempotency key derived
  from the order ID, so a retried request can't charge twice.
- Amounts are integers in cents. Never use floating point for money.

HeyDeer lee estos archivos del pull request, así que un pull request que los modifica se revisa con su propia versión. Consulta Qué puede cambiar un pull request.

Usar CLAUDE.md

En un directorio sin AGENTS.md, HeyDeer lee CLAUDE.md en su lugar. Si un directorio tiene ambos, HeyDeer solo lee AGENTS.md.

Límites

• HeyDeer lee hasta 32 KiB de estos archivos, desde la raíz hasta el más profundo que se aplique. Un archivo que supera el límite se corta, y los archivos más profundos se omiten.
• HeyDeer no sigue las importaciones, como @docs/testing.md en CLAUDE.md. Escribe las convenciones en el propio archivo.