Buenas prácticas de CLAUDE.md: plantilla práctica para proyectos reales

CLAUDE.md evita repetir en cada sesión la arquitectura, los comandos y las reglas del proyecto. No es una política de seguridad ni un lugar para pegar toda la documentación.

Las reglas del equipo deben ser breves, verificables y cercanas al código; las preferencias personales van a archivos locales, y las restricciones fuertes se aplican con permissions y hooks. Este artículo explica qué debe vivir en CLAUDE.md y qué conviene dejar fuera, con un enfoque práctico para principiantes.

El objetivo es empezar con una plantilla copiable y permitir que el equipo la revise sin convertirla en una enciclopedia.

Core idea: CLAUDE.md is guidance, not enforcement

Las reglas del equipo deben ser breves, verificables y cercanas al código; las preferencias personales van a archivos locales, y las restricciones fuertes se aplican con permissions y hooks. Según la documentación oficial, CLAUDE.md es guía contextual, Auto memory guarda aprendizajes locales, settings configuran el cliente y hooks ejecutan comandos en eventos concretos.

Mechanism	Role	Best for
CLAUDE.md	Human-written persistent guidance	Conventions, architecture, verification commands
Auto memory	Claude’s local learned notes	Debugging insights, preferences, repeated discoveries
settings / permissions	Client configuration and permission rules	Allow, deny, extra directories
hooks	Commands run at lifecycle events	Blocking risky actions, verification, formatting

Where to place CLAUDE.md files

Claude Code lee CLAUDE.md y CLAUDE.local.md desde el directorio de trabajo hacia arriba. Las reglas raíz entran al inicio; las reglas anidadas aparecen al leer archivos relacionados. Las reglas compartidas van en la raíz y las notas personales en un archivo local.

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

What to keep in always-loaded memory

En la memoria siempre cargada pon comandos de build, tests, límites de arquitectura, reglas de nombres, patrones prohibidos y puertas de revisión. Deja fuera secretos, logs largos, actas, planes de una sola tarea e investigación extensa.

• Keep build, test, lint, type-check, and release verification commands.
• Keep edit boundaries, non-edit boundaries, naming rules, and review gates.
• Do not keep secrets, long meeting notes, historical logs, or one-off task instructions.
• Do not paste entire official docs. Keep the URL and the decision rule.

Copy-paste CLAUDE.md template

La plantilla siguiente es breve para no inflar el contexto. Adáptala al proyecto y escribe reglas que se puedan verificar.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

Use imports and .claude/rules carefully

Los imports @path ayudan a organizar, pero no ahorran tokens. El contenido importado también entra al contexto. En proyectos grandes, borra contenido viejo y mueve reglas por ruta a .claude/rules/.

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

Three practical use cases

1. Los tres casos más útiles son onboarding, corrección de bugs y producción de contenido con enlaces internos. En onboarding, escribe primero el mapa del proyecto y los comandos de verificación.
2. En bugs, incluye comando de reproducción, ubicación de logs y test mínimo para reducir exploración inútil.
3. En contenido, guarda tono, enlaces internos y quality gates en CLAUDE.md; deja notas largas en Obsidian o docs.

Failure cases and pitfalls

1. El fallo típico es importar todo el README, escribir reglas vagas o confiar en CLAUDE.md para seguridad. La solución es dejar solo reglas siempre necesarias y leer detalles bajo demanda.
2. Sustituye “déjalo limpio” por comandos exactos y límites de archivos.
3. La seguridad fuerte requiere permissions y PreToolUse hooks; CLAUDE.md no basta.

Team maintenance rule

Actualiza CLAUDE.md solo cuando se repite un error, se repite un comentario de review, cambia un comando o cambia un límite arquitectónico.

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

Next step and monetization path

Para un flujo completo, combínalo con Obsidian, optimización de tokens y la página de consultoría. El flujo completo conecta bien con Obsidian, optimización de tokens y la página de consultoría. Related articles: Obsidian workflow, productivity tips, permissions guide, and consultation page.

What was verified

Esta actualización sigue la documentación oficial de memory, context window, settings y commands. Official references: memory, context window, settings, and commands.