AnswersPublished14 sources
Jak uporządkować dokumentację projektu dla agentów AI
Nie ma jednego układu folderów, który pasuje do każdego projektu i każdego agenta. Oddziel wymagania od bieżącego statusu i dowodów wykonania; wskaż jedno miejsce, które jest źródłem prawdy dla każdej ważnej informacji.
Opublikowane przezObrazy wygenerowane za pomocą GPT Image 2
Research answer
Key takeaways
- Nie ma jednego układu folderów, który pasuje do każdego projektu i każdego agenta.
- Oddziel wymagania od bieżącego statusu i dowodów wykonania; wskaż jedno miejsce, które jest źródłem prawdy dla każdej ważnej informacji.
- Po zakończeniu zadania można ograniczyć widoczność planu, ale nie warto usuwać historii potrzebnej do odtworzenia decyzji i postępu.
- Pliki AGENTS.md i inne instrukcje trzeba dostosować do konkretnego narzędzia — sama nazwa pliku nie gwarantuje, że agent go wczyta.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/r4PONBDeiygm6rkyQ1INhTEQyyP2/images/C7AB80FC077AFBDCC74B/E16B680C3CF0FB35FFC8.png)
AI Prompt
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"建议统一“信息职责、权威来源、生命周期和读取契约”，而不是强制所有项目采用同一套目录。BMAD 的任务治理与蓝图的知识分层可以结合，但计划保留、跨宿主加载、测试隔离和文档预算必须分别定义，不能由目录名称代替。\n\n 保留蓝图的职责分离，调整其绝对化规则。\n 借鉴 BMAD 的稳定身份、渐进细化、来源追溯和历史. Topic tags: general web, ai safety, openai, chatgpt, llm. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts
Dokumentacja projektu dla agenta AI ma dwa zadania: podpowiedzieć, co zrobić, i nie zaciemnić, skąd wiadomo, że praca została wykonana poprawnie. To nie zawsze wymaga rozbudowanego systemu folderów. Często ważniejsze są jasne zasady dotyczące źródeł prawdy, planów, historii i tego, które pliki agent powinien przeczytać.
Porównanie praktyk BMAD, dokumentacji AGENTS.md i podejścia Ralpha prowadzi do prostego wniosku: warto ujednolicić role informacji, a nie narzucać wszystkim projektom identyczne drzewo katalogów.
Różne podejścia, różne potrzeby
BMAD można traktować jako system organizacji pracy i powiązanych z nią artefaktów. W analizowanym modelu zadania mają określone miejsce w hierarchii, a plany, wymagania i podsumowania są łączone z pracą, której dotyczą. Szczegóły mogą być rozwijane dopiero wtedy, gdy są potrzebne. Istotne jest też zachowanie ukończonych planów jako zapisu statusu i dowodów, a nie tylko bieżącej listy zadań.
Z kolei AGENTS.md może pełnić rolę trwałych wskazówek dla agenta Codex, ale nie każdy plik związany z organizacją pracy jest wymaganym elementem narzędzia. OpenAI opisuje pozostałe pliki i układy jako konwencje, które można dopasować do projektu 6. To rozróżnienie ma praktyczne znaczenie: folder lub plik o umownej nazwie nie zapewnia sam z siebie, że każde środowisko go odczyta.
Podejście Ralpha kładzie nacisk na mały zakres pracy w pojedynczym cyklu. Geoffrey Huntley opisuje pętlę, w której jeden proces realizuje jedno zadanie na iterację 14. Powiązany przewodnik pokazuje też specyfikacje grupowane według obszaru zainteresowania oraz
AGENTS.md z praktycznymi wskazówkami dotyczącymi budowania i testowania 11. To użyteczne wzorce, nie uniwersalny nakaz stosowania jednej struktury.
Co warto ujednolicić
Niezależnie od wybranego systemu dokumentacja powinna jasno odpowiadać na trzy pytania:
- Co musi być spełnione? To rola specyfikacji i zasad projektu.
- Na jakim etapie jesteśmy? To rola statusu i planu pracy.
- Skąd wiemy, że wymaganie jest spełnione? To rola dowodów, takich jak wyniki testów czy odnotowane ustalenia.
Te informacje mogą znajdować się w jednym pliku albo w kilku. Ważne, by było wiadomo, która z nich jest wiążąca. Jeśli ten sam status jest aktualizowany osobno w planie, karcie zadania i podsumowaniu, szybko powstają sprzeczne wersje.
Dobrym punktem wyjścia są następujące zasady:
- Dla każdej ważnej informacji wskaż jedno edytowalne źródło prawdy. Indeksy i streszczenia mogą powielać treść, ale powinny wskazywać jej źródło i ograniczenia aktualności.
- Zachowuj wiedzę, której nie da się łatwo odczytać z kodu. Chodzi między innymi o uzasadnienie decyzji, ograniczenia zewnętrzne i podział odpowiedzialności między częściami projektu.
- Traktuj plik wejściowy jako mapę, nie encyklopedię. Powinien przekazywać najważniejsze reguły i prowadzić do odpowiednich materiałów. Samo polecenie „wczytaj więcej, jeśli będzie potrzebne” może być zbyt nieprecyzyjne.
- Rozdzielaj wymagania, status i dowody. Agent powinien wiedzieć, co jest normą, co opisuje aktualny postęp, a co uzasadnia ocenę wykonania.
- Po zakończeniu pracy zachowuj ślad, nawet jeśli nie chcesz go stale ładować. Starszy plan może zniknąć z bieżącego widoku, ale nadal być potrzebny do sprawdzenia decyzji i historii zadania.
Historia nie musi oznaczać bałaganu
Jednym z trudniejszych wyborów jest to, co zrobić z planem po ukończeniu zadania. Usunięcie go albo nadpisanie jedynego pliku z aktywną pracą może uprościć widok, ale odbiera kontekst potrzebny do ustalenia, co faktycznie zrobiono.
Rozwiązaniem jest oddzielenie bieżącego widoku od zachowanego zapisu. Agent może pracować na krótkim podsumowaniu aktywnego zadania, które odsyła do pełnego planu. Warto zachować w nim identyfikator zadania, status, zależności i lokalizację dowodów. Dzięki temu historia nie musi być wczytywana przy każdej nowej pracy, ale nie znika.
Podobnie warto ostrożnie podchodzić do pomysłu „jednego aktywnego planu”. Może on oznaczać jeden główny temat dla pojedynczej sesji, lecz w zespole lub przy równoległej pracy nie powinien automatycznie oznaczać jednego wspólnego, stale nadpisywanego pliku.
Dopasuj instrukcje do narzędzia i projektu
Nie zakładaj, że ten sam plik będzie automatycznie rozpoznawany przez różne środowiska. Dokumentacja OpenAI opisuje AGENTS.md jako plik opcjonalny, rozpoznawany przez Codex, a inne elementy przykładowego workflow jako konwencje do dostosowania 6. Przed wdrożeniem warto więc sprawdzić, co konkretny agent rzeczywiście wczytuje — zwłaszcza jeśli instrukcje znajdują się w zagnieżdżonych katalogach.
Podobnie należy podchodzić do wielkości dokumentacji. Krótsze instrukcje mogą być łatwiejsze w użyciu, ale sztywny limit liczby wierszy nie jest uniwersalną miarą jakości. Przydatniejsze pytania brzmią: czy agent faktycznie wczytuje potrzebny kontekst, czy informacje się powtarzają i czy podział dokumentów nie ukrywa zależności, które trzeba znać od razu?
OpenAI opisuje również plany dla złożonych zadań jako rozbudowane, żywe dokumenty, które można sprawdzać przed rozpoczęciem długiej implementacji 5. To dobry przykład, że zwięzłe wskazówki stale dostępne agentowi mogą współistnieć ze szczegółowym planem wczytywanym dla konkretnej pracy.
Testy i wygenerowane pliki — nie wszystko jest „śmieciem”
Warto odróżniać testowe dane wejściowe od plików wytworzonych podczas uruchomienia. Stały, odtwarzalny zestaw testowy może być częścią projektu; logi i tymczasowe wyniki działania mogą wymagać innych zasad przechowywania. Podobnie samo umieszczenie pliku w katalogu testów nie przesądza o jego przeznaczeniu.
Zasady powinny uwzględniać rodzaj testu, wrażliwość danych, rozmiar wyników i czas ich przechowywania. Dobrze też jasno opisać środowisko i skutki uboczne testów. Nie ma potrzeby sprowadzać wszystkich plików JSON czy logów do jednej kategorii tylko ze względu na rozszerzenie lub lokalizację.
Zacznij od odpowiedzialności, nie od migracji folderów
Praktyczny porządek wdrażania wygląda następująco: najpierw określ role dokumentów i wskaż źródła prawdy, potem sprawdź sposób wczytywania instrukcji przez używane narzędzia. Dopiero później przygotuj krótką mapę dla aktywnego zadania i dopasuj zasady przechowywania do rzeczywistej pracy.
Nie trzeba od razu przebudowywać całego repozytorium. Najpierw ustal, jakie informacje agent musi znać zawsze, które powinien wczytywać zależnie od zadania, a które należy zachować jako historię. Czytelne role i sprawdzony mechanizm wczytywania są cenniejsze niż katalogi, które tylko wyglądają na uporządkowane.
Studio Global AI
Continue your research
This page includes a source-backed answer you can continue inside Studio Global.
People also ask
What is the short answer to "Jak uporządkować dokumentację projektu dla agentów AI"?
Nie ma jednego układu folderów, który pasuje do każdego projektu i każdego agenta.
What are the key points to validate first?
Nie ma jednego układu folderów, który pasuje do każdego projektu i każdego agenta. Oddziel wymagania od bieżącego statusu i dowodów wykonania; wskaż jedno miejsce, które jest źródłem prawdy dla każdej ważnej informacji.
What should I do next in practice?
Po zakończeniu zadania można ograniczyć widoczność planu, ale nie warto usuwać historii potrzebnej do odtworzenia decyzji i postępu.
Sources
developers.openai.comdevelopers.openai.com › cookbook › examplesdevelopers.openai.com
ghuntley.comRalph Wiggum as a "software engineer" - Geoffrey Huntley
github.comhow-to-ralph-wiggum/README.md at main - GitHub