← Volver al listado de tecnologías ← Índice de AGENTS.md

Mejores Practicas y Antipatrones

27 de febrero de 2025 Por: Artiko

agents-mdmejores-practicasantipatroneschecklist

Mejores Practicas y Antipatrones

Lecciones de 2,500+ repositorios

GitHub analizo miles de repositorios con AGENTS.md y encontro patrones claros entre los que funcionan y los que no.

Lo que funciona

Agentes especialistas: archivos enfocados en un rol claro superan a los genericos
Comandos tempranos: poner comandos ejecutables en las primeras secciones
Ejemplos reales: apuntar a archivos del repo es mas efectivo que escribir codigo inline
Boundaries explicitos: el sistema always/ask/never previene errores destructivos
Stack con versiones: “React 19 con Vite 6” > “React project”

Lo que falla

Personas vagas: “helpful coding assistant” no guia al agente
Solo nombres de herramientas: “Vitest” sin el comando completo
Explicaciones sin ejemplos: parrafos describiendo estilo sin mostrar codigo
Boundaries ambiguos: “be careful” en vez de “never commit .env”
Descripciones genericas: “web project” no ancla decisiones

Los 10 antipatrones mas comunes

1. El knowledge dump

<!-- MAL: 500 lineas con cada detalle del proyecto -->
# AGENTS.md
[Historial del proyecto, cada endpoint documentado, todas las
decisiones arquitecturales, reglas de negocio completas...]

Solucion: maximo 100-200 lineas. Extraer detalle a documentos enlazados.

2. El espejo del README

Copiar el README y pegarlo como AGENTS.md. El README es para humanos; los agentes necesitan instrucciones diferentes.

Solucion: escribir desde cero pensando en lo que el agente necesita.

3. El archivo fantasma

Crear AGENTS.md y nunca actualizarlo. Informacion desactualizada es peor que no tener archivo.

Solucion: actualizar AGENTS.md en el mismo PR que cambia convenciones, comandos o estructura.

4. La duplicacion multi-archivo

El mismo contenido en AGENTS.md, CLAUDE.md, .cursorrules y copilot-instructions.md.

Solucion: AGENTS.md como fuente de verdad + bridges para cada herramienta.

5. Instrucciones no verificables

<!-- MAL -->
Write clean, maintainable code.
Follow best practices.

<!-- BIEN -->
Functions under 30 lines.
No default exports.
Tests alongside source: module.test.ts.

6. Repetir configuracion existente

<!-- MAL: ya esta en tsconfig.json -->
TypeScript strict mode, target ES2022, moduleResolution bundler.

Solucion: solo incluir lo que no esta en archivos de configuracion.

7. Instrucciones contradictorias

Cuando el archivo crece, secciones diferentes terminan contradiciendose.

Solucion: revisiones periodicas. Si supera 200 lineas, dividir.

8. Delegar al agente el trabajo del linter

<!-- MAL: usar el LLM como linter -->
Ensure consistent indentation (2 spaces).
Add semicolons at end of statements.
Sort imports alphabetically.

Solucion: configurar Biome/ESLint/Prettier. No enviar al LLM a hacer trabajo de linter.

9. Paths hardcodeados que cambian

<!-- Fragil -->
Main component at src/components/dashboard/MainDashboard.tsx line 42.

Solucion: referenciar directorios y patrones, no archivos y lineas especificas.

10. Instrucciones para el humano, no para el agente

<!-- Esto es para humanos, no agentes -->
Please review all PRs before merging.
Schedule standup meetings at 10am.

Solucion: solo instrucciones que un agente de codigo puede ejecutar.

Patron: el AGENTS.md iterativo

No intentes escribir el AGENTS.md perfecto de entrada. El patron mas exitoso:

Semana 1: minimo viable

Project description. TypeScript + Hono + PostgreSQL.
- Test: `bun test`
- Lint: `bun lint`
- Build: `bun run build`

Semana 2: agregar lo que fallo

El agente uso npm en vez de bun? Agrega el package manager. Creo archivos gigantes? Agrega el limite de lineas.

Semana 3+: refinar

Cada vez que el agente comete un error repetido, agrega una instruccion. Cada vez que una instruccion no se sigue, hazla mas especifica.

Patron: mantener actualizado

Agrega esta regla a tu flujo de PR:

## PR checklist
- [ ] If commands changed: update AGENTS.md
- [ ] If conventions changed: update AGENTS.md
- [ ] If structure changed: update AGENTS.md

AGENTS.md es codigo. Se revisa en PRs como cualquier otro archivo.

Checklist final

Contenido esencial

Descripcion del proyecto (1-2 oraciones)
Tech stack con versiones
Comandos: build, test, lint, dev (con flags)
Comandos por archivo individual
Estructura del proyecto (directorios clave)
Convenciones de codigo (con ejemplo o referencia a archivo)
Boundaries: always / ask first / never
Flujo de Git (branch naming, commit format)

Calidad

Bajo 200 lineas (idealmente bajo 100)
Sin repeticion de archivos de config (tsconfig, biome, etc.)
Sin instrucciones vagas o no verificables
Sin informacion para humanos (solo para agentes)
Actualizado en el ultimo mes

Multi-herramienta

AGENTS.md como fuente de verdad
Bridges para herramientas que no lo leen nativamente
Sin contenido duplicado entre archivos

OpenSpec (si aplica)

Responsabilidades divididas: AGENTS.md (contexto) vs config.yaml (rules)
Sin stack duplicado en ambos archivos
CLAUDE.md con @AGENTS.md + extensiones

Resumen

Especialistas > generalistas: archivos enfocados superan a los genericos
Comandos con flags, no solo nombres de herramientas
Ejemplos reales (archivos) > explicaciones abstractas
Boundaries verificables: “never commit .env” > “be careful with secrets”
Iterar: empezar minimo, agregar cuando el agente falla
Actualizar en cada PR que cambie convenciones
No usar el LLM como linter: eso lo hacen herramientas deterministas

← Capitulo 9: Ecosistema de Herramientas | Capitulo 11: Genera tu AGENTS.md →