🏗️ Arquitectura de un proyecto
Estructurar un proyecto duradero: carpetas, módulos, separación de responsabilidades, elección de stack, documentación de decisiones y estrategia de crecimiento incremental.
1 📁 Estructura de carpetas que tiene sentido
Estructura canónica de carpetas — cada directorio con una única responsabilidad
La estructura de carpetas es el primer contrato del proyecto. Le indica a Claude (y a cualquier colaborador) qué va en cada lugar antes de leer una línea de código.
my-project/
├── src/
│ ├── components/ # UI e lógica de apresentação
│ ├── lib/ # Utilitários puros
│ ├── types/ # TypeScript interfaces
│ └── data/ # Artefatos JSON gerados
├── scripts/
│ ├── aggregate.ts # Data pipeline
│ └── setup.ts # Setup único
├── docs/
│ ├── adr/ # Architecture Decision Records
│ └── CHANGELOG.md
├── tests/
├── CLAUDE.md # Instruções do agente
├── package.json
└── .env.example # Template de variáveis✓ Hacer
- • Cada carpeta con una responsabilidad única
- • Nombres en minúsculas y sin espacios
- • README.md o index.ts en cada carpeta
- • scripts/ separado de src/
- • docs/ para decisiones y changelog
✗ Evitar
- • Carpeta
misc/ostuff/ - • Utils gigante con 50 archivos
- • Mezclar scripts de build con código
- • Archivos en la raíz sin un propósito claro
- • Anidamiento de más de 4 niveles
Consejo práctico
Muestra la estructura de carpetas en CLAUDE.md con tree -L 2. Claude entiende el proyecto sin tener que explorar archivo por archivo.
2 🔩 Separación de responsabilidades
Cada módulo debe tener una razón para existir y una razón para cambiar. Cuando esto no se respeta, cualquier cambio propaga efectos inesperados a todo el sistema.
Cómo evoluciona la separación en un proyecto real
Todo en un archivo
Normal al principio. Un index.ts con fetch, lógica y renderizado mezclados. Funciona, pero escala mal.
Separación por capas
Obtención de datos en lib/api.ts, token de sesión, reautenticación cuando vence. types/, componentes React aislados. Cada parte es comprobable.
Módulos con interfaces definidas
Cada módulo exporta una interfaz pública. La implementación interna puede cambiar sin romper otros módulos. Claude modifica un módulo a la vez.
✓ Módulo bien separado
- • Una responsabilidad clara
- • Interfaz pública mínima
- • Dependencias explícitas (parámetros)
- • Se puede probar de forma aislada
- • Se puede sustituir sin efecto en cascada
✗ Módulo acoplado
- • Lee directamente las variables globales
- • Hace I/O y lógica en el mismo lugar
- • Importa half the codebase
- • Necesita una base de datos real para probar
- • Cambiar rompe otras 5 cosas
Regla práctica
Si necesitas explicar más de dos cosas que hace un módulo, probablemente hace demasiadas. Pídele a Claude: «Identifica las responsabilidades mezcladas en este archivo».
3 🧱 Elección de stack
El stack es una decisión a largo plazo. Cambiar de runtime a mitad de un proyecto es costoso. Elegir bien al inicio ahorra meses de trabajo.
Criterios para elegir stack en proyectos con Claude Code
✅ Criterios técnicos
- • Rendimiento adecuado para el problema
- • Ecosistema de paquetes maduro
- • TypeScript nativo o fácil de agregar
- • Soporte integrado para pruebas
🤖 Criterios para Claude
- • Stack popular = Claude lo conoce bien
- • Documentación pública bien indexada
- • Abundantes ejemplos en el entrenamiento
- • Errores con mensajes claros
# ADR-001: Escolha de runtime — Bun
## Status: Aceito (2026-05-01)
## Contexto
Projeto precisa de: TypeScript nativo, execução rápida
de scripts, bundler integrado, compatibilidade Node.js.
## Opções consideradas
- Node.js + tsx: familiar, mas startup lento
- Deno: boa DX, mas ecossistema menor
- Bun: startup 3x mais rápido, bundler nativo, TS out-of-box
## Decisão
Usar Bun como runtime principal.
## Consequências
+ Scripts de build ~200ms (vs ~600ms com Node)
+ Sem configuração adicional de TypeScript
- Alguns pacotes npm com compatibilidade parcial
- Equipe precisa instalar Bun (curl ... | bash)Stacks con mejor soporte de Claude en 2026
TypeScript/Node/Bun, React/Next.js, Python/FastAPI, Go stdlib. Los frameworks de nicho o muy nuevos reciben menos soporte; prefiere los más populares cuando te dé igual cuál elegir.
4 📝 Documentar decisiones con ADRs
Los Architecture Decision Records (ADRs) son documentos breves que registran por qué se tomó una decisión, qué opciones se consideraron y cuáles son las consecuencias esperadas.
Contexto
¿Por qué hubo que tomar esta decisión? ¿Cuál era el problema o la oportunidad?
Opciones
¿Qué alternativas se evaluaron? ¿Por qué se aceptó o rechazó cada una?
Consecuencias
¿Qué cambia después de la decisión? Beneficios positivos y negativos esperados.
Cuidado con los ADR desactualizados
Un ADR que ya no refleja la realidad es peor que no tener ninguno. Claude seguirá instrucciones obsoletas. Revisa los ADR cada vez que cambie la decisión, aunque sea para marcar "Reemplazado por ADR-007".
5 🌱 Empezar poco a poco y crecer
Los proyectos con Claude evolucionan rápido. La trampa es planificar una arquitectura compleja antes de validar el núcleo. Primero, un walking skeleton; después, los detalles.
Ciclo de crecimiento saludable
Semana 1 — Núcleo funcional
Un archivo que hace lo más importante. Sin abstracciones prematuras. Valida la hipótesis principal.
Semana 2-4 — Separación
Extraer módulos a medida que surjan patrones. Agregar pruebas para el núcleo validado.
Mes 2+ — Escala
Agregar features sobre una base sólida. La arquitectura se estableció de forma orgánica, no se diseñó en el vacío.
YAGNI con Claude
"You Aren't Gonna Need It" es doblemente importante con los LLM. Claude puede generar abstracciones elaboradas rápidamente, pero las abstracciones prematuras crean deuda técnica invisible. Pide siempre primero la solución más simple.
6 🔭 Visión a largo plazo
Los proyectos perduran cuando tienen rituales de mantenimiento, no solo features. Lo que haces cada semana importa más que la arquitectura inicial.
✓ Rituales saludables
- • Revisión semanal de TODOs/FIXMEs
- • CHANGELOG actualizado con cada versión
- • Dependencias actualizadas mensualmente
- • CLAUDE.md revisado trimestralmente
- • Métricas de cobertura monitoreadas
✗ Señales de un proyecto enfermo
- • CHANGELOG abandonado en la V0.1
- • Dependencias con 2 años de retraso
- • CLAUDE.md nunca se actualizó
- • TODO que se acumulan sin limpieza
- • Nadie sabe por qué existe X
📋 Resumen del módulo
- • Estructura de carpetas con responsabilidad única
- • Separación de responsabilidades por módulo
- • Criterios para elegir el stack
- • ADR como memoria de decisiones
- • Crecimiento incremental con YAGNI
- • Rituales de mantenimiento saludable
- • Crea la estructura de carpetas de tu proyecto
- • Escribe el primer ADR de stack
- • Define las responsabilidades de cada módulo
- • Configura el CLAUDE.md con el mapa de carpetas