Cómo armar tu carpeta .claude/ desde cero en Claude Code

La carpeta .claude/ es donde configuras cómo se comporta Claude Code en un proyecto concreto. Mucha gente la descubre por accidente, mete un CLAUDE.md dentro y no vuelve a tocarla. Es una lástima, porque bien montada convierte una herramienta genérica en algo ajustado a tu equipo.

Esta guía la monta pieza a pieza, explicando qué hace cada archivo y en qué orden conviene añadirlos.

Qué hay dentro y para qué sirve cada cosa

La estructura básica es esta:

« tu-proyecto/ ├── CLAUDE.md ← instrucciones del proyecto └── .claude/ ├── settings.json ← configuración compartida (va a git) ├── settings.local.json ← configuración personal (no va a git) ├── skills/ ← capacidades reutilizables ├── agents/ ← subagentes especializados └── commands/ ← comandos propios (/loquesea) «

No necesitas todo desde el primer día. El orden de rentabilidad es: primero CLAUDE.md, luego settings.json, y solo cuando notes tareas repetitivas, commands/ y skills/.

Paso 1: el CLAUDE.md

Es el archivo con más impacto y el que más gente escribe mal. La clave: no es documentación, son instrucciones. Se inyecta en el contexto, así que cada línea cuesta y cada línea debe ganarse el sitio.

Lo que sí merece estar:

«`markdown

Proyecto

Estructura

• src/api/: endpoints REST
• src/domain/: lógica de negocio, sin dependencias de framework
• src/infra/: acceso a base de datos y servicios externos
• La autenticación NO está en api/, está en src/infra/auth/

Comandos

• Tests de un archivo: pnpm vitest run <ruta>
• Typecheck: pnpm tsc --noEmit
• Migraciones: pnpm prisma migrate dev

Restricciones

• No toques src/legacy/, está congelado.
• No ejecutes la suite completa de tests, tarda 8 minutos.
• No añadas dependencias sin avisar.

«`

Lo que sobra: la historia del proyecto, cómo se instala Node, qué es TypeScript y cualquier cosa que el modelo deduce solo con abrir un archivo.

El criterio para decidir: ¿esta línea evita una búsqueda, un error o una relectura? Si no, fuera.

Paso 2: settings.json y los permisos

Aquí está la ganancia de comodidad más inmediata. Por defecto, Claude Code te pide confirmación antes de ejecutar comandos. Está bien para rm -rf; es un incordio para git status por decimoquinta vez.

En .claude/settings.json defines qué se permite sin preguntar:

«json { "permissions": { "allow": [ "Bash(git status)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(pnpm vitest run:*)", "Bash(pnpm tsc --noEmit)" ], "deny": [ "Bash(git push:*)", "Bash(rm -rf:*)" ] } } «

Dos matices importantes:

• settings.json va a git, así que lo que pongas afecta a todo el equipo. Sé conservador.
• settings.local.json es tuyo y no se versiona. Ahí van tus atajos personales.

Fíjate en que los permisos van por patrón: Bash(git diff:*) permite cualquier git diff, pero no git push. Empieza permitiendo solo lecturas —status, diff, log, ls— y ve añadiendo según te canses de confirmar.

Paso 3: comandos propios

Cuando te descubras escribiendo el mismo prompt largo por tercera vez, conviértelo en comando. Un archivo en .claude/commands/ pasa a ser un /nombre que puedes invocar.

Por ejemplo, .claude/commands/revisar-pr.md:

«`markdown Revisa el diff actual centrándote en:

1. Errores de lógica que rompan casos límite
2. Consultas a base de datos dentro de bucles
3. Errores silenciados con try/catch vacíos
4. Tests que faltan para la ruta principal

No comentes estilo ni formato, de eso ya se encarga el linter. Ordena los hallazgos por gravedad. «`

A partir de ahí, /revisar-pr ejecuta esa revisión. La ventaja no es escribir menos: es que la revisión sea idéntica cada vez y que todo el equipo aplique el mismo criterio.

Los comandos aceptan argumentos, así que puedes hacerlos genéricos:

«markdown Explica qué hace el módulo $ARGUMENTS: su responsabilidad, quién lo llama y qué pasaría si lo borrásemos. «

Paso 4: skills

Una skill es un paquete de instrucciones que Claude carga solo cuando hace falta. Esa es la diferencia con CLAUDE.md, que está siempre presente: las skills no consumen contexto hasta que se activan.

Se guardan en .claude/skills/<nombre>/SKILL.md con una cabecera que describe cuándo usarlas:

«`markdown

name: desplegar description: Despliega a producción. Úsala cuando pidan desplegar, publicar o subir una versión a producción.

Despliegue

1. Comprueba que la rama es main y está limpia.
2. Ejecuta pnpm build y aborta si falla.
3. Lanza pnpm test:e2e contra staging.
4. Solo si todo pasa: pnpm deploy:prod.
5. Verifica /health y avisa del resultado.

Nunca despliegues un viernes por la tarde sin confirmación explícita. «`

El campo description es el que decide si la skill se activa, así que escríbelo pensando en las palabras que usará quien la necesite, no en la jerga interna.

Las skills son el sitio natural para procesos con pasos que la gente se salta: despliegues, migraciones, altas de cliente, cierres de mes.

Paso 5: subagentes

Un subagente es una configuración especializada que trabaja en su propio contexto. Van en .claude/agents/ y sirven para tareas que ensucian mucho la conversación principal: exploraciones largas, auditorías, búsquedas amplias.

«`markdown

name: auditor-seguridad description: Revisa código en busca de vulnerabilidades tools: Read, Grep, Glob

Eres un auditor de seguridad. Busca:

• Entradas de usuario sin validar que lleguen a consultas SQL
• Secretos escritos en el código
• Endpoints sin comprobación de autorización

Reporta solo lo explotable, con archivo y línea. No propongas mejoras de estilo. «`

Fíjate en tools: solo lectura. Un auditor no debería poder escribir. Restringir herramientas es una forma sencilla de evitar sorpresas.

Un consejo práctico: no crees subagentes por gusto. Cada uno arranca sin contexto y tiene que redescubrir el proyecto, así que solo compensan cuando la tarea es lo bastante grande como para justificar ese arranque en frío.

En qué orden montarlo de verdad

Si empiezas de cero, este es el camino que menos tiempo pierde:

1. Semana 1: solo CLAUDE.md, con rutas y comandos. Nada más.
2. Semana 2: añade permisos en settings.json para lo que más te canse confirmar.
3. Cuando repitas un prompt 3 veces: conviértelo en comando.
4. Cuando un proceso tenga pasos que la gente se salta: hazlo skill.
5. Cuando una tarea te ensucie el contexto: plantéate un subagente.

El error habitual es justo al revés: montar cinco subagentes y doce skills el primer día, sin saber aún dónde está el cuello de botella. Acabas manteniendo configuración que nadie usa.

Cómo saber si va bien

Una carpeta .claude/ sana se nota en tres señales:

• Dejas de repetir contexto. Si sigues explicando dónde está la autenticación, falta una línea en CLAUDE.md.
• Confirmas menos. Si confirmas el mismo comando a diario, falta un permiso.
• Los resultados son consistentes. Si la misma petición da resultados distintos según quién la haga, falta un comando o una skill que fije el criterio.

Y una señal de que va mal: archivos que nadie recuerda haber escrito. Revisa la carpeta cada pocas semanas y borra lo que ya no aplique. La configuración obsoleta no es neutral: confunde y cuesta contexto.