Plantilla CLAUDE.md para Claude Code en proyectos existentes

CLAUDE.md reduce las explicaciones repetidas de cada sesión

Cuando usas Claude Code sobre un proyecto que ya existe, el problema no suele ser que el modelo no pueda escribir código. El problema es que empieza sin conocer las reglas locales: qué gestor de paquetes usa el equipo, dónde vive la app, qué carpetas son generadas, qué comandos son peligrosos y qué significa terminar bien una tarea.

CLAUDE.md sirve para guardar esas instrucciones persistentes. La documentación oficial de Claude Code memory explica que el archivo se carga al inicio de la sesión. También conviene recordar una diferencia importante: es contexto, no una barrera dura. Para bloquear comandos, rutas o acciones de riesgo, combínalo con settings, permisos, hooks, CI y reglas del repositorio. Para trabajos cerca de secretos o despliegues, revisa también la documentación de security.

La idea de este artículo es darte una base pequeña y práctica. Aquí harness significa el andamiaje que ayuda al agente a trabajar con límites claros. No necesitas un manual corporativo desde el primer día. Necesitas el archivo más pequeño que evite el siguiente error repetido. Para más variantes, puedes leer plantillas de CLAUDE.md y la guía de permisos de Claude Code.

Plantilla CLAUDE.md lista para copiar

La primera versión debe contener hechos que Claude Code necesita casi siempre: resumen del proyecto, comandos, límites de trabajo, reglas de calidad y criterio de finalización.

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

Guárdalo comoCLAUDE.mden la raíz del repositorio. Si ya existe unAGENTS.md, no dupliques todo. Crea unCLAUDE.mdpequeño que importe la instrucción común y añade debajo lo específico de Claude Code. Las preferencias personales van mejor enCLAUDE.local.md, no en el archivo compartido del equipo.

Usa settings para controlar lo peligroso

Escribir “no hagas push” dentro deCLAUDE.mdayuda, pero no lo bloquea. Las restricciones reales deben vivir en settings, CI o protección de ramas. Este ejemplo sirve como punto de partida para un repositorio de contenido.

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

Ponlo en.claude/settings.local.jsonsi es una protección personal o en.claude/settings.jsonsi el equipo quiere una base común. Antes de aplicarlo en producción, verifica el esquema actual en la página oficial de settings. CLAUDE.md define intención y contexto; settings define límites de ejecución.

Tres casos de uso reales

Caso de uso	Qué escribir en CLAUDE.md	Resultado
Mantenimiento de artículos localizados	slug objetivo, lista de idiomas, campos de frontmatter a conservar, longitud mínima, CTA y verificación	Menos idiomas olvidados, textos en inglés por error y enlaces rotos
Corrección pequeña en un SaaS	carpetas editables, comando de test, aprobación para base de datos, reglas de logging	Menos refactors fuera de alcance y menos migraciones peligrosas
Revisión de código en equipo	severidad, archivo, línea, impacto, reproducción y test gap	Comentarios de revisión accionables, no solo opiniones generales

En contenido multilingüe, el fallo típico es tener todos los archivos presentes pero con el cuerpo en el idioma equivocado. Indicar directorios, rutas internas y límite de description reduce mucho ese error.

En un SaaS, el límite de edición importa más que una frase genérica como “escribe buen código”. Un bug visual no debería tocar billing, auth o migraciones. Escribe que Claude Code debe leer primero, cambiar la superficie mínima y pedir aprobación antes de tocar datos.

En revisión de código, el formato de salida decide si el resultado se puede usar. Pide severidad, ruta, línea, impacto para usuario, reproducción y prueba faltante. Si quieres ejecutar revisiones desde scripts, revisa la CLI reference.

Errores comunes

El primer error es hacer el archivo demasiado largo. Un documento de 300 líneas parece serio, pero consume contexto y baja la adherencia. Mantén solo reglas que se usan a menudo. Lo específico de una carpeta debe ir a reglas por ruta o documentación separada.

El segundo error es poner secretos. No incluyas API keys, nombres de clientes, URLs internas privadas ni cifras de ingresos no publicadas. Escribe la regla de manejo: los secretos viven en variables de entorno, no se imprimen y se pide permiso antes de abrir archivos sensibles.

El tercer error es dejar comandos antiguos. Si el proyecto cambió de Yarn a npm, de Jest a Vitest o de Next.js a Astro, actualizaCLAUDE.mden el mismo cambio. Una instrucción obsoleta hace que Claude Code ejecute lo incorrecto con confianza.

El cuarto error es confundir instrucción con verificación. El archivo puede pedir que se ejecuten checks, pero no demuestra que se hayan ejecutado. Pide siempre un recibo final: comando, resultado, archivos modificados, enlaces revisados y riesgos restantes.

Cómo introducirlo sin burocracia

Empieza con la plantilla de este artículo y úsala en tres tareas pequeñas: una edición de contenido, un ajuste visual y una revisión. Después añade solo las reglas que habrían evitado un error real. Los límites que deben cumplirse siempre pasan a settings, CI, protección de ramas o aprobación de despliegue.

También hay un motivo comercial. En un sitio con productos, formularios y consultoría, los enlaces de conversión son parte del trabajo. Si Claude Code cambia texto o layout y rompe una CTA, las visitas pueden seguir mientras las ventas caen. Incluye products y training en la definition of done.

Para materiales reutilizables, prompts y checklists, empieza por ClaudeCodeLab products. Si tu equipo necesita permisos, reglas de review, formación y unCLAUDE.mdadaptado al repositorio real, usa Claude Code training and consultation. La mejor plantilla no es la más larga; es la que evita el próximo error repetido.