La estructura lógica de un proyecto.
Claude Code tiene su propia arquitectura de carpetas nativa. Conocerla significa que el agente sabe exactamente dónde buscar cada tipo de instrucción — sin que tengas que decírselo cada vez.
La anatomía de un proyecto
Tres capas de información, cada una con un propósito y un comportamiento distintos.
Capa nativa de Claude Code
CríticoCLAUDE.md y la carpeta .claude/ son la arquitectura oficial. Claude las lee automáticamente. Todo lo que pongas aquí tiene prioridad absoluta.
Capa de contexto del proyecto
Importante/docs/ y /design-system/ son tuyas, en markdown. Claude las lee cuando se lo pides o cuando una skill le indica que las consulte.
Capa de conexiones externas
Opcional.mcp.json conecta el agente con Figma, Supabase, GitHub, Slack. La capa que convierte Claude Code en un agente que actúa fuera del proyecto.
Estructura del proyecto
Qué hace cada pieza
Los 6 elementos clave de la arquitectura de un proyecto para Claude Code.
El cerebro del proyecto
Crítico· se carga siempreCLAUDE.md
Lo primero que lee Claude al abrir el proyecto. Contiene el contexto permanente: quién eres, cómo trabajas, qué no hacer.
máx. ~300 líneas recomendado
Slash commands del equipo
Nativo· carpeta oficial.claude/commands/
Archivos .md que se convierten en comandos reutilizables. Escribes /handoff y Claude ejecuta el proceso completo.
ej: /handoff — /audit — /review
Instrucciones especializadas
Nativo· carpeta oficial.claude/skills/
Instrucciones profundas con proceso, formato de salida y qué leer antes de actuar. Se cargan solo cuando la tarea las requiere.
detalle en sección 05
Permisos y automatizaciones
Nativo· configuración.claude/settings.json
Controla qué puede hacer el agente, qué archivos puede modificar y qué pasa antes y después de cada acción (hooks).
avanzado
Documentos de referencia
Tuyo· contexto del proyectodocs/
Visión de producto, arquetipos de usuario, análisis competitivo, decisiones tomadas. Claude los consulta cuando la tarea lo requiere.
detalle en sección 04
El sistema de diseño documentado
Tuyo· design systemdesign-system/
Tokens, componentes, naming conventions. Claude lo consulta para asegurarse de que cualquier propuesta encaja con el sistema real.
tokens — componentes — naming
Reglas de la documentación oficial
5 reglas que Anthropic recomienda para la documentación de proyectos con Claude Code.
1. CLAUDE.md es conciso, no exhaustivo
La documentación oficial recomienda menos de 300 líneas. Cada línea compite con el trabajo real. Lo específico de una tarea va a una skill, no al CLAUDE.md.
2. Usa /init para generar el primer borrador
Claude Code analiza tu proyecto y genera un CLAUDE.md inicial. Úsalo como punto de partida y elimina lo que no aplique. Borrar es más fácil que crear desde cero.
3. Versiona todo en git, incluyendo .claude/
La carpeta .claude/ debe estar en el repositorio para que todo el equipo comparta las mismas instrucciones. Solo settings.local.json va en el .gitignore.
4. Nunca pongas credenciales en archivos de contexto
CLAUDE.md forma parte del system prompt. Trátalo como documentación pública. Las credenciales van en variables de entorno.
5. El decisions-log.md es el documento más infravalorado
Cada decisión descartada se apunta aquí con el razonamiento. El agente no volverá a proponer lo que ya rechazasteis. Y cuando alguien se incorpora, tiene el contexto en minutos.
Recursos oficiales
Cursos gratuitos de Anthropic y DeepLearning.AI para profundizar en Claude Code.
Claude Code: A Highly Agentic Coding Assistant
learn.deeplearning.ai
DeepLearning.AI — Gratuito
Curso oficial con Andrew Ng. Desde fundamentos hasta multi-agente, git worktrees y MCP.
Claude Code in Action
anthropic.skilljar.com
Anthropic Academy — Gratuito + Certificado
Curso oficial de Anthropic con certificado. Flujo completo de Claude Code en workflows reales.
Agent Skills, MCP y más
anthropic.skilljar.com
Anthropic Academy — Catálogo completo
Skills en Claude Code, Model Context Protocol intro y avanzado, Claude 101.
Clave
Esta arquitectura no es arbitraria — es la que Claude Code entiende de forma nativa. Cuanto más te ciñas a ella, menos tendrás que explicarle al agente dónde están las cosas.