robcsaszar/scaffold

IA Crear / Revisar AGENTS.md

Dos modos: crear un nuevo AGENTS.md o revisar uno existente frente a estándares de calidad respaldados por investigación.

Detección de Modo

• El usuario proporciona un AGENTS.md existente o señala uno → Modo Revisión
• El usuario pide crear/andamiar/generar → Modo Creación
• Ambiguo → pregunta: ¿(c)rear un nuevo AGENTS.md o (r)evisar uno existente?

---

Modo Creación

Paso 1: Preguntar ubicación

¿Dónde debe colocarse el AGENTS.md?
(r)aíz — línea base del repositorio
(p)ath — directorio específico (proporcionar ruta)

Para monorepos: sugerir raíz + archivos por paquete. Gana el AGENTS.md más cercano.

Si AGENTS.md ya existe en la ruta destino → pregunta: El archivo existe. ¿(r)evisar existente / (s)obrescribir / (Q)uitar?

Paso 2: Pensamiento experto

Antes de escribir, determina para ESTE proyecto:

• ¿Qué es indescubrible? ¿Qué no se puede inferir de package.json, configuraciones o estructura de directorios?
• ¿Qué es peligroso? ¿Qué comandos o patrones causan fallos silenciosos?
• ¿Qué es ambiguo? ¿Dónde hay dos enfoques válidos y el agente adivinaría mal?
• ¿Qué no es estándar? ¿Qué convenciones difieren de los valores predeterminados del framework?

Si todas las respuestas son "nada" — es posible que el proyecto no necesite un AGENTS.md. Dilo.

Para repos sin package.json o configuraciones de compilación (solo documentación, repos de datos, scripts simples): centrarse solo en los límites de Misión + Juicio — las secciones de toolchain y cierre no aplicarán.

Paso 3: Escribir en orden de prioridad

Agrega secciones SOLO si pasan la prueba de indescubrible, en este orden:

1. Misión (2–4 oraciones) — propósito del proyecto + restricción central que el agente no puede inferir
2. Registro de toolchain — comandos como tabla, NO lo que las herramientas imponen
3. Límites de juicio — niveles NUNCA / PREGUNTAR / SIEMPRE
4. Definición de cierre — "Hecho" = códigos de salida específicos
5. Reglas de escalada — qué hacer cuando se está bloqueado
6. Secciones organizadas por tarea — "Al escribir… / Al revisar… / Al publicar…"

Paso 4: Validar

• Total ≤ 150 líneas (óptimo: 60–100)
• Cada sección ≤ 50 líneas
• Cada instrucción responde: "¿Qué comando prueba que esto se hizo?"
• Cada "no" está emparejado con un "sí"
• No repetir reglas de linter (toolchain primero)
• Sin párrafos en prosa sin comandos

OBLIGATORIO — LEE references/knowledge-base.md para patrones y evidencia respaldados por investigación. OBLIGATORIO — LEE references/template.md para la estructura inicial. Carga references/example.md solo cuando el usuario pregunte cómo se ve un AGENTS.md terminado, o cuando el repositorio sea un monorepo JS/TS (es un ejemplo práctico de turborepo + pnpm) — ignóralo en caso contrario. NO cargues references/knowledge-base.md durante el Modo Revisión si el AGENTS.md destino tiene < 20 líneas — la lista de verificación del cuerpo y la lista de antipatrones son suficientes para archivos trivialmente cortos.

---

Modo Revisión

Evalúa el AGENTS.md proporcionado frente a criterios de calidad respaldados por investigación.

Dimensiones de Puntuación

Dimensión	Peso	Qué verificar
Densidad de señal	25%	% de líneas que son conocimiento experto indescubrible vs. genérico/redundante
Comando primero	20%	Cada instrucción tiene un comando verificable o código de salida
Definición de cierre	15%	Criterios explícitos de "hecho" con comprobaciones específicas
Sistema de límites	15%	Niveles NUNCA/PREGUNTAR/SIEMPRE presentes y específicos
Disciplina de longitud	10%	≤150 total, ≤50 por sección, sin inflación
Ausencia de antipatrones	15%	Libre de patrones que han demostrado fallar

Guía de Puntuación

• Puntúa severamente en densidad de señal para repos maduros con toolchains establecidos — la mayor parte del contenido probablemente sea redundante
• Puntúa con indulgencia en cierre/límites para proyectos greenfield — es posible que aún no tengan compuertas de CI
• Puntúa severamente en longitud para archivos raíz de monorepo — se cargan en cada sesión a través de todos los paquetes
• Si la puntuación total < 40: recomienda reescritura en lugar de correcciones incrementales

Lista de Verificación de Antipatrones

Señala cualquiera de estos (empíricamente comprobado que perjudican el rendimiento del agente):

• Párrafos en prosa sin comandos
• Directivas ambiguas ("ten cuidado", "cuando sea posible")
• Prioridades contradictorias sin orden explícito
• Reglas de estilo ya aplicadas por la configuración del linter
• Descripciones generales de arquitectura (provoca sobreexploración)
• 15+ advertencias sin alternativas emparejadas
• Plantilla generada por LLM de comandos /init
• Repetir lo que el toolchain impone
• Violaciones de elefante rosa (listas largas de "no hacer" que mantienen activos conceptos prohibidos)

Formato de Salida

## Revisión de AGENTS.md: <nombre de archivo o ruta>

**Puntuación**: X/100
**Veredicto**: [Listo para producción / Necesita trabajo / Se recomienda reescritura]

### Fortalezas
- ...

### Problemas (por gravedad)
1. [CRÍTICO] ...
2. [ALTO] ...
3. [BAJO] ...

### Sugerencias de Reescritura
1. ...
2. ...

Aplicar

La revisión no es el entregable — un AGENTS.md mejor sí lo es. Después de presentarla, ofrece:

¿Aplicar? (t)odas / (s)eleccionar por número / (n)inguna

En (t) o (s): edita el archivo en el lugar, un elemento numerado a la vez, luego vuelve a ejecutar las dimensiones de puntuación e informa la nueva puntuación junto con la anterior. Cada línea que la revisión no señaló sobrevive textualmente — una revisión no es un mandato de reescritura, y "mejorar" silenciosamente prosa no señalada es cómo un pase de revisión destruye la voz y la intención del autor.

Omite la oferta cuando el usuario proporcionó el contenido en línea en lugar de una ruta, o el archivo no es editable. Dilo en lugar de informar mejoras como aplicadas.

OBLIGATORIO — LEE references/knowledge-base.md para la evidencia de investigación detrás de cada criterio.

---

NUNCA

• NUNCA incluyas contenido que el agente pueda descubrir de la estructura del repositorio — los scripts de package.json, el diseño de directorios y los archivos de configuración se documentan por sí mismos; repetirlos desperdicia tokens y crea desviación de mantenimiento. EN SU LUGAR: referencia el archivo (ver biome.json) y sigue adelante.
• NUNCA repitas reglas de linter/formateador — la herramienta ES la restricción; la duplicación crea desactualización y los requisitos innecesarios perjudican activamente el rendimiento del agente. EN SU LUGAR: enumera solo el comando de ejecución (Lint: \pnpm lint``).
• NUNCA escribas un "no" sin un "sí" emparejado — los documentos solo con advertencias causan sobreexploración; 15+ no sin alternativas vuelve a los agentes conservadores y menos productivos. EN SU LUGAR: empareja cada prohibición con la alternativa correcta.
• NUNCA superes las 150 líneas — más allá de este umbral, las ganancias se revierten y el archivo perjudica activamente la calidad. EN SU LUGAR: extrae los detalles en archivos referenciados o elimínalos.
• NUNCA uses contenido generado por LLM como final — la salida de /init es un inventario de lo que el agente ya sabe; reduce el rendimiento e infla el costo. EN SU LUGAR: trátalo como borrador de inventario, luego elimina todo lo que el toolchain ya impone.
• NUNCA escribas párrafos en prosa — los agentes los saltan; usa comandos, tablas y viñetas con resultados verificables. EN SU LUGAR: convierte a comando + código de salida + descripción de una línea.