Estructura del repo para sesiones largas
Un repo bien estructurado es legible por agentes en sesiones de 4+ horas sin perderse. Un repo mal estructurado sature el [[context-window]] con paths confusos y archivos innecesarios. La estructura es el primer lugar donde se nota si un founder pensó o solo escribió código.
Estructura predictible = agente navega sin leer todo el repo cada vez.
La estructura base
`
src/
routes/ ← rutas (file-based)
components/ ← componentes UI reusables
lib/
stores/ ← auth, ui
utils/ ← helpers puros
db/ ← queries Supabase agrupadas
specs/ ← specs de features (md)
tests/ ← tests unitarios y e2e
.claude/
CLAUDE.md ← system prompt
skills/ ← skills por dominio
`
Las tres reglas
1. Profundidad máxima 3 niveles
Más profundo = el agente tarda en encontrar. Si un archivo vive 5 niveles abajo, probablemente categorizaste mal.
2. Agrupar por dominio, no por tipo
Mal: src/types/, src/models/, src/hooks/. Cada feature dispersa en 3 carpetas. Bien: src/lib/billing/ con types, models, hooks juntos. El agente puede tocar todo el dominio sin abrir 10 archivos dispersos.
3. specs/ en el repo, no en Notion
Los specs son código para el agente. Si viven fuera del repo, el agente no los puede leer en contexto. Como cualquier código, se versionan, se PR-review, se merge.
Cuando el repo crece
Al pasar ~200 archivos, considera sub-apps con workspaces. Antes de eso, mono-repo plano es más simple para agentes.
Dibuja tu estructura actual en un árbol. ¿Profundidad máxima? ¿Agrupas por dominio o por tipo? ¿Specs en repo? Ajusta lo que no calce.
- Tres reglas: profundidad máx 3, agrupar por dominio, specs en repo.
- Estructura predictible = agente navega rápido en sesiones largas.
- Mono-repo plano hasta ~200 archivos; después workspaces.