AnswersPublished14 sources
Porządek w repozytorium: testy, ADR-y, plany i dokumentacja
Testy warto domyślnie gromadzić w jednym miejscu, ale testy Go sprawdzające nieeksportowane elementy pakietu mogą wymagać pozostania obok kodu. Specyfikacja opisuje aktualne wymagania, ADR wyjaśnia podjęte decyzje, a test sprawdza zachowanie — te elementy powinny się uzupełniać, nie zastępować.
Opublikowane przezObrazy wygenerowane za pomocą GPT Image 2
Research answer
Key takeaways
- Testy warto domyślnie gromadzić w jednym miejscu, ale testy Go sprawdzające nieeksportowane elementy pakietu mogą wymagać pozostania obok kodu.
- Specyfikacja opisuje aktualne wymagania, ADR wyjaśnia podjęte decyzje, a test sprawdza zachowanie — te elementy powinny się uzupełniać, nie zastępować.
- Zamrożony plan nie jest planem ukończonym: trzeba zachować jego status, niedokończone zadania i warunki wznowienia.
- Pliki tymczasowe można sprzątać, o ile nie są jedynym źródłem dowodu ani nie podtrzymują wniosków, na których nadal ktoś polega.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/L2Q8zxg7UqZZOsMb8CmQKOfK9IR2/images/53D2DD20E6A8C8FDDC17/74C3321FB646B5554586.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":"这套布局可以作为收敛方向，但需要纠正三个等同关系：所有测试不能无条件迁出业务包，规范不是全部 ADR 的摘要，冻结也不是完成归档。以下是六项建议的明确边界；涉及的新路径均为候选，尚未创建或迁移。\n\n 1.. Topic tags: general web, openai, automation, workflow, code. 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 with fake numbers, clickbait thumbnails, icons, a
Proponowany układ katalogów może być dobrym kierunkiem, ale warto od razu rozdzielić trzy rzeczy, które łatwo ze sobą pomylić: centralizację testów, relację między specyfikacją a decyzjami architektonicznymi oraz zamrożenie planu z jego ukończeniem. Poniższe ścieżki są propozycjami — nie oznaczają, że pliki zostały już utworzone lub przeniesione.
1. Testy w jednym miejscu — jako zasada domyślna, nie bezwzględny nakaz
Warto przyjąć centralny katalog testów jako punkt wyjścia, ale nie wymagać, by testy zawsze znajdowały się poza katalogiem kodu.
- W projektach Python testy można domyślnie umieszczać w
tests/. Przy przenoszeniu trzeba sprawdzić importy, wykrywanie testów, fixture’y i konfigurację CI. W tym repozytorium CI jest już ustawione na scentralizowaną ścieżkę testów. - W Go testy białoskrzynkowe, które muszą odwoływać się do nieeksportowanych elementów pakietu, mogą pozostać w katalogu testowanego pakietu. Testy czarnoskrzynkowe, przekrojowe i end-to-end warto w miarę możliwości grupować osobno. Narzędzia Go budują testy dla pakietów i obsługują zarówno testy w tym samym pakiecie, jak i w osobnym pakiecie o sufiksie
_test.14
- Nie należy utożsamiać ograniczeń importu pakietów
internalz regułami dostępu do elementów nieeksportowanych. To odrębne granice: pierwsza zależy od położenia katalogu w ścieżce importu, druga od przynależności do pakietu.10
W praktyce nie da się więc obiecać, że wszystkie testy Go zostaną wyprowadzone z katalogów kodu, a jednocześnie zachowają dostęp do nieeksportowanych szczegółów bez zmiany granic pakietu. Nie warto dla porządku katalogów eksportować wewnętrznego stanu ani dublować logiki produkcyjnej.
Celem powinno być ograniczenie niepotrzebnych plików i powtarzanych kontroli, a nie eliminowanie sensownych, osobnych testów. Testy regresyjne, które mają być uruchamiane ponownie, powinny być wersjonowane. Jednorazowe sondy i eksperymenty można trzymać w obszarze tymczasowym.
2. Specyfikacja, ADR i reguły globalne pełnią różne funkcje
specs/ nie powinno być po prostu zbiorem ogólnych zasad wyciągniętych ze wszystkich ADR-ów. Czytelniejszy podział wygląda tak:
| Warstwa | Na jakie pytanie odpowiada? | Co zawiera? |
|---|---|---|
| Metodyka globalna | Jak analizować, weryfikować i dostarczać zmiany? | Zasady utrzymywane na poziomie metodyki |
AGENTS.md |
Jak pracować w tym projekcie? | Potwierdzone ograniczenia projektu i wskazówki operacyjne |
specs/ |
Jakie zachowanie lub kontrakt obowiązują obecnie? | Wymagania, zaakceptowane decyzje i zatwierdzone zmiany |
docs/adr/ |
Dlaczego wybrano dane rozwiązanie? | Istotne decyzje, ich uzasadnienia i rozważane alternatywy |
Dokumentacja Cline opisuje reguły, które pozwalają zachować instrukcje między sesjami.4 Nie wynika z tego jednak, że Cline automatycznie zapisuje określone pliki w katalogu specyfikacji. Taki sposób pracy należy traktować jako konwencję projektu, a nie gwarantowaną funkcję narzędzia.
Specyfikacja nie musi być w całości pisana ręcznie ani czekać na pojawienie się problemu. Proces może wyglądać następująco:
- Podczas przygotowania projektu asystent może zaproponować specyfikację na podstawie wymagań użytkownika i dowodów z repozytorium. Niewiadome powinny pozostać jawnie oznaczone jako niewiadome.
- Przed zadaniem należy przeczytać odpowiednie specyfikacje i decyzje, a następnie określić kryteria akceptacji i zakres weryfikacji.
- Nowy ADR ma sens wtedy, gdy pojawia się ważny wybór architektoniczny. Jeśli istniejąca decyzja nadal obowiązuje, wystarczy się na nią powołać.
- Wynik testów może potwierdzić poprawność implementacji albo ujawnić problem ze specyfikacją. Sam rezultat testu nie powinien automatycznie rozstrzygać, jakie wymaganie było właściwe.
- Po zatwierdzeniu decyzji należy wpisać aktualne wymagania do odpowiedniej specyfikacji i powiązać ją z ADR-em. Nie ma potrzeby przepisywania całej historii decyzji.
Krótko mówiąc: specyfikacja opisuje aktualny kontrakt, ADR dokumentuje podstawę decyzji, a test jest wykonywalnym sprawdzeniem. Są ze sobą powiązane, ale żaden z tych elementów nie zastępuje pozostałych. Odkrycia dotyczące jednego projektu nie powinny też bez przeglądu stawać się regułami globalnymi.
3. ADR-y w docs/adr/ — zmiana ścieżki, nie zasad akceptacji
Ujednolicenie domyślnego miejsca dla nowych ADR-ów do docs/adr/ jest rozsądną konwencją projektu. Nie trzeba przy tym przedstawiać tej ścieżki jako jedynego obowiązującego standardu.
Warto zachować dotychczasowe rozróżnienia:
- można przechowywać propozycje, decyzje zaakceptowane, odrzucone i zastąpione — nie tylko decyzje zaakceptowane;
- przy nowym zadaniu należy ponownie wykorzystać pasujące decyzje zamiast tworzyć kolejny ADR o tym samym;
- jeśli decyzja zostaje zastąpiona, trzeba powiązać oba dokumenty, nie zmieniając po fakcie uzasadnienia historycznego wyboru;
- pozytywny wynik testów sam w sobie nie oznacza, że ADR został formalnie zaakceptowany.
Migracja wymaga też aktualizacji istniejących odwołań, reguł lokalizacji plików i ograniczeń dostępu. Samo przeniesienie dokumentu nie wystarczy.
4. Katalog planów może być płaski, ale zamrożenie to nie ukończenie
Katalog plans/ nie musi być dzielony na podkatalogi, jeśli liczba planów nie uzasadnia dodatkowej hierarchii. Można rozważyć taki układ nazw:
| Przeznaczenie | Przykładowa ścieżka | Znaczenie |
|---|---|---|
| Aktywny plan | plans/pending_implementation_plan.md |
Domyślny, pojedynczy punkt wejścia do bieżących prac |
| Plan ukończony | plans/plan-20261022-example-id.md |
Plan ukończony i zatwierdzony do archiwizacji |
| Plan zamrożony | plans/plan-20261022-example-id-frozen.md |
Plan nieukończony, wycofany z aktywnego toku prac |
Zamrożenie nie wymaga osobnego katalogu ani natychmiastowego dodawania nowego statusu. Istniejący walidator obsługuje już stan wstrzymania; można go wykorzystać, zapisując w zamrożonym planie powód wstrzymania, pozostałe zadania i warunki wznowienia.
Należy jednak odróżnić trzy sytuacje:
- Archiwizacja po ukończeniu: wymagane kryteria akceptacji zostały spełnione i uzyskano zgodę na archiwizację.
- Zamrożenie: plan znika z aktywnego punktu wejścia, ale pozostaje nieukończony. Nieweryfikowana propozycja nie staje się przez to faktem.
- Rezygnacja: trzeba jasno zapisać, że prace nie będą kontynuowane, i wskazać konsekwencje. Nie należy nazywać trwałego porzucenia chwilowym wstrzymaniem. Formalny status zakończenia wymagałby osobnej zmiany kontraktu.
Domyślnie należy czytać tylko aktywny plan, a nie wszystkie historyczne pliki z katalogu. Do archiwum warto sięgać na żądanie — na przykład przy przywracaniu prac lub sprawdzaniu historii. Wznowienie zamrożonego planu powinno wymagać nowej zgody, zachowania informacji o źródłowym planie i ponownej weryfikacji. Dawny pozytywny wynik nie zastępuje nowego sprawdzenia. Jest to zgodne z opisanym cyklem życia planów.
Zmiana nazwy pliku nie jest dowodem ukończenia. Przy archiwizacji trzeba zapobiec nadpisaniu istniejącego dokumentu, zachować listę niedokończonych prac i zaktualizować odwołania. Nie należy też tworzyć pustego szablonu tylko po to, by zawsze istniał plik aktywnego planu.
5. Powiązania kodu z testami: wiele do wielu
Nie warto wymagać relacji „jeden plik kodu — jeden plik testu”. Pojedynczy test może obejmować kilka komponentów, a jeden komponent może wymagać testów jednostkowych, własnościowych i integracyjnych.
Na początek wystarczy:
- porządkować
tests/według modułów lub odpowiedzialności; - w odpowiedniej specyfikacji wskazywać kluczowe niezmienniki, istotne testy i ograniczone polecenia weryfikacyjne;
- dodać osobny plik, na przykład
tests/test-map.yaml, dopiero wtedy, gdy rzeczywistych zależności nie da się łatwo znaleźć w inny sposób.
Taka mapa powinna zawierać tylko potrzebne powiązania: identyfikator modułu lub kontraktu, zakres kodu źródłowego, zakres testów i sposób ich uruchomienia. Nie musi kopiować całego drzewa katalogów ani odzwierciedlać stanu zaliczenia testów.
Kontrola utrzymania mapy powinna sprawdzać, czy ścieżki i polecenia nadal są poprawne. Sam fakt, że mapa istnieje, nie dowodzi ani wystarczającego pokrycia, ani pomyślnego wyniku testów.
6. Porządkowanie szkiców bez usuwania jedynych dowodów
Jednorazowe szkice, skrypty tymczasowe i raporty z eksperymentów można grupować w .scratch/. Trzeba jednak uważać na dwie zbyt daleko idące zasady: że nic w tym katalogu nie może być źródłem pierwotnym oraz że wszystko można skasować bez sprawdzenia.
- Podsumowanie badań przygotowane przez model jest wtórną interpretacją, a nie samodzielnym dowodem faktu.
- Surowy wynik testu lub rzeczywisty zapis diagnostyczny może być dowodem pierwotnym nawet wtedy, gdy znajduje się w katalogu tymczasowym. Liczą się źródło, środowisko, czas i kompletność zapisu.
- Nie należy usuwać jedynego dowodu, na który powołuje się plan, decyzja lub kryterium akceptacji. Przed sprzątaniem trzeba zachować potrzebny oryginał albo wyraźnie wycofać oparty na nim wniosek.
- Ważne ustalenia powinny zachowywać wskazanie źródła, zakres zastosowania i nierozstrzygnięte kwestie. Skrócenie notatki nie może zmienić hipotezy w fakt.
Starsze raporty i diagramy architektury w docs/ warto podzielić na dokumenty aktualne, materiały historyczne i treści wymagające ponownej weryfikacji. Sam wiek pliku nie przesądza, że jest on zbędny.
- Dokumenty aktualne powinny wskazywać zakres obowiązywania i być przeglądane przy zmianach powiązanych kontraktów.
- Nieaktualne diagramy i wcześniejsze propozycje można oznaczyć jako historyczne, przestarzałe lub zastąpione; nie powinny domyślnie służyć jako bieżąca podstawa.
- Materiały procesowe bez trwałej wartości i zależnych od nich odwołań można, po uzyskaniu zgody, przenieść do katalogu tymczasowego albo usunąć.
Przechowywanie materiału i ładowanie go do kontekstu w każdej sesji to dwie różne sprawy. Warto zachować potrzebną historię, ale ograniczać zbędny kontekst przez selektywne odczytywanie plików i oznaczanie ich aktualności — nie przez usuwanie dowodów.
Wniosek
Proponowany układ można przyjąć z czterema wyraźnymi zastrzeżeniami: centralizacja testów musi uwzględniać wyjątki językowe; specyfikacja ma opisywać aktualny kontrakt, a nie streszczać wszystkie ADR-y; zamrożony plan pozostaje nieukończony; sprzątanie plików tymczasowych nie może usuwać jedynego potrzebnego dowodu.
Domyślna ścieżka planu, dozwolone lokalizacje i zakres edycji w trybach analizy nadal są powiązane ze starszym układem. Migracja powinna objąć reguły, szablony, odwołania, walidację i konfigurację narzędzi, a nie ograniczać się do zmiany nazw katalogów. Na tym etapie przedstawiono analizę; żadne pliki nie zostały zapisane, przeniesione, zamrożone ani usunięte.
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 "Porządek w repozytorium: testy, ADR-y, plany i dokumentacja"?
Testy warto domyślnie gromadzić w jednym miejscu, ale testy Go sprawdzające nieeksportowane elementy pakietu mogą wymagać pozostania obok kodu.
What are the key points to validate first?
Testy warto domyślnie gromadzić w jednym miejscu, ale testy Go sprawdzające nieeksportowane elementy pakietu mogą wymagać pozostania obok kodu. Specyfikacja opisuje aktualne wymagania, ADR wyjaśnia podjęte decyzje, a test sprawdza zachowanie — te elementy powinny się uzupełniać, nie zastępować.
What should I do next in practice?
Zamrożony plan nie jest planem ukończonym: trzeba zachować jego status, niedokończone zadania i warunki wznowienia.