agents-md-starter

¿Qué hace agents-md-starter?

Salida: AGENTS.md en la raíz del repositorio como fuente de verdad única, más CLAUDE.md que contiene @AGENTS.md (Claude Code lee CLAUDE.md y soporta importaciones con @path). Cada comando en el archivo debe haberse ejecutado exitosamente o estar claramente marcado como no verificado.

Paso 1 — Escanear

python3 scripts/scan_repo.py /ruta/al/repositorio            # resumen legible
python3 scripts/scan_repo.py /ruta/al/repositorio --json     # datos como JSON
python3 scripts/scan_repo.py /ruta/al/repositorio --draft > AGENTS.draft.md   # plantilla rellenada

Detecta: lenguajes por conteo de archivos, gestor de paquetes desde archivos de bloqueo, scripts en package.json, objetivos de Makefile, herramientas en pyproject.toml (pytest, ruff, mypy, uv/poetry), archivos de construcción de Go/Rust/Java, frameworks (Next.js, Astro, Vite, Django, FastAPI, Rails...), espacios de trabajo monorepo, flujos de CI, archivos de ejemplo de entorno, y archivos de reglas de agente existentes. Nunca ejecuta código del repositorio.

Paso 2 — Leer antes de escribir

• Lee cada archivo de reglas existente que encontró (CLAUDE.md, .cursorrules, .cursor/rules/*.mdc, .github/copilot-instructions.md, GEMINI.md, CONTRIBUTING.md). Conserva sus reglas reales; fusiona, elimina duplicados, descarta las genéricas ("escribe código limpio").
• Lee el flujo de CI: los comandos que ejecuta CI son la definición más fiable de "las pruebas pasan".
• Examina 2–3 archivos fuente representativos para capturar las convenciones reales (nombrado, manejo de errores, estilo de importaciones) — no inventes convenciones que el código no siga.

Paso 3 — Verificar comandos

Ejecuta los comandos de instalación/construcción/prueba/linting del borrador (de forma segura: sin despliegues, sin migraciones contra bases de datos reales, sin publicaciones). Para cada uno: consérvalo si funciona; corrígelo si la variante correcta es obvia; de lo contrario, márcalo como (no verificado) e informa al usuario. Anota cuánto tarda la suite de pruebas si es lenta.

Paso 4 — Escribir AGENTS.md

Comienza desde assets/AGENTS.template.md. Reglas para un buen contenido:

• Corto. Apunta a menos de ~150 líneas. Los agentes leen esto en cada tarea; cada línea cuesta contexto.
• Específico y verificable: "Ejecuta pnpm test --filter web antes de confirmar" es mejor que "prueba tu código".
• Pon los comandos primero. Luego la estructura, convenciones, trampas, y reglas de "no hacer".
• Registra lo no obvio: archivos generados que no se deben editar, variables de entorno necesarias para las pruebas, la única prueba lenta que se debe saltar localmente, dónde nunca deben ir los secretos.
• Monorepos: AGENTS.md raíz para reglas compartidas + packages/x/AGENTS.md anidados para comandos específicos del paquete (los agentes que lo soportan leen el archivo más cercano).

Paso 5 — Conectar las otras herramientas

• Claude Code: crea CLAUDE.md a partir de assets/CLAUDE.template.md (contiene @AGENTS.md). Si ya existe un CLAUDE.md, mueve sus reglas a AGENTS.md y deja notas solo de Claude debajo de la importación.
• Codex: lee AGENTS.md de forma nativa — no se necesita nada más.
• Cursor: lee AGENTS.md en la raíz; migra el contenido de .cursorrules a AGENTS.md y, después de que el usuario acepte, elimina .cursorrules (obsoleto). Conserva .cursor/rules/*.mdc solo para reglas con ámbito de glob.
• Gemini CLI: por defecto lee GEMINI.md; establece "context": {"fileName": ["AGENTS.md", "GEMINI.md"]} en .gemini/settings.json o crea un GEMINI.md de una línea que apunte a AGENTS.md. Consulta la documentación de la versión instalada si esta clave ha cambiado.
• Los enlaces simbólicos (ln -s AGENTS.md CLAUDE.md) también funcionan pero fallan en repositorios de Windows sin core.symlinks; el enfoque de importación es más seguro.

Consulta references/tool-support.md para el archivo que lee cada herramienta.

Paso 6 — Reportar

Lista: archivos creados/modificados, comandos verificados (con resultado), comandos marcados como no verificados, reglas descartadas por duplicadas o genéricas, y cualquier cosa que necesites que el usuario decida (por ejemplo, ¿eliminar .cursorrules?). No hagas commit a menos que el usuario lo pida.