# Claude Code Projects: як один ШІ координує команду автономних агентів > Глибокий аналіз Claude Code Projects: архітектура Coordinator та Threads, паралельні гілки, спільна пам'ять MEMORY.md та управління хмарними агентами. З виходом **Claude Code Projects** розробка за допомогою штучного інтелекту переходить від парадигми *«один розробник — один чат»* до повноцінної **багатоагентної оркестрації**. Раніше для вирішення великої комплексної задачі інженеру доводилося вручну відкривати кілька термінових сесій, копіювати між ними контекст, стежити за гілками в Git і самостійно склеювати результати. У новій моделі всю диспетчеризацію бере на себе провідний ШІ. Ви формулюєте одну загальну стратегічну мету, а Claude бере управління на себе: - **Декомпозиція роботи:** розбиває масштабну мету на ізольовані підзадачі. - **Оркестрація потоків:** запускає паралельні хмарні сесії (**Threads**). - **Контроль контексту:** синхронізує рішення через спільну пам’ять проекту (`MEMORY.md`). - **Верифікація результату:** проганяє тести, перевіряє статус збірки в CI та готує фінальні Pull Requests. > [!NOTE] > **Автономність без прив’язки до локальної машини:** робочі потоки (Threads) функціонують в ізольованих хмарних контейнерах Anthropic. Вони продовжують виконувати тести та писати код навіть при закритій кришці вашого ноутбука, а статус роботи можна перевіряти зі смартфона. --- ## Архітектура системи: Координатор та Робочі Потоки (Threads) В основі багатоагентної системи Claude Code Projects лежить двохрівнева модель розподілу обов’язків: ``` ┌──────────────────────────────┐ │ ПОРИСТУВАЧ / ТЕХЛІД │ └──────────────┬───────────────┘ │ Постановка загальної мети ▼ ┌──────────────────────────────┐ │ КООРДИНАТОР (COORDINATOR) │ │ Основний діалог Project │ └──────────────┬───────────────┘ │ ┌───────────────────────┼───────────────────────┐ │ Делегування │ Делегування │ Делегування ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ THREAD 1 │ │ THREAD 2 │ │ THREAD 3 │ │ Хмарна сесія │ │ Хмарна сесія │ │ Хмарна сесія │ │ Гілка: `feat/p75`│ │ Гілка: `ref/api` │ │ Гілка: `fix/db` │ │ Тести ➔ PR #101 │ │ Тести ➔ PR #102 │ │ Тести ➔ PR #103 │ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ └───────────────────────┴───────────────────────┘ │ Спільна пам'ять: `MEMORY.md` / `CLAUDE.md` ``` ### Порівняльна таблиця рівнів системи: | Компонент | Роль у системі | Середовище виконання | Контекст та Пам’ять | Головний результат | | :--- | :--- | :--- | :--- | :--- | | **Coordinator** | Керуючий центр, диспетчер | Головний діалог проекту | Бачить звіти всіх потоків | Декомпозиція, зведений статус | | **Thread** | Автономний робочий агент | Хмарна сесія (Cloud VM) | Власна копія Git-гілки | Готовий Pull Request, тести | | **Subagent** | Вузкоспеціалізований помічник | Всередині конкретного Thread | Локальний цикл обробки | Виконання мікро-скрипту | --- ## 1. Координатор (Coordinator): керуючий центр Головна розмова всередині Project виступає як диспетчерський вузол. Саме сюди ви надсилаєте високорівневі вимоги, технічні специфікації та корективи. Координатор виконує такі завдання: - **Приймання вимог:** аналізує складний запит і визначає межі задачі. - **Маршрутизація:** вирішує, запустити чи новий потік, або передати задачу в уже існуючий контекст. - **Агрегація звітів:** отримує короткі резюме від агентів, не засмічуючи головний чат гігабайтами проміжних логів. - **Синтез:** поєднує результати розрізнених потоків у єдиний фінальний продукт. > [!IMPORTANT] > Координатор не виконує низькорівневу роботу самостійно. Він виступає в ролі технічного ліда: розподіляє ролі, валідує архітектурну сумісність і контролює статус виконання. --- ## 2. Робочі потоки (Threads): хмарні розробники Кожен **Thread** — це повноцінна незалежна сесія Claude Code, розгорнута в хмарній інфраструктурі. При роботі з кодовою базою кожен потік: - **Ізолює середовище:** клонує свіжу копію репозиторію в окремий контейнер. - **Працює у своїй гілці:** створює Git-гілку під конкретну фічу, виключаючи прямі конфлікти з сусідніми агентами. - **Валідує код:** запускає локальні лінтери, юніт-тести та інтеграційні сценарії. - **Оформлює результат:** самостійно відкриває Pull Request на GitHub і надсилає коротку вижимку координатору. Ви можете продовжувати ставити координатору нові завдання, поки кілька потоків одночасно рефакторять різні модулі системи. --- ## 3. Як Claude декомпонує задачі Вам не потрібно вручну нарізати задачі та створювати агентів через кнопки інтерфейсу. Ви надсилаєте в чат глобальну вимогу, а координатор обирає одну з трьох стратегій: ### Стратегія А: Нова задача ➔ Новий Thread Якщо задача незалежна і потребує значного обсягу змін, координатор створює для неї чисту хмарну сесію. Наприклад, якщо в одному промпті попросити: - *«Оптимізуй швидкість холодного старту API та онови документацію в OpenAPI-специфікації»* — Claude паралельно запустить два ізольовані потоки. ### Стратегія Б: Розвиток теми ➔ Існуючий Thread Якщо нова вхідна доповнює задачу, над якою потік вже працює, Claude не плодить дублікати. Він направляє запит у вже «розігрітий» контекст, де агент пам’ятає попередні правки та структуру задіяних файлів. ### Стратегія В: Просте питання ➔ Відповідь в основному чаті Короткі довідкові запити (*«Яка версія Node.js вказана в кореневому package.json?»*) координатор обробляє миттєво в головному вікні, не витрачаючи час на ініціалізацію хмарного контейнера. > [!TIP] > **Керування логікою координатора:** якщо вам не подобається автоматичний розподіл завдань, задайте суворе правило в чаті: > `«Перед створенням будь-яких нових threads завжди покажи мені план декомпозиції та дочекайся мого підтвердження».` --- ## 4. Панель Overview: прозорий контроль статусів Коли в проекті одночасно працюють 5–10 агентів, моніторити їх через окремі термінали неможливо. Вся активність консолідується в дашборді **Overview**. ### Матриця життєвого циклу потоків: | Статус потоку | Що відбувається «під капотом» | Дія з боку користувача | | :--- | :--- | :--- | | **`Working`** | Агент пише код, запускає збірку або тести | Втручання не потрібне, задача в процесі виконання | | **`Waiting on you`** | Агент заблокований: потрібне підтвердження дії або API-ключ | Відкрити потік і надати відповідь / підтвердження | | **`Ready for review`** | Код написаний, тести пройдені, Pull Request відкрито | Провести код-рев’ю в GitHub | | **`Landing`** | Pull Request схвалено й очікує на мердж у основну гілку | Підтвердити злиття (Merge) | | **`Idle`** | Агент завершив роботу й перебуває в режимі очікування | Потік готовий прийняти наступну підзадачу | | **`Resolved`** | Гілку злито, задачу повністю закрито | Потік архівується | ### Спеціалізовані вкладки проекту: - **Library:** база знань проекту, куди зберігаються створені агентами специфікації, звіти та файли даних. - **Pull Requests:** єдиний список усіх відкритих агентами PR із позначками про статус проходження CI. - **Routines:** заплановані регулярні процедури (наприклад, щоденний аудит безпеки залежностей). --- ## 5. Загальна пам'ять проекту: синхронізація без втрат Усі потоки всередині одного проекту працюють не ізольовано — вони підключені до єдиної системи **Project Memory**. ``` Project Root/ ├── MEMORY.md # Головний індекс рішень, архітектурних правил та обмежень ├── CLAUDE.md # Локальні інструкції для конкретного репозиторію └── docs/ # Специфікації та документація, доступні всім агентам ``` ### Що запам'ятовує Claude: - **Архітектурні домовленості:** наприклад, відмова від бібліотеки X на користь легковажного рішення Y. - **Операційні рамки:** перенесення дати релізу, особливий регламент погодження правок у модулі білінгу. - **Вподобання автора:** угоди щодо стилю коду, заборонені патерни, вибір пакетного менеджера (`pnpm` замість `npm`). Кожен новий потік при старті першочергово зчитує файл `MEMORY.md`. Тому вам не доводиться повторювати одним і тим самим агентам базові вимоги проекту. --- ## 6. Як втручатися в роботу окремого агента Попри високий рівень автономності координатора, розробник зберігає повний контроль над кожним етапом. Ви можете в будь-який момент «провалитися» всередину будь-якого потоку: - **Переглад повного Transcript:** похвилинний лог виконаних shell-команд, прочитаних файлів та висновків лінтера. - **Точкова корекція курсу:** надсилання прямого вказівки конкретному агенту (*«Сконцентруйся лише на endpoint /checkout, решту поки не чіпай»*). - **Екстрена зупинка (Stop):** переривання завислого потоку в один клік. > [!WARNING] > **Критичне правило маршрутизації:** > Якщо агент зупинився й запитує дозвіл на виконання небезпечної дії (наприклад, видалення файлів або деплой), підтверджувати команду необхідно **суто всередині самого Thread**. Команда «Продовжуй», надіслана в загальний чат координатора, до заблокованого потоку не дійде! --- ## 7. Практичні сценарії застосування Багатоагентний підхід особливо ефективний у чотирьох інженерних сценаріях: ### Сценарій 1: Оптимізація продуктивності (Latency Profiling) **Задача:** Знизити затримку відповіді сервісу оформлення замовлень (Checkout p75 latency) з 800 мс до 200 мс. - *Thread 1:* Профілює SQL-запити до бази даних і створює міграцію для відсутніх індексів. - *Thread 2:* Налаштовує Redis-кешування важких відповідей каталогу. - *Thread 3:* Оптимізує розмір клієнтського бандла та прибирає невикористані імпорти. Кожен потік готує окремий PR з ізольованими бенчмарками. ### Сценарій 2: Крос-репозиторна міграція API **Задача:** Вивести з експлуатації застарілий v1 API в усіх суміжних сервісах компанії. - До Project підключаються репозиторії Backend API, Web App та Mobile App. - Координатор запускає 3 потоки: кожен потік переводить виклики на v2 API у своєму репозиторії, проганяє локальні тести та оформлює PR із зазначенням порядку їхнього злиття. ### Сценарій 3: Сквозний рефакторинг за технічною специфікацією **Задача:** Реалізувати складний модуль авторизації за файлом `docs/auth-spec.md`. - Координатор дробить специфікацію на логічні фази: генерація моделей даних ➔ реалізація middleware ➔ інтеграція OAuth ➔ написання e2e-тестів. Знання передаються від фази до фази через `MEMORY.md`. ### Сценарій 4: Пакетний аудит документації та контрактів **Задача:** Перевірити сотні договорів або тікетів техпідтримки. - Threads розподіляють між собою пачки документів, витягують ключові ризики та складають структуровані JSON/Markdown зведення в загальне сховище `Library`. --- ## 8. Обмеження та підводні камені архітектури Паралельна робота суттєво скорочує час розробки, однак потребує розуміння технічної специфіки: 1. **Витрата токенів та лімітів тарифу:** кожен активний Thread споживає квоту моделі незалежно. Крім того, координатор витрачає токени на читання довгих звітів. У системі встановлено ліміт — до **200 нових потоків на день** на проект. 2. **Merge Conflicts:** хоча потоки працюють у різних гілках, одночасне редагування спільних модулів або конфігураційних файлів неминуче призведе до конфліктів при злитті, які доведеться вирішувати вручну. 3. **Ізоляція хмарного середовища:** Threads виконуються у віртуальних контейнерах Anthropic. Вони не мають прямого доступу до ваших локальних баз даних, емуляторів пристроїв або внутрішніх сервісів за корпоративним VPN. Для таких задач досі потрібна локальна сесія Claude Code. 4. **Контекстні вікна:** попри автоматичне стиснення контексту (*compaction*), потік під час тривалої відладки може вичерпати доступне вікно. У такому разі координатор створює чистий потік-спадкоємець. --- ## Резюме: новий рівень розподілу праці Claude Code Projects кардинально змінює роль інженера в процесі розробки: ``` БЫЛО: Человек пишет код ➔ Человек запускает тесты ➔ Человек склеивает ветки СТАЛО: Человек ставит цель ➔ ИИ-координатор оркестрирует ➔ Агенты пишут код ``` Замість ручного набору команд у десятку термінальних вікон розробник перетворюється на **архітектора та технічного директора власної команди автономних AI-агентів**, залишаючи за собою фінальний огляд архітектури та схвалення Pull Requests.