AnswersPublished14 sources
Testy, specifikace a ADR: přehledná struktura bez ztráty důkazů
Testy je vhodné soustředit do společné složky, ale u Go mohou bílé testy zůstat v adresáři testovaného balíčku. Specifikace popisuje současný kontrakt, ADR vysvětluje důvody rozhodnutí a testy ověřují chování.
PublikovalObrázky vytvořeny pomocí GPT Image 2
Research answer
Key takeaways
- Testy je vhodné soustředit do společné složky, ale u Go mohou bílé testy zůstat v adresáři testovaného balíčku.
- Specifikace popisuje současný kontrakt, ADR vysvětluje důvody rozhodnutí a testy ověřují chování.
- Dokončený plán a zmrazený plán nejsou totéž: zmrazený si zachovává nedokončené úkoly a není automaticky schválený k realizaci.
- Dočasné soubory lze uklízet, ne však tak, aby zmizel jediný potřebný důkaz nebo zůstaly závěry bez opory.
![[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
Tato struktura může být dobrým směrem, je však potřeba vyhnout se třem falešným rovnítkům: ne všechny testy lze bez výjimky přesunout mimo zdrojový balíček, specifikace není souhrnem všech ADR a zmrazení plánu neznamená jeho dokončení. Níže jsou hranice šesti navrhovaných pravidel. Uvedené nové cesty jsou zatím jen návrhy — nebyly vytvořeny ani migrovány.
1. Testy soustředit, ale ponechat výjimky pro jazyk
Soustředění testů do společné složky může být výchozím pravidlem. Nemělo by se však změnit v požadavek, aby žádný projekt nikdy neměl test vedle zdrojového kódu.
- Python: upřednostnit společnou složku
tests/. Při přesunu ověřit importy, vyhledávání testů, přípravky i CI. V tomto repozitáři už CI používá centralizované umístění testů. - Go: bílé testy, které potřebují přístup k neexportovaným členům balíčku, mohou zůstat v adresáři testovaného balíčku. Černé testy, testy napříč komponentami a end-to-end testy lze přednostně soustředit jinam. Nástroj Go překládá testovací soubory v rámci balíčku a podporuje testy ve stejném balíčku i v externím testovacím balíčku.
14
Je také třeba rozlišovat dvě věci: omezení importu interních balíčků se odvíjí od vztahu adresářů, nikoli od pravidla, že importovat lze pouze ze stejného adresáře. Přístup k neexportovaným členům je samostatná hranice balíčku.10
16
Proto není vhodné jako obecnou podmínku přijmout „přesuňme všechny testy Go mimo adresáře aplikace, ale zachovejme bílé pokrytí i zapouzdření“. Kvůli úklidu struktury neexportujte interní stav ani nekopírujte logiku aplikace.
Cílem je omezit zbytečné pracovní fragmenty a duplicitní ověřování, nikoli zakázat smysluplné samostatné testovací soubory. Regresní testy, které mají sloužit dlouhodobě, patří do správy verzí; jednorázové sondy do dočasného prostoru.
2. Metodika, projektová pravidla a ADR mají odlišné role
Složka specs/ by neměla být definována jako místo, kam se shrnou všechny ADR. Vhodnější je rozdělit odpovědnosti takto:
| Vrstva | Na jakou otázku odpovídá | Odkud vychází |
|---|---|---|
| Celková metodika | Jak analyzovat, ověřovat a předávat práci? | Vytvářejí ji správci metodiky. |
Projektový vstup AGENTS.md |
Jak se pracuje právě v tomto projektu? | Z potvrzených projektových omezení a pracovních pokynů. |
Projektové specifikace specs/ |
Jaké chování a kontrakty mají aktuálně platit? | Z požadavků, přijatých rozhodnutí a schválených změn. |
Záznamy rozhodnutí docs/adr/ |
Proč byla zvolena právě tato varianta? | Z architektonických kompromisů a posouzených alternativ. |
Cline podporuje trvalá pravidla, která umožňují zachovat pokyny napříč relacemi.4 Z dostupných podkladů ale nevyplývá, že by Cline nativně a automaticky zapisoval určitý typ souborů do složky specifikací. Takové propojení je proto třeba chápat jako projektovou konvenci, ne jako zaručené chování Cline.
Projektové materiály navíc nemusí vznikat pouze ručně ani až poté, co se v praxi objeví problém. Mohou se vyvíjet v několika krocích:
- Při inicializaci může asistent navrhnout specifikace podle uživatelských požadavků a důkazů v repozitáři. Neznámé skutečnosti musí zůstat označené jako neznámé.
- Před prací na konkrétním úkolu se načtou relevantní specifikace a rozhodnutí a stanoví se kritéria převzetí i ověření.
- Nové ADR se navrhne tehdy, když se objeví důležitá nová volba. Pokud se už existující rozhodnutí hodí, stačí na ně odkázat.
- Výsledek testů může ukázat, že implementace vyhovuje, nebo odhalit nedostatek ve specifikaci. Sám o sobě ale nemění požadavky.
- Po schválení rozhodnutí a aktualizace specifikace se platná omezení zapíší do příslušného dokumentu a odkáže se na relevantní ADR. Není třeba přepisovat celou historii.
Stručně: specifikace popisuje aktuální kontrakt, ADR zachycuje důvody rozhodnutí a testy představují proveditelnou kontrolu. Jsou propojené, ale navzájem se nenahrazují. Zjištění specifická pro jeden projekt by se bez posouzení neměla měnit v globální pravidla.
3. Sjednotit cestu ADR, ne však pravidla jejich přijímání
Je rozumné používat docs/adr/ jako výchozí místo pro nová rozhodnutí. Jde o konvenci projektu, ne o tvrzení, že existuje jediný závazný standard pro celý obor.
Zachovat je vhodné dosavadní přístup:
- Záznamy mohou zachycovat návrhy, přijatá i zamítnutá rozhodnutí a rozhodnutí později nahrazená jinými.
- Nové úkoly mají využít platná související rozhodnutí, ne vytvářet totožné ADR znovu.
- Když je rozhodnutí nahrazeno, zaznamená se návaznost. Původní důvody se nepřepisují.
- Úspěšné testy samy o sobě neznamenají, že bylo rozhodnutí v ADR schváleno.
Při migraci je nutné aktualizovat i skutečné odkazy, směrování a omezení přístupu. Samotné přemístění souborů nestačí.
4. Plány lze ukládat naplocho, ale zmrazení není dokončení
Navržené ploché uspořádání plans/ je použitelné. Kvůli malému počtu historických plánů není nutné zavádět další vnořené složky. Možná konvence názvů:
| Účel | Návrhový název | Význam |
|---|---|---|
| Aktivní plán | plans/pending_implementation_plan.md |
Jediný výchozí vstup pro právě probíhající plán. |
| Archiv dokončeného plánu | plans/plan-20261022-example-id.md |
Dokončený plán, který byl schválen k archivaci. |
| Zmrazený nedokončený plán | plans/plan-20261022-example-id-frozen.md |
Plán s nevyřízenými úkoly, který už není ve výchozím seznamu aktivní práce. |
Zmrazení nevyžaduje novou složku ani okamžité zavedení dalšího stavu. Stávající validátor už podporuje stav pozastavení; lze ho prozatím použít a do zmrazeného souboru uvést důvod, zbývající práci a podmínky obnovení.
Je nutné rozlišovat tři situace:
- Dokončený a archivovaný plán: všechna povinná kritéria byla splněna a archivace byla schválena.
- Zmrazený plán: byl vyřazen z aktivního vstupu, ale zůstává nedokončený. Návrh, který nebyl ověřen, se tím nemění ve fakt.
- Výslovně opuštěný plán: dokumentuje, že se v práci pokračovat nebude, a uvádí dopady. Nestačí ho označit za dočasně pozastavený. Zavedení samostatného formálního stavu ukončení by vyžadovalo další změnu pravidel.
Ve výchozím nastavení se načítá jen aktivní vstup, nikoli všechny historické soubory ve stejné složce. Historie se cíleně prohledává, až když si ji uživatel vyžádá nebo chce plán obnovit. Obnovení zmrazeného plánu vyžaduje nové oprávnění, vytvoření nové instance s odkazem na původní plán a nové ověření. Starší „zelený“ výsledek nelze automaticky převzít. To odpovídá současným pravidlům životního cyklu.
Přejmenování souboru je jen operace uložení, nikoli důkaz, že byla práce převzata. Je třeba zabránit přepsání, zachovat nedokončené body a ošetřit odkazy. Pevná cesta pro aktivní plán také neznamená, že se má vždy vytvářet prázdná šablona.
5. Testy mapovat na moduly a kontrakty, ne kus za kusem
Nevyžadujte model „jeden soubor se zdrojovým kódem = jeden testovací soubor“. Jeden test může ověřovat více komponent a jedna komponenta může potřebovat jednotkové, vlastnostní i integrační regresní testy.
Jako první krok může stačit:
- Uspořádat
tests/podle modulů nebo odpovědností. - V příslušné specifikaci uvést klíčové invarianty, související testy a omezené příkazy pro ověření.
- Teprve pokud se vztahy mezi cestami špatně hledají, přidat návrhový soubor
tests/test-map.yaml.
Mapa má obsahovat pouze potřebné vazby: identifikátor modulu nebo kontraktu, rozsah zdrojového kódu, rozsah testů a příkaz pro ověření. Nemá duplikovat celou stromovou strukturu ani zrcadlit aktuální stav úspěšnosti testů.
Kontrola má ověřovat, že cesty a příkazy zůstávají platné. Samotná existence mapy nedokazuje dostatečné pokrytí ani úspěšné testy. Předejde se tak tomu, aby kvůli snaze o přehlednost vznikla další ručně vedená evidence, která rychle zastará.
6. Dočasné materiály čistit, ale důvěryhodnost neurčuje složka
Jednorázové návrhy, dočasné skripty a průzkumné reporty lze soustředit do .scratch/. Pravidla „nic odsud není primární informace“ a „vše lze kdykoli smazat“ je však nutné zmírnit.
- Shrnutí výzkumu vytvořené modelem je druhotná interpretace a samo se nestává faktem.
- Původní výstup testu nebo skutečný diagnostický záznam může být primárním důkazem i v dočasné složce. Jeho věrohodnost závisí na původu, prostředí, době pořízení a úplnosti.
- Jediný důkaz, na který se stále odkazuje plán, rozhodnutí nebo kritérium převzetí, nelze bez dalšího smazat. Před úklidem je třeba zachovat potřebný originál nebo výslovně odvolat závěr, který na něm závisí.
- Důležité zjištění, které se přenese do trvalých dokumentů, musí zachovat odkaz na důkaz, rozsah platnosti a neznámé. Zkrácení nesmí změnit předpoklad v ověřený fakt.
U starších reportů a architektonických diagramů v docs/ je lepší rozlišovat aktuálně udržovanou dokumentaci, vědomě uchovávanou historii a materiály čekající na ověření. Ne všechno staré je automaticky bezcenné:
- U aktuálních dokumentů uvést rozsah platnosti a při změně souvisejících kontraktů je znovu prověřit.
- Staré diagramy a návrhy označit jako historické, zastaralé nebo nahrazené; nepoužívat je jako výchozí popis současného stavu.
- Procesní materiály bez dlouhodobé hodnoty a bez závislých odkazů lze po schválení přesunout do dočasné oblasti nebo odstranit.
Uchovávat dokument neznamená načítat ho při každém úkolu. Potřebnou historii lze zachovat a současně omezit zahlcení kontextu cíleným čtením a jasným označením platnosti — místo mazání důkazů.
Závěr
Navrženou strukturu lze přijmout se čtyřmi pevnými hranicemi: testy soustředit s výjimkami pro jazykové potřeby; specifikace chápat jako aktuální kontrakt, nikoli souhrn všech ADR; zmrazením zachovat nedokončený stav; a při úklidu dočasných materiálů nesmazat jediný potřebný důkaz.
Stávající výchozí cesta pro plány a povolené cesty i rozsah úprav analytického režimu jsou stále navázané na starší strukturu. Budoucí migrace proto musí upravit také pravidla, šablony, odkazy, validaci a napojení na používané prostředí. Pouhé přejmenování složek neznamená, že změna začala platit. Tato analýza sama o sobě žádné soubory nezapsala, nepřesunula, nezmrazila ani nevyčistila.
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 "Testy, specifikace a ADR: přehledná struktura bez ztráty důkazů"?
Testy je vhodné soustředit do společné složky, ale u Go mohou bílé testy zůstat v adresáři testovaného balíčku.
What are the key points to validate first?
Testy je vhodné soustředit do společné složky, ale u Go mohou bílé testy zůstat v adresáři testovaného balíčku. Specifikace popisuje současný kontrakt, ADR vysvětluje důvody rozhodnutí a testy ověřují chování.
What should I do next in practice?
Dokončený plán a zmrazený plán nejsou totéž: zmrazený si zachovává nedokončené úkoly a není automaticky schválený k realizaci.