En 2026 ya no basta con abrir tu agente favorito, pegarle una tarea y esperar magia.
Cuando trabajas con herramientas como Claude Code, Cursor, Codex CLI o cualquier otro coding agent, el salto grande no suele venir de escribir un prompt “más listo”. El salto de verdad llega cuando el agente entiende cómo está construido tu proyecto, qué reglas sigue, qué no debe tocar y qué significa “hacerlo bien” dentro de tu código.
Ahí es donde entran dos archivos que cada vez tienen más sentido:
AGENTS.mdCLAUDE.md
Da igual si usas uno, otro o ambos. La idea importante es la misma: darle contexto operativo al agente.
No una novela.
No una wiki infinita.
No un documento corporativo que nadie lee.
Contexto útil para que tome mejores decisiones mientras programa.
El error de casi todo el mundo#
La mayoría usa agentes así:
- abre el editor
- escribe una petición grande
- espera que el modelo deduzca la estructura del proyecto
- corrige manualmente lo que no entendió
- vuelve a intentarlo
Eso funciona a veces, pero escala fatal.
En cuanto el proyecto tiene:
- arquitectura por capas
- reglas de negocio propias
- decisiones técnicas ya tomadas
- convenciones de naming
- tests obligatorios
- varios entornos
- límites de seguridad
…el agente deja de necesitar “más creatividad” y empieza a necesitar más contexto.
Qué es realmente AGENTS.md o CLAUDE.md#
Es un archivo markdown en la raíz del proyecto donde dejas claro cómo debe comportarse un agente cuando trabaja en ese repositorio.
Piensa en él como una mezcla entre:
- guía de colaboración
- manual rápido de arquitectura
- contrato de calidad
- mapa de contexto del dominio
No sustituye a la documentación técnica profunda.
La resume para que el agente tenga a mano justo lo que necesita antes de leer, modificar o generar código.
Por qué el contexto gana al prompt#
Un prompt puede decir:
> Añade login con Google y sigue buenas prácticas.
El problema es que “buenas prácticas” no significan nada sin contexto.
¿Tu proyecto usa:
- Server Actions o API routes?
- Zod o class-validator?
- Prisma o Supabase?
- Angular signals o RxJS clásico?
- arquitectura modular o feature-first?
- tests obligatorios o solo smoke tests?
- naming en inglés o español?
Si el agente no lo sabe, rellenará los huecos con patrones genéricos.
Y ahí es donde empiezan los problemas:
- código correcto, pero inconsistente
- dependencias nuevas que no querías
- validaciones duplicadas
- tests fuera del patrón del repo
- soluciones que “funcionan”, pero no encajan
Cuando el contexto está bien definido, el agente deja de improvisar tanto y empieza a trabajar como un colaborador que ya conoce la casa.
Lo que sí debe tener un buen archivo de contexto#
Aquí es donde mucha gente falla: o ponen cuatro líneas inútiles o escriben un documento eterno que nadie mantiene.
Lo bueno está en el punto medio.
1. Propósito del proyecto#
Dos o tres párrafos para explicar:
- qué producto es
- qué problema resuelve
- quién lo usa
- cuáles son sus entidades principales
Ejemplo:
## Propósito
Este proyecto es un SaaS B2B multi-tenant para agencias y consultoras.
Gestiona clientes, usuarios, proyectos, permisos y facturación por organización.
Las entidades clave son organizations, memberships, projects e invoices.Esto parece básico, pero evita muchísimos errores de interpretación.
2. Stack y restricciones técnicas#
No basta con decir “usamos Next.js”.
Hay que dejar claro también qué decisiones ya están tomadas.
## Stack
- Next.js App Router
- TypeScript estricto
- Supabase para auth y base de datos
- Tailwind para estilos
- Zod para validación
## Restricciones
- No añadir librerías nuevas sin justificarlo
- Priorizar Server Components salvo necesidad clara de client component
- No usar localStorage para datos sensibles### 3. Convenciones de código
Aquí ahorras muchísimo retrabajo.Convenciones#
- Nombres de funciones en camelCase
- Componentes React en PascalCase
- Tipos y schemas cerca de la feature
- No mezclar lógica de negocio con componentes de UI
- Los mensajes de error visibles al usuario deben estar en español
### 4. Flujo esperado de trabajo
Muy útil para que el agente no se lance a tocar medio proyecto sin control.Flujo de trabajo#
- Entender el problema
- Revisar archivos relacionados antes de proponer cambios
- Explicar el enfoque antes de aplicar refactors grandes
- Mantener cambios pequeños y fáciles de revisar
- Añadir o actualizar tests si cambia lógica crítica
### 5. Criterios de calidad
Esto es lo que convierte el archivo en una herramienta seria.Calidad#
- No romper tipado
- No degradar accesibilidad
- No dejar TODOs vagos
- Si se toca auth, validar edge cases
- Si se toca facturación, no asumir estados implícitos
### 6. Reglas del dominio
Este bloque es oro puro y casi nadie lo escribe.Reglas de negocio#
- Un usuario puede pertenecer a varias organizaciones
- Cada organization tiene roles owner, admin, member y billing
- Nunca se debe confiar el organization_id enviado desde frontend
- Todo acceso a datos debe validarse contra el contexto del tenant
Un agente con esto toma decisiones mucho mejores.
## Qué NO debería tener
Igual de importante que lo anterior.
No metas aquí:
- documentación kilométrica
- decisiones ya obsoletas
- tutoriales genéricos del framework
- secretos
- tokens
- variables privadas
- listas eternas de “buenas prácticas” copiadas de internet
Si el archivo pesa demasiado, se vuelve difuso.
Y si se vuelve difuso, deja de ayudar.
## Plantilla práctica de `AGENTS.md`
Esta estructura suele funcionar muy bien:AGENTS.md#
- Propósito del proyecto
- Entidades y reglas de negocio
- Stack principal
- Restricciones técnicas
- Convenciones de código
- Estructura del repositorio
- Flujo de trabajo esperado
- Criterios de calidad
- Testing
- Seguridad y datos sensibles
- Qué evitar
Sencilla, mantenible y clara.
## Ejemplo realista para un proyecto webAGENTS.md
Propósito#
Aplicación SaaS B2B para gestionar clientes, proyectos y documentos por organización.
Stack#
- Next.js 16
- TypeScript
- Supabase
- Tailwind
- Zod
Estructura#
- app/: rutas y layouts
- components/: UI reutilizable
- features/: lógica por dominio
- lib/: utilidades y clientes
- db/: queries y helpers de acceso a datos
Convenciones#
- Mantener componentes pequeños
- Extraer lógica de negocio fuera de la UI
- No añadir dependencias sin necesidad
- Reutilizar helpers existentes antes de crear nuevos
Testing#
- Añadir tests cuando cambie lógica de validación, auth o facturación
- No generar snapshots sin justificarlo
Seguridad#
- Nunca imprimir tokens o secretos
- No confiar en IDs enviados por frontend sin validación
- No exponer variables privadas al cliente
Qué evitar#
- Refactors grandes sin pedirlo
- Introducir patrones distintos a los ya usados
- Duplicar validaciones o schemas
Con algo así ya mejoras muchísimo el rendimiento práctico del agente.
## `AGENTS.md` vs `CLAUDE.md`
Aquí no hay guerra religiosa.
La diferencia real depende del flujo de trabajo y la herramienta que uses.
- `AGENTS.md` funciona muy bien como archivo general de contexto para coding agents.
- `CLAUDE.md` suele usarse cuando quieres ajustar especialmente bien cómo debe colaborar Claude Code en ese repo.
En muchos proyectos incluso tiene sentido usar ambos con funciones distintas:
- `AGENTS.md` como guía general del proyecto
- `CLAUDE.md` como guía específica de colaboración y estilo de trabajo con Claude
Lo importante no es el nombre.
Lo importante es que exista un **contrato operativo claro**.
## Cómo mantenerlo sin que se pudra
Esto es clave.
El mayor riesgo no es no tener archivo.
El mayor riesgo es tenerlo y que mienta.
Para evitarlo:
### 1. Trátalo como código
Si cambia la arquitectura, cambia el archivo.
Si cambian las reglas del dominio, cambia el archivo.
Si cambia el estándar de tests, cambia el archivo.
### 2. No metas ruido
Cada línea debería ayudar a decidir mejor.
Si no ayuda, sobra.
### 3. Revisa lo que más falla
Una técnica muy buena es mirar qué errores repite el agente y convertir esos errores en reglas claras.
Ejemplos:
- “Siempre me mete client components donde no toca”
- “Duplica lógica de validación”
- “Rompe el patrón de carpetas”
- “Hace queries sin respetar el tenant activo”
Todo eso debería acabar resumido en el archivo.
### 4. Prioriza lo específico sobre lo obvio
No hace falta escribir:
> Usa buenas prácticas.
Eso no aporta nada.
Sí aporta escribir:
> En este proyecto no se aceptan fetches directos desde componentes cliente para datos sensibles; usar siempre server-side access control.
## Cuándo notas de verdad la diferencia
La mejora se nota sobre todo cuando el agente tiene que:
- tocar varios archivos
- respetar una arquitectura existente
- trabajar con dominio de negocio real
- seguir restricciones de seguridad
- mantener consistencia entre features
En scripts sueltos o tareas pequeñas puede dar igual.
En un producto vivo, no.
## Mi recomendación práctica
Si ya estás usando agentes en desarrollo, haría esto hoy mismo:
1. crear `AGENTS.md` en la raíz
2. empezar por una versión corta y útil
3. meter propósito, reglas, stack, convenciones y seguridad
4. añadir un bloque de “errores frecuentes del agente”
5. revisarlo cada vez que cambie una decisión importante del proyecto
No hace falta complicarlo más.
Pero sí hacerlo de verdad.
## Checklist rápido
- [ ] Explica qué hace el proyecto
- [ ] Resume entidades y reglas de negocio
- [ ] Deja claro el stack y sus límites
- [ ] Marca convenciones de código
- [ ] Define cuándo hay que añadir tests
- [ ] Explica qué zonas son sensibles
- [ ] Prohíbe prácticas que ya sabes que rompen el repo
- [ ] Se mantiene actualizado
## Conclusión
En 2026, trabajar bien con coding agents va menos de escribir prompts espectaculares y más de diseñar **buen contexto de ejecución**.
`AGENTS.md` y `CLAUDE.md` son útiles precisamente por eso: convierten conocimiento disperso del proyecto en instrucciones concretas, reutilizables y accionables.
Y cuando el agente entiende mejor el proyecto:
- mete menos ruido
- respeta más tus decisiones
- necesita menos correcciones
- genera cambios más consistentes
Dicho fácil: **mejor contexto, mejores soluciones**.
Si estás metiendo IA en tu flujo de desarrollo, este tipo de archivo deja de ser un extra y empieza a parecerse bastante a una ventaja real.
## Fuentes recomendadas
- Vercel: evaluación sobre `AGENTS.md` frente a skills en proyectos Next.js
- Anthropic: documentación oficial y buenas prácticas de Claude CodeMás sobre IA & Automación
Ver todos →
