Un CLAUDE.md que Claude Code sí respeta: ejemplo real con Terraform

Claude Code lee el archivo CLAUDE.md de la raíz de tu repositorio al iniciar cada sesión. Es su memoria de proyecto: lo que escribas ahí lo tendrá presente sin que lo repitas. El problema es que la mayoría de los CLAUDE.md que veo son listas de buenas intenciones ("escribe código limpio", "sigue las buenas prácticas") que no cambian nada.

Vamos a escribir uno que sí funcione, con un caso donde equivocarse cuesta caro: infraestructura con Terraform.

1. Comandos exactos, no descripciones

Claude va a ejecutar comandos. Dale los que son seguros y dile exactamente cómo:

## Comandos (seguros, de solo lectura o locales)
- Formato: `terraform fmt -recursive`
- Validar: `terraform validate`
- Lint: `tflint --recursive`
- Plan: `terraform plan -out=tfplan` y revisar con `terraform show tfplan`

"Valida el código" es ambiguo. terraform validate no lo es. Si tu equipo usa OpenTofu, cámbialo por tofu: los comandos son iguales.

2. Convenciones que el modelo no puede adivinar

Claude ya sabe Terraform. Lo que no sabe es cómo lo usa tu equipo. Escribe solo eso, y añade el porqué cuando la regla no sea obvia:

- `for_each` con claves estables en lugar de `count` (con `count`, reordenar la lista recrea recursos).
- Para renombrar recursos usa bloques `moved {}` en vez de destruir y recrear.
- Variables sensibles con `sensitive = true`; secretos desde el gestor de secretos, nunca en `.tfvars`.

El motivo entre paréntesis importa: con él, Claude aplica la idea a casos que no listaste.

3. Un flujo con punto de parada

La clave en IaC es decir dónde termina el trabajo de Claude y empieza el tuyo:

## Flujo
1. Lee el módulo y el entorno afectados.
2. Haz el cambio mínimo.
3. `fmt` + `validate` + `tflint` + `plan`.
4. Resume el plan: qué se crea, cambia y **destruye**. La aplicación la hace una persona.

El paso 4 convierte un plan de 300 líneas en un resumen que puedes revisar en un minuto, y deja claro que el apply no le corresponde.

4. La sección "No hacer"

Es la más importante y la que casi todos olvidan:

## No hacer
- **Nunca** ejecutar `terraform apply`, `terraform destroy`, `-auto-approve`,
  `terraform state rm/mv` ni `terraform import` sin aprobación explícita.
- No editar el `.tfstate` a mano ni commitearlo.
- Sí commitear `.terraform.lock.hcl`.

Un detalle: CLAUDE.md guía el comportamiento, pero no es una barrera técnica. Para bloquear de verdad un comando, combínalo con reglas de permisos (deny) en .claude/settings.json o con un hook PreToolUse. Lo ideal es usar las dos capas.

5. Mantenlo corto y vivo

• Apunta a 30-80 líneas: todo se carga en cada sesión.
• Si corriges a Claude dos veces por lo mismo, esa corrección va al CLAUDE.md.
• Usa /memory dentro de Claude Code para editarlo sin salir de la sesión.
• En monorepos, pon un CLAUDE.md por paquete (infra/CLAUDE.md, api/CLAUDE.md): Claude lo lee cuando trabaja en esa carpeta.

Prueba rápida

Después de escribirlo, abre una sesión nueva y pide: "Añade un bucket S3 para logs en el entorno dev". Si Claude formatea, valida, genera el plan, te lo resume y se detiene sin aplicar, tu CLAUDE.md está funcionando.

---

¿Te sirvió? Este ejemplo es parte de las 15 Plantillas CLAUDE.md por Stack para Claude Code (en español): paga lo que quieras, desde 3 USD. Más recursos gratis en GitHub.