AnswersPublished15 sources
Mniej zbędnych plików, nie mniej kontroli: porządek w testach i dokumentacji
Nie warto rezygnować z utrzymywanych testów tylko dlatego, że zajmują miejsce w repozytorium. Porządek w kodzie źródłowym, zawartość pakietu instalacyjnego i materiały wczytywane przez model to trzy osobne kwestie — każda wymaga własnych reguł.
Opublikowane przezObrazy wygenerowane za pomocą GPT Image 2
Research answer
Key takeaways
- Nie warto rezygnować z utrzymywanych testów tylko dlatego, że zajmują miejsce w repozytorium.
- Porządek w kodzie źródłowym, zawartość pakietu instalacyjnego i materiały wczytywane przez model to trzy osobne kwestie — każda wymaga własnych reguł.
- Dokumentację lepiej porządkować według funkcji niż dążyć do jak najmniejszej liczby plików: analiza, decyzja, plan, materiały tymczasowe i instrukcje operacyjne nie powinny się dublować.
- Dostępne ustalenia są częściowe. Nie ukończono przeglądu wszystkich wskazanych źródeł, a rekomendacje nie oznaczają, że zmiany zostały już wdrożone.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/oBMfTzLzQzYo7VcXQdEGj2yQgAw1/images/73E9D63489E02AC46209/BEDABC175BE8FCADFC63.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":"两个痛点都适合纳入 V4 的“产物生命周期背压”，但不应简化成“测试全部不提交”或“文档全部合并”。建议保留长期质量资产，隔离一次性验证材料，并分别控制仓库维护、安装分发和模型上下文。\n\n本次交付为阶段性调研：仓库静态证据、Geoffrey Huntley 的作者资料及部分学术资料已取得；Python 官方布. Topic tags: general web, openai, llm, agents, ai. 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 fa
Dwa problemy — nadmiar testów i rozrastająca się dokumentacja — warto potraktować jako część jednego zagadnienia: zarządzania cyklem życia materiałów projektu. Nie oznacza to jednak, że rozwiązaniem jest „nie commitować testów” albo „trzymać całą dokumentację w jednym pliku”. Rozsądniejszy kierunek to zachować trwałe zasoby jakościowe, oddzielić jednorazowe materiały i osobno ustalić, co trafia do repozytorium, instalacji oraz kontekstu modelu.
To wnioski z częściowego rozpoznania. Sprawdzono statyczne ślady w repozytorium, część materiałów Geoffrey’ego Huntleya oraz wybrane publikacje. Nie dokończono przeglądu oficjalnych zaleceń dotyczących układu projektów w Pythonie ani szerszego przeglądu dyskusji na X, Reddicie, Hacker News i Lobsters. Nie ma więc podstaw, by przedstawiać te ustalenia jako pełne badanie.
Testy: oddzielić materiały tymczasowe, nie rezygnować z kontroli jakości
Co wynika z obecnej struktury V4
- Konfiguracja CI wskazuje na scentralizowany katalog testów i obejmuje m.in. kontrakty konfiguracji, instalację oraz ochronę zasobów (
.github/workflows/ci.yml:55,tests/). To, że testy są widoczne w repozytorium, nie czyni ich automatycznie zbędnymi. W tym rozpoznaniu nie uruchomiono testów ani nie oceniono osobno wartości utrzymaniowej każdego z nich. - Reguły w
.gitignorewykluczają część piaskownic, cache’y i plików tymczasowych, ale nie wymieniają wprost materiałów roboczych z katalogów_bmad-output/scratch/i_bmad-output/verification/. Samo istnienie katalogu nie przesądza, że znajdujące się w nim pliki są śledzone przez Git; tego nie zweryfikowano (.gitignore:1). - Skrypt aktualizacyjny operuje na repozytorium, a mechanizm zbierania źródeł wdrożenia odczytuje wybrany zestaw (
bs.sh:298,scripts/deployment_source.py:64). To odrębne granice: obecność testów w kopii repozytorium nie dowodzi, że trafiają do katalogu instalowanego w projekcie. - Mechanizm zbierania źródeł przechodzi rekurencyjnie przez zwykłe pliki w zestawie i mapuje je na zasoby wdrożeniowe (
scripts/deployment_source.py:47,scripts/deployment_source.py:81). Wynika z tego ryzyko: jeśli materiały tymczasowe trafią do katalogu zestawu, mogą zostać objęte dystrybucją. Nie ma jednak dowodu, że już do tego doszło.
Proponowany podział
| Rodzaj materiału | Zalecenie dotyczące wersjonowania | Zalecenie dotyczące układu i dystrybucji |
|---|---|---|
| Długoterminowe testy regresyjne, kontraktowe i niezbędne testy integracyjne | Wersjonować i utrzymywać razem z kodem | Stosować konwencje danego języka i projektu; domyślnie nie dołączać do pakietu uruchomieniowego |
| Jednorazowe skrypty diagnostyczne, eksperymenty i dane do weryfikacji | Domyślnie pozostawiać lokalnie, bez automatycznego commitowania | Umieszczać w zatwierdzonym obszarze roboczym, poza zasobami przeznaczonymi do dystrybucji |
| Logi, wyniki pokrycia i raporty z uruchomień | Zwykle nie dodawać do źródeł; zachowywać tylko wtedy, gdy pełnią konkretną funkcję dowodową | Trzymać oddzielnie od kodu testów i nie dołączać do pakietu instalacyjnego |
To propozycja zasad, a nie opis już wdrożonej polityki.
Nie ma też jednej uniwersalnej reguły układania testów dla wszystkich języków. Oficjalny samouczek Go pokazuje testy jednostkowe w pliku obok kodu testowanego pakietu, w tym samym katalogu. Nie uzasadnia to przenoszenia wszystkich testów Go do jednego zewnętrznego folderu jako ogólnej zasady.15 W tym repozytorium istnieje już centralny katalog testów, więc dla V4 naturalnym pierwszym krokiem byłoby jego wykorzystanie. Zebrane tu źródła nie wystarczają natomiast do sformułowania ogólnej rekomendacji dotyczącej najlepszego układu projektów w Pythonie.
Warto rozdzielić dwa cele. Jeśli chodzi o czystszą zawartość dla użytkownika, należy przede wszystkim dopracować pakiet wydaniowy lub listę instalowanych plików. Jeśli problemem jest nieporządek w drzewie źródeł, można rozważyć układ testów zgodny z praktykami danego języka. Samo przeniesienie plików nie rozwiąże obu kwestii naraz.
Dokumentacja: porządkować według funkcji, nie liczby plików
Obecne reguły routingu materiałów rozróżniają analizę, ADR — zapis decyzji architektonicznej — plan i kontrakt oraz przewidują pytanie o miejsce zapisu, gdy nie jest ono jasne (bmad-suite-v4/rules/bmad-core.md:129). Osobna reguła dotycząca szkiców wskazuje jednak inny sposób organizacji (bmad-suite-v4/rules/bmad-core.md:117). Taki obraz uzasadnia wniosek o niepełnych zasadach cyklu życia materiałów, ale nie dowodzi, że znamy konkretną przyczynę każdej sytuacji, w której powstaje nowy katalog.
Zamiast tworzyć kolejne warstwy folderów, lepiej doprecyzować rolę już istniejących materiałów:
- Analiza powinna zawierać dowody, porównania, kontrargumenty i niewiadome. Zwykła konsultacja może pozostać w rozmowie; raport nie musi powstawać, jeśli nie ma potrzeby trwałego zapisu.
- ADR powinien odnotowywać ważną decyzję, jej uzasadnienie i ograniczenia, a nie powielać całą analizę ani przebiegu prac.
- Plan wdrożenia powinien określać uprawnienia, zakres, zależności i kryteria odbioru. Może odwoływać się do decyzji, zamiast przepisywać wyniki badań.
- Materiały tymczasowe — szkice, dane diagnostyczne i surowe wyniki — powinny trafiać do zatwierdzonego obszaru roboczego. Samo słowo „szkic” w nazwie nie powinno przesądzać o umieszczeniu pliku wśród oficjalnych analiz.
- Trwała dokumentacja operacyjna ma sens, gdy pełni rolę wielokrotnie używanego podręcznika. Pojedynczy przebieg wdrożenia nie powinien automatycznie tworzyć nowego katalogu dokumentacji.
Liczbę dokumentów, ich wersjonowanie, obecność w instalacji i wczytywanie przez model należy oceniać osobno. Zebranie wszystkiego w jednym folderze nie zastępuje jasnych zasad.
Co wynika z materiałów Geoffrey’ego Huntleya
Huntley opisuje „back pressure” jako automatyczny mechanizm informacji zwrotnej o jakości i poprawności, który pomaga agentowi wykrywać błędy w trakcie dłuższych zadań.12 W tym ujęciu testy nie są szumem do usunięcia, lecz mogą stanowić element kontroli pracy agenta.
W tekście o przenoszeniu oprogramowania między językami proponuje najpierw opisać zachowanie testów w postaci specyfikacji, a następnie użyć jej przy migracji.14 To przykład konkretnego procesu migracyjnego, nie dowód na to, że dokumentacja powinna zastępować testy we wszystkich projektach.
Praktyczny wniosek dla V4 jest węższy: warto zachować wykonywalne sprawdziany poprawności, ograniczając jednocześnie liczbę powtarzalnych albo jednorazowych materiałów weryfikacyjnych. Specyfikacja opisuje oczekiwane zachowanie, a test pozwala je sprawdzić — nie należy uznawać tych form za zamienne bez oceny konkretnego przypadku.
Dostępne źródła nie wystarczają, by ustalić, czy Huntley ma jedną ogólną politykę dotyczącą commitowania testów, katalogów roboczych i wykluczania materiałów z dystrybucji. Nie ma też podstaw do opisania zgodnego stanowiska wspomnianych forów.
Rozrost dokumentacji a błędy modeli: ważniejsze jest to, co model czyta
Badania nad długim kontekstem omawiają trudność w wykorzystywaniu przez modele informacji położonych w środku długiego wejścia.3 Praca HELMET podkreśla, że zdolności modeli w długim kontekście wymagają oceny na wielu rodzajach zadań, a nie tylko na prostych testach wyszukiwania.
4 Nie wynika z tego jednak, że plik przekraczający określoną liczbę wierszy automatycznie powoduje halucynacje — ani że te źródła pozwalają zmierzyć ryzyko w V4.
Praktyczniejsze podejście to:
- dzielić dokumenty według tematu i granic decyzyjnych, zamiast bez końca rozbudowywać jeden plik zbiorczy;
- domyślnie wczytywać treści związane z bieżącym zadaniem, a do materiałów historycznych sięgać w razie potrzeby;
- w krótkich podsumowaniach zachowywać odnośniki do dowodów, niewiadome i niezrealizowane zobowiązania, pozostawiając oryginały do weryfikacji;
- używać indeksów do nawigacji, a nie tworzyć w nich drugiego, powielonego zbioru informacji;
- nie przekazywać modelowi domyślnie całych logów i historycznych raportów.
Minimalny zestaw zmian dla V4
Najbardziej proporcjonalnym krokiem byłoby dodanie jednej reguły obejmującej cały cykl życia materiałów, zamiast rozbudowywania procesu o kolejne ciężkie procedury:
- Przed utworzeniem pliku: określić jego rolę i sprawdzić, czy można rozszerzyć istniejący test lub dokument, zamiast mechanicznie tworzyć nowy.
- Przed zapisaniem: ustalić zatwierdzoną lokalizację, tymczasowy lub trwały charakter pliku, zasady wersjonowania i ewentualne włączenie do dystrybucji. Jeśli nie jest to jasne, nie tworzyć samodzielnie nowej konwencji katalogów.
- Przed commitem: sprawdzić, czy wśród zmian nie ma tymczasowych wyników, wrażliwych danych, powielonych testów lub dublującej się dokumentacji. Wyłączanie wszystkich testów nie jest sposobem na uporządkowanie repozytorium.
- Przed dystrybucją: określić granice instalowanych zasobów i chronić zestaw przed przypadkowym dołączeniem materiałów roboczych. Uproszczenie nie powinno usuwać obecnych zabezpieczeń dotyczących podsumowań, tożsamości ani ochrony zasobów.
- Przed usunięciem: sprawdzić, czy plik nie zawiera dowodów nieudanego testu, nie należy do aktywnego zadania i nie jest wskazywany przez historię. Zakończenie zadania lub wiek materiału same w sobie nie oznaczają zgody na jego skasowanie.
Wniosek: w pierwszej kolejności warto doprecyzować zasady dla materiałów tymczasowych i granice pakietu instalacyjnego, a następnie uporządkować role dokumentów oraz zasady ich wczytywania. Zebrane dowody nie uzasadniają masowego przenoszenia testów Go, rezygnacji z commitowania długoterminowych testów ani scalania całej dokumentacji w jeden plik. Ewentualne zmiany powinny zachować wykrywanie testów, zgodność z CI, czystość pakietu instalacyjnego oraz możliwość prześledzenia wcześniejszych odwołań i niewykonanych zobowiązań.
To opracowanie nie wprowadzało zmian w plikach, nie uruchamiało terminala ani testów i nie wykonywało porządkowania repozytorium.
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 "Mniej zbędnych plików, nie mniej kontroli: porządek w testach i dokumentacji"?
Nie warto rezygnować z utrzymywanych testów tylko dlatego, że zajmują miejsce w repozytorium.
What are the key points to validate first?
Nie warto rezygnować z utrzymywanych testów tylko dlatego, że zajmują miejsce w repozytorium. Porządek w kodzie źródłowym, zawartość pakietu instalacyjnego i materiały wczytywane przez model to trzy osobne kwestie — każda wymaga własnych reguł.
What should I do next in practice?
Dokumentację lepiej porządkować według funkcji niż dążyć do jak najmniejszej liczby plików: analiza, decyzja, plan, materiały tymczasowe i instrukcje operacyjne nie powinny się dublować.
Sources
go.devAdd a test
ghuntley.comdon't waste your back pressure
doi.orgFound in the Middle: How Language Models Use Long Contexts Better via Plug-and-Play Positional Encoding