CLAUDE.md: 7 plantillas listas para pegar y cómo escribir las prohibiciones

“En el CLAUDE.md basta con apuntar el stack, ¿no?”

Yo también lo pensaba al principio. Astro, TypeScript y Tailwind: listo, escrito. Satisfecho, le pasé el trabajo a Claude Code y… me repitió el mismo error tres veces. Se saltaba los tests una y otra vez. Metía mano en un archivo de configuración que no había que tocar. Decía “¡Ya está arreglado!” mientras el build seguía sin pasar.

Un CLAUDE.md que solo lista el stack es como soltar a alguien nuevo en la oficina diciéndole únicamente “aquí trabajamos con Java”. Le cuentas qué conocemos, pero no le transmites ni una pizca de cómo hay que moverse.

En este artículo dejo, en formato listo para copiar, las 7 plantillas de CLAUDE.md que uso tal cual en proyectos reales. No son descripciones del stack: están volcadas en “el orden de las cosas” y “lo que no hay que hacer nunca”.

Puntos clave

• Lo que de verdad funciona en un CLAUDE.md no es el stack técnico, sino dos cosas: el orden de trabajo (Working Rules) y las prohibiciones (Do Not).
• Hay 7 plantillas por caso de uso: proyecto personal, sitio de contenido, API, equipo, legacy, automatización y monorepo. Elige la más parecida a tu repo y pégala, sin más.
• En todas, después de pegar es obligatorio añadir 3 líneas de Do Not propias. Eso es lo que frena los accidentes.
• “Cuanto más largo, mejor” es un mito. El CLAUDE.md no es un manual, es un archivo operativo. Ganan las reglas de acción cortas.
• Si Claude Code repite el mismo fallo tres veces, no sospeches de la IA: sospecha de la granularidad de tu CLAUDE.md.

Pensé esta página como un “catálogo físico” que rellena el hueco entre la Guía completa para empezar con Claude Code y Cómo escribir un buen CLAUDE.md. La teoría léela allí; desde aquí, llévate los objetos reales a casa.

Lo que un buen CLAUDE.md hace sin hacer ruido

Un CLAUDE.md potente no es que escriba cosas brillantes. Solo elimina, sin alardes, tres “accidentes de toda la vida”:

• El sitio que edita es el correcto, pero se salta la convención propia de ese proyecto.
• La corrección en sí sale bien, pero omite los tests o las comprobaciones que tocaba pasar.
• No queda claro hasta dónde llega su responsabilidad, la exploración se desborda y se funde el tiempo.

Para evitar estos tres, lo mínimo que quieres tener es esto:

Sección	Función	Efecto
Stack técnico y comandos clave	Igualar el contexto de partida	Medio
Rol de cada directorio	Acotar el área de exploración	Medio
Reglas propias del proyecto	Hacer respetar la convención	Alto
Orden de trabajo (la secuencia)	Evitar comprobaciones olvidadas	Alto
Prohibiciones (Do Not)	Frenar los accidentes	Máximo

Las dos primeras son el extra; las que de verdad funcionan son las tres de abajo. En particular, en cuanto escribes el orden de trabajo y las prohibiciones, Claude Code se calma como si fuera otra persona. “Cómo avanzar” y “qué no hacer”… al final es el mismo manual que le darías a alguien nuevo del equipo.

A partir de aquí van los objetos reales. Copia el contenido de cada bloque de código directamente en tu CLAUDE.md.

1. Para una app web de proyecto personal

Si llevas tú solo un servicio pequeño, empieza por esta.

# Project Overview

Customer-facing Astro site with a small Node API.

## Tech Stack

- Frontend: Astro 5 + TypeScript
- Styling: Tailwind CSS
- Backend: Node.js 22
- Tests: Vitest

## Key Directories

- `site/src/pages/` route entrypoints
- `site/src/components/` reusable UI
- `site/src/content/` blog and docs content
- `scripts/` operational scripts

## Common Commands

- Build: `cd site && npm run build`
- Test: `npm run test`
- Search content: `rg "keyword" site/src/content`

## Working Rules

- Prefer minimal diffs over wide refactors
- Keep copy changes aligned with existing brand tone
- When editing UI, verify mobile width before calling the task done

## Do Not

- Do not rename routes unless required
- Do not delete analytics or SEO fields
- Do not claim deploy success without checking the public URL

Lo que más funciona aquí no es la descripción del stack, sino las últimas líneas de Working Rules y Do Not. “No digas que está terminado hasta verificar el ancho móvil” y “no digas que el deploy fue un éxito hasta mirar la URL pública”. Antes de meter estas dos líneas, tuve varias veces el accidente de una UI que en el monitor del PC se veía perfecta y en el móvil se salía toda por los bordes. En cuanto atas la condición de éxito con una frase, eso desaparece.

2. Para un sitio de contenido con artículos, PDF y embudo de productos

Este mismo blog es un ejemplo: un sitio con un embudo de ingresos se queda demasiado corto con una plantilla de desarrollo genérica.

# Project Overview

Multilingual Claude Code content site with free PDF lead magnet, Gumroad products, and consultation funnel.

## Business Goal

- Priority 1: free PDF registration
- Priority 2: Gumroad product clicks and purchases
- Priority 3: consultation inquiries

## Content Rules

- Every new article must include internal links
- Every article must include free PDF, product, and consultation CTA paths
- Use the same slug across all locales when publishing multilingual posts

## Verification Workflow

1. Build the site
2. Deploy the site
3. Open the public URL
4. Check mobile layout
5. Confirm CTA destination links

## Do Not

- Do not publish only one locale when the article requires all locales
- Do not treat build success as release success
- Do not prioritize pageviews over conversion path quality

La clave está en la última línea del Do Not: dejo escrito de forma explícita “prioriza la calidad del embudo de conversión por encima de las visitas”. Sin esa línea, Claude Code se inclina hacia “artículos que parezcan leerse mucho” y produce en serie páginas con CTAs flojos justo donde más importan. Solo con priorizar el objetivo de negocio y ponerlo al principio, la dirección de la salida cambió por completo.

3. Para una API de backend

A una API donde la coherencia es sagrada le impongo “lee antes de tocar” y “después de tocar, ponlo en palabras”.

# Project Overview

Internal TypeScript API for billing and account management.

## Tech Stack

- Node.js 22
- Fastify
- PostgreSQL + Prisma
- Zod
- Vitest

## Directory Map

- `src/routes/` HTTP handlers
- `src/services/` business logic
- `src/repositories/` DB access
- `src/lib/` shared utilities

## Required Workflow

1. Read the route or service first
2. Check for existing schema and tests
3. Make the smallest safe change
4. Run unit tests or type checks
5. Summarize risk in plain English

## Do Not

- Do not bypass Zod validation
- Do not edit migrations casually
- Do not touch billing logic without tests

De todo esto, lo que más me gusta es la línea Summarize risk in plain English: “resume el riesgo en lenguaje llano”. Con ella, Claude Code no se queda en “ya lo arreglé”, sino que pone en palabras el alcance del impacto por su cuenta, algo como “este cambio toca muy de cerca el límite de la lógica de facturación, así que podría afectar al proceso por lotes mensual”. El primer paso de la revisión se vuelve muchísimo más fácil.

4. Para desarrollo en equipo

Lo que de verdad duele en un equipo no es la falta de productividad, sino los diffs difíciles de revisar. Esto se les adelanta.

# Team Workflow

- Work on the current branch only
- Do not revert changes you did not make
- Call out uncertainty before making broad edits
- Prefer review-friendly patches over large rewrites

## Pull Request Expectations

- Mention user-facing behavior changes
- Mention test coverage gaps
- Flag security, permissions, and deploy risks first

## Approval Boundaries

- Ask before deploy commands
- Ask before editing CI, infra, or secrets-related files
- Ask before changing lockfiles unless required

Do not revert changes you did not make (“no deshagas cambios que no hiciste tú”) parece menor, pero funciona. La IA tiende a “de paso” dejar “más limpio” el código de al lado y, al hacerlo, revierte código que otra persona escribió a propósito. Sobre cómo separar los límites de aprobación lo cuento en detalle en la Guía de aprobaciones y sandbox de Claude Code, así que si trabajas en equipo échale un ojo también.

5. Para código legacy

Al reformar código viejo, la justicia no es la “limpieza”, sino “no romper nada”.

# Legacy Repo Notes

- This codebase has inconsistent patterns
- Prefer compatibility over elegance
- Preserve behavior unless the task explicitly allows change

## Investigation First

1. Explain current behavior
2. Locate the smallest responsible file set
3. Identify risks before editing

## Do Not

- Do not rename public methods casually
- Do not introduce new frameworks
- Do not rewrite files only to match modern style

Prefer compatibility over elegance (“prioriza la compatibilidad sobre la elegancia”). En proyectos legacy, esta suele ser la frase más importante. Si lo dejas a su aire, Claude Code te dirá con toda la buena intención “te lo reescribo al estilo moderno”, pero en legacy ese es justo el portal de los accidentes. Meto Do not rewrite files only to match modern style en las prohibiciones y le pongo tapa a esa buena intención.

6. Para scripts de automatización y operaciones

Envío de correos, deploys, escrituras a APIs externas… si vas a dejar que toque scripts con efectos secundarios, el primer candidato es este.

# Automation Rules

- Dry-run whenever the script supports it
- Log intended side effects before executing
- Prefer idempotent operations
- Keep secrets out of logs and generated files

## Required Checks

- Confirm environment variables used
- Confirm target environment
- Confirm output path or destination service

## Do Not

- Do not send emails, deploy, or publish without explicit approval
- Do not delete generated assets unless cleanup is requested

Log intended side effects before executing (“antes de ejecutar, escribe qué vas a provocar”) es la válvula de seguridad. Si le obligas a declarar primero “voy a enviar 120 correos a producción”, una persona puede frenarlo a tiempo. Junto con Dry-run whenever the script supports it, las operaciones irreversibles llevan siempre un freno de seguridad de por medio.

7. Para monorepos

Si conviven varias apps con paquetes compartidos, escribe primero “qué paquete tiene la responsabilidad”.

# Monorepo Map

- `apps/web/` customer app
- `apps/admin/` internal admin tool
- `packages/ui/` shared UI
- `packages/config/` lint and tsconfig presets

## Ownership Rules

- Web UI work should stay inside `apps/web/` unless the task clearly needs a shared component change
- Shared package edits require checking downstream usage
- Avoid version or config churn unless necessary

## Verification

- Run the narrowest relevant build or test command first
- Describe cross-package impact before editing shared code

Solo con escribir las Ownership Rules se reducen bastante los accidentes de edición transversal. Lo que iba a ser una pequeña corrección en apps/web/ acaba, sin que te des cuenta, metiendo mano en un componente compartido de packages/ui/ y arrastra hasta apps/admin/ hasta romperlo: ese es el accidente típico de monorepo. Haz que declare su área de responsabilidad al principio y déjale dicho “explica el impacto aguas abajo” antes de tocar código compartido.

Cómo elegir qué plantilla usar

Con 7 puestas en fila es fácil dudar, así que dejo el criterio de elección en una línea cada uno.

• UI o producto en el centro → plantilla de proyecto personal
• Hay artículos, PDF y embudo de Gumroad → plantilla de sitio de contenido
• La coherencia es sagrada → plantilla de API
• El coste de coordinación es alto → plantilla de equipo o monorepo
• El coste de un accidente es alto → plantilla legacy o automatización

No hace falta mezclar las 7. Más bien, mezclarlas alarga el archivo y baja su efecto. Toma una como base y añade solo las reglas que cambian el comportamiento en tu propio terreno. Esa es la respuesta correcta.

4 errores típicos con CLAUDE.md

Comparto, tal cual, las minas que pisé yo mismo.

Error 1. Escribirlo largo como una wiki de empresa. “Cuanto más explicación, mejor” era un malentendido total. El CLAUDE.md no es un manual, es un archivo operativo. Una regla de acción corta funciona varias veces mejor que un párrafo de contexto. Es fácil olvidar la premisa de que quien lo lee no es una persona, sino la IA.

Error 2. Escribir solo los comandos, no el procedimiento. Es muchísimo más fuerte poner si tocas billing, pasa siempre los tests que escribir solo npm run test. El comando solo comunica que “existe”. El procedimiento comunica hasta “cuándo usarlo”.

Error 3. No tener prohibiciones. Esto es lo que más pena da. No toques el .env, no digas que el deploy fue un éxito sin verificar la URL pública, no hagas force push. Una sola frase evita un accidente de toda una noche. La sección Do Not no es un adorno, es un seguro.

Error 4. No actualizarlo. Si Claude Code repite el mismo fallo tres veces, casi nunca es culpa de la IA: es que falta granularidad en el CLAUDE.md. En ese momento, en lugar de regañar, añade una línea de regla. El CLAUDE.md no se escribe y se acaba; es un archivo que se cultiva.

Preguntas frecuentes

P. ¿Dónde coloco el CLAUDE.md dentro del proyecto? R. Si lo pones en la raíz del repositorio con el nombre CLAUDE.md, Claude Code lo carga automáticamente. En un monorepo también puedes ponerlo justo dentro de cada paquete, y gana prioridad el más cercano. Cómo colocarlo de verdad y comprobar que está funcionando son solo estos dos comandos.

# Solo ponlo en la raíz del proyecto. Claude Code lo carga solo al arrancar
cat > CLAUDE.md <<'EOF'
# Project
(pega aquí la plantilla de arriba tal cual)
EOF

# Comprueba que funciona: pídele que te repita las reglas
claude -p "Dime tres reglas de Do Not que haya en el CLAUDE.md de este proyecto"

Para las reglas detalladas de colocación, consulta la documentación oficial de Claude Code.

P. ¿Funciona bien si lo escribo en español? R. Funciona. Yo a veces escribo las prohibiciones o el procedimiento en mi idioma. Aun así, dejar la plantilla en sí en inglés facilita alinearla con compañeros de otros países y con los ejemplos de fuera, así que en este artículo uso una base en inglés. Mientras el contenido se entienda, cualquiera de las dos opciones está bien.

P. ¿Mejor un CLAUDE.md largo o uno corto? R. El corto. Como referencia, que quepa más o menos en una pantalla. Cuando empiece a crecer, esa es la señal de que toca sacarlo a otro documento. En el CLAUDE.md deja solo “las reglas que cambian el comportamiento”.

P. Después de pegar la plantilla, ¿qué añado primero? R. Tres líneas de Do Not para tu propio proyecto. Una línea para “el archivo que no quieres que toquen”, otra para “la operación que no quieres que ejecute” y otra para “la mentira que no quieres oír” (por ejemplo, un informe de éxito sin verificar). Esta es la añadidura con mayor retorno.

P. ¿En qué se diferencian el CLAUDE.md y los permissions (permisos)? R. El CLAUDE.md es “petición y criterio”; los permissions son una “lista de permisos con fuerza obligatoria”. Si quieres hacer respetar de verdad las prohibiciones, usa ambos a la vez. Cómo separar los permisos lo toco también en la Guía completa para empezar con Claude Code.

El resultado de probarlo de verdad

Cuando en el CLAUDE.md solo tenía escrito el stack técnico, me ponía nervioso con cada salida de Claude Code. “¿Esta vez pasará bien los tests?”

Desde que añadí Working Rules y Do Not, esa ansiedad casi desapareció. En particular, la línea “no digas que el deploy fue un éxito hasta mirar la URL pública” se nota claramente en los números. Antes, varias veces al mes pasaba lo de “ya está desplegado” y luego en realidad un 404; desde que la metí, eso bajó a cero.

La conclusión es simple. El CLAUDE.md no es un archivo para hacer más lista a la IA, sino para evitar que la IA provoque accidentes. Añadir 3 líneas de prohibiciones funciona, en sensación, diez veces más que añadir stack. Para empezar, pega la plantilla más parecida a tu repositorio y añade solo 3 líneas de Do Not.

Si quieres profundizar más en la filosofía de diseño del propio CLAUDE.md, pásate por Cómo escribir un buen CLAUDE.md; y para la idea global del “andamiaje” que deja delegar trabajo a la IA con seguridad, lee Decirle a la IA “hazlo todo tú” es una receta para el desastre. Si quieres tener a mano una colección de plantillas y ejemplos de configuración, te serán útiles el gratuito Claude Code Quick Reference Cheatsheet y la más completa The Complete Claude Code Setup & Configuration Guide, que entra hasta en hooks y permissions. Si quieres ver todo el material de un vistazo, pásate por el catálogo de materiales; y si quieres que afinemos juntos hasta la estandarización en equipo, ve a consultoría de implementación.