# Strategie dla baz kodu powyżej miliona linii z agentami

URL: https://developertoolkit.ai/pl/workflows/build/large-codebases/
Description: Prowadź agentów w repozytoriach powyżej miliona linii: warstwowy kontekst, serwery MCP z analizą kodu, raporty zasięgu zmian i automatyczne bramki CI.

Strategie pracy z agentami w bazach kodu powyżej miliona linii opierają się na dyscyplinie doboru kontekstu zamiast na samej pojemności okna. Warstwowe pliki instrukcji opisują architekturę, serwer MCP do analizy kodu rozwiązuje symbole i wywołania między pakietami, raport zasięgu zmian wskazuje każdego konsumenta przed edycją, a deterministyczne bramki CI dowodzą kompletności bez czytania każdej linii.

Deweloperzy zmieniający rozległe systemy i tech leadzi projektujący standardy harnessu zderzają się z tym samym błędem. Odziedziczasz monolit na 1,8 miliona linii, którego autorzy odeszli dwa lata temu, a pierwsze zgłoszenie zmienia nazwę `User.role`. Agent poprawia trzy pliki w `packages/web`, melduje zielone testy jednostkowe, a dwie godziny po wdrożeniu `billing-worker` rzuca wyjątkiem, bo czyta to pole ze współdzielonego zdarzenia, którego agent nigdy nie otworzył. Problem powstał na etapie rozpoznania: kluczowy konsument został niewidoczny.

## Dlaczego większe okno kontekstu nie rozwiązuje skali milionów linii

Żadne okno kontekstu nie mieści czysto wielomilionowego repozytorium, a zapchanie większości okna luźno powiązanymi plikami obniża jakość wnioskowania na długo przed limitem tokenów (zobacz [okna kontekstu](/pl/workflows/context/context-windows/)). W dużej skali projektujesz ładowanie kontekstu w trzech warstwach, tak aby każda linia pracowała na wynik:

| Warstwa | Co zawiera | Gdzie żyje | Reguła ładowania |
| --- | --- | --- | --- |
| **Architektura** | Mapa modułów, kierunek zależności, reguły współdzielonych schematów, komendy weryfikacji | Główny `AGENTS.md`, `CLAUDE.md` albo zawsze aktywna reguła Cursora | Każda sesja (krótko, ≤ 150 linii) |
| **Domena** | Niezmienniki pakietu, reguły płatności lub uprawnień, lokalne komendy testów | Zagnieżdżony `AGENTS.md`, `.claude/rules/` albo `.cursor/rules/*.mdc` z globami | Tylko podczas pracy w tym pakiecie |
| **Implementacja** | Zmieniane pliki, bezpośredni wywołujący i jeden dobry wzorzec do naśladowania | Pobierane przez nawigację po symbolach lub celowane wyszukiwanie | Na żądanie, dla bieżącego zadania |

Warstwę architektury piszesz raz i regularnie ją odchudzasz, bo każda zbędna linia obciąża każdą sesję w zespole. Praktykę utrzymywania zwięzłych plików opisują przewodniki [kontekst w AGENTS.md](/pl/workflows/context/agents-md-context/) oraz [przycinanie plików kontekstowych](/pl/workflows/context/pruning-context-files/).

### Jak poszczególne narzędzia ładują warstwowe instrukcje

Zagnieżdżone reguły chronią niepowiązane sesje przed szumem domenowym, lecz każde narzędzie wczytuje je według własnego mechanizmu:

- **Claude Code:** Ładuje pliki `CLAUDE.md` od katalogu roboczego w górę przy starcie, a pliki z podkatalogów na żądanie podczas ich czytania. Reguły przekrojowe po ścieżkach umieszczaj w `.claude/rules/`, a wspólne zasady deleguj przez `@AGENTS.md`, żeby uniknąć rozjazdu. Aktualne zasady pierwszeństwa znajdziesz w [dokumentacji Claude Code](https://code.claude.com/docs).
- **OpenAI Codex:** Automatycznie wczytuje `AGENTS.md` od katalogu głównego repozytorium w dół do katalogu uruchomienia, w ramach limitu bajtów dokumentacji projektu. Zbyt długi plik główny wypiera reguły pakietu. Uruchamiaj sesję wewnątrz docelowego pakietu, gdy jego niezmienniki są krytyczne, albo wskaż plik pakietu w specyfikacji zadania. Szczegóły hierarchii i sandboksu podaje [dokumentacja Codex](https://developers.openai.com/codex).
- **Cursor:** Warstwę architektury trzyma w `.cursor/rules/*.mdc` z `alwaysApply: true` (lub głównym `AGENTS.md`), a reguły domenowe z polami `globs` lub `description`. Zacommituj `.cursorignore` wykluczający generowanych klientów, lockfile i snapshoty, aby szum nie zalewał wyszukiwania. Format reguł opisuje [dokumentacja Cursora](https://cursor.com/docs).

## Zastąp pętle grepa analizą kodu przez MCP

Przeszukiwanie milionowego repozytorium dziesiątkami zapytań tekstowych marnuje kontekst na fałszywe trafienia i pomija referencje przez reeksporty. Serwer analizy kodu podpięty przez [Model Context Protocol](https://modelcontextprotocol.io) pozwala agentowi znaleźć definicje, wywołujących i ścieżki wywołań jednym ustrukturyzowanym zapytaniem. Dobierz model indeksowania do wymagań bezpieczeństwa i rodzaju pytań:

| Podejście | Najlepsze zastosowanie | Kompromis |
| --- | --- | --- |
| **MCP z serwerem językowym (LSP)** (np. Serena) | Dokładne rozwiązywanie symboli, zmiany nazw między pakietami, typowani wywołujący | Działa w pełni lokalnie; wymaga sprawnego serwera językowego dla każdego stosu |
| **MCP z grafem tree-sitter** | Szybki graf strukturalny i śledzenie ścieżek wywołań w repozytoriach wielojęzycznych | Działa lokalnie; pomija refleksję w runtime i nietypowane zdarzenia |
| **Hybrydowe wyszukiwanie wektorowe + BM25** | Pytania pojęciowe („gdzie ponawiamy nieudane obciążenia?”) przy niespójnym nazewnictwie | Wymaga potoku indeksowania; przed wysłaniem fragmentów do hostowanych embeddingów sprawdź politykę danych |

Rejestruj rozbudowane serwery MCP w zakresie projektu tylko tam, gdzie realnie pracują: każdy serwer dokłada definicje narzędzi do każdej tury. Pełne porównanie kompromisów znajdziesz w [przeglądzie MCP](/pl/ecosystem/mcp/).

## Kolejność działań: mapa, zasięg zmian, wycinki od kontraktów

W dużych repozytoriach kolejność prac rozstrzyga, czy braki wykryje kompilator w kilka sekund, czy dopiero produkcja po godzinach.

1. **Utrzymuj trwałą mapę architektury.** Zacommituj zwięzłe `docs/architecture/map.md` (poniżej 300 linii) z pakietami, tabelami, kierunkiem zależności oraz każdym nietypowanym konsumentem (zdarzenia, kolejki, współdzielone tabele, konfiguracja). Odświeżaj i przeglądaj diff po dużych scaleniach.
2. **Zrób raport zasięgu zmian przed edycją.** Przeszukaj kod, schematy zdarzeń, migracje SQL, serializatory, fixture'y i flagi, tworząc blok `FILES` i ranking pięciu najbardziej ryzykownych plików. Gdy brakuje znanego konsumenta, najpierw napraw indeks lub reguły ignorowania.
3. **Najpierw zmień współdzielone kontrakty.** Zacommituj `blast-radius.txt` na gałęzi i zaktualizuj współdzielone typy, schematy oraz migracje w pierwszym wycinku, aby kompilator dał drugą, niezależną listę konsumentów.
4. **Wdrażaj po jednym pakiecie w izolowanym wycinku.** Każdy wycinek to jeden PR do przeglądu. Niezależne pakiety rozdzielaj na osobne worktree lub chmurę — w tempie ludzkiej recenzji ([Git worktree](/pl/workflows/harness/git-worktrees/), [wzorce orkiestracji](/pl/workflows/automate/orchestration-patterns/)).
5. **Resetuj kontekst między zadaniami.** Otwieraj czystą sesję lub jawnie kompaktuj kontekst przy każdej zmianie wycinka albo po dwukrotnym powtórzeniu tej samej poprawki.

**Wzorzec promptu: raport zasięgu zmian tylko do odczytu**

```text
We are renaming User.role to User.accountType. Do not edit any file.
Search code, event schemas, SQL migrations, serializers, fixtures, and flags:
1. List every file reading or writing User.role (path:line), grouped by package.
2. List consumers reading `role` from events, queues, APIs, or SQL without importing User.
3. Rank the five riskiest files with one line each.
4. End with a fenced FILES block listing every path from sections 1 and 2.
Use the connected code-intelligence MCP server and show the search commands run.
```

## Jak zweryfikować zmianę w 60 plikach bez czytania każdej linii

Zatwierdzasz przekrojową zmianę dlatego, że przeszły niezależne, falsyfikowalne bramki na stacjach Verification i Release w Software Factory (Poziom 3 → Poziom 4).

| Bramka weryfikacji | Czego dowodzi | Kiedy blokuje |
| --- | --- | --- |
| **Kontrola typów całego repozytorium** | Każdy kompilowany konsument pasuje do nowego kontraktu | Wywołanie nadal przekazuje stary kształt |
| **Testy dotkniętych konsumentów** | Zachowanie zależnych pakietów pozostaje nienaruszone | Graf budowania uruchamia testy wszystkich zależnych celów, a nie tylko zmienionego pakietu |
| **Wyszukiwanie pozostałości** | Żadna stara nazwa pola ani klucz tekstowy nie przetrwały | Wyszukiwanie regex lub AST w kodzie i schematach znajduje ślady starej nazwy |
| **Uzgodnienie raportu z diffem** | Każdy plik z `blast-radius.txt` został zmieniony lub jawnie wyjaśniony | Różnica zbiorów między `blast-radius.txt` a `git diff --name-only` zawiera niewyjaśnione ścieżki |
| **Testy kontraktów i schematów** | Nietypowani konsumenci (zdarzenia JSON, kolejki, widoki SQL) wciąż poprawnie parsują dane | Porażka testów schematu lub kontraktu konsumenta |
| **[Funkcje dopasowania](/pl/workflows/test/fitness-functions/)** | Kierunek zależności i warstwy zostały zachowane | Agent dodał zakazany import między pakietami |
| **Niezależna recenzja agenta** | Świeży model sprawdził błędy logiki niewidoczne dla narzędzi statycznych | Agent recenzujący zgłasza znalezisko P0 lub P1 |

Dołącz listę zasięgu zmian, wyniki bramek i plik `excused.txt` z uzasadnieniami pominięć do [pakietu dowodów](/pl/workflows/ship/evidence-bundle/) pull requesta. Właściciele pakietów wskazani w `CODEOWNERS` sprawdzają wiarygodność raportu i wyjątków dla swojej domeny zamiast czytać sześćdziesiąt mechanicznych diffów. Uruchom `npx @wondelai/harness-audit` (zobacz [Harness Audit](/pl/harness-audit/)), żeby sprawdzić budżet instrukcji, pojedynczą komendę weryfikacji i izolację worktree.

## Co się psuje w bazach kodu powyżej miliona linii?

- **Nieaktualna mapa architektury lub indeks po dużym scaleniu.** Agenci wskazują przeniesione albo usunięte pliki. *Wyjście:* Przeindeksuj repozytorium po dużych rebase'ach lub generacji kodu, odśwież `docs/architecture/map.md` i przejrzyj jej diff.
- **Zmyślone importy albo wyssane z palca liczby.** Agent zgaduje ścieżkę symbolu albo podaje liczbę wywołań bez uruchomienia polecenia. *Wyjście:* Wymagaj znalezienia definicji przed napisaniem importu i uznawaj liczby tylko z powtarzalną komendą wyszukiwania.
- **Jeden wygenerowany plik zatyka okno kontekstu.** Klient API na 8000 linii wypiera realne niezmienniki. *Wyjście:* Wyklucz kod generowany w `.cursorignore` i regułach serwera MCP, a agentowi wskazuj konkretne symbole lub zakresy linii.
- **Pojedyncze wycinki przechodzą, a integracja pada.** Nietypowany subskrybent zdarzeń albo widok SQL zależał od starego pola. *Wyjście:* Dodaj test kontraktu na tej granicy, dopisz konsumenta do sekcji „czyta bez importu” w `docs/architecture/map.md` i powtórz uzgodnienie.
- **Agent edytuje reeksport zamiast źródła prawdy.** W trakcie eksploracji zgubił kierunek zależności. *Wyjście:* Uruchom rozpoznanie grafu zależności dla modułu i podaj wprost ścieżkę źródłową w prompcie wycinka.
- **Równoległe wycinki zderzają się na wspólnych helperach.** Dwa równoległe worktree zmieniają to samo narzędzie. *Wyjście:* Przypisz współdzielone pliki do jednego wycinka wstępnego i scal go przed uruchomieniem zależnych pakietów.

## Oficjalna dokumentacja i kolejne kroki

- Dokumentacja dostawców: [Claude Code](https://code.claude.com/docs), [OpenAI Codex](https://developers.openai.com/codex), [Cursor](https://cursor.com/docs) oraz [Model Context Protocol](https://modelcontextprotocol.io).
- Powiązane przewodniki: [modernizacja legacy z agentami](/pl/workflows/build/legacy-modernization/), [Git worktree dla równoległych agentów](/pl/workflows/harness/git-worktrees/), [funkcje dopasowania architektury](/pl/workflows/test/fitness-functions/) oraz [pakiet dowodów](/pl/workflows/ship/evidence-bundle/).
