La arquitectura que sostiene un proyecto cuando cambia el modelo
Cuando arranqué a usar Claude Code en serio, mis primeros proyectos eran un único directorio con archivos sueltos y un prompt enorme cada vez que abría una sesión. Funcionaba para tareas chicas. Para cualquier cosa más larga, se rompía: el modelo perdía contexto, repetía decisiones que ya habíamos tomado, ignoraba reglas que yo daba por sentadas.
Con el tiempo aprendí que un proyecto de IA tiene una arquitectura propia, distinta a la de un proyecto tradicional. No es código en una carpeta. Es código + instrucciones persistentes + memoria + skills + agentes + integraciones + servicios externos. Cómo organizás todo eso define qué tan lejos vas a llegar antes de empezar a parchear.
Lo que sigue es lo que hoy uso para mis proyectos personales y los que armo en mi empresa. No es la única forma. Es la que me sirvió.
Las capas que conviene separar.
En cualquier proyecto mediano hay seis capas que conviene tratar por separado:
- Reglas del proyecto — qué hace, cómo se llama, qué convenciones usa, qué no se toca. Va en un
CLAUDE.md(o equivalente). - Memoria — lo que el agente tiene que recordar entre sesiones, separado de las reglas fijas.
- Credenciales y secretos — API keys, tokens, claves de servicios. Viven en
.env, fuera del repo, nunca en el chat. - Skills y plugins — capacidades concretas que el agente puede invocar.
- Agentes especializados — sub-agentes con un rol definido (revisor, explorador, planner).
- Conexiones externas — servidores MCP que conectan al agente con herramientas reales (Gmail, Drive, n8n, browser).
Son seis capas, no seis carpetas necesariamente. Pensarlas por separado evita que terminen mezcladas en un único prompt gigante que nadie quiere mantener.
El CLAUDE.md como contrato — y por qué importa que sea corto.
El CLAUDE.md es el archivo que el agente lee al inicio de cada sesión. Son las reglas duras del proyecto: qué hace, qué no hace, cómo se llaman las cosas, qué no tocar nunca. Equivalente a un brief para un colaborador nuevo.
Acá hay un detalle que me costó internalizar: el contenido del CLAUDE.md se queda en el contexto durante toda la sesión. Cuanto más largo, más espacio del context window ocupa antes siquiera de empezar a trabajar. Y aunque el prompt caching alivia el costo, sigue compitiendo con el espacio que necesitás para el trabajo real.
Mi recomendación: tratá el CLAUDE.md como un contrato breve, no como un manual. Reglas duras, convenciones, qué no hacer. Lo que cambia o lo que es opcional, llevalo a otro lado.
Para mantenerlo completo y corto al mismo tiempo, hay skills y patrones de memoria modular que sirven: el archivo principal queda como índice y los detalles viven en archivos chicos que se cargan bajo demanda. El plugin que uso a nivel global para esto es claude-md-management, oficial de Anthropic.
En proyectos con subcarpetas, conviene tener un CLAUDE.md por carpeta con lo específico de esa carpeta. El agente los carga jerárquicamente: las reglas transversales viven en la raíz; el detalle operativo, abajo.
.env y secretos: nunca en el chat.
Las API keys y tokens van en .env local (o en el panel del servidor cuando despliegues). Nunca pegadas en el chat con el agente — quedan en logs, a veces en texto plano, a veces más allá del proveedor.
Es la regla más simple y la que más veces vi violar — incluyendo proyectos con equipos que sí saben de seguridad. Una sesión apurada, una key pegada para “probar rápido”, y ya quedó donde no querés.
El .env se ignora en .gitignore antes del primer commit. No después. Antes.
No todo vive en el proyecto: la arquitectura externa.
La trampa mental más común al armar un proyecto de IA es pensar que todo tiene que estar adentro de la carpeta. No es así. Un proyecto serio se apoya en servicios externos, y eso es una virtud, no una complicación.
Los que más uso, en proyectos chicos y medianos:
- GitHub — código, versionado, historial. Lo uso siempre, incluso para proyectos personales que nadie más va a ver. El historial vale.
- Supabase — base de datos Postgres + auth + storage, gestionados. Para cualquier app que necesite persistir datos, evita armar y mantener una base propia.
- Docker — contenedores para correr el agente o sus dependencias en un entorno aislado, reproducible.
- EasyPanel — panel para gestionar el VPS donde despliego los servicios. Hace fácil lo que en consola pura es tedioso.
- Cloudflare Workers — edge functions para piezas chicas que necesito accesibles desde internet. En este mismo proyecto lo uso para el OAuth proxy del módulo de admin.
Cada uno cubre algo que sería un dolor armar a mano. La arquitectura buena no maximiza lo que está adentro del proyecto — minimiza lo que tiene sentido tener adentro.
Skills y plugins: a nivel proyecto, no global, salvo excepciones.
Lo aprendí caro. Cargar todo a nivel global hace que cada conversación arranque con kilobytes de contexto irrelevante. Más tokens, más latencia, más costo, más confusión para el modelo.
Lo que te recomiendo:
- Lo que te sirve en cualquier proyecto (manejo de documentos, creador de skills, revisión de código) → global.
- Lo que es específico al stack o al dominio (frontend, automatización de browser, conector con un sistema concreto) → al proyecto.
Cinco minutos pensando dónde instalar cada cosa te ahorran horas de debugging después.
No reinventes la rueda.
La tentación más cara que vi (en mí y en otros) es desarrollar todo desde cero.
La realidad: para casi cualquier tarea común ya hay una skill, un plugin o un MCP probado por miles de personas, con meses de mejoras encima. Manejo de documentos, browser automation, conectores con servicios populares, frontend, testing — todo eso ya está. Y mejor que lo que vos vas a armar en una tarde.
Antes de escribir código, busco. Si existe algo decente, lo uso. Solo armo desde cero cuando hay un caso real que no encuentra solución en el ecosistema, y es mucho menos seguido de lo que uno asume al arrancar.
Esa disciplina sola libera horas. Y hace que tu proyecto se beneficie de las mejoras que otros le van haciendo a la pieza que vos elegiste.
Sub-agentes para tareas que merecen contexto propio.
Un agente principal puede hacer todo. Pero cuando hay tareas con un foco muy distinto (revisar código vs. escribir contenido vs. explorar el repo), conviene delegarlas a sub-agentes especializados.
Ventajas concretas que vi:
- Contexto limpio. Cada sub-agente arranca con su propia memoria de trabajo.
- Paralelización. Varios sub-agentes pueden correr a la vez.
- Auditoría. Si algo sale mal, sé qué sub-agente lo hizo.
No tengo decenas. Tengo unos pocos, bien definidos: un explorador (mapea código existente), un revisor (audita cambios), un planner (descompone features grandes). Cada uno con su rol claro y su prompt corto.
MCP: conectar el agente a herramientas reales.
MCP (Model Context Protocol) es el puente entre el agente y el mundo exterior. Le permite leer un mail, agendar un evento, abrir un browser, consultar una base de datos.
Mi recomendación para activarlos:
- Activá solo los que vas a usar de verdad esta semana. No los acumules “por si acaso”.
- Permisos mínimos. Si solo necesitás leer, no le des permiso de escribir.
- A nivel proyecto cuando son específicos, global solo cuando son transversales (Gmail, Calendar).
Cada MCP que agregás abre una superficie de ataque. La pregunta antes de instalarlo no es solo “¿es útil?” sino “¿qué pasa si una instrucción maliciosa logra usarlo?”.
Dónde corre todo esto: Claude Code en VS Code.
Una recomendación concreta. Probé Claude Code en cuatro formatos: la app de Claude para Windows, vía browser, corriendo en Ubuntu desde mi terminal, y como extensión dentro de VS Code. La que me dejó más productivo, por mucho, es la última.
Tener el editor a la izquierda, la conversación con el agente a la derecha, y los archivos cambiando frente a mí mientras trabaja, cambia la cuenta. Veo en tiempo real qué edita, intervengo cuando hace algo raro, abro el archivo donde dejó algo a medio resolver y le señalo dónde mirar.
Si estás arrancando, esa sería la primera configuración que te recomendaría. La terminal sirve para tareas específicas, pero el editor es donde el flujo se vuelve cómodo de sostener todo el día.
Lo que me llevo.
Un proyecto de IA bien armado se siente distinto. El agente entra en contexto rápido, no inventa convenciones, no me hace repetir cosas que ya le dije. Cuando algo falla, sé en qué capa pasó y dónde mirar.
Y cuando viene un cambio — un modelo nuevo, una skill mejor, un MCP que reemplaza a otro — la arquitectura aguanta. Cambio una pieza, no rearmo el proyecto.
Esa es la prueba que me importa: que el proyecto sobreviva a la próxima novedad sin que tenga que volver a empezar.
Comentarios