Optimizacion de Tokens

El presupuesto de instrucciones

Cada token en AGENTS.md se carga en cada request al agente, sin importar si es relevante para la tarea actual. Esto tiene un costo:

• Token budget: los LLMs frontier pueden seguir ~150-200 instrucciones con consistencia razonable
• Atencion: mas instrucciones = menos atencion a cada una
• Costo: mas tokens = mas caro en APIs de pago

Metricas: el impacto real

Los datos de Vercel son contundentes:

Configuracion	Pass rate	Tamano
Sin documentacion	53%	0 KB
Skills (default)	53%	variable
Skills con instrucciones	79%	variable
AGENTS.md optimizado	100%	~8 KB

Vercel redujo su documentacion de 40 KB a 8 KB (80% de reduccion) y alcanzo 100% de pass rate. Menos es mas.

Reglas de concision

1. Una oracion para describir el proyecto

<!-- Bien -->
E-commerce API with Express 5, TypeScript, PostgreSQL.

<!-- Mal -->
This project is an e-commerce platform that allows users to browse
products, add them to cart, and complete purchases. It was started
in 2023 and has been actively maintained since then...

2. Comandos, no explicaciones

<!-- Bien -->
- Test: `bunx vitest run`
- Lint: `bunx biome check src/`

<!-- Mal -->
To run the tests, you should use Vitest which is our testing
framework. You can execute the test suite by running the
following command in the terminal...

3. Apuntar a archivos, no describir patrones

<!-- Bien -->
See `src/domain/user/user-entity.ts` for entity pattern reference.

<!-- Mal -->
Entities should be classes with a private constructor and a static
factory method. They should validate their invariants in the
constructor. Properties should be readonly and exposed through
getter methods. Example:
[30 lines of code]

4. Solo lo que el agente no puede inferir

No repitas lo que esta en package.json, tsconfig.json o biome.json. El agente puede leer esos archivos.

<!-- Innecesario (ya esta en tsconfig.json) -->
TypeScript is configured with strict mode, target ES2022, module ESNext.

<!-- Util (no esta en ningun archivo de config) -->
New features go in domain/ first, then bubble up to application/ and infrastructure/.

Cuando el archivo crece demasiado

Senales de alerta

• Mas de 200 lineas
• Secciones que solo aplican a partes del proyecto
• Instrucciones contradictorias entre secciones
• Informacion que cambia frecuentemente (paths a archivos especificos)

Estrategia: extraer a documentos

# AGENTS.md (raiz, ~30 lineas)

E-commerce API. TypeScript + Hono + PostgreSQL.

## Commands
- Test: `bun test`
- Lint: `bun lint`
- Build: `bun run build`

## Key conventions
- Hexagonal architecture (see `docs/ARCHITECTURE.md`)
- Testing patterns (see `docs/TESTING.md`)
- Security policies (see `docs/SECURITY.md`)

## Boundaries
- Never commit secrets
- Ask before adding production dependencies
- Always run tests after source changes

El agente lee el AGENTS.md raiz (30 lineas, pocos tokens) y navega a los documentos de detalle solo cuando trabaja en esa area.

Antipatron: el knowledge dump

<!-- NUNCA hagas esto -->
# AGENTS.md

[500 lineas con cada detalle del proyecto, historial de decisiones
arquitecturales, todos los endpoints documentados, cada tipo de
TypeScript explicado, reglas de negocio completas...]

Esto causa:

• El agente pierde atencion en las instrucciones criticas
• Tokens desperdiciados en contexto irrelevante
• Instrucciones contradictorias cuando el archivo crece
• Mantenimiento imposible

Checklist de optimizacion

• Descripcion del proyecto en 1-2 oraciones
• Comandos con flags exactos (no explicaciones)
• Stack con versiones (sin narrativa)
• Boundaries claros (always/ask/never)
• Referencias a archivos reales en vez de code snippets largos
• Sin repeticion de lo que ya esta en archivos de config
• Bajo 200 lineas (idealmente bajo 100)
• Documentos de detalle enlazados, no inline

La instruccion clave de Vercel

La instruccion que mas impacto tuvo en las evaluaciones de Vercel:

“Prefer retrieval-led reasoning over pre-training-led reasoning”

Traduccion: “consulta la documentacion del proyecto en vez de confiar en lo que sabes de entrenamiento”. Esta unica instruccion cambio el comportamiento del agente de manera fundamental.

Resumen

• AGENTS.md se carga en cada request: cada token cuenta
• LLMs siguen ~150-200 instrucciones con consistencia
• Vercel logro 100% pass rate con solo 8 KB (vs 40 KB original)
• Concision: comandos sin explicaciones, referencias a archivos, sin repetir configs
• Si supera 200 lineas, extrae a documentos de detalle
• Una instruccion clave puede cambiar mas que 100 lineas de detalle

---

← Capitulo 5: Sistema de Boundaries | Capitulo 7: AGENTS.md con Claude Code →