¿Tu repo está listo para agentes?

Un agente de IA como Claude Code es tan bueno como el contexto que encuentra en tu repo. Le das una tarea, y antes de tocar nada tiene que responderse: ¿qué es esto?, ¿cómo está organizado?, ¿cómo se hacen aquí las cosas?, ¿dónde toco?

Instrumentalizar un repo es responder esas preguntas por adelantado, dejándolas escritas donde el agente las va a buscar. Un repo instrumentalizado convierte al agente en un ingeniero que conoce tu código. Uno que no, lo deja adivinando — y adivinar es alucinar.

Este checklist mide eso en 16 puntos, repartidos en cuatro bloques. No escanea nada: respondes tú, honestamente, sobre el estado real de tu repo.

• Documentación (CLAUDE.md) — el mapa: qué hay, cómo se construye, qué reglas seguir. Por feature, no solo en la raíz.
• Configuración (.claude/) — comandos, skills, hooks de validación y herramientas conectadas (MCP).
• Estructura y navegabilidad — organización por feature, naming claro, vendor aislado. Que el agente se ubique sin perderse.
• Verificación y seguridad — tests, type-check, lint, PRs y secrets fuera del código. Que el agente valide sus cambios sin romper ni filtrar nada.

El error más común es un único CLAUDE.md gigante en la raíz. Funciona en un proyecto pequeño, pero a medida que creces el agente tiene que cargar todo el contexto del mundo para tocar una sola feature — y se pierde lo importante.

La alternativa es un árbol de CLAUDE.md: uno en la raíz con el mapa general, y uno por feature o módulo con el contexto local. Así, cuando el agente trabaja en «pagos», lee el CLAUDE.md de pagos y nada más. Contexto justo, en el sitio justo.

La señal de alarma son las carpetas grandes (>500 líneas) sin ningún CLAUDE.md cerca: ahí es donde el agente improvisa. Cúbrelas primero.

Este checklist te dice qué falta. El siguiente paso es arreglarlo — y eso también puede hacerlo un agente.

Estoy preparando una herramienta para justo eso: le pegas un prompt a tu Claude Code, él se trae el flujo, audita tu repo de verdad (cuenta CLAUDE.md, carpetas sin documentar, ratios de código/doc), te enseña el plan y crea los CLAUDE.md que faltan — leyendo tu código real y siempre con tu confirmación. Nunca toca código de producto.

Mientras tanto, usa este checklist para saber por dónde empezar.

No hace falta hacerlo todo de golpe. El orden que más mueve la aguja:

1. CLAUDE.md raíz si no lo tienes — el mapa de entrada.
2. Las carpetas grandes sin documentar — los puntos ciegos donde más alucina.
3. Un hook de validación (type-check + lint post-edit) — para que el agente se autocorrija.
4. Skills/commands para lo que repites — deja de explicar lo mismo cada vez.

Con esos cuatro, la mayoría de repos saltan de «no apto» a «apto» en una tarde.