7 plantillas de CLAUDE.md para Claude Code que puedes copiar en proyectos reales

Muchos artículos sobre CLAUDE.md terminan en “describe tu stack”. Eso no está mal, pero no basta cuando Claude Code empieza a tocar trabajo real.

La pregunta útil no es “¿debería tener un CLAUDE.md?” La pregunta útil es: ¿qué debe decir para que Claude Code deje de cometer los mismos errores en este repo?

Esta guía cubre ese hueco entre la guía para principiantes y CLAUDE.md Best Practices con siete plantillas copiables.

Ruta corta:

1. Ten a mano el Claude Code Quick Reference Cheatsheet.
2. Copia la plantilla más cercana a tu repositorio.
3. Añade primero tres reglas de Do Not.
4. Si quieres más ejemplos de templates, hooks y permissions, pasa a The Complete Claude Code Setup & Configuration Guide.
5. Si necesitas estandarizar esto para un equipo, usa la consultation page.

Qué hace de verdad un buen CLAUDE.md

Debe reducir tres fallos:

• Claude Code edita la zona correcta pero rompe la convención local.
• Resuelve la tarea pero se salta la verificación importante.
• Explora demasiados archivos porque los límites del repo no están claros.

Por eso suele necesitar:

• stack y comandos
• mapa de directorios
• reglas específicas del proyecto
• orden de trabajo recomendado
• prohibiciones

Las dos últimas cambian más el comportamiento que una larga descripción técnica.

Plantilla 1: app web individual

# 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

La línea decisiva aquí no es el stack. Es exigir validación móvil y comprobación de la URL pública.

Plantilla 2: sitio de contenido con CTAs de ingresos

# 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

Si el negocio depende de artículos, PDF gratis, Gumroad y consultas, esta plantilla es más útil que una plantilla técnica genérica.

Plantilla 3: repo de API backend

# 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

Summarize risk in plain English obliga a Claude Code a hablar del impacto en vez de tratar todo como rutinario.

Plantilla 4: repo de equipo con review estricta

# 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

El problema típico de equipo no es falta de velocidad, sino diffs difíciles de revisar.

Plantilla 5: rescate de código legacy

# 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

En legacy, compatibility over elegance suele ser la frase más valiosa de todo el archivo.

Plantilla 6: scripts y automatización

# 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

Si el repo toca deploys, emails o APIs de terceros, esta plantilla suele ser la mejor base.

Plantilla 7: monorepo

# 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

Muchos errores en monorepos aparecen cuando Claude Code cruza límites de paquetes demasiado rápido.

Errores a evitar

• Escribir un wiki entero dentro de CLAUDE.md
• Poner comandos pero no el orden de trabajo
• No incluir reglas de prohibición
• No actualizar el archivo cuando el mismo error se repite

Qué plantilla elegir

• App o UI: plantilla individual
• Sitio con artículos, PDF y Gumroad: plantilla de contenido
• Datos y validación: plantilla API
• Coordinación y límites: plantilla de equipo o monorepo
• Riesgo alto por errores: plantilla legacy o automatización

No necesitas mezclar las siete. Empieza con una y añade solo reglas que cambien el comportamiento.

Siguiente paso

1. Copia una plantilla en CLAUDE.md
2. Añade tres reglas de Do Not
3. Define la verificación exacta que significa “terminado”

Si quieres una referencia rápida, usa primero el Claude Code Quick Reference Cheatsheet. Si quieres más ejemplos completos de CLAUDE.md, setup, hooks, permissions y workflow, sigue con The Complete Claude Code Setup & Configuration Guide. Si necesitas convertir esto en una práctica de equipo, usa la consultation page.