Claude Code · Nawigowalność projektu

Dlaczego agent AI sam się odnalazł w moim projekcie i jak ułożyć projekt, żeby to było możliwe.

Praktyczny przewodnik po tym, jak ułożyć projekt, żeby agent AI potrafił sam się w nim zorientować, znaleźć właściwe pliki i wykonać zadanie bez tego, żebyś za każdym razem tłumaczył mu, gdzie co leży. Przykład pochodzi z pracy w Claude Code, ale ta sama zasada działa w innych narzędziach tego typu, na przykład w Codex od OpenAI. Zaczynamy od prawdziwej obserwacji: patrzyłem, jak mój agent pracuje, zanim cokolwiek napisał, i zobaczyłem, dlaczego mu się to udało.

Scena, od której się zaczęło

Patrzyłem, jak agent orientuje się sam.

Jedna rzecz, żeby było jasno od początku. Kiedy w tym artykule piszę „agent", mam na myśli główne AI, czyli model językowy (LLM), w tym przypadku Opus 4.8 od Anthropic, który jest częścią Claude Code. To z nim rozmawiasz wprost i to on kieruje całą pracą, czasem wołając do pomocy osobnych pomocników.

A teraz, co się właściwie wydarzyło. Poprosiłem go o napisanie artykułu. Zamiast od razu zacząć pisać, zrobił na start coś ciekawego.

Najpierw przejrzał całą strukturę folderów w moim projekcie. Potem sam otworzył kilka plików, bo wiedział, gdzie są, i ocenił, że dotyczą tematu artykułu. Dzięki temu miał na start idealny kontekst. Znalazł zapisany u mnie opis tego, jak piszę, czyli mój głos marki. Skąd wiedział, że ma go użyć? Bo w regułach jest to napisane wprost: przy pisaniu artykułów korzystaj z głosu marki. Reguły to po prostu zapisane na stałe wskazówki, jak agent ma pracować, które czyta na starcie każdej rozmowy. Zajrzał też do istniejących artykułów, żeby dopasować format. Wiedział, gdzie ich szukać, bo główny plik projektu, CLAUDE.md, jasno pokazuje strukturę folderów i ich opisy. Dopiero wtedy zaczął pisać.

Nie powiedziałem mu, gdzie są te rzeczy. Nie wytłumaczyłem, jaki mam styl ani jak buduję artykuły. Sam to wszystko znalazł. Dlaczego mógł?

Odpowiedź jest niewygodna dla większości projektów. Mógł, bo struktura była zaprojektowana tak, żeby dało się to znaleźć. Gdyby nie była, ten sam agent zgadywałby, pytałby o oczywistości albo napisałby artykuł obok moich konwencji, nie w nich.

Główna myśl

Agent jest tak dobry, jak kontekst, który sam sobie znajdzie.

Model językowy jest mądry, ale startuje z niczym. Nie wie, co jest w twoim projekcie, dopóki tego nie przeczyta. Każda sesja, czyli każda nowa rozmowa z agentem, zaczyna się na zimno.

To znaczy, że jakość jego pracy nie zależy tylko od tego, jak dobry jest model. Zależy od tego, ile sensownego kontekstu potrafi sam zebrać, zanim zacznie działać. Kontekst to po prostu wszystko, co agent zdążył o twoim projekcie przeczytać i co ma w danej chwili w pamięci. A to już nie jest właściwość modelu. To właściwość twojego projektu.

Co z tego wynika

Ty znasz swój projekt na pamięć, więc każdy układ folderów wyda ci się logiczny. Agent nie zna go wcale. Za każdym razem wchodzi do niego jak ktoś, kto widzi go pierwszy raz, i musi się zorientować od zera. Dlatego foldery układasz pod niego, nie pod siebie.

To, jak ułożysz foldery, jest dla agenta mapą twojego projektu. Nie po to, żeby wyglądało ładnie, ale żeby agent potrafił się w tym połapać i sam trafił tam, gdzie trzeba.

Anatomia przebiegu

Co agent faktycznie zrobił, krok po kroku.

Rozłóżmy ten przebieg, bo pokazuje, z czego składa się dobra nawigacja. Zadziałało kilka rzeczy naraz, nie jedna.

Zacznijmy od tego, co najłatwiej źle zrozumieć. Niczego mu nie podałem ani nie wgrałem. Projekt jest po prostu ułożony tak, że agent sam znalazł jego opis. Punktem wyjścia jest jedna rzecz: agent AI na starcie każdej rozmowy automatycznie czyta główny plik na górze projektu, CLAUDE.md. Nie trzeba mu tego kazać, robi to zawsze. I właśnie z niego od razu wie, czym jest projekt, jak są ułożone główne foldery i że każdy folder ma własny opis, który doczepi się sam, gdy agent do niego wejdzie. O samym tym pliku więcej poniżej, przy omówieniu warstw. Za chwilę zobaczysz też przykładową strukturę, na której to wszystko pokazuję.

Kiedy agent wszedł do folderu z materiałami, opis tego folderu sam się załadował i powiedział mu, co w środku. Dzięki temu trafił prosto do właściwych materiałów, których potrzebował, zamiast przeszukiwać wszystko po kolei. Przewidywalne nazwy plików sprawiły, że zgadywanie, gdzie co leży, prawie zawsze trafiało. A zasady, które ładują się przy każdej sesji, dały mu mój styl i sposób pracy, zanim w ogóle o to zapytał.

Pojedynczo żadna z nich by nie wystarczyła. Dopiero połączone tworzą system, po którym da się chodzić bez przewodnika.

Tak ten projekt wygląda od środka. Nie cały, bo to byłaby ściana nazw, tylko tyle, żeby było widać, z czego się składa i czym agent szedł krok po kroku.

brain-ai2expert/                  <-- mój projekt
│
├── CLAUDE.md                     <-- agent czyta go automatycznie na starcie: czym jest projekt i gdzie czego szukać
│
├── .claude/                      <-- tu mieszkają reguły, umiejętności i sub-agenci
│   ├── rules/                    <-- zasady, ładują się przy każdej rozmowie
│   │   ├── working-with-marek.md
│   │   ├── language.md
│   │   └── naming.md
│   ├── skills/                   <-- umiejętności wywoływane do konkretnych zadań
│   │   ├── create-html/
│   │   └── new-note/
│   └── agents/                   <-- sub-agenci: osobni pomocnicy do zadań
│       ├── thinking-partner.md
│       └── devils-advocate.md
│
├── 01-System/
│   └── CLAUDE.md                 <-- lokalna mapa tego folderu
├── 03-Resources/                 <-- materiały, tu agent wszedł po wiedzę
│   ├── CLAUDE.md                 <-- lokalna mapa: co jest w środku
│   ├── ai/                       <-- wiedza o AI
│   └── articles/                 <-- gotowe artykuły, stąd agent wziął format
│       ├── regula-skill-czy-subagent/
│       └── struktura-projektu-dla-agenta-ai/
└── 04-Work/
    └── CLAUDE.md                 <-- lokalna mapa tego folderu

Prześledź na niej to, co przed chwilą opisałem. Agent zaczął od CLAUDE.md na samej górze, żeby wiedzieć, gdzie wylądował. Wszedł do 03-Resources, gdzie lokalny CLAUDE.md powiedział mu, co jest w środku. Stamtąd trafił do articles, żeby podejrzeć format gotowych tekstów, a mój styl pisania miał już z reguł w .claude/rules. Sub-agenci i umiejętności czekały obok, w .claude, gotowe na moment, gdy będą potrzebne. Każdy krok to skok do miejsca, które samo się tłumaczy.

Gdzie szukać więcej

Reguły, umiejętności (skille) i sub-agenci to osobny, większy temat. Tutaj pokazuję tylko, gdzie mieszkają w strukturze, bo to artykuł o nawigacji. Jak każde z nich działa i kiedy którego użyć, rozłożyłem w osobnym tekście: Reguła, Skill czy Sub-Agent.

Model trzech warstw

Trzy warstwy, dzięki którym agent się odnajduje.

Sprowadźmy to do trzech warstw, które razem tworzą projekt, po którym agent sam się porusza. Każda odpowiada na inne pytanie agenta.

Warstwa 01

Indeks na górze

„Czym to w ogóle jest"

Na samym szczycie projektu potrzebujesz jednego pliku, który mówi agentowi, gdzie wylądował. Czym jest ten projekt, jaki ma cel, jak są ułożone główne foldery i gdzie szukać szczegółów. W Claude Code tę rolę pełni główny plik o nazwie CLAUDE.md.

Nie jest to specyficzne dla jednego narzędzia. Inne rozwiązania tego typu, jak Codex od OpenAI, czytają projekt tak samo. Zmienia się nazwa pliku, nie idea. Wszędzie agent najpierw szuka miejsca, które powie mu, gdzie się znalazł.

To jest pierwsza rzecz, którą agent czyta. Jeśli jej nie ma albo jest mglista, agent zaczyna od zgadywania, a zgadywanie na starcie zatruwa wszystko, co dalej.

Najważniejsze, czego ten plik nie powinien robić, to próbować zmieścić w sobie wszystkiego. Jego zadaniem jest być mapą, nie encyklopedią. Ma pokazać agentowi, dokąd pójść po resztę, a nie wyłożyć całą resztę od razu.

U mnie ten plik nie trzyma nawet całej mapy folderów u siebie. Wskazuje na osobny plik, który jest jedynym źródłem prawdy o tym, jak ułożone są główne foldery i co w którym jest. Dzięki temu, gdy struktura się zmienia, poprawiam ją w jednym miejscu, a każda reguła i każdy agent, który potrzebuje się w projekcie odnaleźć, czyta to samo, aktualne źródło, zamiast zgadywać z kopii, która zdążyła się już rozjechać z rzeczywistością. To ta sama zasada w mniejszej skali: na górze wskaźnik, treść niżej, w jednym przewidywalnym miejscu.

Żeby to nie zostało abstrakcją, zobacz, jak taki plik wygląda od środka. To nic skomplikowanego. W głównym CLAUDE.md trzymam prosty spis, w którym każdy wiersz to jedna pozycja: nazwa folderu i krótki opis, co w nim jest. Sama nazwa działa jak wskaźnik, dokąd agent ma pójść po szczegóły.

CLAUDE.md                         <-- główny plik na górze projektu

## Doc Index

| Folder          | Co w nim jest                          |
|-----------------|----------------------------------------|
| `01-System/`    | tożsamość, głosy marki, szablony       |
| `03-Resources/` | wiedza i materiały referencyjne        |
| `04-Work/`      | cała praca AI2Expert, aktywne projekty |

Agent czyta ten spis i od razu wie, że po wiedzę o AI idzie do 03-Resources, a po szablony do 01-System. Nie musi niczego zgadywać ani otwierać folderów na próbę. Dokładnie tak samo wygląda lokalna mapa wewnątrz każdego folderu, tyle że opisuje to, co leży o piętro niżej. To ten sam wzór, powtórzony na każdym poziomie.

I jeszcze jedno, żeby nie zostało wrażenie, że trzeba to klepać ręcznie. Ja tych plików nie piszę manualnie. Mam do tego osobną umiejętność, jeden z tych skilli, o których wspominałem wcześniej. Patrzy, co realnie leży w folderze, i sama generuje taki opis, a mnie zostaje tylko sprawdzić, czy się zgadza.

Tip

Dobry plik na górze to spis treści, nie księga. Jeśli rośnie w stronę dokumentu na tysiąc linijek, to znak, że treść powinna zejść do folderów, a na górze ma zostać tylko wskaźnik, gdzie jej szukać.

Warstwa 02

Lokalne mapy w każdym folderze

„Co tu jest"

To jest sedno i to jest dokładnie ta rzecz, której nie docenia większość ludzi. Każdy istotny folder powinien mieć własny krótki opis swojej zawartości.

Siła tego rozwiązania polega na tym, że ten opis pojawia się dokładnie wtedy, gdy agent wchodzi do danego folderu, a nie wcześniej. Agent nie musi trzymać w głowie mapy całego projektu naraz. Wchodzi do folderu, dostaje jego lokalną mapę, wie co i gdzie. To jest dawkowanie kontekstu: właściwy kawałek we właściwym momencie.

W moim przebiegu to właśnie ta warstwa zadziałała najmocniej. Lokalny opis folderu z materiałami powiedział agentowi, co zawiera podfolder z artykułami i co podfolder z wiedzą o AI. Bez tego musiałby otwierać pliki na ślepo, żeby zrozumieć, co jest czym.

Kluczowa zasada

Lokalna mapa folderu jest cenniejsza niż jeden wielki opis na górze. Wielki opis agent musi przeszukać. Lokalną mapę dostaje gotową, w chwili gdy jej potrzebuje.

Warstwa 03

Przewidywalne nazwy i stałe miejsca

„Gdzie to znajdę"

Dwie pierwsze warstwy mówią agentowi, co jest. Trzecia sprawia, że agent może trafnie zgadnąć, gdzie coś jest, zanim jeszcze przeczyta opis.

Działa to tylko wtedy, gdy nazwy i miejsca są przewidywalne. Jeśli pliki nazywasz raz tak, raz inaczej, a podobne rzeczy lądują w trzech różnych folderach zależnie od nastroju, agent nie ma jak zgadywać. Musi wszystko sprawdzać, a to kosztuje i często prowadzi do błędu.

Przewidywalność bije pomysłowość. Nudna struktura, którą da się niezawodnie odgadnąć, jest lepsza od sprytnej, której trzeba się nauczyć. To samo dotyczy trzymania rzeczy na swoim miejscu: jeśli dla każdej nowej rzeczy jest oczywiste miejsce, agent odkłada ją tam, gdzie potem sam ją znajdzie.

Sprawdzian

Jak sprawdzić, czy twoja struktura jest dobra.

Jest jedno pytanie, które prześwietla każdy projekt lepiej niż jakakolwiek lista kontrolna.

Jedno pytanie

Czy za każdym razem, gdy zaczynasz nową rozmowę z AI, musisz tłumaczyć wszystko od nowa? Wpisywać, gdzie co leży i czego gdzie szukać?

Jeśli tak, struktura jest do poprawy, bo logika projektu siedzi w twojej głowie, a nie w plikach. Coś wymaga naprawy: albo układ folderów, albo nazwy, albo lokalne opisy. Jeśli nie musisz nic tłumaczyć, bo agent łapie kontekst sam, struktura działa.

To kryterium jest namacalne, bo sprawdza nie to, czy struktura jest ładna, ale czy jest czytelna dla kogoś bez twojej wiedzy. A agent zawsze jest kimś bez twojej wiedzy. Każda sesja zaczyna jako ten nowy, zdezorientowany przybysz.

Warning

Najgroźniejszy jest projekt, który ty rozumiesz, bo go zbudowałeś, ale którego logika siedzi tylko w twojej głowie. Ty patrzysz na ekran i od razu widzisz, gdzie co leży, bo rozpoznajesz to wzrokiem. Agent nie ma twoich oczu. Nie widzi folderów tak jak ty i nie domyśla się reszty z wyglądu. Dostaje dokładnie to, co zapisane, nie to, co ty widzisz na ekranie i masz w pamięci.

Antywzorzec

Jak wygląda zła struktura.

Dla kontrastu, oto co zwykle psuje nawigację. Tworzysz nowe pliki i wrzucasz je do jednego folderu bez pomysłu i bez struktury. Nie masz porządnie zdefiniowanego CLAUDE.md, więc agent nie ma od czego zacząć. Wtedy dzieje się jedno z dwojga. Albo znajdzie informację niepełną i da ci odpowiedź, której nie oczekiwałeś. Albo nie znajdzie nic, bo nie wie, gdzie szukać. Agent działa na predykcji, więc bez mapy chodzi po projekcie jak po omacku w ciemnym pokoju, szuka czegoś, nie wiedząc, gdzie co leży.

Podobnie z zasadami. Jeśli nie dasz agentowi żadnych reguł, wymyśli je sobie sam, na podstawie tego, jak był trenowany. A to nie zawsze pokrywa się z tym, czego ty chcesz. Domyślnie dostaniesz styl i konwencje modelu, nie swoje.

Nawet nazwy plików robią różnicę. Jeśli raz nazywasz coś tak, raz inaczej, dostajesz zupełnie inny efekt, bo agent nie ma jak przewidzieć, gdzie zajrzeć. U mnie w projekcie wszystkie nazwy trzymają się jednej konwencji: małe litery, słowa rozdzielone kreską, wszystko logiczne i spójne. Dzięki temu agent trafia w nazwę, zanim jeszcze otworzy plik.

Efekt jest taki sam jak przy złej dokumentacji dla człowieka, tylko boli szybciej. Człowiek dopyta. Agent po prostu zgadnie i pójdzie dalej w złą stronę.