Uno de los problemas más comunes al trabajar con agentes de código como Claude Code en un proyecto real es la gestión del conocimiento. La documentación se duplica, cada copia deriva por su cuenta, y terminas con instrucciones que parecen correctas pero generan código roto.
Este artículo propone una estructura clara basada en cuándo se carga cada tipo de instrucción y quién la necesita.
El problema
La mayoría de los proyectos terminan con cuatro tipos de archivos de instrucciones:
- Archivos
CLAUDE.md/AGENTS.md - Skills (
.claude/skills/...) - Definiciones de agentes (
.claude/agents/...) - Documentos de referencia grandes (API de librerías, herramientas internas, etc.)
El problema es que el mismo conocimiento se copia y pega en todos ellos. Cuando auditas cada afirmación contra el código real, los resultados pueden ser preocupantes:
- Los documentos de estilo muestran un patrón de CSS-modules que genera nombres de clase que nunca coinciden con la configuración de build. Cualquier agente que los siga produce estilos rotos.
- La plantilla de tests configura mocks en
beforeAll, pero el archivo de setup restaura todos los mocks después de cada test. El mock muere silenciosamente después del primer test. - Un componente de fetching de datos se renderiza sin su provider requerido. Crash instantáneo.
- El “helper” recomendado para tests era usado por exactamente 1 de 50 archivos de test reales.
La documentación se veía completa. Estaba confiadamente equivocada. Y cada documento incorrecto te cuesta un bucle de depuración de miles de tokens cuando el agente lo encuentra.
La regla de oro
Todo se reduce a cuándo se carga y quién lo necesita:
| Superficie | ¿Cuándo carga? | ¿Qué debería contener? |
|---|---|---|
| CLAUDE.md / AGENTS.md | siempre, cada sesión | reglas que aplican a toda edición |
| Skill | bajo demanda, por tipo de tarea | conocimiento profundo de cómo hacer algo |
| Agent | cuando se delega | flujo de trabajo y compuertas, no conocimiento |
| Hook | forzado por código | reglas que nunca deben saltarse |
Cuatro preguntas para enrutar cualquier contenido:
- ¿Aplica a cada cambio en la carpeta? → CLAUDE.md: estilo de imports, naming, comandos, estructura del proyecto. Mantenlo pequeño, paga renta de tokens cada sesión.
- ¿Solo se necesita para un tipo de tarea, pero requiere conocimiento profundo? → Skill cargable bajo demanda.
- ¿Define cómo se ejecuta un flujo de trabajo? → Agent definition.
- ¿Debe cumplirse siempre, sin excepción? → Hook en git o CI.
Cómo implementarlo en tu proyecto
- Centraliza en CLAUDE.md solo lo que aplica globalmente: convenciones de nomenclatura, comandos de build/test, estructura de directorios.
- Crea skills específicas para áreas como “estilos CSS”, “patrones de testing”, “APIs internas”. Cada skill se carga solo cuando el agente necesita trabajar en esa área.
- Define agentes para flujos de trabajo completos: “revisar PR”, “generar documentación”, “refactorizar módulo”.
- Usa hooks (pre-commit, CI) para validar reglas que no pueden negociarse.
“La documentación completa pero incorrecta es más peligrosa que la documentación incompleta. El agente confiará en ella, y tú pagarás el costo de la depuración.”
Conclusión
La estructuración correcta de CLAUDE.md, skills y agentes no es un lujo — es una necesidad para cualquier equipo que use agentes de código en producción. Cada pieza de conocimiento debe vivir en el lugar correcto, cargarse en el momento correcto, y pertenecer a la audiencia correcta.
Implementa esta arquitectura desde el día uno y evitarás los costosos bucles de depuración que genera la documentación mal estructurada.
Sigue explorando estos temas en el blog de DojoFullStack.