Estructura de proyecto Claude Code: que tu IA piense como un ingeniero

Introducción

Muchos desarrolladores tratan a Claude Code (o cualquier LLM) como una supuesta “autocomplete mejorada”: abren un archivo, escriben un prompt y esperan que el resultado sea perfecto. A veces funciona, otras veces falla, pierde contexto o repite errores iniciales. El problema no es solo el modelo: es la estructura del proyecto. Un LLM no es una característica aislada; es el núcleo de un sistema que necesita memoria, reglas, rutas y documentación programática.

En esta guía proponemos una arquitectura de repositorio que convierte a Claude Code en un colaborador consistente. Tomamos como ejemplo un sistema cloud de gestión de incidentes llamado respondly (ingesta de alertas, clasificación, generación de runbooks, enrutamiento y seguimiento). Pero el patrón sirve para cualquier sistema impulsado por LLM.

El error conceptual más común

La creencia más extendida es: “usa un LLM y ya está”. Eso no es suficiente. Un sistema de clase producción requiere:

• Pipelines de datos (ingesta → fragmentación → embeddings)
• Recuperación híbrida (search + re-ranking)
• Memoria (caching semántico, recall en memoria)
• Routing (selección de fuente con fallback)
• Generación estructurada
• Evaluación offline/online
• Seguridad y observabilidad
• Infraestructura asíncrona y containerizada

La mayoría de los equipos se detiene en las llamadas a la API. Para avanzar, hay que organizar el repositorio: la estructura determina qué tan bien Claude Code puede operar con contexto, reglas y workflows.

Los cuatro componentes que Claude Code necesita para pensar como un ingeniero

Antes de crear carpetas, recuerden las cuatro piezas indispensables que debe conocer el modelo:

1. El porqué: qué hace cada componente y por qué existe
2. El mapa: dónde está todo (archivos, endpoints, dependencias)
3. Las reglas: lo permitido y lo prohibido
4. El flujo de trabajo: cómo se completa una tarea de inicio a fin

Cada carpeta en el directorio respondly/ debe cumplir alguna de estas funciones. Nada es accidental.

CLAUDE.md raíz: la memoria de arranque

CLAUDE.md en la raíz no es documentación extensa: es la memoria base que el modelo revisa al comenzar. Piensen en darle a un ingeniero nuevo un resumen claro el primer día. Debe ser breve (máximo tres secciones), directo y sin filosofías largas. Si CLAUDE.md se vuelve demasiado extenso, el modelo puede perder las instrucciones clave.

Qué incluir: misión del proyecto, responsabilidades principales del agente y los límites operativos. Lo esencial: claridad sobre el objetivo y el rol de Claude dentro del repositorio.

.claude/skills: modos expertos reutilizables

Un gran beneficio de Claude Code es poder pasar de generalista a especialista mediante “skills” reutilizables. Estas instrucciones codificadas permiten que Claude ejecute procesos sin re-explicarlos cada vez.

Ejemplos (en respondly):

• triage-review/SKILL.md: cómo revisar severidad, detectar falsos positivos y validar la clasificación
• runbook-gen/SKILL.md: formato y campos obligatorios para generar runbooks
• eval-run/SKILL.md: cómo ejecutar evaluación offline y qué métricas usar

Definir estos skills una sola vez garantiza salidas consistentes y de calidad para todo el equipo.

.claude/rules: guardrails que no se olvidan

Los modelos tienden a olvidar detalles; las reglas no. Aquí van las políticas innegociables del proyecto:

• code-style.md: formato, orden de imports, tipos y convenciones para todos los archivos
• testing.md: cuándo y cómo deben correr los tests, umbrales de cobertura, módulos protegidos

Consideren estas reglas como contratos que acompañan cualquier output generado por Claude. Así se evita que un buen prompt produzca código que no cumple normas de producción.

.claude/Docs: contexto progresivo, no sobrecarga de prompt

No intenten poner toda la información en un mismo prompt. En vez de eso, armen documentación modular que Claude pueda consultar por secciones cuando sea necesario.

En respondly esta carpeta contiene, entre otros:

• architecture.md: diseño general, relaciones entre componentes y flujo de datos
• api-reference.md: especificaciones de endpoints y esquemas
• deployment.md: instrucciones de infraestructura, variables de entorno y contenedores

Este enfoque reduce la carga cognitiva y permite a Claude acceder a contexto puntual sin sobresaturar.

ARCHIVOS CLAUDE.md locales: contexto para zonas de riesgo

Además del CLAUDE.md global, mantengan CLAUDE.md locales en subcomponentes críticos (por ejemplo, el módulo de enrutamiento o el generador de runbooks). Son resúmenes específicos que aclaran expectativas y límites operativos en áreas donde un error puede ser costoso.

Por qué la capa agents/ es la verdadera capa de inteligencia

Los agentes o la capa “agents/” encapsulan la lógica que orquesta llamadas, maneja fallbacks, consulta memoria y decide qué skill invocar. Es aquí donde reside la inteligencia operativa: no solo generar texto, sino tomar decisiones sobre rutas, reintentos y validaciones.

Separar esta capa facilita auditoría, pruebas y mejora iterativa —algo crucial en equipos con restricciones de recursos o regulaciones, como suele suceder en muchas empresas latinoamericanas.

El cambio que lo transforma todo

El salto fundamental es abandonar la idea de que un LLM es sólo un endpoint. Pasar a pensar en él como un componente que interactúa con memoria, reglas y pipelines es lo que convierte prototipos en sistemas confiables. La estructura del repositorio define esa transición.

Conclusión

Si desean que Claude Code “piense” como un ingeniero, no lo dejen a la improvisación. Organizar el repositorio con una CLAUDE.md raíz, skills reutilizables, reglas inmutables y documentación modular es lo que permite resultados consistentes y auditablemente seguros.

Para equipos en América Latina esto significa aprovechar al máximo recursos limitados, facilitar la colaboración entre desarrolladores distribuidos y cumplir estándares de calidad y gobernanza con menos fricción.

Preguntas frecuentes

Q: ¿Debo poner todo el conocimiento en CLAUDE.md? A: No. Mantengan CLAUDE.md concisa. El resto del contexto debe estar en .claude/Docs y archivos locales.

Q: ¿Cuántos skills debo crear? A: Los necesarios para cubrir procesos repetibles: triage, generación de runbooks, evaluación y cualquier flujo crítico. Mejor pocos y bien definidos que muchos improvisados.

Q: ¿Esto aplica solo a incident response? A: No. El patrón es aplicable a cualquier sistema LLM-driven: atención al cliente, generación de documentación, pipelines de datos, etc.

Q: ¿Cómo empiezo si mi equipo es pequeño? A: Comiencen por CLAUDE.md raíz y una carpeta de rules. Agreguen skills y docs conforme identifiquen procesos repetidos.

Adoptar esta estructura no garantiza que todos los errores desaparezcan, pero sí convierte un LLM inconsistente en un componente predecible y gobernable dentro de un sistema productivo.