Cómo se organiza un proyecto con Claude Code: qué va en cada fichero

Por Rafa Martínez y el equipo de Kalmia Zen · 7 min de lectura · Actualizada el 9 de octubre de 2026

Claude Code es un asistente de programación que trabaja dentro de tu proyecto: lee el código, ejecuta comandos y propone cambios. Lo que hace bien o mal depende mucho de lo que encuentra al entrar. Si las instrucciones están dispersas, cada sesión empieza de cero y repites lo mismo cada mañana. Si están ordenadas, cualquier persona del equipo y cualquier agente trabajan igual.

Esta guía recorre las piezas que Claude Code reconoce en un proyecto, para qué sirve cada una y cuáles usamos nosotros. No hace falta tenerlas todas: nuestro propio repositorio no las usa todas, y lo contamos más abajo.

El mapa en una tabla

CLAUDE.md: la memoria del proyecto

Se carga solo al empezar cada sesión. Puede vivir en la raíz del proyecto (o en .claude/CLAUDE.md), en carpetas superiores y en tu carpeta personal para lo que vale en todos tus proyectos. La documentación recomienda que no pase de unas 200 líneas: lo que se carga siempre ocupa contexto siempre.

Qué poner: qué es el proyecto, los comandos de verdad (instalar, probar, desplegar) y las reglas que no se discuten. Admite importar otros ficheros con @ruta, así que no hace falta copiar nada.

Nuestro CLAUDE.md tiene 62 líneas. Incluye reglas como «toda la configuración pasa por un único sitio», «toda operación con efectos respeta el modo de prueba» y «la lógica que se puede escribir en código no se deja al modelo». Son frases cortas que evitan discusiones largas.

CLAUDE.local.md es la versión personal: atajos o preferencias que sólo te importan a ti. No se excluye de git solo; añádelo tú al .gitignore.

AGENTS.md: el mismo contenido, para todas las herramientas

AGENTS.md es un formato común que leen varias herramientas de IA para programar (Codex, Cursor, Copilot…). Claude Code también lo lee por su cuenta, pero sólo si no encuentra un CLAUDE.md. Si tienes los dos, lo práctico es importarlo desde CLAUDE.md con @AGENTS.md y así no mantienes dos copias.

Nosotros lo usamos así: CLAUDE.md es corto y dice «el método de trabajo obligatorio está en AGENTS.md». AGENTS.md (148 líneas) explica cómo se trabaja: avanzar poco a poco, documentar en cada interacción, cuándo algo está «hecho» y, sobre todo, qué no hace un agente sin preguntar.

.mcp.json: los conectores del proyecto

Declara los conectores MCP que necesita el proyecto, por ejemplo una base de datos o el gestor de incidencias, para que todo el equipo tenga los mismos. La primera vez, Claude Code pide permiso antes de usar los del proyecto. Las claves no se escriben aquí: se referencian con variables (${API_KEY}). Si MCP te suena a sopa de letras, lo explicamos en qué es MCP para una empresa.

settings.json: qué puede hacer sin preguntar

Aquí se decide qué comandos puede ejecutar sin pedir permiso, qué tiene prohibido, qué hooks se lanzan, con qué modelo trabaja y qué variables de entorno ve. settings.json es el del equipo y va a git. settings.local.json es el tuyo, manda sobre el del equipo y no se comparte. Por encima de los dos puede haber una política de la organización que nadie del proyecto puede saltarse.

rules/: reglas por tema y por carpeta

Cuando CLAUDE.md empieza a crecer, las reglas se pueden partir en ficheros dentro de .claude/rules/, como estilo de código, pruebas o convenciones de la API. Lo interesante es que una regla puede llevar en su cabecera las rutas a las que aplica (paths:). Así, las reglas de pruebas sólo se cargan cuando se toca la carpeta de pruebas y no ocupan contexto el resto del tiempo.

skills/: procedimientos que se repiten

Una skill es un procedimiento escrito (.claude/skills/<nombre>/SKILL.md) que Claude usa cuando la tarea encaja o cuando la lanzas con /nombre. Al empezar sólo se carga su nombre y su descripción; el resto, cuando hace falta. Puede llevar ficheros de apoyo, como plantillas o scripts. Los antiguos comandos de .claude/commands/ siguen funcionando, pero para lo nuevo se recomiendan skills.

Tenemos 8. La que más usamos es /revision: revisa todo el sistema (servidor, tareas programadas, copias, conectores, registros) y devuelve siempre un informe con el mismo formato, lo que fallaba, lo que está bien y lo que te toca a ti. Otras planifican cada cambio grande antes de tocar código: propuesta, diseño y lista de tareas.

agents/: subagentes especializados

Un subagente es otro asistente con su propio papel, sus herramientas y, si quieres, otro modelo. Por ejemplo, un revisor de código o un auditor de seguridad. Trabaja en un contexto aparte y sólo devuelve el resultado, así que no llena la conversación principal de detalles. Puede trabajar en una copia aislada del repositorio (isolation: worktree).

Hooks: lo que no debe pasar nunca

Los hooks son scripts que se ejecutan en momentos concretos, y la documentación recoge más de 30. Por ejemplo, antes de usar una herramienta, después de editar un fichero o al empezar o terminar una sesión. Se configuran en los ajustes; guardar los scripts en .claude/hooks/ es sólo una costumbre. Un hook previo a una herramienta puede bloquearla: si un comando intenta un borrado masivo, el hook lo para y le explica a Claude por qué.

worktrees/: trabajar en paralelo sin pisarse

Un worktree es una copia de trabajo del mismo repositorio en otra rama. Claude Code los crea en .claude/worktrees/ para sesiones en paralelo o para subagentes aislados, y los borra si no cambian nada. Esa carpeta conviene añadirla al .gitignore.

Lo que hemos aprendido

• Empieza por un CLAUDE.md corto. Con los comandos y cinco reglas de verdad ya se nota. Lo demás se añade cuando duele su falta.
• Lo que repites, a una skill. Si explicas lo mismo dos veces, escríbelo una vez.
• Lo que no debe pasar nunca, a un permiso o un hook, no a una frase. El modelo puede pasar por alto una línea del texto; un permiso denegado no se lo salta.
• Ni un secreto en estos ficheros. Se comparten en git: las claves van en variables o en un gestor de contraseñas.
• Revisa la carpeta .claude/ como revisas el código. Es parte del proyecto: si cambia, que se vea en la revisión.

Qué no resuelve

Ordenar el proyecto no sustituye a una persona que revisa lo que se cambia. Tampoco hace falta usar todas las piezas: en nuestro repositorio principal todavía no hay rules/, agents/ ni hooks, porque un CLAUDE.md corto, un método claro y unas pocas skills nos cubren lo que necesitamos hoy. La estructura es una ayuda para trabajar igual cada día, no un fin en sí misma.

Fuentes

• Claude Code: memoria del proyecto (CLAUDE.md, AGENTS.md y reglas)
• Claude Code: ajustes (settings.json)
• Claude Code: skills
• Claude Code: subagentes
• Claude Code: hooks
• Claude Code: MCP
• Claude Code: worktrees

Registro de cambios

• 9 de octubre de 2026: primera versión.

Más sobre Agentes de IA

• Qué es un agente de IA (y qué no lo es)
• OpenSpec: qué es y cómo se usa para trabajar con agentes de código

← Todas las guías · Glosario