Twoje pliki są promptem. Jak przygotować repozytorium do pracy z AI?

Praca z AI w kodzie często zaczyna się od okna chata. Piszemy: „napraw ten błąd", „dopisz testy", „wyjaśnij ten moduł". Czasem działa świetnie. Czasem model odpowiada pewnie, ale po chwili okazuje się, że nie zna konwencji projektu, nie wie jak uruchomić testy albo zmienił plik, którego wcale nie powinien dotykać.

Problemem nie zawsze jest model. Często problemem jest to, że projekt nie daje modelowi dobrego kontekstu: tego, co widzi i na czym pracuje.

Jeżeli repozytorium ma czytelne README.md, zasady w CONTRIBUTING.md, krótkie instrukcje dla agenta w AGENTS.md, procedury w docs/ i testy pokazujące oczekiwane zachowanie, to AI ma się czego trzymać. Te pliki nie są dodatkiem do prompta. One są częścią prompta.

Z tego artykułu dowiesz się

• dlaczego praca z AI w kodzie zaczyna się jeszcze przed napisaniem prompta,
• jak AGENTS.md, CLAUDE.md i CONTRIBUTING.md mogą porządkować współpracę człowieka, zespołu i agenta,
• po co agentowi komendy typu grep -R albo rg, zanim zacznie zmieniać pliki,
• jak ograniczać zakres pracy agenta, by nie dotknął innej domeny bez uzasadnienia albo nie naruszył publicznego kontraktu,
• jak weryfikować wynik pracy agenta przez diff i patch, zanim zmiana zostanie zatwierdzona,
• kiedy lepiej przekazać agentowi krótkie podsumowanie z pliku niż dodawać całą dokumentację do kontekstu.

Projekt, który tłumaczy sam siebie

Dobre repozytorium nie musi mieć dokumentacji na sto stron. Powinno jednak szybko odpowiadać na kilka pytań:

• od czego zacząć,
• jak uruchomić projekt,
• gdzie jest kod aplikacji,
• gdzie są testy,
• jakie są zasady zmiany kodu,
• gdzie opisano decyzje i procedury.

Przykładowa struktura:

1project/
2├── README.md
3├── CONTRIBUTING.md
4├── AGENTS.md               # instrukcje dla agentów
5├── CLAUDE.md               # adapter dla Claude Code
6├── .env.example
7├── config/
8├── docs/
9│   ├── architecture/
10│   ├── runbooks/
11│   ├── context/
12│   └── examples/
13├── src/
14└── tests/

README.md pomaga wejść do projektu, pokazuje m.in jak go uruchomić. CONTRIBUTING.md opisuje zasady pracy dla ludzi: testy, pull requesty, styl commitów, code review. Ten sam plik jest przydatny także dla agenta, bo pokazuje oczekiwany sposób pracy w repozytorium.

AGENTS.md i CLAUDE.md pełnią podobną rolę, ale są bardziej techniczne: wskazują agentowi, jak szukać kontekstu, kiedy pytać o doprecyzowanie, czego nie zmieniać bez zgody i gdzie są procedury. Nie powinny zastępować dokumentacji. Powinny być krótką instrukcją wejściową.

Krótki AGENTS.md, a nie zjadacz tokenów

AGENTS.md to rozwijający się standard pliku instrukcji dla agentów. Ten sam plik działa w kilku narzędziach jednocześnie.

Długi AGENTS.md obciąża kontekst: trafia do niego przy każdym zadaniu.

AGENTS.md łatwo rozbudować za bardzo. To kuszące: dopisać wszystkie komendy, wszystkie wyjątki i pół dokumentacji projektu. Efekt bywa odwrotny od zamierzonego. Agent dostaje dużo tekstu, którego nie potrzebuje przy każdym zadaniu.

AGENTS.md ma mówić, jak pracować. Szczegóły mają mieszkać w dokumentacji, do której plik tylko linkuje.

Przykład krótszej wersji:

1# AGENTS.md
2
3Search before editing. Before touching any symbol, run
4`rg "Symbol|symbol_variant" src tests docs config` and list every affected file.
5
6Declare scope before changing files. Keep diffs small and reviewable.
7
8Do not modify public APIs, schemas, migrations, auth rules or cross-domain behavior
9without explicit confirmation.
10
11If requirements are unclear, ask before touching files. Once scope is confirmed,
12continue until acceptance criteria are met. Ask mid-task only when genuinely blocked.
13
14References: CONTRIBUTING.md · docs/runbooks/local-dev.md · docs/architecture/overview.md

Ten plik jest krótki, ale zawiera najważniejsze reguły. Agent wie, kiedy ma pytać, kiedy może iść dalej, jak sprawdzić wpływ zmiany i gdzie szukać szczegółów.

CLAUDE.md jako adapter

Różne narzędzia mogą oczekiwać różnych nazw plików. Claude Code czyta domyślnie CLAUDE.md, nie AGENTS.md. Jeżeli projekt używa AGENTS.md również dla innych agentów, nie trzeba dublować zasad.

Wystarczy prosty adapter:

1# CLAUDE.md
2
3@AGENTS.md
4
5## Claude Code specific notes
6
7- For larger refactors, first summarize the plan.
8- Before editing more than 3 files, list expected files to change.
9- When unsure about conventions, inspect nearby files first.

Dzięki temu główne zasady są w jednym miejscu, a dopiski specyficzne dla narzędzia są krótkie i łatwe do utrzymania.

@ to składnia ładowania pliku do kontekstu obsługiwana przez Claude Code. To ten sam mechanizm jak użycie @plik w promptach.

Po co agentowi grep albo ripgrep?

Agent, tak jak człowiek, może zobaczyć pierwszy pasujący plik i wyciągnąć zbyt szybki wniosek. W większym projekcie ta sama funkcjonalność może występować w kilku miejscach: w kodzie, testach, dokumentacji, konfiguracji i przykładach.

Dlatego przed zmianą warto wykonać wyszukiwanie po repozytorium. Najprostszy wariant to grep:

1grep -RIn "PaymentValidator" src tests docs

Znaczenie flag:

• -R przeszukuje katalogi rekurencyjnie,
• -I pomija pliki binarne,
• -n pokazuje numery linii,
• PaymentValidator to szukana nazwa klasy, funkcji albo pojęcia,
• src tests docs ogranicza szukanie do kodu, testów i dokumentacji.

Dla AI jest to przydatne, bo zamiast zgadywać zakres zmiany, agent może najpierw powiedzieć:

1Znaleziono powiązania w:
2- src/payments/validator.py
3- tests/payments/test_validator.py
4- docs/payments.md
5
6Proponuję zmienić tylko implementację i test dotyczący walidacji.

W codziennej pracy wygodniejszy bywa ripgrep, czyli rg. To zewnętrzne narzędzie. Wymaga osobnej instalacji.

1rg "PaymentValidator|payment_validator|validatePayment" src tests docs config examples

Dlaczego taka komenda:

• PaymentValidator może być nazwą klasy,
• payment_validator może być nazwą modułu, pliku albo funkcji,
• validatePayment może występować w kodzie frontendowym.

src, tests, docs, config i examples zawężają szukanie do katalogów kodu, testów, dokumentacji, konfiguracji i przykładów.

rg domyślnie respektuje .gitignore, pomija pliki ukryte i binarne oraz wspiera filtrowanie po typach plików, np. rg "PaymentValidator" -t py dla plików Pythona. To ogranicza szum i zmniejsza ryzyko, że agent zacznie analizować katalogi wygenerowane, zależności albo przypadkowe binarki.

Jeśli zachodzi podejrzenie, że rg ukrywa zbyt dużo, można świadomie rozszerzyć wyszukiwanie:

Przykład: .env jest jednocześnie wylistowany w .gitignore i ukryty (zaczyna się od .) - oba filtry działają niezależnie.

Polecenie	Efekt	Znajdzie .env?
rg -u "SECRET"	ignoruje .gitignore	nie
rg -uu "SECRET"	jak wyżej + pliki ukryte	tak
rg -uuu "SECRET"	jak wyżej + pliki binarne	tak

Nie chodzi o to, że rg jest jedynym słusznym narzędziem. grep warto znać, bo jest dostępny prawie wszędzie, rg jest osobnym programem, który można doinstalować. rg ma domyślne ustawienia wygodne dla pracy z kodem i agentem.

Żeby agent mógł realnie uruchomić rg lub git, musi mieć dostęp do powłoki. W Claude Code oznacza to jawne nadanie uprawnień do narzędzi: sama zawartość CLAUDE.md nie wystarczy.

Reguła dla agenta: sprawdź wpływ zmiany

W AGENTS.md można trzymać prostą regułę:

1## Change impact check
2
3Before changing a class, function, domain concept or public behavior:
4
51. Search for the exact name.
62. Search for common naming variants.
73. Check implementation, tests, docs, config and examples.
84. List potentially affected files before editing.
95. If public API, schema, migration, auth or another domain may be affected, ask for confirmation first.

To jest miejsce, w którym można wskazać preferowane komendy:

1rg "PaymentValidator|payment_validator|validatePayment" src tests docs config examples

Fallback:

1grep -RIn "PaymentValidator\|payment_validator\|validatePayment" src tests docs config examples

Taka reguła chroni przed zmianą w jednym pliku tam, gdzie ta sama poprawka powinna objąć też powiązane pliki w innych częściach projektu. Pomaga też w drugą stronę: agent łatwiej zauważa, że nie powinien dotykać innej domeny.

Boundaries: gdzie umieścić reguły, żeby działały?

Boundaries (granice zakresu pracy agenta) nie powinny pojawić się nagle jako osobna teoria. Najlepiej potraktować je jako sekcję w AGENTS.md albo jako część prompta przy konkretnym zadaniu.

Przykład w AGENTS.md:

1## Boundaries
2
3For every code change:
4
51. State intended scope before editing.
62. List expected files to change.
73. Do not edit files outside that scope unless you explain why first.
84. Do not modify public contracts, schemas, migrations, auth rules or other domains without explicit confirmation.
95. At the end, show changed files and summarize behavior changes separately from refactors.

Przykład w promptcie do konkretnego zadania:

1Zakres: tylko walidacja importu CSV.
2Możliwe pliki: src/imports/, tests/imports/, docs/imports.md.
3Nie zmieniaj formatu błędów, API importu ani zachowania innych importerów bez osobnego potwierdzenia.
4Najpierw pokaż listę plików, które mogą być dotknięte zmianą.

To nadal nie jest twarde zabezpieczenie techniczne. To instrukcja operacyjna. Dlatego po pracy agenta warto sprawdzić wynik przez Git:

1git status --short
2git diff --stat

Jeżeli agent wygenerował patch zamiast od razu edytować pliki, można najpierw sprawdzić, czy patch w ogóle da się zastosować:

1git apply --check change.patch

Albo dla klasycznego narzędzia patch:

1patch --dry-run -p1 < change.patch

patch --dry-run nie zmienia plików. Sprawdza, czy zmiana pasuje do aktualnego kodu. To dobre rozwiązanie, gdy chcemy najpierw obejrzeć i zweryfikować propozycję, a dopiero później ją zastosować.

W systemach wieloagentowych patch zyskuje dodatkową wartość: agent generujący zmianę nie musi mieć uprawnień do edycji plików. Redukujemy tym również część problemów związanych z konkurencyjnością. Wystarczy, że dostarczy patch: weryfikacja i zastosowanie to osobny krok, wykonany przez dedykowany skrypt, człowieka albo innego agenta.

Sekrety: instrukcja w pliku to za mało

W AGENTS.md można napisać, żeby agent nie używał sekretów w promptach, logach ani commitach. To dobry sygnał intencji, ale słaba granica bezpieczeństwa. Jeżeli narzędzie działa z uprawnieniami użytkownika systemowego, może odczytać te same zasoby.

Lepsze podejście to ograniczyć dostęp technicznie:

1sudo chown appuser:appuser .env
2sudo chmod 600 .env
3
4sudo chown -R appuser:appuser secrets/
5sudo chmod 700 secrets/

chmod 600 .env albo chmod 700 secrets/ nie pomoże, jeśli agent działa jako ten sam użytkownik, który jest właścicielem tych plików. To rozwiązanie działa wyłącznie lokalnie: zdalne repozytoria nie przechowują informacji o uprawnieniach. Po pobraniu pliku przez inną osobę ustawienia znikają. Granicę daje dopiero separacja użytkowników, kontenerów albo izolowanego środowiska pracy.

Bezpieczniejszym podejściem technicznym jest zbudowanie warstwy dostępu do plików: skryptu albo dedykowanego narzędzia, które eksponuje agentowi tylko te zasoby, które powinien widzieć. Zamiast instrukcji w pliku tekstowym, zakres dostępu jest kontrolowany programowo.

Pierwsza prosta linia obrony to .gitignore. Pliki z sekretami wylistowane w .gitignore są niewidoczne dla rg domyślnie i dla wielu agentów korzystających z rg do przeszukiwania repozytorium. To nie jest twarda granica bezpieczeństwa, ale porządkuje zakres kontekstu.

Kontekst bez szumu

Przy większym zadaniu kontekst rośnie szybko. Dokumentacja architektury, runbooki, historia zmian: wszystko to ma wartość, ale nie musi znajdować się w jednym prompcie od początku do końca.

Zamiast przekazywać całą dokumentację, wystarczy stworzyć plik pośredni: krótkie, ustrukturyzowane podsumowanie przygotowane pod konkretne zadanie. By następnie budować kontekst zadania na kanwie tego pliku.

1# docs/context/current-task.md
2
3## Task
4Zmiana walidacji importu CSV dla pustego pola email.
5
6## Sources checked
7- docs/architecture/imports.md
8- docs/runbooks/local-dev.md
9- tests/imports/test_csv_import.py
10
11## Relevant facts
12- Import CSV jest obsługiwany w src/imports/.
13- Format błędów jest publicznym kontraktem.
14- Puste email powinno odrzucać wiersz.
15
16## Unknowns
17- Czy zmiana ma dotyczyć tylko CSV, czy także XLSX?
18
19## Suggested scope
20- src/imports/
21- tests/imports/
22- docs/imports.md tylko jeśli opisane zachowanie się zmienia
23
24## Do not change without confirmation
25- publiczny format błędów
26- migracje
27- zachowanie innych importerów

Ten plik działa, bo jest mały, pojawia się czytelnie w git diff i może być wspólną przestrzenią dla kilku narzędzi. Takie podsumowanie może przygotować osobne narzędzie albo automatyczny krok przygotowawczy, niezależnie od nazwy przyjętej w danym środowisku. Właściwe narzędzie pracuje na gotowym podsumowaniu, nie na całej dokumentacji.

Wynik: zamiast obszernego payloadu, narzędzie dostaje kilkanaście linii ustrukturyzowanej informacji.

Mini-scenariusz: zmiana walidacji importu CSV

Załóżmy, że chcemy zmienić walidację importu CSV. Problem: pliki z pustą kolumną email przechodzą walidację, chociaż powinny zostać odrzucone.

Słaby prompt:

1Napraw import CSV, bo czasem nie działa.

Lepszy prompt:

1Chcę zmienić walidację importu CSV.
2
3Problem:
4- pusty email przechodzi walidację
5- oczekiwane zachowanie: wiersz powinien zostać odrzucony
6
7Zanim zmienisz pliki:
81. Przeczytaj AGENTS.md i CONTRIBUTING.md.
92. Znajdź powiązane miejsca w src, tests, docs, config i examples.
103. Pokaż proponowany zakres plików.
114. Jeśli wymagania są niejasne, zapytaj przed edycją.
12
13Po ustaleniu zakresu wprowadź minimalną zmianę i test dla tego przypadku.
14Nie zmieniaj publicznego API, formatu błędów ani zachowania innych importerów bez osobnego potwierdzenia.
15Na końcu pokaż git diff --stat i krótko oddziel zmianę zachowania od refaktoru.

Różnica jest praktyczna. AI nie dostaje tylko zadania. Dostaje mapę, zasady, granice i sposób weryfikacji.

Do AGENTS.md można przenieść zakres, listę plików poza zasięgiem i oczekiwany format odpowiedzi. Wtedy nie trzeba ich wpisywać przy każdym zadaniu.

Z dobrze skonfigurowanym AGENTS.md nawet uproszczony prompt ma większą szansę trafić w oczekiwany wynik: reguły, zakres i sposób weryfikacji są już wbudowane w projekt.

Podsumowanie

Dobre promptowanie nie zaczyna się w oknie chata. Zaczyna się w repozytorium.

Jeśli projekt ma czytelne pliki, krótki AGENTS.md, testy i prosty sposób zbierania kontekstu, praca z AI staje się mniej losowa. Nie trzeba budować skomplikowanego systemu. Wystarczy zacząć od kilku konkretnych nawyków:

• używać rg albo grep przed zmianą kodu,
• deklarować zakres zmian i sprawdzać diff,
• weryfikować patch przed zastosowaniem,
• ograniczyć agentowi dostęp do plików, których nie powinien czytać.

Instrukcje w plikach poprawiają zachowanie modelu, ale go nie gwarantują. Modele są niedeterministyczne: reguły tekstowe warto łączyć z kodem, narzędziami i kontrolą dostępu, żeby uzyskać twardsze granice.

To są zwykłe pliki i proste komendy. W praktyce często właśnie one decydują, czy AI jest wsparciem, czy tylko bardzo pewnym siebie narzędziem bez wystarczającego kontekstu.

Kto chce pójść dalej: praca z patch i uprawnieniami plików wchodzi w obszar administracji systemami Linux, a projektowanie instrukcji dla agentów i praca z Claude Code to oddzielne dyscypliny z własnymi kursami i dobrymi praktykami.

To dopiero fragment możliwości współpracy z AI. Więcej praktycznych podejść, narzędzi i workflow znajdziesz w szkoleniach:

• Agentic Coding z AI - Claude Code i Cline w praktyce
• AI-Driven Development — warsztaty z Claude Code dla developerów
• AI Toolchain – zestaw narzędzi dla programistów
• AI - Powered Development z Claude Code i GitHub Copilot

---

Materiały i źródła

• AGENTS.md - format instrukcji dla agentów kodujących
• How Claude remembers your project - mechanizm @plik i CLAUDE.md w Claude Code
• ripgrep guide - respektowanie .gitignore, pliki ukryte, filtrowanie po typach