AnswersPublished14 sources
Saml projektets dokumentation – uden at gøre reglerne for rigide
Gør en fælles testmappe til udgangspunktet, men behold Go whiteboxtests i pakken, når de skal bruge ikke eksporterede medlemmer. Skeln mellem projektets aktuelle krav, beslutningshistorik og generelle arbejdsregler – de har forskellige formål.
Udgivet afBilleder genereret med GPT Image 2
Research answer
Key takeaways
- Gør en fælles testmappe til udgangspunktet, men behold Go whiteboxtests i pakken, når de skal bruge ikke eksporterede medlemmer.
- Skeln mellem projektets aktuelle krav, beslutningshistorik og generelle arbejdsregler – de har forskellige formål.
- En frossen plan er ikke en afsluttet plan, og midlertidige mapper må ikke blive en anledning til at slette nødvendig dokumentation.
![[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
En mere samlet mappestruktur kan gøre et softwareprojekt nemmere at forstå og vedligeholde. Men oprydning bør ikke udviske vigtige forskelle: Tests skal ikke altid flyttes væk fra koden, specifikationer er ikke et resumé af alle beslutningsnotater, og en plan, der sættes på pause, er ikke dermed afsluttet.
Her er seks forslag til, hvordan man kan skabe orden uden at gøre strukturen til et mål i sig selv. De nye stier, der nævnes, er forslag – de er ikke oprettet eller taget i brug endnu.
1. Saml som udgangspunkt tests – men gør plads til undtagelser
Det kan være praktisk at samle tests ét sted, men det er bedre at gøre det til en hovedregel end at kræve, at alle tests flyttes ud af kildens mapper.
- Python: Læg som udgangspunkt tests i
tests/. Ved en flytning skal man kontrollere imports, testopdagelse, fixtures og CI. I det aktuelle repository bruger CI allerede en samlet teststi (.github/workflows/ci.yml:60). - Go: Behold whiteboxtests i den testede pakkes mappe, hvis de skal tilgå ikke-eksporterede medlemmer. Tests af eksterne kontrakter, flere komponenter eller end-to-end-forløb kan som udgangspunkt samles centralt. Go-værktøjerne bygger testfiler sammen med den relevante pakke, og Go understøtter både tests i samme pakke og tests i en separat ekstern testpakke.
14
Der er også to forskellige begrænsninger, som er lette at blande sammen: Reglerne for, hvem der må importere en internal-pakke, handler om forholdet mellem mappestier. Det betyder ikke, at en pakke kun kan importeres fra præcis samme mappe. Adgang til ikke-eksporterede medlemmer handler derimod om pakkens grænser.10
16
Derfor bør man ikke som standard kræve, at alle Go-tests flyttes ud af kildemapperne, samtidig med at whiteboxdækningen og indkapslingen skal forblive uændret. Undgå at eksportere intern tilstand eller kopiere forretningslogik alene for at opnå en pænere mappestruktur.
Det, der bør begrænses, er værdiløse opgavefragmenter og gentagne kontroller – ikke selvstændige testfiler, der har en reel funktion. Regressionstests, som fortsat skal bruges, hører til i versionsstyringen. En engangsundersøgelse kan derimod placeres i et midlertidigt område.
2. Hold arbejdsregler, specifikationer og ADR’er adskilt
Det er rigtigt, at projektets krav og regler skal være tilgængelige for det aktuelle arbejde. Men specs/ bør ikke forstås som en generel samling af alt indhold fra alle ADR’er. De tre lag har forskellige opgaver:
| Lag | Spørgsmålet, det besvarer | Hvor indholdet kommer fra |
|---|---|---|
| Generel metode | Hvordan analyserer, verificerer og afleverer man arbejde? | Fastlægges af dem, der vedligeholder metoden |
Projektets indgang, AGENTS.md |
Hvordan arbejder man i netop dette projekt? | Bekræftede projektkrav og praktiske indgange |
Projektspecifikationer, specs/ |
Hvilken adfærd og hvilke kontrakter gælder nu? | Brugerbehov, accepterede beslutninger og godkendte ændringer |
Beslutningslog, docs/adr/ |
Hvorfor blev en løsning valgt? | Arkitektoniske afvejninger og alternativer |
Cline dokumenterer en funktion til vedvarende regler, som kan gemme instruktioner på tværs af samtaler.4 Det dokumenterer ikke i sig selv, at Cline automatisk opretter en bestemt filtype i projektets specifikationsmappe. Det bør derfor beskrives som en projektaftale – ikke som en garanteret Cline-funktion.
Projektmateriale behøver hverken være skrevet udelukkende manuelt eller vente på, at et problem opstår. En mulig arbejdsgang er:
- Ved opstart kan en assistent foreslå projektspecifikationer ud fra brugerens behov og belæg i repository. Ukendte forhold skal fortsat stå som ukendte.
- Før en opgave begynder, gennemgås de relevante specifikationer og beslutninger, så acceptkriterier og verifikation er tydelige.
- Opret kun en ny ADR, når der faktisk er en vigtig ny afvejning. Hvis en eksisterende beslutning dækker situationen, henvis til den i stedet for at gentage den i en ny ADR for hver plan.
- Verifikation kan vise, at implementeringen opfylder kravene, eller at en specifikation har en mangel. Testresultatet afgør ikke automatisk, hvad behovet burde være.
- Når en beslutning er godkendt, og specifikationen er opdateret, beskrives den gældende kontrakt i den relevante specifikation med henvisning til ADR’en. Hele beslutningshistorikken behøver ikke kopieres.
Kort sagt: Specifikationen beskriver den aktuelle kontrakt, ADR’en forklarer beslutningen, og testen kontrollerer dele af den kontrakt. De hænger sammen, men erstatter ikke hinanden. Fund, der kun gælder ét projekt, bør heller ikke uden gennemgang blive til globale regler.
3. Brug docs/adr/ som standardsti – uden at ændre beslutningspraksis
Det er en fornuftig projektkonvention at lægge nye beslutningsnotater i docs/adr/. Det behøver ikke fremstilles som den eneste korrekte standard på tværs af branchen.
Den nuværende praksis kan fortsætte:
- Gem relevante forslag, accepterede og afviste beslutninger samt beslutninger, der senere er blevet erstattet. En beslutningslog bør ikke kun indeholde accepterede valg.
- Genbrug relevante, gældende beslutninger i nye opgaver i stedet for at oprette dubletter.
- Når en beslutning erstattes, skal forbindelsen til den nye beslutning fremgå. Skriv ikke den oprindelige begrundelse om, så historikken ændres.
- Et bestået testresultat er ikke i sig selv en godkendelse af en ADR.
En flytning kræver også, at reelle henvisninger, routing og adgangsregler bliver opdateret. Det er ikke nok blot at flytte filerne.
4. Hold planer fladt organiseret – og skeln mellem pause og afslutning
En flad plans/-mappe kan være tilstrækkelig; der er ikke behov for at oprette undermapper alene for at sortere et mindre antal historiske planer. Følgende navne kan bruges som udgangspunkt:
| Formål | Forslag til filnavn | Betydning |
|---|---|---|
| Aktiv plan | plans/pending_implementation_plan.md |
Den ene standardindgang til arbejdet, der er i gang |
| Afsluttet plan | plans/plan-20261022-example-id.md |
Arbejdet er gennemført og godkendt til arkivering |
| Plan sat på pause | plans/plan-20261022-example-id-frozen.md |
Uafsluttede opgaver bevares, men udføres ikke som standard |
En frossen plan kræver ikke en ny mappe eller nødvendigvis en ny statusværdi. Den eksisterende validator (scripts/validate-roo-contracts.py:66) understøtter allerede en pausetilstand. Den kan bruges, mens den frosne plan beskriver årsagen til pausen, de resterende opgaver og betingelserne for at genoptage arbejdet.
De vigtige skel er:
- Afsluttet og arkiveret: Alle nødvendige acceptkriterier er opfyldt, og arkivering er godkendt.
- Sat på pause: Planen er fjernet fra den aktive indgang, men arbejdet er ikke afsluttet. Forslag, der ikke er verificeret, må ikke fremstilles som fakta.
- Opgivet: Det fremgår, at arbejdet ikke skal gennemføres, og hvilke følger det har. Det er ikke det samme som en midlertidig pause. En formel status for opgivelse kræver en særskilt ændring af projektets kontrakt.
Som standard bør man kun læse den aktive indgang – ikke gennemsøge alle historiske filer i mappen. Historikken findes frem, når brugeren beder om det, eller når en tidligere plan skal genoptages. Genoptagelse kræver ny godkendelse, en ny udførelsesinstans med tydelig reference til originalen og ny verifikation. Et gammelt grønt resultat gælder ikke automatisk for det genoptagne arbejde. Det følger den eksisterende livscyklusregel (bmad-suite-v4/roo/rules/02-bmad-core.md:5).
Et filnavnsskift er desuden kun en lagringshandling – ikke bevis på, at arbejdet er godkendt. Undgå at overskrive planer, bevar uafsluttede opgaver, og opdater henvisninger. Opret ikke en tom plan alene for at holde en fast indgangsfil på plads.
5. Knyt tests til moduler og kontrakter – ikke én til én
En regel om, at hver kodefil skal have præcis én testfil, er for rigid. En test kan dække flere komponenter, og én komponent kan have brug for enhedstests, egenskabsbaserede tests og integrationsregressioner.
Start hellere med at:
- organisere
tests/efter modul eller ansvar; - angive centrale invariants, relevante testindgange og afgrænsede verifikationskommandoer i den tilhørende specifikation;
- først tilføje en testoversigt, eksempelvis
tests/test-map.yaml, hvis forbindelsen mellem kode og tests reelt er svær at finde.
En sådan oversigt bør kun indeholde det nødvendige: modul- eller kontrakt-id, kodeområde, testområde og verifikationsindgang. Undgå at kopiere hele mappetræet eller at spejle teststatus i en manuel oversigt.
Vedligeholdelseskravet bør være, at stier og kommandoer stadig virker. At en mappingfil findes, beviser ikke, at testdækningen er tilstrækkelig, eller at testene består. På den måde undgår man at løse filrod ved at indføre endnu et manuelt register, der kan blive forældet.
6. Ryd op i kladder uden at lade mappen afgøre troværdigheden
Det giver mening at samle engangskladder, midlertidige scripts og undersøgende rapporter i .scratch/. Men to strengere regler bør justeres: Indholdet er ikke automatisk andenhåndsinformation, fordi det ligger dér, og det er ikke altid forsvarligt at slette hele mappen uden videre.
- Et resumé af modelresearch er en andenhåndsforklaring og kan ikke i sig selv opgraderes til et faktum.
- Rå testoutput eller en faktisk diagnostiklog kan være førstehåndsbelæg, selv om den ligger midlertidigt. Troværdigheden afhænger af kilde, miljø, tidspunkt og fuldstændighed.
- Slet ikke det eneste belæg, som en plan, beslutning eller acceptvurdering stadig bygger på. Gem nødvendige originaler, eller træk den afhængige konklusion tydeligt tilbage, før materialet fjernes.
- Når vigtige fund kondenseres, skal kildehenvisning, anvendelsesområde og ukendte forhold stadig fremgå. En kortere tekst må ikke gøre en antagelse til et faktum.
Ældre rapporter og arkitekturdiagrammer i docs/ bør også klassificeres efter deres status – ikke bare kasseres, fordi de er gamle:
- Gældende dokumenter beskriver deres anvendelsesområde og gennemgås, når den relevante kontrakt ændres.
- Forældede eller erstattede diagrammer og forslag mærkes som historiske og bruges ikke automatisk som den aktuelle baseline.
- Procesmateriale uden varig værdi og uden aktive henvisninger kan flyttes til et midlertidigt område eller slettes, når det er godkendt.
At bevare historik er ikke det samme som at indlæse den som standard. Det nødvendige historiske materiale kan gemmes, uden at det skal læses ved hver opgave. For at mindske støj i arbejdskonteksten bør man først bruge målrettet læsning og tydelige statusmarkeringer – ikke slette belæg.
Konklusion: En ryddelig struktur kræver klare grænser
Forslaget kan samles om fire grundregler: Gør central testorganisering til udgangspunktet, men behold sprogspecifikke undtagelser; lad specifikationerne beskrive den aktuelle kontrakt i stedet for at opsummere alle ADR’er; behandl en frossen plan som uafsluttet; og ryd ikke midlertidigt materiale væk, hvis det rummer det eneste nødvendige belæg.
Den nuværende standardsti for planer og tilladte stier (scripts/validate-roo-contracts.py:48) samt redigeringsområdet for analysetilstand (bmad-suite-v4/roo/settings/custom_modes.yaml:5) er stadig knyttet til den gamle struktur. En senere migrering skal derfor også opdatere regler, skabeloner, henvisninger, validering og værtsintegration. En ændring af mappenavne alene gør ikke den nye struktur gældende.
Denne gennemgang er kun en analyse af arbejdsgangen. Der er ikke skrevet til, flyttet, frosset eller ryddet op i nogen projektfiler.
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 "Saml projektets dokumentation – uden at gøre reglerne for rigide"?
Gør en fælles testmappe til udgangspunktet, men behold Go whiteboxtests i pakken, når de skal bruge ikke eksporterede medlemmer.
What are the key points to validate first?
Gør en fælles testmappe til udgangspunktet, men behold Go whiteboxtests i pakken, når de skal bruge ikke eksporterede medlemmer. Skeln mellem projektets aktuelle krav, beslutningshistorik og generelle arbejdsregler – de har forskellige formål.
What should I do next in practice?
En frossen plan er ikke en afsluttet plan, og midlertidige mapper må ikke blive en anledning til at slette nødvendig dokumentation.