La mayoría de las personas tratan CLAUDE.md como un archivo de prompt.

Ese es el error.

Si quieres que Claude Code se sienta como un ingeniero senior viviendo dentro de tu repo — no un chatbot que casualmente tiene acceso a archivos — tu proyecto necesita estructura. Claude necesita cuatro cosas en todo momento: el porqué (qué hace el sistema), el mapa (dónde viven las cosas), las reglas (qué está permitido) y los flujos de trabajo (cómo se hace el trabajo).

Aquí están las cinco capas que lo hacen funcionar.

1. CLAUDE.md — Memoria del Repo (Mantenlo Corto)

Este es el archivo estrella del norte. Es lo primero que Claude lee cuando entra en tu proyecto, y establece el tono para todo lo que sigue.

Pero aquí es donde la mayoría de los equipos se equivocan: convierten CLAUDE.md en un vertedero de conocimiento. Documentos de arquitectura, estándares de codificación, referencias de API, procedimientos de implementación — todo metido en un solo archivo.

¿El resultado? El modelo comienza a perder contexto importante porque hay demasiado ruido.

Mantén CLAUDE.md enfocado en tres cosas:

  • Propósito — ¿Por qué existe este sistema?
  • Mapa del repo — ¿Qué vive dónde?
  • Reglas y comandos — ¿Qué está permitido, qué no, y cómo se hace el trabajo?

Eso es todo. Todo lo demás pertenece a una de las capas siguientes.

2. Skills — Modos Expertos Reutilizables

Deja de reescribir instrucciones cada sesión.

Las skills de Claude Code (.claude/skills/ o ~/.agents/skills/) te permiten empaquetar flujos de trabajo comunes en módulos reutilizables que Claude carga bajo demanda. Piénsalos como modos expertos:

  • Lista de verificación de revisión de código
  • Manual de refactorización
  • Procedimiento de lanzamiento
  • Flujo de depuración

El resultado es consistencia entre sesiones y compañeros de equipo. Cuando tus skills están bien estructuradas, Claude no solo genera código — sigue los procesos reales de tu equipo.

Si estás usando OpenClaw o frameworks de agentes similares, las skills se vuelven aún más poderosas. Pueden agrupar scripts, documentos de referencia y activos en paquetes portátiles que cualquier agente puede recoger.

Para más información sobre cómo evolucionan las herramientas de creación de skills, consulta nuestra publicación reciente sobre el creador de skills de Anthropic y la CLI de Workspace de Google.

3. Hooks — Barreras de Contención que No Olvidan

Los modelos olvidan. Los hooks no.

Los hooks de Claude Code son acciones deterministas que se activan automáticamente — antes o después de que Claude realice ciertas operaciones. Úsalos para las cosas que deben suceder cada vez:

  • Ejecutar el formateador después de ediciones de archivos
  • Ejecutar pruebas cuando cambian módulos principales
  • Bloquear directorios inseguros (auth, facturación, migraciones)

La distinción importa: los prompts son sugerencias. Los hooks son garantías. Cuando le dices a Claude “siempre ejecuta pruebas después de editar src/auth/” en un prompt, podría olvidarlo para la tercera edición. Cuando lo conectas como un hook, es automático.

4. Docs — Contexto Progresivo

No infles tus prompts con todo lo que Claude podría necesitar. En su lugar, dale a Claude un mapa de dónde vive la verdad:

  • Visión general de arquitectura — Diseño del sistema, flujo de datos, infraestructura
  • ADRs (Registros de Decisiones de Arquitectura) — Por qué tomaste las decisiones que tomaste
  • Runbooks operativos — Cómo implementar, depurar y recuperar

Claude es bueno leyendo archivos bajo demanda. No necesita cada detalle de antemano — necesita saber dónde buscar. Un directorio docs/ bien organizado significa que Claude puede obtener contexto exactamente cuando es relevante.

5. CLAUDE.md Local para Módulos de Riesgo

Esta es la capa que la mayoría de los equipos pasan por alto por completo.

Coloca archivos pequeños y enfocados CLAUDE.md cerca de los bordes afilados de tu código base:

src/auth/CLAUDE.md
src/persistence/CLAUDE.md
infra/CLAUDE.md

Estos archivos contienen detalles, restricciones y advertencias específicas del módulo. Cuando Claude trabaja en src/auth/, ve automáticamente la guía específica de autenticación — las peculiaridades de rotación de tokens, los casos límite de manejo de sesiones, las advertencias de “nunca modifiques esta función sin actualizar la migración”.

Así es como obtienes precisión quirúrgica sin inflar el CLAUDE.md raíz.

Estructura sobre Prompts

Los prompts son temporales. La estructura es permanente.

Cuando tu repo está organizado de esta manera, Claude deja de comportarse como un chatbot y comienza a actuar como un ingeniero nativo del proyecto. Conoce el contexto, sigue los procesos, respeta las barreras de contención y encuentra la documentación correcta — porque el proyecto mismo le enseña cómo trabajar.

El panorama de las CLIs de codificación de IA se mueve rápido. Claude Code, Codex CLI, Gemini CLI — todos están enviando capacidades de agentes. Pero los equipos que obtienen valor real no son los que tienen los mejores prompts. Son los que tienen los repos mejor estructurados.

Kevin Kaminski es Microsoft MVP y Principal en Big Hat Group, donde ayuda a equipos empresariales a implementar agentes de IA, Windows 365 y soluciones de gestión moderna. Para ayuda estructurando tus flujos de trabajo de codificación de IA, ponte en contacto.