# Proyectos de Claude Code: cómo una IA coordina un equipo de agentes autónomos > Análisis exhaustivo de Proyectos de Claude Code: arquitectura Coordinator y Threads, ramas paralelas, memoria compartida MEMORY.md y gestión de agentes en la nube. Con el lanzamiento de **Claude Code Projects**, el desarrollo asistido por inteligencia artificial evoluciona desde la paradigma *«un desarrollador — un chat»* hacia una **orquestación multiagente** completa. Anteriormente, para resolver tareas complejas y a gran escala, los ingenieros debían abrir manualmente varias sesiones de terminal, copiar contexto entre ellas, gestionar ramas en Git y ensamblar los resultados por su cuenta. En el nuevo modelo, la IA principal asume toda la labor de despacho. Usted formula un único objetivo estratégico general, y Claude toma el control: - **Descompone el trabajo:** divide el objetivo a gran escala en subtareas aisladas. - **Orquesta flujos:** lanza sesiones paralelas en la nube (**Threads**). - **Controla el contexto:** sincroniza las soluciones mediante la memoria compartida del proyecto (`MEMORY.md`). - **Verifica el resultado:** ejecuta pruebas, revisa el estado de compilación en CI y prepara los Pull Requests finales. > [!NOTE] > **Autonomía sin dependencia de la máquina local:** los flujos de trabajo (Threads) funcionan en contenedores aislados en la nube de Anthropic. Continúan ejecutando pruebas y escribiendo código incluso si cierra la tapa de su portátil, y puede consultar el estado del trabajo desde su smartphone. --- ## Arquitectura del sistema: Coordinador y Flujos de Trabajo (Threads) En el corazón del sistema multiagente de Claude Code Projects reside un modelo de dos niveles de división de responsabilidades: ``` ┌──────────────────────────────┐ │ USUARIO / TECH LEAD │ └──────────────┬───────────────┘ │ Definición del objetivo general ▼ ┌──────────────────────────────┐ │ COORDINADOR (COORDINATOR) │ │ Diálogo Principal Project │ └──────────────┬───────────────┘ │ ┌───────────────────────┼───────────────────────┐ │ Delegación │ Delegación │ Delegación ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ THREAD 1 │ │ THREAD 2 │ │ THREAD 3 │ │ Sesión Cloud │ │ Sesión Cloud │ │ Sesión Cloud │ │ Rama: `feat/p75` │ │ Rama: `ref/api` │ │ Rama: `fix/db` │ │ Pruebas ➔ PR #101│ │ Pruebas ➔ PR #102│ │ Pruebas ➔ PR #103│ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ └───────────────────────┴───────────────────────┘ │ Memoria común: `MEMORY.md` / `CLAUDE.md` ``` ### Tabla comparativa de niveles del sistema: | Componente | Rol en el sistema | Entorno de ejecución | Contexto y Memoria | Resultado principal | | :--- | :--- | :--- | :--- | :--- | | **Coordinator** | Centro de mando, despachador | Diálogo principal del proyecto | Ve informes de todos los flujos | Descomposición, estado consolidado | | **Thread** | Agente de trabajo autónomo | Sesión en la nube (Cloud VM) | Copia propia de la rama Git | Pull Request listo, pruebas | | **Subagent** | Asistente altamente especializado | Dentro de un Thread específico | Ciclo de procesamiento local | Ejecución de micro-scripts | --- ## 1. El Coordinador (Coordinator): centro de mando La conversación principal dentro de Project actúa como nodo de despacho. Es aquí donde usted envía requisitos de alto nivel, especificaciones técnicas y ajustes. El Coordinador realiza las siguientes tareas: - **Recepción de requisitos:** analiza consultas complejas y define los límites de la tarea. - **Enrutamiento:** decide si lanzar un nuevo flujo o pasar la tarea a un contexto existente. - **Agregación de informes:** recibe resúmenes breves de los agentes sin saturar el chat principal con gigabytes de logs intermedios. - **Síntesis:** une los resultados de flujos dispersos en un producto final coherente. > [!IMPORTANT] > El Coordinador no realiza trabajo de bajo nivel por sí mismo. Actúa como un líder técnico: distribuye roles, valida la compatibilidad arquitectónica y supervisa el estado de ejecución. --- ## 2. Flujos de Trabajo (Threads): desarrolladores en la nube Cada **Thread** es una sesión independiente completa de Claude Code desplegada en infraestructura cloud. Al trabajar con la base de código, cada flujo: - **Aísla el entorno:** clona una copia fresca del repositorio en un contenedor separado. - **Trabaja en su propia rama:** crea una rama Git para una funcionalidad específica, evitando conflictos directos con otros agentes vecinos. - **Valida el código:** ejecuta linters locales, pruebas unitarias y escenarios de integración. - **Formaliza el resultado:** abre automáticamente un Pull Request en GitHub y envía un resumen breve al coordinador. Puede seguir asignando nuevas tareas al coordinador mientras varios flujos refactorizan simultáneamente diferentes módulos del sistema. --- ## 3. Cómo descompone tareas Claude No necesita dividir manualmente las tareas ni crear agentes mediante botones de interfaz. Envía un requisito global al chat, y el coordinador elige una de tres estrategias: ### Estrategia A: Nueva tarea ➔ Nuevo Thread Si la tarea es independiente y requiere cambios sustanciales, el coordinador crea una sesión limpia en la nube para ella. Por ejemplo, si en un solo prompt pide: - *«Optimiza la velocidad de arranque en frío de la API y actualiza la documentación en la especificación OpenAPI»* — Claude lanzará paralelamente dos flujos aislados. ### Estrategia B: Desarrollo del tema ➔ Thread Existente Si la nueva entrada complementa una tarea en la que un flujo ya está trabajando, Claude no duplica recursos. Dirige la consulta al contexto ya "calentado", donde el agente recuerda ediciones previas y la estructura de los archivos afectados. ### Estrategia C: Pregunta simple ➔ Respuesta en el chat principal Las consultas cortas de referencia (*«¿Qué versión de Node.js se indica en el package.json raíz?»*) son procesadas instantáneamente por el coordinador en la ventana principal, sin gastar tiempo en inicializar un contenedor en la nube. > [!TIP] > **Gestión de la lógica del coordinador:** si no te gusta la distribución automática, establece una regla estricta en el chat: > `«Antes de crear nuevos threads, siempre muéstrame el plan de descomposición y espera mi confirmación».` --- ## 4. Panel Overview: control transparente de estados Cuando entre 5 y 10 agentes trabajan simultáneamente en un proyecto, es imposible monitorearlos a través de terminales separados. Toda la actividad se consolida en el dashboard **Overview**. ### Matriz del ciclo de vida de los flujos (threads): | Estado del flujo | Qué ocurre bajo el capó | Acción por parte del usuario | | :--- | :--- | :--- | | **`Working`** | El agente escribe código, ejecuta compilaciones o pruebas | No se requiere intervención, la tarea está en proceso | | **`Waiting on you`** | El agente está bloqueado: se requiere confirmación de acción o clave API | Abrir el flujo y dar respuesta / confirmación | | **`Ready for review`** | Código escrito, pruebas superadas, Pull Request abierto | Realizar la revisión de código en GitHub | | **`Landing`** | Pull Request aprobado y esperando fusión (merge) en la rama principal | Confirmar la fusión (Merge) | | **`Idle`** | El agente ha finalizado su trabajo y está en modo de espera | El flujo está listo para aceptar la siguiente subtarea | | **`Resolved`** | Rama fusionada, tarea completamente cerrada | El flujo se archiva | ### Pestañas especializadas del proyecto: - **Library:** base de conocimiento del proyecto donde se guardan las especificaciones, informes y archivos de datos creados por los agentes. - **Pull Requests:** lista única de todos los PR abiertos por los agentes con marcas sobre el estado de paso de CI. - **Routines:** procedimientos regulares programados (por ejemplo, auditoría diaria de seguridad de dependencias). --- ## 5. Memoria compartida del proyecto: sincronización sin pérdidas Todos los flujos dentro de un mismo proyecto no funcionan de forma aislada; están conectados a un sistema único de **Project Memory**. ``` Project Root/ ├── MEMORY.md # Índice principal de decisiones, reglas arquitectónicas y restricciones ├── CLAUDE.md # Instrucciones locales para un repositorio específico └── docs/ # Especificaciones y documentación accesibles para todos los agentes ``` ### Qué recuerda Claude: - **Acuerdos arquitectónicos:** por ejemplo, el rechazo de la librería X en favor de una solución ligera Y. - **Marco operativo:** cambio de fecha de lanzamiento, reglamento especial para aprobar cambios en el módulo de facturación. - **Preferencias del autor:** convenciones de estilo de código, patrones prohibidos, elección del gestor de paquetes (`pnpm` en lugar de `npm`). Cada nuevo flujo lee primero el archivo `MEMORY.md` al iniciarse. Por lo tanto, no tienes que repetir los requisitos básicos del proyecto a los mismos agentes una y otra vez. --- ## 6. Cómo intervenir en el trabajo de un agente individual A pesar del alto nivel de autonomía del coordinador, el desarrollador mantiene un control total sobre cada eslabón. En cualquier momento puedes "adentrarte" dentro de cualquier flujo: - **Vista completa del Transcript:** registro minuto a minuto de comandos shell ejecutados, archivos leídos y salidas del linter. - **Ajuste puntual del rumbo:** envío de una instrucción directa a un agente concreto (*«Concéntrate solo en el endpoint /checkout, no toques los demás por ahora»*). - **Parada de emergencia (Stop):** interrupción de un flujo en bucle infinito con un solo clic. > [!WARNING] > **Regla crítica de enrutamiento:** > Si un agente se detiene y solicita permiso para ejecutar una acción peligrosa (como eliminar archivos o desplegar), debes confirmar el comando **estrictamente dentro del propio Thread**. ¡El comando «Continúa», enviado en el chat general del coordinador, no llegará al flujo bloqueado! --- ## 7. Escenarios prácticos de aplicación El enfoque multiagente es especialmente eficaz en cuatro escenarios de ingeniería: ### Escenario 1: Optimización del rendimiento (Latency Profiling) **Tarea:** Reducir la latencia de respuesta del servicio de checkout (Checkout p75 latency) de 800 ms a 200 ms. - *Thread 1:* Perfila las consultas SQL a la base de datos y crea una migración para los índices faltantes. - *Thread 2:* Configura el caché Redis para respuestas pesadas del catálogo. - *Thread 3:* Optimiza el tamaño del bundle cliente y elimina importaciones no utilizadas. Cada flujo prepara un PR separado con benchmarks aislados. ### Escenario 2: Migración de API entre repositorios **Tarea:** Retirar la API v1 obsoleta en todos los servicios relacionados de la empresa. - Se conectan los repositorios Backend API, Web App y Mobile App al Project. - El coordinador lanza 3 flujos: cada uno migra las llamadas a la API v2 en su repositorio, ejecuta pruebas locales y abre un PR indicando el orden de fusión. ### Escenario 3: Refactorización transversal según especificación técnica **Tarea:** Implementar un módulo complejo de autorización basado en el archivo `docs/auth-spec.md`. - El coordinador divide la especificación en fases lógicas: generación de modelos de datos ➔ implementación de middleware ➔ integración OAuth ➔ escritura de pruebas e2e. Los conocimientos se transmiten de fase a fase a través de `MEMORY.md`. ### Escenario 4: Auditoría masiva de documentación y contratos **Tarea:** Revisar cientos de contratos o tickets de soporte técnico. - Los Threads se reparten lotes de documentos, extraen riesgos clave y almacenan resúmenes estructurados en JSON/Markdown en el almacenamiento común `Library`. --- ## 8. Limitaciones y trampas de la arquitectura El trabajo paralelo reduce significativamente el tiempo de desarrollo, pero requiere comprender las particularidades técnicas: 1. **Consumo de tokens y límites de tarifa:** cada Thread activo consume la cuota del modelo de forma independiente. Además, el coordinador gasta tokens al leer informes largos. El sistema tiene un límite establecido: hasta **200 nuevos flujos al día** por proyecto. 2. **Conflictos de fusión (Merge Conflicts):** aunque los flujos trabajan en ramas diferentes, la edición simultánea de módulos comunes o archivos de configuración inevitablemente provocará conflictos al fusionar, que deberán resolverse manualmente. 3. **Aislamiento del entorno cloud:** Los Threads se ejecutan en contenedores virtuales de Anthropic. No tienen acceso directo a tus bases de datos locales, emuladores de dispositivos ni servicios internos detrás de una VPN corporativa. Para tales tareas, todavía se requiere una sesión local de Claude Code. 4. **Ventanas de contexto:** a pesar de la compresión automática del contexto (*compaction*), el flujo puede agotar la ventana disponible durante una depuración prolongada. En tal caso, el coordinador crea un flujo sucesor limpio. --- ## Resumen: un nuevo nivel de división del trabajo Claude Code Projects cambia radicalmente el rol del ingeniero en el proceso de desarrollo: ``` ANTES: La persona escribe código ➔ La persona ejecuta pruebas ➔ La persona fusiona ramas AHORA: La persona establece el objetivo ➔ El coordinador de IA orquesta ➔ Los agentes escriben código ``` En lugar de ejecutar comandos manualmente en una decena de ventanas de terminal, el desarrollador se convierte en **arquitecto y director técnico de su propio equipo de agentes autónomos de IA**, reservándose para sí mismo la revisión final de la arquitectura y la aprobación de las Pull Requests.