agents-md

CLI para generar archivos AGENTS.md automáticamente para proyectos Node.js.

Tabla de contenido

• ¿Qué es AGENTS.md?
• Quickstart
• Instalación
• Uso
• Perfiles de salida
• Límites de salida
• Proyectos soportados
• Estado actual de plantillas
• Cómo funciona
• Releases y novedades
• Desarrollo
• Dependency maintenance
• Contribuciones
• Soporte
• Licencia

¿Qué es AGENTS.md?

AGENTS.md es un documento para asistentes de código (IA) que resume cómo trabajar en tu proyecto sin adivinar.

Incluye, de forma práctica:

• Comandos recomendados para instalar, ejecutar, compilar, lint y pruebas.
• Convenciones de código y estilo.
• Guía de validación y pruebas antes de cerrar tareas.
• Reglas de seguridad y calidad.
• Criterios claros para considerar una tarea como terminada.

Quickstart

Antes de ejecutar:

• Paquete en npm: @sebasgc0399/agents-md
• Comando del CLI: agents-md
• Importante: no uses npx agents-md ... sin scope; usa @sebasgc0399/agents-md.

Uso sin instalación (recomendado):

npx @sebasgc0399/agents-md init
npx @sebasgc0399/agents-md init --dry-run
npx @sebasgc0399/agents-md init --profile compact
npx @sebasgc0399/agents-md init --profile standard
npx @sebasgc0399/agents-md init --profile full

Instalación

Opción 1: sin instalación (npx)

npx @sebasgc0399/agents-md init

Opción 2: instalación global

npm install -g @sebasgc0399/agents-md
agents-md init

Requisitos:

• Node.js >= 18
• package.json en la raíz del proyecto

Uso

# Generar AGENTS.md en el directorio actual
agents-md init

# Vista previa sin escribir archivo
agents-md init --dry-run

# Elegir perfil de salida (default: compact)
agents-md init --profile compact
agents-md init --profile standard
agents-md init --profile full

# Sobrescribir archivo existente
agents-md init --force

# Mostrar detalles de detección
agents-md init --verbose

# Especificar ruta de salida
agents-md init --out ./docs/AGENTS.md

Qué hace cada opción clave:

• --dry-run: muestra el resultado sin escribir AGENTS.md.
• --profile: cambia nivel de detalle (compact, standard, full).
• --force: permite sobrescribir un archivo existente.
• --verbose: muestra cómo se detectó el proyecto y los comandos encontrados.
• --out: define la ruta y nombre del archivo de salida.

Nota: las flags -y/--yes y -i/--interactive están reservadas y hoy no cambian el comportamiento.

Perfiles de salida

• compact (default): salida breve y directa (objetivo aproximado: 30-90 líneas).
• standard: salida intermedia para equipos (objetivo aproximado: 130-190 líneas).
• full: salida más detallada para traspaso técnico y CI (objetivo aproximado: 200-280 líneas).

Límites de salida (límites suaves)

• compact: 190-700 tokens, 30-90 líneas
• standard: 1050-1700 tokens, 130-190 líneas
• full: 1650-2600 tokens, 200-280 líneas

Cómo se interpretan estos límites:

• El rango base es el objetivo principal por perfil.
• Se aplica una tolerancia de +-10%.
• Si el resultado queda fuera del rango base, se reporta advertencia.
• Si queda fuera de la tolerancia, se reporta incumplimiento P0 no bloqueante.
• La generación solo se bloquea cuando hay errores de validación.

Proyectos soportados

• React (Vite, CRA, Next.js)
• Vue (Vite, Nuxt)
• Angular
• Svelte y SvelteKit
• Astro
• NestJS
• Firebase Functions
• Express y Fastify
• Proyectos Node.js genéricos
• Monorepos (Turborepo/Nx)

Estado actual de plantillas

Plantilla	Frameworks que la usan
react.mustache	react, next
vue.mustache	vue, nuxt
angular.mustache	angular
svelte.mustache	svelte, sveltekit
nestjs.mustache	nestjs
astro.mustache	astro
fastify.mustache	fastify
firebase.mustache	firebase-functions
monorepo.mustache	cualquier monorepo
base.mustache	express, proyectos Node.js genericos y casos unknown

Notas importantes:

• Si se detecta monorepo, monorepo.mustache tiene prioridad sobre cualquier framework.
• express usa base.mustache por ser un framework intencionalmente no-opinado.
• Las plantillas compartidas usan bloques condicionales internos: svelte.mustache incluye secciones especificas de SvelteKit y vue.mustache incluye secciones especificas de Nuxt.

Cómo funciona

1. Lee package.json del proyecto.
2. Detecta la estructura de carpetas y el framework principal.
3. Detecta runtime y gestor de paquetes (npm, yarn, pnpm o bun) usando lockfiles y metadatos.
4. Revisa package.json > scripts para encontrar comandos existentes.
5. Para cada tarea usa una prioridad fija de nombres: desarrollo (dev > start > serve), build (build > compile), pruebas (test > test:unit > vitest > jest), lint (lint > eslint) y formato (format > prettier).
6. Construye el comando final según el gestor detectado (por ejemplo npm run build, yarn build, pnpm run build).
7. Si un script no existe, no lo inventa: ese comando se deja como no disponible.
8. Genera un AGENTS.md limpio y consistente según el perfil seleccionado.

Releases y novedades

Cambios en la versión actual (v0.4.1 - 2026-02-21):

• Se incorporó una política de actualización segura de dependencias con runbooks en Docs/DEPENDENCY_UPDATES.md y Docs/SECURITY_TRACKING.md.
• Se agregó configuración de Dependabot y mejoras en CI para reforzar validaciones de calidad y mantenimiento.
• Se actualizaron dependencias en package.json y package-lock.json, eliminando entradas obsoletas.

Actualizar a la última versión global:

npm update -g @sebasgc0399/agents-md 

Ver historial completo de versiones

Desarrollo

# Instalar dependencias
npm install

# Build
npm run build

# Modo desarrollo (watch)
npm run dev

# Tests
npm test

# Coverage
npm run test:coverage

# Lint (verificar tipos)
npm run lint

# Benchmark base de calidad (P0)
npm run benchmark:lite

# Benchmark de límites por perfil (estimado vs token real)
npm run benchmark:limits

# Benchmark P1 (línea base semántica y control de regresión)
npm run benchmark:p1

# Regenerar línea base P1 (solo cuando el cambio es intencional)
npm run benchmark:p1:update

# Benchmark P2 (tendencias semanales, no bloqueante)
npm run benchmark:p2

# Benchmark P2 local (sin GitHub Issues)
npm run benchmark:p2:local

# Benchmark P2 determinístico (json-only, fecha fija)
npm run benchmark:p2:deterministic

# Smoke del CLI compilado
node dist/cli.js init --dry-run

Dependency maintenance

Policy and workflow:

• Docs/DEPENDENCY_UPDATES.md
• Docs/SECURITY_TRACKING.md

Operational commands:

• Runtime update: npm run deps:update:runtime
• Runtime verification: npm run deps:verify:runtime
• Dev update batch: npm run deps:update:all
• Dev verification: npm run deps:verify:dev

Runbook P2 (operación)

Comandos de operación:

• Local sin red/issues: npm run benchmark:p2:local
• Determinístico local: npm run benchmark:p2:deterministic
• CI/semanal: npm run benchmark:p2

Cómo leer los reportes:

• artifacts/benchmark-p2/report.json: salida estructurada con metrics, issues y alerts.
• artifacts/benchmark-p2/report.md: resumen pensado para GITHUB_STEP_SUMMARY.

Interpretación rápida de alertas P2:

• determinism_rate: revisar salidas inestables entre corridas del mismo fixture/perfil.
• invalid_command_rate: revisar detección de comandos contra scripts reales y la lista permitida (allowlist).
• score_vs_baseline: revisar diferencia de puntaje contra la línea base P1; corregir o justificar actualización.
• p1_status: ejecutar npm run benchmark:p1 y resolver diferencias antes de continuar.

Contribuciones

Gracias por ayudar a mejorar agents-md.

Para mantener calidad y claridad en el proyecto:

• Abre un issue antes de cambios no triviales.
• Incluye problema, propuesta de solución y trade-offs técnicos.
• Si usaste IA, revisa manualmente el resultado antes de abrir PR.
• Mantén los PRs pequeños y enfocados.
• Agrega o actualiza tests cuando cambie el comportamiento.
• Ejecuta npm test antes de enviar.

Comandos de desarrollo y validación: ver sección ## Desarrollo.

Soporte

Si esta herramienta te resulta útil, puedes apoyar el proyecto de estas formas:

• Dar estrella al repo.
• Compartirlo con tu equipo.
• Reportar bugs con pasos reproducibles.
• Proponer mejoras vía issues o PRs acotados.

Licencia

MIT © 2026 sebasgc0399