Uwagi praktyczne: Plik AGENTS.md został napisany dla gorszego modelu.

To przewodnictwo pokazuje, jak odbudować ścieżkę od surowców do działającego systemu w przypadku sytuacji, gdy plik AGENTS.md został napisany dla gorszego modelu. Skupia się na krokach operacyjnych, wyraźnych sprawdzeniach oraz kodzie, który można bez problemu dodać do repozytorium, nie musząc zgadywać intencji twórcy. Na etapie przeglądu należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu systemu. Konfigurację należy przechowywać oddzielnie od kodu aplikacji. Pliki środowiskowe, magazyny tajemnic oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić, nie musząc czytać całej struktury aplikacji.

OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done

Każda awaria pozostawia „skamieniałość”

Gdy pracujesz nad „Every failure leaves a stage”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego awarii. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych wysyłek, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Zachowuj w pamięci podręcznej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego prefiksu to częsty powód marnotrawstwa zasobów.

Always run the entire test suite after every change.

Nawigacja umiejętności ma swoją cenę przed kosztem ich wykonywania

Gdy pracujesz nad umiejętnościami obejmującymi etap routingu, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolę małe, testowalne jednostki niż rozbudowane skrypty. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na jedną konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Zachowuj w pamięci podręcznej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego prefiksu to częsty powód marnotrawstwa zasobów.

database/
├── router.md
└── references/
    ├── migrations.md
    ├── performance.md
    └── recovery.md

AGENTS.md powinien zachować to, czego kod nie może wyjaśnić

Gdy pracuje się nad dokumentacją AGENTS, należy zachować informacje o etapie realizacji i najpierw zapisać umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć przypadki cichego, częściowego ukończenia zadania. Zachowuj w pamięci podręcznej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego nagłówka jest częstą przyczyną marnotrawstwa zasobów. Gdy pracuje się nad dokumentacją AGENTS, należy zachować informacje o etapie realizacji i najpierw zapisać umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny haseł oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.

KEEP

Generated API clients in /src/sdk are immutable.
Edit the generator source instead.

MOVE OR REMOVE

Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies

Lepsze modele sprawiają, że uprawnienia stają się ważniejsze

Lepsze modele sprawiają, że etap uzyskiwania uprawnień działa najlepiej, gdy traktuje się go jako mierzalną zmienną. Zanim rozszerzysz zakres, zdokumentuj jeden idealny przypadek działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań. Zdokumentuj jednocześnie ścieżkę prawidłowego działania oraz ścieżkę naprawczą. Próby ponownych działań, kontrola przez ludzi oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później. Przydziel budżet tokenów na każdy ruch i sesję. Narzędzia agentowe intensywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by demonstracje przerodziły się w niespodziewane rachunki.

Local tests use disposable fixtures and have no production access.

Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.

Zdefiniuj zakończenie przed procedurą

Faza uzupełniania definicji przed procedurą działa najlepiej, gdy traktuje się ją jako mierzalną powierzchnię. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Wolimy małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Określ budżet tokenów na jeden ruch i na jedną sesję. Narzędzia typu agentic intensywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by demonstracje przerodziły się w niespodziewane rachunki.

Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.

Implement the avatar endpoint.

Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.

Hierarchia instrukcji powinna być celowa

Hierarchia instrukcji funkcjonuje najlepiej, gdy jest traktowana jako mierzalna struktura. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzucaj ciche, częściowe ukończenie zadań. Określ budżet tokenów na każdą rundę i sesję. Narzędzia typu agentic intensywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by demonstracje przerodziły się w niespodziewane rachunki. Hierarchia instrukcji funkcjonuje najlepiej, gdy jest traktowana jako mierzalna struktura. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres pracy. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.

AGENTS.md
    ↓
Repository invariants
Safety boundaries
Global permissions

Skills
    ↓
Specialized workflows
Loaded only when relevantTask prompt
    ↓
Immediate objective
Local constraints
Definition of done

Kontrola zadłużenia związkanego z promptami przy każdej zmianie modelu

W fazie kontroli zadłużenia związkanego z promptami należy określić dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrola przez ludzi oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Przy następnym kroku będącym kodem lub wywołaniem narzędzia należy preferować ustrukturyzowane wyniki z walidacją schematu zamiast tekstów w formie swobodnej.

Inwentaryzacja historycznych kompensacji

W fazie historycznych kompensacji w systemie Inwentarza należy zdefiniować dane wejściowe, osobę odpowiedzialną za daną etap oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić daną etap na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu systemu. Należy preferować małe, łatwe do przetestowania jednostki nad rozbudowanymi skryptami. Gdy jakiś etap zawiedzie, powinno to wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę procesu. W przypadku, gdy następnym krokiem jest kod lub wywołanie narzędzia, lepsze są ustrukturyzowane wyniki z walidacją schematu niż tekst w formie swobodnej.

Rozdzielaj niezmienniki od rutynowych działań

W fazie oddzielania niezmienników od rytuałów należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie wykonać ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadań. Przy następnym kroku, który polega na tworzeniu kodu lub wywoływaniu narzędzi, preferuj strukturyzowane wyniki z walidacją schematu zamiast tekstów w formie swobodnej. W fazie oddzielania niezmienników od rytuałów należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie wykonać ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.

.

Zmień skomplikowane umiejętności na routery

Gdy przechodzisz przez etap przekształcania skomplikowanych umiejętności w routery, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno prawidłowy przebieg działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później. Zachowuj w pamięci podręcznej stabilne instrukcje systemowe oraz schematy narzędzi. Ponowne wysyłanie identycznego preambułu jest częstą przyczyną problemów.

Rozpatrz zakazy jako granice decyzji

Gdy przechodzisz przez etap oceny zakazów w fazie podejmowania decyzji, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co się dzieje w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolij małe, testowalne jednostki od rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na jedną konkretne odpowiedzialność, a nie na skomplikowany łańcuch operacji. Zachowuj w pamięci tymczasowej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego prefiksu to częsty powód marnotrawstwa zasobów.

Co powinno przetrwać każdą aktualizację

Gdy pracujesz nad pytaniem „Co powinno przetrwać każdy etap”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadań. Zachowuj w pamięci tymczasowej stabilne instrukcje systemu oraz schematy narzędzi. Ponowne wysyłanie identycznego nagłówka jest częstą przyczyną marnotrawstwa zasobów. Gdy pracujesz nad pytaniem „Co powinno przetrwać każdy etap”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny haseł oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.

Etap listy kontrolnej operacyjnej działa najlepiej, gdy traktuje się go jako mierzalną powierzchnię. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę o cofnięciu zmian, zanim rozszerzysz zakres.

Zapisuj czasy wykonywania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy przechodzi się od wersji demonstracyjnej do środowisk współdzielonych.

Ustal budżet tokenów na jeden ruch i na jedną sesję. Narzędzia agentowe intensywnie rozszerzają kontekst; sztywne limity zapobiegają temu, by wersje demonstracyjne przeradzały się w nieoczekiwane rachunki.

Zapewnij ludzką aprobatę w przypadkach, gdy wydawane są pieniądze lub zmieniane są dane produkcyjne. Połączenia realizowane w czasie kompilacji nie równają się pełnej kompletności rozwiązania biznesowego.

Napisz krótki podręcznik: jak rotować klucze, jak opróżniać kolej z zadań, jak cofnąć ostatni proces importu.

Należy preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji.

Zanim wdrożymy nową architekturę, należy zamrozić istniejące wersje, utworzyć dokładny zapis działań dla kluczowych etapów oraz potwierdzić kroki odwracające zmiany. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji uprawnień użytkowników oraz wyraźnego odpowiedzialnego za rotację haseł. Lepiej mieć nudną, niezawodną architekturę niż sprytnie przygotowane jednorazowe demonstracje.

Uwaga dotycząca wersji 42ea40c30a21: unikaj przechowywania kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj zapisy działań obok plików testowych, aby późniejsze zmiany modeli pozostawały porównywalne.

Literatura pokrewna

• Praktyczne notatki: Twój agent AI potrzebuje warstwy zarządzania, a nie kolejnego promptu — Szczegółowy przewodnik po Praktycznych notatkach: Twój agent AI potrzebuje warstwy zarządzania, a nie kolejnego promptu: umowy, sprawdzenia oraz gotowe elementy kodu dla zespołów wdrażających ten model.
• Praktyczne notatki: Twój model semantyczny to API, które będą wzywać agenci — Szczegółowy przewodnik po Praktycznych notatkach: Twój model semantyczny to API, które będą wzywać agenci: umowy, sprawdzenia oraz gotowe elementy kodu dla zespołów wdrażających ten model.