Mantenimiento de AGENTS.md

¿Qué hace Mantenimiento de AGENTS.md?

AGENTS.md es la documentación canónica orientada al agente. Mantenla al mínimo: los agentes son capaces y no necesitan ser guiados. Apunta a menos de 60 líneas; nunca superes las 100. La calidad de seguimiento de instrucciones disminuye a medida que aumenta la longitud del documento.

Cuándo Usar

• El usuario solicita crear, actualizar o auditar AGENTS.md o CLAUDE.md.
• El proyecto necesita instrucciones concisas y de alta señal para el agente, derivadas del toolchain real y la estructura del repositorio.
• La documentación de agente existente es demasiado larga, está duplicada o se aleja de las convenciones reales del proyecto.

Configuración del Archivo

1. Crea AGENTS.md en la raíz del proyecto
2. Crea un enlace simbólico: ln -s AGENTS.md CLAUDE.md

Antes de Escribir

Analiza el proyecto para entender qué debe incluirse en el archivo:

1. Gestor de paquetes — Busca archivos de bloqueo (pnpm-lock.yaml, yarn.lock, package-lock.json, uv.lock, poetry.lock)
2. Configuraciones de linter/formateador — Busca .eslintrc, biome.json, ruff.toml, .prettierrc, etc. (no los dupliques en AGENTS.md)
3. Comandos de CI/build — Revisa Makefile, scripts de package.json, configuraciones de CI para comandos canónicos
4. Indicadores de monorepo — Busca pnpm-workspace.yaml, nx.json, workspace de Cargo o archivos package.json en subdirectorios
5. Convenciones existentes — Revisa si existe CONTRIBUTING.md, docs/ o patrones en README

Reglas de Escritura

• Cabeceras + viñetas — Sin párrafos
• Bloques de código — Para comandos y plantillas
• Referencia, no incrustes — Apunta a la documentación existente: "Consulta CONTRIBUTING.md para la configuración" o "Sigue los patrones en src/api/routes/"
• Sin relleno — Sin introducciones, conclusiones ni cortesías
• Confía en las capacidades — Omite el contexto obvio
• Prefiere comandos por archivo — Comandos de test/lint/typecheck por archivo en lugar de builds completos del proyecto
• No dupliques linters — El estilo de código reside en las configuraciones de linter, no en AGENTS.md

Secciones Obligatorias

Gestor de Paquetes

Solo la herramienta y los comandos clave:

## Gestor de Paquetes
Usa **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`

Comandos por Archivo

Los comandos por archivo son más rápidos y económicos que los builds completos del proyecto. Inclúyelos siempre que estén disponibles:

## Comandos por Archivo
| Tarea | Comando |
|-------|---------|
| Typecheck | `pnpm tsc --noEmit ruta/al/archivo.ts` |
| Lint | `pnpm eslint ruta/al/archivo.ts` |
| Test | `pnpm jest ruta/al/archivo.test.ts` |

Atribución de Commits

Incluye siempre esta sección. Los agentes deben usar su propia identidad:

## Atribución de Commits
Los commits de IA DEBEN incluir:

Co-Authored-By: (nombre del modelo de agente y línea de atribución)

Ejemplo: `Co-Authored-By: Claude Sonnet 4 <[email protected]>`

Convenciones Clave

Patrones específicos del proyecto que los agentes deben seguir. Mantenlo breve.

Secciones Opcionales

Agrega solo si es realmente necesario:

• Patrones de rutas API (muestra la plantilla, no la explicación)
• Comandos CLI (en formato tabla)
• Convenciones de nombres de archivos
• Pistas sobre la estructura del proyecto (señala archivos críticos, marca código heredado que evitar)
• Anulaciones de monorepo (los archivos AGENTS.md en subdirectorios anulan la raíz)

Antipatrones

Omite estos:

• "Bienvenido a..." o "Este documento explica..."
• "Deberías..." o "Recuerda..."
• Reglas de linter/formateador ya presentes en archivos de configuración (.eslintrc, biome.json, ruff.toml)
• Listar habilidades o plugins instalados (los agentes los descubren automáticamente)
• Comandos completos de build del proyecto cuando existan alternativas por archivo
• Instrucciones obvias ("ejecuta pruebas", "escribe código limpio")
• Explicaciones del porqué (solo di qué hacer)
• Párrafos largos de prosa

Estructura de Ejemplo

# Instrucciones del Agente

## Gestor de Paquetes
Usa **pnpm**: `pnpm install`, `pnpm dev`

## Atribución de Commits
Los commits de IA DEBEN incluir:

Co-Authored-By: (nombre del modelo de agente y línea de atribución)

## Comandos por Archivo
| Tarea | Comando |
|-------|---------|
| Typecheck | `pnpm tsc --noEmit ruta/al/archivo.ts` |
| Lint | `pnpm eslint ruta/al/archivo.ts` |
| Test | `pnpm jest ruta/al/archivo.test.ts` |

## Rutas API
[Bloque de código de plantilla]

## CLI
| Comando | Descripción |
|---------|-------------|
| `pnpm cli sync` | Sincronizar datos |

Limitaciones

• Usa esta habilidad solo cuando la tarea coincida claramente con el ámbito descrito anteriormente.
• No trates el resultado como un sustituto de validación específica del entorno, pruebas o revisión experta.
• Detente y pide aclaraciones si faltan entradas requeridas, permisos, límites de seguridad o criterios de éxito.