Cómo implementar CLAUDE.md para agentes de código automatizados
DominicodeCLAUDE.md: el contrato entre tú y el agente
Tiempo estimado de lectura: 6 min
- Define reglas operativas claras para evitar que agentes automaticen o “improvisen” sobre código base.
- Estandariza stack, comandos y convenciones para que el agente genere cambios compatibles con el repositorio.
- Mantén el archivo actualizado y versiónalo junto con cambios en el stack para evitar divergencias.
Introducción
CLAUDE.md: el contrato entre tú y el agente es el punto de control que evita que Claude Code “improvise” sobre tu base de código. Colocar ese archivo en la raíz del repo cambia la relación: el agente deja de adivinar y empieza a obedecer reglas explícitas antes de generar cualquier cambio.
Claude Code incorpora los CLAUDE.md al contexto inicial de la sesión. Si quieres que el agente respete decisiones de arquitectura, convenciones y restricciones operativas, no hay atajo: ponlas por escrito en un CLAUDE.md que Claude pueda leer. Para entender el diseño técnico del protocolo, revisa la documentación oficial (Anthropic — claude-code) y la página de Claude en Anthropic.
¿Qué debe contener un CLAUDE.md?
Un CLAUDE.md no es un README para humanos ni un changelog. Es un contrato operativo para máquinas. Limítalo a lo esencial que el agente necesita conocer para no romper invariantes del sistema. Divide el archivo en cuatro bloques obligatorios:
- 1. Stack técnico y decisiones no negociables.
- 2. Comandos operativos (build, test, lint).
- 3. Convenciones de código que el linter no puede forzar.
- 4. Patrones prohibidos y límites de seguridad.
A continuación, una plantilla mínima que puedes adaptar.
Plantilla mínima
## Stack
- Next.js 14 (App Router). No Pages Router.
- TypeScript (strict: true).
- Tailwind CSS. No CSS Modules ni styled-components.
- Prisma como ORM. No SQL raw salvo migraciones.
## Comandos
- `pnpm dev` — dev server
- `pnpm test` — Jest (coverage >= 80%)
- `pnpm lint` — ESLint (project config)
- `pnpm build` — build prod (sin warnings)
## Convenciones
- Componentes: PascalCase en `/src/components`.
- Hooks: prefijo `use` en `/src/hooks`.
- Errores: usar tipos, no `any`. `catch(e: unknown)` -> narrow.
- No llamadas a APIs desde componentes: usar `/src/services`.
## Patrones prohibidos
- No introducir dependencias sin PR aprobado.
- No usar `useEffect` para sincronización derivada.
- No crear contextos globales nuevos; usar Zustand.
¿Dónde colocarlo en monorepos?
Claude Code respeta jerarquías: lee CLAUDE.md en la raíz y en submódulos relevantes. En monorepos, combina reglas globales con reglas locales:
/CLAUDE.md— reglas globales (tooling, CI, linters)/apps/web/CLAUDE.md— reglas específicas del frontend/packages/ui/CLAUDE.md— reglas del diseño compartido
El agente fusiona las reglas aplicables según el contexto del archivo que edita. Esto te permite mantener consistencia sin replicar todo el contrato en cada paquete.
Cómo cambia el flujo de trabajo con un CLAUDE.md
Sin CLAUDE.md, cada sesión de Claude Code es una pizarra limpia: el agente infiere patrones, instala dependencias y propone cambios que “funcionan” pero rompen la coherencia del repo. Con CLAUDE.md:
- El agente conoce el tooling exacto (ej. pnpm vs npm) y no ejecuta comandos incorrectos.
- No propone o instala librerías fuera del stack definido.
- Genera código que cumple las convenciones locales: ubicación de archivos, nombres, patrones de error.
- Respeta las reglas de seguridad y de auditoría (por ejemplo, rutas que requieren autorización).
El resultado práctico: menos PRs de corrección, menos reescrituras y menos deuda técnica introducida por el agente.
Mantenimiento: el contrato debe evolucionar con el código
Un CLAUDE.md desactualizado es peor que no tenerlo. El agente aplicará reglas obsoletas con tanta disciplina como aplicaría las correctas.
Reglas simples de mantenimiento:
- Actualiza CLAUDE.md en el mismo PR que cambia el stack o introduce un patrón nuevo.
- Versiona las secciones críticas (ej. Stack v2) si el cambio es migratorio.
- Añade ejemplos de I/O cuando la interacción es ambigua (ej. formatos JSON esperados).
- No uses el archivo para documentación extensa de negocio; su propósito es técnico y operativo.
Casos prácticos y límites
– Si tu agente debe interactuar con la UI (acciones del DOM), documenta los casos en CLAUDE.md pero combina con una especificación de UI semántica (p. ej., WebMCP).
– No almacenes secretos ni variables de entorno en CLAUDE.md. Usa vaults y referencias a los secretos gestionados por CI/CD.
– Si tu repositorio permite múltiples stacks (ej. experimentos), usa CLAUDE.md por carpeta para evitar ambigüedades.
Conclusión
CLAUDE.md: el contrato entre tú y el agente es una inversión pequeña con retorno inmediato. Poner las reglas por escrito antes de pedirle a Claude Code que haga cambios transforma una relación de adivinanza en una colaboración predecible. Si tu objetivo es integrar agentes de forma práctica y segura, escribir y mantener CLAUDE.md debería ser parte del proceso de desarrollo —actualizado en el mismo PR que cambia tu arquitectura— no una tarea opcional.
Dominicode Labs
Para equipos que trabajan con agentes, automatización y flujos de trabajo técnicos, la práctica de formalizar contratos operativos como CLAUDE.md encaja con iniciativas de investigación aplicada. Más recursos y experimentos relacionados están disponibles en Dominicode Labs.
FAQ
Respuesta: ¿Qué es un CLAUDE.md y para qué sirve?
Un CLAUDE.md es un archivo de reglas operativas que define cómo un agente (ej. Claude Code) debe comportarse respecto al repositorio. Sirve para evitar que el agente realice cambios incompatibles o no autorizados.
Respuesta: ¿Dónde debe ubicarse en un monorepo?
Colócalo en la raíz del repositorio para reglas globales y en subcarpetas relevantes para reglas locales (por ejemplo, /apps/web/CLAUDE.md). Claude Code combinará las reglas aplicables.
Respuesta: ¿Qué pasa si no lo actualizo?
Si está desactualizado, el agente aplicará reglas obsoletas, lo que puede introducir errores o incoherencias. Actualízalo en el mismo PR que modifica el stack o las convenciones.
Respuesta: ¿Puedo incluir secretos en CLAUDE.md?
No. No almacenes secretos ni variables de entorno en CLAUDE.md. Usa vaults o referencias gestionadas por CI/CD.
Respuesta: ¿Cómo integro cambios en el contrato durante una migración del stack?
Versiona secciones críticas (ej. “Stack v2”) y añade la actualización en el mismo PR que realiza la migración para mantener coherencia entre el código y el contrato.