Buenas prácticas de CLAUDE.md: plantilla útil para Claude Code

Una solicitud de cambios vuelve por tercera vez con el mismo comentario. Claude Code modificó la función correcta, pero no ejecutó la prueba que usa el repositorio, tocó una migración que quedaba fuera del encargo o no comprobó el diseño en móvil. Repetir una explicación más larga al principio de cada sesión no resuelve ese problema de trabajo.

Un CLAUDE.md útil entrega a Claude Code unas pocas decisiones duraderas antes de empezar. No tiene que contar toda la historia de la empresa ni copiar el README. En esta guía veremos qué debe incluir, qué restricciones se aplican en otro lugar y cómo comprobar el archivo con un script real de Node.js.

Respuesta breve

CLAUDE.md debe contener los comandos, los límites de edición y los criterios de revisión que se repiten en la mayoría de las tareas de su ámbito. Estas cinco reglas sirven como punto de partida:

• CLAUDE.md ofrece instrucciones persistentes a Claude Code; no es un sistema de control de acceso.
• Las reglas compartidas van en la raíz del repositorio, las notas personales en CLAUDE.local.md y las reglas específicas de una ruta en .claude/rules/.
• Conviene mantenerlo por debajo de unas 200 líneas. Las rutas, los comandos y las condiciones de aprobación aportan más que una explicación extensa.
• Las prohibiciones de seguridad se aplican con permisos y hooks, no solo con una advertencia escrita.
• Una instrucción nueva debe probarse en una tarea pequeña y real antes de convertirse en regla del equipo.

No intente crear el documento perfecto el primer día. Revise los comentarios repetidos en las tres últimas solicitudes de cambios y conserve únicamente las decisiones que también serán necesarias en el próximo trabajo.

Qué delegar en Claude Code y qué debe decidir una persona

Un archivo de instrucciones y un límite de permisos resuelven problemas distintos. Claude Code puede examinar el código existente, hacer un cambio acotado, ejecutar comprobaciones conocidas y resumir la diferencia. Una persona sigue siendo responsable de la política de producto, la aprobación de producción y cualquier decisión relacionada con clientes, dinero, privacidad o requisitos legales.

Decisión	Delegar en Claude Code	Mantener bajo revisión humana
Investigación	Localizar archivos, patrones y pruebas relacionadas	Decidir si se pueden consultar datos de clientes o contratos
Implementación	Modificar código y pruebas dentro del alcance indicado	Aprobar cambios de precios, autorización, aspectos legales o políticas visibles para clientes
Verificación	Ejecutar lint, tipos, pruebas y build	Decidir si se cumplen los criterios de aceptación y autorizar la publicación
Mantenimiento	Informar de archivos modificados y riesgos pendientes	Añadir o retirar reglas permanentes del repositorio

En la práctica, CLAUDE.md dice: «comprueba estas cosas en este orden». No garantiza que nunca se ejecute una orden destructiva. Si git push --force, el acceso a la base de datos de producción o la lectura de archivos con secretos deben bloquearse de verdad, use reglas deny en los permisos o un hook PreToolUse. La guía de permisos de Claude Code explica esa capa de protección por separado.

Elegir el ámbito correcto antes de escribir

La ubicación del archivo determina dónde se aplican sus instrucciones. Un CLAUDE.md en la raíz sirve para reglas compartidas del proyecto. ~/.claude/CLAUDE.md se aplica a los proyectos del usuario. CLAUDE.local.md es apropiado para notas privadas de una máquina y debe añadirse a .gitignore. Los archivos anidados y las reglas limitadas por ruta evitan que un repositorio grande cargue instrucciones que no corresponden a la tarea.

La estructura puede ser tan sencilla como esta: repo/CLAUDE.md para las reglas comunes, repo/CLAUDE.local.md para notas personales, repo/.claude/rules/api.md para instrucciones de los archivos de API y repo/packages/admin/CLAUDE.md para el paquete de administración.

Al iniciar, Claude Code lee los archivos aplicables del directorio actual y de sus directorios superiores. Un CLAUDE.md anidado se carga cuando Claude lee archivos de ese subárbol. Por eso las reglas de un paquete deben vivir cerca del paquete, en vez de acumularse todas en la raíz.

Una importación como @docs/project-map.md puede ordenar mejor la información, pero no reduce el contexto: el contenido importado también se carga al iniciar. Deje en CLAUDE.md la decisión que siempre hace falta y señale la documentación detallada para leerla solo cuando la tarea la necesite. En Windows, Claude Code lee CLAUDE.md, no AGENTS.md; si ambos deben compartir instrucciones, una importación explícita @AGENTS.md resulta más fiable que depender de un enlace simbólico.

Plantilla inicial de CLAUDE.md

Los comandos y las reglas de cambio deberían caber en una pantalla. La plantilla siguiente evita frases vagas como «escribe código limpio»: nombra rutas, comprobaciones, exclusiones y el informe final que se espera del agente.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- Database schema: prisma/schema.prisma
- Tests: Vitest for units, Playwright for checkout

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

## Change rules
- Follow nearby code before adding a new abstraction.
- Do not change auth, billing, or migrations unless the task names them.
- When an API handler changes, update validation and tests together.
- Never place secrets in code, fixtures, logs, or screenshots.

## Review checklist
- Run the checks related to the changed files.
- Test an error path as well as the happy path.
- Report changed files, commands run, and skipped checks.

El archivo puede estar escrito en el idioma del equipo. La precisión importa más que el idioma. Sustituya «prueba lo necesario» por npm test, y «respeta la arquitectura» por una regla comprobable como «las respuestas de API usan src/lib/api-response.ts». Una persona revisora debe poder decidir si la instrucción se cumplió sin interpretar su intención.

Tres casos de uso reales

Los siguientes casos separan entrada, salida y revisión humana. Antes de guardar una lección en el archivo permanente, aplíquela a un trabajo pequeño y observe si cambia un resultado concreto.

Caso de uso 1: reducir comentarios repetidos en una agencia

Una agencia web puede usar convenciones de CSS, tamaños de imagen y navegadores objetivo distintos en cada repositorio de cliente. Copiar el manual completo de la agencia en todos los proyectos oculta las reglas que sí importan. Es mejor conservar entre tres y cinco comprobaciones propias de ese cliente y ese código.

Entrada: Los tres últimos hilos de revisión, los archivos dentro del alcance y los comandos actuales de lint y build.

Salida: Un informe de diferencias que indique los componentes reutilizados, las páginas modificadas, los comandos ejecutados y las condiciones de navegador que quedaron sin comprobar.

Revisión humana: La intención del diseño, los derechos de las imágenes, el texto de la llamada a la acción y el resultado final en móvil. Compare cuántas tareas regresan a revisión antes y después de diez trabajos; ese dato revela más que el número de líneas de CLAUDE.md.

Caso de uso 2: modificar de forma segura un formulario SaaS

Un formulario puede verse bien aunque fallen la validación del servidor, el correo de aviso o el tratamiento de errores. Las instrucciones del proyecto deben nombrar los archivos y pruebas que siempre cambian juntos cuando se modifica ese flujo.

Entrada: El componente del formulario, el esquema de validación, el handler de API, la plantilla de correo y las pruebas existentes.

Salida: Pruebas del recorrido correcto y de entradas inválidas, mensajes comprensibles para el usuario y una lista de ajustes modificados. El informe final también debe confirmar que no se escribió información personal en los logs.

Revisión humana: Los datos que se solicitan, el periodo de conservación, los destinatarios de las notificaciones y la salida a producción. Mida los envíos fallidos y el tiempo de soporte, además de la conversión.

Caso de uso 3: evitar publicaciones de contenido incompletas

Una página MDX puede tener un texto correcto y aun así publicarse sin description, enlace interno, imagen principal o un bloque de código utilizable en móvil. Una lista breve de publicación proporciona al agente una meta observable.

Entrada: El archivo MDX, el esquema de frontmatter, los destinos de enlaces internos, el comando de build y la URL de producción.

Salida: Longitud de la descripción, resultado de enlaces rotos, comprobación de bloques de código, estado del build y URLs revisadas en un navegador.

Revisión humana: Exactitud factual, intención de búsqueda, posición de anuncios, legibilidad y aprobación de la publicación. Revise cada semana los clics de búsqueda, la lectura con interacción y los clics en la llamada a la acción, no solo las páginas vistas.

Verificador ejecutable para CLAUDE.md

El siguiente script de Node.js comprueba el número de líneas, tres encabezados obligatorios y varios patrones de secretos de señal alta. Guárdelo como check-claude-md.mjs y ejecútelo con Node.js 20 o posterior.

import { readFile } from "node:fs/promises";

const filePath = process.argv[2] ?? "CLAUDE.md";
const text = await readFile(filePath, "utf8");
const lines = text.split(/\r?\n/);
const lineCount = text.endsWith("\n") ? lines.length - 1 : lines.length;

// Pass localized H2 names as the third argument, separated by "|".
const requiredHeadings = (
  process.argv[3] ?? "Commands|Change rules|Review checklist"
)
  .split("|")
  .map((heading) => heading.trim())
  .filter(Boolean);
const h2Headings = new Set();
let fenceMarker = null;

for (const line of lines) {
  const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
  if (fenceMatch) {
    const marker = fenceMatch[1];
    if (fenceMarker === null) fenceMarker = marker;
    else if (marker[0] === fenceMarker[0] && marker.length >= fenceMarker.length) fenceMarker = null;
    continue;
  }
  if (fenceMarker !== null) continue;

  const heading = line.match(/^##\s+(.+?)\s*$/)?.[1];
  if (heading) h2Headings.add(heading);
}

const secretPatterns = [
  ["AWS access key", /AKIA[0-9A-Z]{16}/],
  ["GitHub token", /gh[pousr]_[A-Za-z0-9]{20,}/],
  ["assigned secret", /\b(api[_-]?key|password|token)\s*[:=]\s*["'][^"'\n]{8,}["']/i],
];

const failures = [];
if (lineCount > 200) failures.push(`too many lines: ${lineCount} (max 200)`);
if (requiredHeadings.length === 0) failures.push("required heading list is empty");

for (const heading of requiredHeadings) {
  if (!h2Headings.has(heading)) failures.push(`missing h2: ${heading}`);
}

for (const [label, pattern] of secretPatterns) {
  if (pattern.test(text)) failures.push(`possible secret: ${label}`);
}

if (failures.length > 0) {
  console.table(failures.map((problem) => ({ problem })));
  process.exitCode = 1;
} else {
  console.log(`CLAUDE.md check passed: ${lineCount} lines`);
}

El comando es deliberadamente sencillo para usarlo tanto en local como en CI: node check-claude-md.mjs CLAUDE.md. Con títulos H2 traducidos, páselos como tercer argumento: node check-claude-md.mjs CLAUDE.md "Comandos|Reglas de cambio|Lista de revisión". Si devuelve código 1, corrija primero cada fila de la tabla y vuelva a ejecutarlo antes de aprobar el cambio.

Este verificador no sustituye a un escáner completo de secretos. Combínelo con el secret scanning de GitHub o con una herramienta especializada. Si aparece una credencial, revoque el valor y elimínelo del historial cuando sea necesario; borrar solo la línea visible no resuelve la exposición.

Errores frecuentes: causa y corrección

Error 1: el archivo crece después de cada revisión. La causa es convertir cualquier comentario en regla permanente sin comprobar si volverá a ocurrir. Corríjalo añadiendo solo decisiones repetidas, eliminando primero comandos obsoletos y moviendo el detalle de cada paquete junto al propio paquete.

Error 2: las instrucciones no se pueden verificar. «Mantén la calidad» o «sigue el diseño actual» no definen una condición de aprobación. Sustituya esas frases por una ruta, un comando, el código de salida esperado, un ancho de navegador o una prueba con nombre. Una persona recién incorporada debería llegar a la misma conclusión que quien escribió la regla.

Error 3: la seguridad depende de una frase. Escribir «no toques producción» no crea una barrera. Añada los patrones de comandos peligrosos a las reglas de denegación y use un hook PreToolUse cuando la operación deba detenerse de manera determinista. CLAUDE.md puede conservar el motivo y la alternativa autorizada.

Error 4: las importaciones esconden un almacén de documentación. La causa es creer que los archivos importados no consumen contexto. Se cargan al iniciar. Mantenga en la raíz una regla de decisión breve y ofrezca una ruta o URL para los detalles que Claude solo necesita en ciertas tareas.

Mantenimiento sin documentación obsoleta

Trate una modificación de CLAUDE.md como una modificación de código: abra el diff, ejecute el verificador y pruebe una tarea representativa. Retire una regla cuando ya no exista el comando, la ruta o la arquitectura que describe.

Una revisión mensual ligera puede responder cuatro preguntas:

1. ¿Qué comentario de revisión apareció más de una vez?
2. ¿Qué instrucción se ignoró o se interpretó de dos formas distintas?
3. ¿Qué comando o ruta ha quedado obsoleto?
4. ¿Qué advertencia debería convertirse en un permiso o hook?

La métrica útil no es el número de tokens ni la longitud del documento. Observe cuántas tareas regresan de revisión, qué fallos se detectan antes de integrar cambios y cuánto tiempo se dedica a explicar de nuevo la estructura del repositorio. Si esas cifras no mejoran, reescriba o elimine la regla.

Preguntas frecuentes

¿Qué longitud debe tener CLAUDE.md?

No hay un límite rígido de contenido, pero la guía oficial recomienda apuntar a menos de 200 líneas. Empezar cerca de 100 deja espacio para el mapa del proyecto, los comandos, los límites y las puertas de revisión. Mueva el material exclusivo de un paquete a archivos anidados o a .claude/rules/.

¿El archivo sigue disponible después de /compact?

El CLAUDE.md raíz vuelve a introducirse en el contexto después de la compactación. Las instrucciones anidadas y limitadas por ruta se cargan otra vez cuando Claude lee archivos coincidentes. Las decisiones duraderas deben vivir en archivos, no depender de una conversación que puede compactarse.

¿En qué se diferencia de Auto memory?

CLAUDE.md contiene instrucciones que las personas redactan y mantienen. Auto memory almacena notas locales que Claude obtiene de su experiencia, como hallazgos de depuración y preferencias. Los comandos y límites compartidos pertenecen a CLAUDE.md; un descubrimiento local permanece en Auto memory salvo que una persona decida promoverlo a regla del equipo.

¿Qué debe incluir la primera versión?

Empiece con los comandos de instalación, pruebas y build; una lista de zonas protegidas; y el contenido obligatorio del informe final. Ejecute una tarea real y añada únicamente la decisión ausente que provocó una repetición observable del trabajo.

Convertir la guía en una plantilla de proyecto

Escribir CLAUDE.md es solo una parte de un flujo fiable. Los permisos, las pruebas, el traspaso de contexto y la revisión deben expresar los mismos límites. El catálogo de materiales de ClaudeCodeLab reúne listas de comprobación y ejercicios reutilizables para convertir estas piezas en una plantilla adaptada a su proyecto.

Resultados de la prueba real

El 22 de julio de 2026 se ejecutó el código check-claude-md.mjs de este artículo contra dos archivos temporales. Una muestra válida de 10 líneas terminó con código 0 y mostró el mensaje de aprobación. La muestra negativa, preparada con un encabezado ausente y un token de prueba, terminó con código 1 y comunicó tres hallazgos: el encabezado que faltaba y dos patrones de secretos coincidentes.

La revisión también comprobó la sintaxis de JavaScript, las URLs oficiales, los enlaces internos, el frontmatter, esta sección final y la existencia de una sola llamada a la acción comercial. El comportamiento descrito se contrastó con la documentación oficial de Claude Code sobre memoria, ventana de contexto, ajustes y hooks. Ejecute ahora el verificador sobre su propio CLAUDE.md y corrija el primer problema que muestre.