No vuelques el árbol de archivos y lo llames onboarding
Un árbol de archivos no es documentación. Volcar nombres de carpetas no le enseña nada útil a tu agente de código. src/, utils/, services/, handlers/ — todos los repos del planeta tienen esos directorios, y ninguno dice por dónde entra una petición, qué módulo maneja el dinero, o cuál archivo de "utils" es en realidad el corazón del sistema. Un recién llegado, humano o IA, necesita saber sobre qué actuar, no solo qué existe.
Por qué el volcado crudo falla
Un listado de directorios es un inventario, no un mapa. No carga información sobre importancia (el archivo de 40 líneas que todo importa se ve idéntico al archivo de 40 líneas que nadie toca desde 2023), ni sobre flujo (nada dice router → middleware → service → repo), ni sobre peligro (el módulo que jamás debes editar a mano se ve igual que los demás). Un agente que solo recibe nombres recurre a la estadística: adivina el significado más común de cada carpeta, y cada punto donde tu repo se desvía de esa suposición se convierte en una edición equivocada. Las herramientas que construyen contexto serio de código coinciden — el repo map de aider, por ejemplo, incluye deliberadamente "las clases y funciones más importantes junto con sus tipos y firmas", ordenadas por cuántas veces el resto del código las referencia, precisamente porque los nombres de archivo no bastan.
Los cinco movimientos que sí son onboarding
Reemplaza el volcado del árbol con cinco movimientos narrados. Cada uno responde una pregunta que el árbol no puede responder.
| # | Movimiento | Responde | Presupuesto |
|---|---|---|---|
| 1 | Orientación | ¿Qué es este sistema, para quién, en una pantalla? | ~10 líneas |
| 2 | Mapa de módulos | ¿Cuáles 5–10 módulos importan, y qué posee cada uno? | 1 línea por módulo |
| 3 | Camino de ejecución central | ¿Cómo fluye una petición real, de entrada a respuesta? | 10–20 líneas, de punta a punta |
| 4 | Gotchas | ¿Qué le va a morder a quien edite sin conocer la historia? | 3–5 viñetas |
| 5 | Un siguiente paso | ¿Dónde suele empezar el primer cambio? | 1–2 líneas |
El camino de ejecución es el movimiento que más equipos omiten y el que más vale: convierte una pila de nombres en terreno. "Un POST llega a routes/orders.py, el middleware de auth adjunta el usuario, OrderService.create valida y abre una transacción, repo/orders.py escribe, el serializador en api/schemas.py da forma a la respuesta" — veinte líneas así le enseñan al agente tu división en capas, tu manejo de errores y tu nomenclatura en una sola pasada. Ahora el agente puede seguir una petición real en vez de adivinar por nombres de directorios. Eso sí es onboarding.
Dónde ponerlo
Escribe los cinco movimientos en el archivo que tu agente ya carga:
AGENTS.md— el "README para agentes" abierto y agnóstico de herramienta; su propia guía recomienda incluir una visión general del proyecto y todo lo que le dirías a un nuevo compañero de equipo, en Markdown plano y sin campos obligatorios.CLAUDE.md— se carga al inicio de cada sesión de Claude Code. La documentación fija como objetivo menos de ~200 líneas por archivo; cinco movimientos disciplinados caben en bastante menos de la mitad.
Los dos se componen: un import de una línea @AGENTS.md (o un symlink) permite que ambos formatos compartan una sola fuente de verdad.
Nivel avanzado: mantenlo vivo, mantenlo pequeño
- Borra la sección del árbol si la tienes. Los agentes pueden ejecutar
lspor su cuenta; la documentación de Claude Code dice explícitamente que los archivos de memoria deben limitarse a lo que el agente no puede derivar leyendo código. La estructura de directorios es derivable; los gotchas y el flujo no. - Un camino trazado vale más que tres resumidos. La profundidad transfiere convenciones; la amplitud solo agrega nombres. Agrega un segundo trazo solo si el sistema de verdad tiene dos caminos disjuntos (por ejemplo, HTTP y una cola de trabajos).
- Actualiza cuando mienta, no por calendario. En cuanto la descripción de un movimiento contradiga el código, el agente le cree al documento y edita mal. Trata un gotcha desactualizado como un bug P1 de documentación.
- Usa el lente de Diátaxis. Los cinco movimientos son sobre todo explicación y how-to — las dos formas de documentación que un volcado de árbol no contiene en absoluto. Si tu documento de onboarding se lee como referencia (listas de cosas), reconstruiste el árbol en prosa.
Recursos
- AGENTS.md — el formato abierto para guiar agentes de código
- Cómo Claude recuerda tu proyecto — archivos de memoria CLAUDE.md
- El repository map de aider — símbolos y firmas, no solo nombres de archivo
- Diátaxis — las cuatro formas de documentación
¿Construyendo una funcionalidad con IA? Yeda AI diseña, audita y entrega sistemas LLM de producción.