Cómo configurar un proyecto de Claude Code (y qué va dónde)

Es fácil improvisar prompts con Claude Code porque entiende el contexto tan bien que puedes farolear tu camino hasta un proyecto "que funciona" y largarte. Pero tienes que construir un repo de Claude como Dios manda si quieres retomar fácilmente donde lo dejaste. Hoy vamos a ver la estructura adecuada de un proyecto de Claude Code, incluido el conocido archivo CLAUDE.md.

---

El problema de improvisar los prompts

La mayoría usa Claude Code como yo solía: abrir la terminal, empezar a teclear y rezar. Está bien para scripts desechables y preguntas puntuales. Pero en cuanto construyes algo de verdad a lo que volverás mañana, en cualquier formato, te encuentras re-explicando todo tu proyecto en cada sesión. Tu arquitectura, tu ejecutor de tests, por qué esa carpeta está generada y no debe editarse, todo, desde cero, cada vez. Esto hoy es menos problema que hace unos meses; aun así, la higiene es un componente clave para aprender a crear.

Claude Code no arrastra nada de tu última conversación por defecto. No tiene ni idea de que tu proyecto usa el modo estricto de TypeScript, de que tus tests viven en carpetas __tests__/, de que tienes un monorepo donde cada paquete necesita un comando de build distinto. Lo deducirá en parte leyendo tu código, pero eso quema tokens de contexto (que no son gratis, y tengo las facturas para demostrarlo) y a veces adivina mal.

Haciendo algo de investigación de palabras clave para crecer, este sitio de hecho.

La carpeta .claude/ y el archivo CLAUDE.md resuelven esto. Son la memoria de proyecto de Claude: un conjunto de archivos que se cargan automáticamente al inicio de cada sesión, dándole a Claude las reglas, permisos y contexto arquitectónico que necesita sin que tengas que repetirte.

Si has usado Cursor, reconocerás el concepto: tienen .cursor/rules/, Windsurf tiene .windsurf/rules/, misma idea general. La versión de Claude Code va más lejos que ambas (skills que se disparan automáticamente, subagentes con acceso restringido a herramientas, un modelo de permisos como Dios manda), pero el principio subyacente es idéntico: describes tu proyecto una vez y la IA lo recuerda en cada sesión.

¿Qué hay en la carpeta .claude/?

Esto es lo que parece un proyecto maduro de Claude Code (más o menos a lo que han evolucionado mis propios repos a lo largo de unos seis meses):

my-project/
├── CLAUDE.md                  # Team instructions (committed to git)
├── CLAUDE.local.md            # Personal overrides (gitignored)
│
└── .claude/
    ├── settings.json          # Permissions + MCP server config
    ├── settings.local.json    # Personal permission overrides (gitignored)
    │
    ├── rules/                 # Modular, path-scoped instruction files
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    │
    ├── skills/                # Auto-invoked workflows + slash commands
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/                # Specialised subagent personas
        ├── code-reviewer.md
        └── security-auditor.md

No todos los proyectos necesitan todo esto, y el mío desde luego no empezó así. Mis repos más pequeños siguen teniendo solo un CLAUDE.md y un settings.json. Los más grandes —como mi sistema de producción de contenidos— crecieron hasta la configuración completa con reglas, skills y agentes personalizados con el tiempo.

CLAUDE.md: el archivo cerebro

Todo en la carpeta .claude/ se construye sobre este archivo. Claude lo lee al iniciar una sesión y lo mantiene cargado durante toda la conversación, así que lo que escribas aquí da forma a cada respuesta que recibes. Le dices que escriba siempre los tests antes de la implementación, y lo hará. Le dices que nunca use console.log para el manejo de errores, y no lo hará.

La forma más rápida de empezar es ejecutar /init: Claude escanea tu codebase, lee tu package.json, inspecciona la estructura de carpetas, comprueba los frameworks de test y genera un CLAUDE.md de inicio. Es muy bueno detectando tu stack (identificó correctamente Vitest en uno de mis repos donde incluso yo había olvidado que había cambiado desde Jest).

Pero trata la salida de /init como un primer borrador. No puede adivinar tu lógica de negocio ni las decisiones arquitectónicas que tomaste hace seis meses y que no se deducen del código. Yo siempre pelo el archivo generado hasta quizá la mitad de su longitud original y luego añado lo que de verdad importa: las convenciones, las trampas, las advertencias de "no toques esta carpeta".

Esto es más o menos lo que debería ir ahí:

## Commands
npm run dev          # Start dev server
npm run test         # Run tests (Vitest)
npm run lint         # ESLint check
npm run build        # Production build

## Architecture
- Express REST API, Node 20, TypeScript strict
- PostgreSQL via Prisma ORM
- Handlers in src/handlers/, shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run npm run db:test:reset first
- Strict TypeScript: no unused imports, ever

Eso son quizá 20 líneas, y le da a Claude todo lo que necesita para trabajar productivamente en este codebase en particular. Fíjate en lo que no está ahí: ni documentación completa de la API, ni guía de estilo, ni esquema de la base de datos. Solo las cosas que Claude podría hacer mal si no se las dices.

La documentación oficial tiene una buena heurística para esto: "Para cada línea, pregúntate: si la quitara, ¿Claude cometería errores? Si no, córtala". Yo iría más lejos, de hecho: mantén todo el archivo por debajo de 200 líneas. Los archivos más largos empiezan a devorar demasiado contexto y la adherencia de Claude a las instrucciones cae de hecho (el problema de la aguja en el pajar, del que he escrito en el contexto de gestionar costes).

Qué NO poner en CLAUDE.md

No vuelques aquí toda tu documentación. Lo veo constantemente: alguien crea un CLAUDE.md de 500 líneas con su referencia completa de la API, su guía de estilo entera, tres párrafos explicando su esquema de base de datos. Claude ignora la mitad. Las reglas importantes quedan enterradas bajo 400 líneas de contexto que no necesitaba.

• Configuración de linter y formateador: deja que tus herramientas lo gestionen vía hooks
• Documentación completa: enlázala, no la inline
• Información que cambia con frecuencia: quedará obsoleta
• Cosas que Claude ya sabe leyendo código: convenciones estándar del lenguaje, patrones obvios

Puedes usar importaciones con @ para referenciar otros archivos sin inlinearlos: @docs/git-workflow.md o @README.md. Claude los carga bajo demanda sin inflar permanentemente el contexto.

CLAUDE.local.md: tus anulaciones personales

A veces tienes preferencias que son solo tuyas, no de todo el equipo. Quizá tu Postgres local corre en el puerto 5433, o usas podman en vez de Docker, o estás a mitad de un refactor y quieres que Claude ignore ciertos tests que fallan por ahora.

Para eso está CLAUDE.local.md: déjalo en la raíz de tu proyecto y Claude lo lee junto al CLAUDE.md principal, pero se gitignored automáticamente, así que tus ajustes personales nunca aterrizan en el repo compartido.

Reglas: para cuando CLAUDE.md se llena

Cuando tu proyecto crece y tu CLAUDE.md empieza a pasar de 200 líneas, pártelo. Cada archivo markdown dentro de .claude/rules/ se carga junto a CLAUDE.md automáticamente.

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

Cada archivo se centra en un único asunto, lo que también significa que la persona responsable de las convenciones de la API edita api-conventions.md, el responsable de testing edita testing.md, y nadie pisa las reglas de los demás.

Pero la verdadera ventaja aquí son las reglas con ámbito de ruta: añades frontmatter YAML y la regla solo se activa cuando Claude toca archivos que coinciden:

---
description: Standards for API route handlers
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules

- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients

Claude no cargará esta regla cuando esté editando un componente de React: solo se dispara al trabajar dentro de src/api/ o src/handlers/, lo que mantiene tu contexto limpio y enfocado. Las reglas sin campo paths se cargan incondicionalmente en cada sesión, así que usa el ámbito por ruta siempre que tenga sentido.

Skills: flujos de trabajo reutilizables

Los skills son flujos de trabajo que Claude puede invocar automáticamente cuando la tarea encaja, sin que tú teclees un comando slash. Cada skill vive en su propio subdirectorio con un SKILL.md:

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

El SKILL.md usa frontmatter YAML para describir cuándo activarse:

---
name: security-review
description: Security audit. Use when reviewing code for vulnerabilities
  or before deployments.
---
Analyse the codebase for security vulnerabilities:

1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations

Report findings with severity ratings and remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

Cuando dices "revisa este PR por problemas de seguridad", Claude reconoce la coincidencia e invoca el skill. O puedes llamarlo explícitamente con /security-review si quieres ser deliberado.

Una cosa que me gustaría que los blogs mencionaran con más claridad: los comandos se han fusionado con los skills. La carpeta .claude/commands/ sigue funcionando por compatibilidad hacia atrás, pero los skills son donde Anthropic está poniendo el esfuerzo de desarrollo de cara al futuro. Los skills pueden agrupar archivos de apoyo junto a ellos (como esa referencia a DETAILED_GUIDE.md de arriba), aceptan $ARGUMENTS y se disparan automáticamente según el contexto de la tarea; los comandos siempre fueron archivos únicos sin esa flexibilidad. Conclusión: si estás configurando un proyecto nuevo hoy, no te molestes con la carpeta de comandos: ve directo a los skills.

Uso los skills a tope en mi flujo de desarrollo de servidores MCP: tengo un skill de TDD que aplica el desarrollo test-first, un skill de revisión de código y un checklist de despliegue. Solo el de TDD me habrá salvado de publicar código roto una docena de veces. (Soy del tipo que escribe primero la implementación y "planea añadir tests luego". El skill no me deja salirme con la mía.)

Agentes: subagentes especialistas

Para tareas que necesitan atención enfocada sin ensuciar tu conversación principal, define personalidades de subagente en .claude/agents/:

---
name: code-reviewer
description: Reviews code for bugs and maintainability issues
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer. Focus on:
- Bugs, not style issues
- Specific fixes, not vague improvements
- Edge cases and error handling gaps

El campo tools restringe lo que el agente puede hacer, y debes pensarlo con cuidado. Un auditor de seguridad necesita Read, Grep y Glob; no debería poder escribir archivos, así que no le des acceso a Write. El campo model te permite elegir un modelo más barato y rápido para tareas enfocadas (Sonnet maneja bastante bien la exploración de solo lectura; reserva Opus para el trabajo de razonamiento pesado donde de verdad lo necesites).

Lo que hace que los agentes merezcan la configuración, sin embargo, es que tienen su propia ventana de contexto totalmente separada de la tuya. Explorarán tu codebase, leerán decenas de archivos, comprimirán todo lo que encuentran y te devolverán un resumen; y tu sesión principal se mantiene limpia porque no has quemado contexto en toda esa exploración intermedia.

settings.json: permisos

El archivo .claude/settings.json controla lo que Claude puede y no puede hacer:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Los comandos en la lista de permitidos se ejecutan sin preguntar. Los denegados se bloquean por completo. Todo lo demás dispara un aviso de permiso.

Sin este archivo, tendrás lo que yo llamo "fatiga de aprobación": Claude pide permiso para npm run test cuarenta veces al día y al final dejas de leer los avisos y le das a sí a todo. En cuyo punto todo el modelo de seguridad es teatro. Lo aprendí por las malas cuando casi dejé que Claude ejecutara un comando destructivo de base de datos porque iba en piloto automático. Configura tu lista de permitidos el día uno, antes de que ese hábito se asiente.

También puedes tener un settings.local.json para anulaciones de permisos personales, misma idea que CLAUDE.local.md. Se gitignored automáticamente.

Proyecto frente a global

En realidad hay dos directorios .claude, lo que me confundió más tiempo del que me gustaría admitir:

A nivel de proyecto (./.claude/) vive en tu repo, commiteado en git, así que todo el equipo tiene las mismas reglas, skills y permisos. Toda tu configuración específica de proyecto va aquí.

Global (~/.claude/) vive en tu directorio home y se aplica a todos los proyectos en los que trabajas. Almacena tus preferencias personales, el historial de sesiones, la auto-memoria por proyecto y cualquier skill personal que hayas construido.

Tu ~/.claude/CLAUDE.md global se carga en cada sesión independientemente del proyecto en el que estés: yo pongo cosas como "prefiero respuestas concisas" y "usa siempre patrones funcionales" en el mío. Cuando hay un conflicto entre los ajustes de proyecto y los globales, gana el archivo a nivel de proyecto, que es lo que esperarías.

También hay un sistema de auto-memoria escondido en ~/.claude/projects/: Claude se guarda notas para sí mismo mientras trabaja, cosas como comandos que descubre, patrones que nota, ideas sobre la arquitectura que capta. Estas notas persisten entre sesiones y puedes navegarlas con /memory. No esperaba usarlas mucho, pero resultan bastante útiles. Claude recordó que uno de mis repos tenía un paso de build peculiar que yo mismo había olvidado.

La configuración en cinco pasos

Si empiezas desde cero, esta es la progresión que uso:

Paso 1: Ejecuta /init y luego edita de inmediato lo que produce. El CLAUDE.md generado es un punto de partida sólido pero será demasiado largo y demasiado genérico. Pélalo, añade las convenciones de tu equipo y las trampas que no se deducen del código.

Paso 2: Crea .claude/settings.json con tus listas de permitidos y denegados. Como mínimo, permite tus comandos de build y test y deniega las lecturas de .env. Esto elimina el problema de la fatiga de aprobación desde el día uno (no puedo exagerar lo mucho que mejora el flujo de trabajo una vez que no estás cliqueando "permitir" cada treinta segundos).

Paso 3: Construye uno o dos skills para los flujos de trabajo que repites más a menudo. Revisión de código y arreglo de issues son buenas elecciones iniciales: ponlos en .claude/skills/ con un SKILL.md que describa cuándo deben activarse.

Paso 4: Parte CLAUDE.md en rules/ cuando se llene. Cuando pases de 200 líneas (y lo pasarás, tarde o temprano), divide las instrucciones en archivos .claude/rules/ y dales ámbito por ruta donde tenga sentido.

Paso 5: Configura ~/.claude/CLAUDE.md para tus preferencias personales entre proyectos. Cosas como "prefiero el modo estricto de TypeScript" o "usa siempre inglés británico en los comentarios": lo que quieres en todos los proyectos independientemente del equipo.

Eso es todo lo que necesitas para el 95 % de los proyectos. Los agentes y los hooks llegan después, cuando tienes flujos de trabajo complejos recurrentes que justifican el coste de configuración. No añadí mi primer agente personalizado hasta unos cuatro meses de uso diario de Claude Code, y deseé haberlo hecho antes.

Si te llevas una sola cosa de este artículo, que sea esta: deja tu CLAUDE.md bien antes de tocar nada más. Pasé meses sin uno y la diferencia una vez lo añadí fue inmediata: menos errores, menos repetición, menos yo tecleando las mismas instrucciones en cada sesión. Reglas, skills, agentes, hooks: todo se construye sobre los cimientos de un buen CLAUDE.md. Mantenlo por debajo de 200 líneas, manténlo honesto y actualízalo cuando tu proyecto cambie.

---