# Claude Code Projects: jak jeden AI koordynuje zespół autonomicznych agentów > Głęboka analiza Claude Code Projects: architektura Coordinator i Threads, równoległe gałęzie, wspólna pamięć MEMORY.md oraz zarządzanie agentami w chmurze. Wraz z premierą **Claude Code Projects** rozwój wspierany przez sztuczną inteligencję przechodzi od paradygmatu *„jeden programista – jeden czat”* do pełnoprawnej **wieloagentowej orkiestracji**. Wcześniej, aby rozwiązać duże, złożone zadanie, inżynier musiał ręcznie otwierać wiele sesji terminalowych, kopiować między nimi kontekst, śledzić gałęzie w Git i samodzielnie scalać wyniki. W nowym modelu całe zarządzanie przejmuje wiodący AI. Formułujesz jedną ogólną, strategiczną cel, a Claude przejmuję sterowanie: - **Dekompozycja pracy:** dzieli duży cel na izolowane podzadania. - **Orkiestracja przepływów:** uruchamia równoległe sesje chmurowe (**Threads**). - **Kontrola kontekstu:** synchronizuje decyzje poprzez wspólną pamięć projektu (`MEMORY.md`). - **Weryfikacja wyniku:** uruchamia testy, sprawdza status buildu w CI i przygotowuje finalne Pull Requesty. > [!NOTE] > **Autonomia bez przywiązania do lokalnej maszyny:** przepływy robocze (Threads) działają w izolowanych kontenerach chmurowych Anthropic. Kontynuują one wykonywanie testów i pisanie kodu nawet przy zamkniętej klapie laptopa, a status pracy można sprawdzać ze smartfona. --- ## Architektura systemu: Koordynator i Przepływy Robocze (Threads) W podstawie wieloagentowego systemu Claude Code Projects leży dwupoziomowy model podziału obowiązków: ``` ┌──────────────────────────────┐ │ UŻYTKOWNIK / TECH LEAD │ └──────────────┬───────────────┘ │ Określenie ogólnego celu ▼ ┌──────────────────────────────┐ │ KOORDYNATOR (COORDINATOR) │ │ Główny dialog Project │ └──────────────┬───────────────┘ │ ┌───────────────────────┼───────────────────────┐ │ Delegowanie │ Delegowanie │ Delegowanie ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ THREAD 1 │ │ THREAD 2 │ │ THREAD 3 │ │ Sesja w chmurze │ │ Sesja w chmurze │ │ Sesja w chmurze │ │ Gałąź: `feat/p75`│ │ Gałąź: `ref/api` │ │ Gałąź: `fix/db` │ │ Testy ➔ PR #101 │ │ Testy ➔ PR #102 │ │ Testy ➔ PR #103 │ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ └───────────────────────┴───────────────────────┘ │ Wspólna pamięć: `MEMORY.md` / `CLAUDE.md` ``` ### Tabela porównawcza poziomów systemu: | Komponent | Rola w systemie | Środowisko wykonania | Kontekst i Pamięć | Główny wynik | | :--- | :--- | :--- | :--- | :--- | | **Coordinator** | Centrum zarządzające, dyspozytor | Główny dialog projektu | Widzi raporty wszystkich przepływów | Dekompozycja, zbiorczy status | | **Thread** | Autonomiczny agent roboczy | Sesja chmurowa (Cloud VM) | Własna kopia gałęzi Git | Gotowy Pull Request, testy | | **Subagent** | Wyspecjalizowany asystent | Wewnątrz konkretnego Thread | Lokalny cykl przetwarzania | Wykonanie mikro-skryptu | --- ## 1. Koordynator (Coordinator): centrum zarządzania Główna rozmowa wewnątrz Project pełni rolę węzła dyspozytorskiego. To tutaj wysyłasz wysokopoziomowe wymagania, specyfikacje techniczne i korekty. Koordynator wykonuje następujące zadania: - **Przyjmowanie wymagań:** analizuje złożone zapytanie i określa granice zadania. - **Trasowanie:** decyduje, czy uruchomić nowy przepływ, czy przekazać zadanie do już istniejącego kontekstu. - **Agregacja raportów:** otrzymuje krótkie streszczenia od agentów, nie zaśmiecając głównego czatu gigabajtami logów pośrednich. - **Sinteza:** łączy wyniki rozproszonych przepływów w jeden finalny produkt. > [!IMPORTANT] > Koordynator nie wykonuje niskopoziomowych prac samodzielnie. Występuje w roli Tech Leada: rozdziela role, waliduje zgodność architektoniczną i kontroluje status wykonania. --- ## 2. Przepływy Robocze (Threads): chmurowi deweloperzy Każdy **Thread** to pełnoprawna, niezależna sesja Claude Code, wdrożona w infrastrukturze chmurowej. Podczas pracy z bazą kodu każdy przepływ: - **Izoluje środowisko:** klonuje świeżą kopię repozytorium do osobnego kontenera. - **Pracuje we własnej gałęzi:** tworzy gałąź Git dla konkretnej funkcjonalności, wykluczając bezpośrednie konflikty z sąsiednimi agentami. - **Waliduje kod:** uruchamia lokalne lintery, testy jednostkowe oraz scenariusze integracyjne. - **Formalizuje wynik:** samodzielnie otwiera Pull Request na GitHub i wysyła krótkie podsumowanie koordynatorowi. Możesz nadal stawiać koordynatorowi nowe zadania, podczas gdy kilka przepływów jednocześnie refaktoryzuje różne moduły systemu. --- ## 3. Jak Claude dekomponuje zadania Nie musisz ręcznie dzielić zadań ani tworzyć agentów za pomocą przycisków interfejsu. Wysyłasz do czatu globalne wymaganie, a koordynator wybiera jedną z trzech strategii: ### Strategia A: Nowe zadanie ➔ Nowy Thread Jeśli zadanie jest niezależne i wymaga znacznych zmian, koordynator tworzy dla niego czystą sesję chmurową. Na przykład, jeśli w jednym prompcie poprosisz o: - *«Zoptymalizuj szybkość zimnego startu API i zaktualizuj dokumentację w specyfikacji OpenAPI»* — Claude równolegle uruchomi dwa izolowane przepływy. ### Strategia B: Rozwój tematu ➔ Istniejący Thread Jeśli nowe wejście uzupełnia zadanie, nad którym przepływ już pracuje, Claude nie mnoży duplikatów. Kieruje zapytanie do już „rozgrzanego” kontekstu, gdzie agent pamięta poprzednie poprawki i strukturę zaangażowanych plików. ### Strategia C: Proste pytanie ➔ Odpowiedź w głównym czacie Krótkie pytania referencyjne (*«Jaka wersja Node.js jest wskazana w korzeniowym package.json?»*) koordynator obsługuje natychmiast w oknie głównym, nie tracąc czasu na inicjalizację kontenera chmurowego. > [!TIP] > **Zarządzanie logiką koordynatora:** jeśli nie odpowiada Ci automatyczny przydział zadań, ustaw surową regułę w czacie: > `«Przed utworzeniem jakichkolwiek nowych threads zawsze pokaż mi plan dekompozycji i czekaj na moje potwierdzenie».` --- ## 4. Panel Overview: przejrzysta kontrola statusów Gdy w projekcie jednocześnie pracuje 5–10 agentów, monitorowanie ich przez osobne terminale jest niemożliwe. Cała aktywność konsolidowana jest w dashboardzie **Overview**. ### Macierz cyklu życia przepływów: | Status przepływu | Co dzieje się „pod maską” | Działanie użytkownika | | :--- | :--- | :--- | | **`Working`** | Agent pisze kod, uruchamia build lub testy | Brak ingerencji, zadanie w trakcie realizacji | | **`Waiting on you`** | Agent zablokowany: potrzebne potwierdzenie działania lub klucz API | Otwórz przepływ i udziel odpowiedzi / potwierdzenia | | **`Ready for review`** | Kod napisany, testy zaliczone, Pull Request otwarty | Przeprowadź code-review na GitHub | | **`Landing`** | Pull Request zatwierdzony i czeka na merge do głównej gałęzi | Potwierdź scalenie (Merge) | | **`Idle`** | Agent zakończył pracę i znajduje się w trybie oczekiwania | Przepływ gotowy do przyjęcia kolejnego podzadania | | **`Resolved`** | Gałąź scalona, zadanie całkowicie zamknięte | Przepływ archiwizowany | ### Specjalistyczne zakładki projektu: - **Library:** baza wiedzy projektu, gdzie przechowywane są specyfikacje, raporty i pliki danych tworzone przez agentów. - **Pull Requests:** jedyna lista wszystkich otwartych PR-ów tworzonych przez agentów, z oznaczeniami statusu przejścia CI. - **Routines:** zaplanowane regularne procedury (np. codzienny audyt bezpieczeństwa zależności). --- ## 5. Wspólna pamięć projektu: synchronizacja bez strat Wszystkie przepływy wewnątrz jednego projektu nie działają w izolacji — są połączone z jednolitym systemem **Project Memory**. ``` Project Root/ ├── MEMORY.md # Główny indeks decyzji, reguł architektonicznych i ograniczeń ├── CLAUDE.md # Lokalne instrukcje dla konkretnego repozytorium └── docs/ # Specyfikacje i dokumentacja dostępne dla wszystkich agentów ``` ### Co zapamiętuje Claude: - **Ustalenia architektoniczne:** np. rezygnacja z biblioteki X na rzecz lekkiego rozwiązania Y. - **Ramki operacyjne:** przesunięcie daty release’u, szczególny regulamin zatwierdzania poprawek w module billingowym. - **Preferencje autora:** ustalenia dotyczące stylu kodu, zakazane wzorce, wybór menedżera pakietów (`pnpm` zamiast `npm`). Każdy nowy przepływ przy starcie priorytetowo odczytuje plik `MEMORY.md`. Dlatego nie musisz powtarzać tym samym agentom podstawowych wymagań projektu. --- ## 6. Jak ingerować w pracę pojedynczego agenta Mimo wysokiego poziomu autonomii koordynatora, developer zachowuje pełną kontrolę nad każdym etapem. W dowolnym momencie możesz „wejść” do wnętrza dowolnego przepływu: - **Pełny Transcript:** minutowy log wykonanych komend shell, przeczytanych plików oraz wniosków lintera. - **Punktowa korekta kursu:** wysłanie bezpośredniego polecenia konkretnemu agentowi (*„Skup się tylko na endpoint /checkout, resztę na razie nie ruszaj”*). - **Awaryjne zatrzymanie (Stop):** przerwanie zawieszonego przepływu jednym kliknięciem. > [!WARNING] > **Krytyczna zasada trasowania:** > Jeśli agent się zatrzymał i pyta o pozwolenie na wykonanie niebezpiecznej akcji (np. usunięcie plików lub deploy), potwierdzenie polecenia musi nastąpić **wyłącznie wewnątrz samego Thread**. Polecenie „Kontynuuj”, wysłane do ogólnego czatu koordynatora, nie dotrze do zablokowanego przepływu! --- ## 7. Praktyczne scenariusze zastosowania Podejście wieloagentowe jest szczególnie efektywne w czterech scenariuszach inżynierskich: ### Scenariusz 1: Optymalizacja wydajności (Latency Profiling) **Zadanie:** Obniżyć opóźnienie odpowiedzi serwisu finalizacji zamówień (Checkout p75 latency) z 800 ms do 200 ms. - *Thread 1:* Profiluje zapytania SQL do bazy danych i tworzy migrację dla brakujących indeksów. - *Thread 2:* Konfiguruje cache Redis dla ciężkich odpowiedzi katalogu. - *Thread 3:* Optymalizuje rozmiar bundle’a klienta i usuwa nieużywane importy. Każdy przepływ przygotowuje osobny PR z izolowanymi benchmarkami. ### Scenariusz 2: Migracja API cross-repo **Zadanie:** Wycofać z eksploatacji przestarzałe v1 API we wszystkich powiązanych serwisach firmy. - Do Project podłączane są repozytoria Backend API, Web App oraz Mobile App. - Koordynator uruchamia 3 przepływy: każdy przepływ migruje wywołania na v2 API w swoim repozytorium, uruchamia lokalne testy i tworzy PR z zaznaczeniem kolejności ich scalenia. ### Scenariusz 3: End-to-end refactoring wg specyfikacji technicznej **Zadanie:** Zaimplementować złożony moduł autoryzacji zgodnie z plikiem `docs/auth-spec.md`. - Koordynator dzieli specyfikację na logiczne fazy: generowanie modeli danych ➔ implementacja middleware ➔ integracja OAuth ➔ pisanie testów e2e. Wiedza przekazywana jest z fazy do fazy poprzez `MEMORY.md`. ### Scenariusz 4: Masowy audyt dokumentacji i kontraktów **Zadanie:** Sprawdzić setki umów lub ticketów wsparcia technicznego. - Threads rozdzielają między sobą partie dokumentów, ekstrahują kluczowe ryzyka i układają ustrukturyzowane podsumowania JSON/Markdown we wspólnym repozytorium `Library`. --- ## 8. Ograniczenia i pułapki architektury Równoległa praca znacząco skraca czas rozwoju, jednak wymaga zrozumienia specyfiki technicznej: 1. **Zużycie tokenów i limitów taryfy:** każdy aktywny Thread konsumuje kwotę modelu niezależnie. Ponadto koordynator zużywa tokeny na czytanie długich raportów. W systemie ustalono limit – do **200 nowych przepływów dziennie** na projekt. 2. **Merge Conflicts:** choć przepływy pracują w różnych gałęziach, jednoczesna edycja wspólnych modułów lub plików konfiguracyjnych nieuchronnie doprowadzi do konfliktów przy scaleniu, które trzeba będzie rozwiązać ręcznie. 3. **Izolacja środowiska chmurowego:** Threads działają w wirtualnych kontenerach Anthropic. Nie mają bezpośredniego dostępu do Twoich lokalnych baz danych, emulatorów urządzeń ani wewnętrznych serwisów za korporacyjnym VPN. Dla takich zadań nadal potrzebna jest lokalna sesja Claude Code. 4. **Okna kontekstowe:** mimo automatycznej kompresji kontekstu (*compaction*), przepływ podczas długotrwałego debugowania może wyczerpać dostępne okno. W takim przypadku koordynator tworzy czysty przepływ-spadkobiercę. --- ## Podsumowanie: nowy poziom rozwoju