AnswersPublished14 sources
En tydligare struktur för tester, dokumentation och beslut i kodprojekt
Samla tester som huvudregel, men behåll Go tester i paketet när de behöver åtkomst till icke exporterade delar. Låt specifikationer beskriva projektets aktuella krav och ADR:er dokumentera viktiga beslut och avvägningar.
Publicerad avBilder genererade med GPT Image 2
Research answer
Key takeaways
- Samla tester som huvudregel, men behåll Go tester i paketet när de behöver åtkomst till icke exporterade delar.
- Låt specifikationer beskriva projektets aktuella krav och ADR:er dokumentera viktiga beslut och avvägningar.
- Skilj mellan en färdig plan och en fryst, ofullständig plan – och återuppta inte en gammal plan utan ny granskning.
- Rensa tillfälligt material först när det inte längre behövs som enda belägg för ett beslut eller en slutsats.
![[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 enhetlig mappstruktur kan göra ett kodprojekt lättare att förstå och underhålla. Men det finns en viktig skillnad mellan att samla material och att tvinga in allt i samma form. Tester måste fortfarande gå att skriva på ett bra sätt, dokumentationen behöver skilja mellan krav och beslut, och en fryst plan får inte misstas för en färdig.
Här är en modell med sex delar. Nya sökvägar och filnamn nedan är förslag – de har inte skapats eller flyttats.
1. Samla tester som huvudregel, men gör undantag där språket kräver det
En gemensam testmapp kan vara en bra standard, men det är inte alltid rimligt att flytta varje test bort från källkoden.
- Python: samla tester i
tests/som förstahandsval. Kontrollera vid en flytt att importer, testupptäckt, fixtures och CI fortfarande fungerar. I den aktuella projektmiljön använderCIredan en samlad testsökväg. - Go: tester som behöver komma åt icke-exporterade delar kan ligga i samma paket som koden. Svartlådetester, tester över flera komponenter och end-to-end-tester kan i första hand samlas separat. Go bygger testfiler tillsammans med det paket som testas och stöder både tester i samma paket och tester i ett separat paket med suffixet
_test.14
Blanda inte ihop paketgränser med reglerna för kataloger som heter internal: sådana kataloger begränsar vilka paket som får importera dem, men det betyder inte att alla tester måste ligga i samma katalog som produktionskoden. Att komma åt icke-exporterade identifierare är en separat fråga om paketgränser.10
16
Det går därför inte att kräva att alla Go-tester flyttas bort från källkatalogerna och samtidigt förutsätta att testerna behåller åtkomsten till interna delar. Exportera inte intern status eller kopiera verksamhetslogik bara för att få en prydligare mappstruktur.
Det som bör motverkas är onödiga, kortlivade testfragment och upprepade kontroller utan syfte – inte självständiga testfiler som ger värde. Regressionstester bör versionshanteras. Tillfälliga sonderingar hör hemma i en tillfällig arbetsyta.
2. Håll isär regler, specifikationer och beslut
Projektets specifikationer bör inte vara en samling sammanfattningar av alla ADR:er. En ADR, eller Architecture Decision Record, dokumenterar ett viktigt arkitekturbeslut och varför ett alternativ valdes. En specifikation beskriver i stället vad som gäller nu.
| Lager | Frågan det besvarar | Innehåll |
|---|---|---|
| Övergripande arbetssätt | Hur analyserar, verifierar och levererar vi? | Metodregler som gäller brett |
Projektets AGENTS.md |
Hur arbetar man i just det här projektet? | Bekräftade projektregler och ingångar |
Projektets specs/ |
Vilka beteenden och gränssnitt ska gälla? | Aktuella krav och kontrakt |
Beslutsdokument i docs/adr/ |
Varför valde vi den här lösningen? | Viktiga avvägningar och alternativ |
Cline, en AI-assistent för kodarbete, beskriver stöd för beständiga regler som kan användas mellan samtal.4 Det belägger däremot inte att Cline automatiskt skriver en viss typ av fil till projektets specifikationsmapp. En sådan rutin bör beskrivas som ett projektbeslut, inte som en garanterad funktion i verktyget.
En fungerande process kan se ut så här:
- Vid projektstart kan assistenten föreslå specifikationer utifrån användarens behov och vad som faktiskt finns i kodbasen. Sådant som är oklart ska fortsätta vara markerat som oklart.
- Inför en uppgift läser man relevanta specifikationer och beslut och gör tydligt vad som ska godkännas och hur det ska verifieras.
- En ny ADR behövs när ett viktigt nytt vägval uppstår. Om ett redan gällande beslut täcker frågan räcker det att hänvisa till det.
- Testresultat kan visa att en implementation uppfyller kraven – eller att kraven behöver ses över. Resultatet avgör inte automatiskt vad kravet borde vara.
- När en ändring har godkänts uppdateras den aktuella specifikationen. Hänvisa till relevanta ADR:er i stället för att kopiera hela beslutshistoriken.
Kort sagt: specifikationen är det aktuella kontraktet, ADR:n förklarar beslutsgrunden och testet kontrollerar sådant som går att verifiera automatiskt. De hör ihop, men ersätter inte varandra. Lärdomar från ett enskilt projekt bör inte heller bli globala regler utan granskning.
3. Samla nya ADR:er på en tydlig plats
Att använda docs/adr/ som standardplats för nya beslut är en rimlig konvention. Det behöver inte beskrivas som den enda branschstandarden.
Behåll en beslutshistorik som kan omfatta förslag, accepterade och avvisade beslut samt beslut som senare har ersatts. När ett nytt arbete börjar bör man återanvända relevanta, gällande beslut i stället för att skriva en ny ADR med samma innehåll. Om ett beslut ersätts bör kopplingen dokumenteras utan att den ursprungliga motiveringen skrivs om.
Ett godkänt test innebär inte i sig att någon har gett mandat att acceptera en ADR. Vid en flytt behöver man dessutom uppdatera faktiska länkar, regler och behörighetsbegränsningar – inte bara flytta filerna.
4. Håll planerna samlade och skilj på fryst och färdig
En platt struktur i plans/ kan räcka; ett fåtal äldre planer motiverar inte automatiskt fler undermappar. Exempel på möjliga filnamn:
| Användning | Exempel | Betydelse |
|---|---|---|
| Aktiv plan | pending_implementation_plan.md |
Den enda standardingången för aktivt arbete |
| Avslutad plan | plan-20261022-example-id.md |
Färdig och godkänd för arkivering |
| Fryst plan | plan-20261022-example-id-frozen.md |
Ofärdigt arbete som inte längre är aktivt |
En fryst plan behöver inte kräva en ny mapp eller omedelbart en ny statuskategori. Den befintliga valideraren stöder redan pausad status; den kan användas tills vidare, med orsak till pausen, kvarvarande arbete och villkor för återupptagning dokumenterade i planen.
Skillnaden är viktig:
- Färdig och arkiverad: alla nödvändiga godkännandekriterier är uppfyllda och arkivering har godkänts.
- Fryst: planen lämnar den aktiva ingången men är fortfarande ofullständig. Förslag som inte har verifierats får inte beskrivas som fakta.
- Övergiven: det framgår att arbetet inte ska genomföras och vilka följder det får. Att kalla planen pausad räcker inte. En formell slutstatus kräver i så fall att projektets regler ändras.
Som standard bör man läsa den aktiva planens ingång, inte genomsöka varje äldre fil. Historik kan sökas fram när någon ber om den. För att återuppta en fryst plan behövs ett nytt godkännande, en ny genomförandeinstans som bevarar hänvisningen till ursprunget och en ny verifiering. Gammalt klartecken följer inte automatiskt med. Det överensstämmer med reglerna för den aktuella livscykeln.
Att byta namn på en fil är dessutom en lagringsåtgärd, inte ett bevis på att arbetet är godkänt. Undvik överskrivning, bevara kvarvarande uppgifter och uppdatera relevanta hänvisningar. Skapa inte en tom planmall bara för att hålla en fast sökväg vid liv.
5. Koppla tester till moduler och krav – inte ett till ett
En strikt regel om en testfil per källfil blir lätt missvisande. Ett test kan täcka flera komponenter, och en komponent kan behöva enhetstester, egenskapstester och integrationstester.
Börja hellre med att organisera tests/ efter modul eller ansvar. Låt relevanta specifikationer ange centrala invarianter, testkommandon och avgränsade verifieringssteg. Om kopplingen mellan kod, krav och test ändå är svår att hitta kan en fil som tests/test-map.yaml införas.
En sådan karta bör bara innehålla nödvändiga kopplingar: modul eller kontrakt, källkodsområde, testområde och verifieringsingång. Undvik att kopiera hela filträdet eller föra en manuell parallell logg över testresultat. Kontrollera att sökvägar och kommandon fortfarande fungerar, men kom ihåg att en karta i sig inte bevisar att täckningen är tillräcklig eller att testerna passerar.
6. Rensa tillfälligt material utan att kasta bort det enda belägget
En mapp som .scratch/ kan samla engångsutkast, tillfälliga skript och utforskande rapporter. Men materialets tillförlitlighet avgörs inte enbart av vilken mapp det ligger i.
En AI-skriven sammanfattning av en undersökning är en andrahandsbeskrivning och blir inte automatiskt ett faktaunderlag. Samtidigt kan ett rått testresultat eller en diagnostiklogg vara en förstahandskälla även om den ligger i en tillfällig mapp. Bedömningen beror på var materialet kommer ifrån, vilken miljö det gäller, när det skapades och om det är komplett.
Ta därför inte bort den enda evidens som fortfarande används av en plan, ett beslut eller ett godkännande. Innan rensning behöver nödvändiga original bevaras eller slutsatser som bygger på dem uttryckligen omprövas. När viktiga upptäckter sammanfattas bör källa, räckvidd och osäkerheter följa med. En kortare sammanfattning får inte förvandla ett antagande till ett faktum.
Äldre rapporter och arkitekturdiagram i docs/ bör inte kastas bara för att de är gamla. Skilj mellan dokument som fortfarande underhålls, tydligt historiskt material och sådant som behöver kontrolleras. Märk äldre lösningar som historiska, inaktuella eller ersatta så att de inte förväxlas med dagens utgångspunkt. Material utan långsiktigt värde och utan beroenden kan flyttas till en tillfällig mapp eller tas bort efter godkännande.
Att bevara historik betyder inte att allt måste läsas vid varje arbetstillfälle. För att minska onödigt sammanhang är riktad läsning och tydliga giltighetsmarkeringar bättre verktyg än att radera nödvändiga belägg.
Slutsats: ordning med tydliga undantag
En hållbar struktur samlar material där det gör arbetet lättare att följa, men låter inte mapparna styra över testbarhet och spårbarhet. Samla tester som huvudregel men ta hänsyn till språket. Beskriv aktuella krav i specifikationer och viktiga vägval i ADR:er. Bevara skillnaden mellan fryst och färdig plan. Rensa inte bort nödvändig evidens.
I den aktuella miljön är standardplatsen för planer och listan över tillåtna sökvägar samt redigeringsomfånget för analysläget fortfarande kopplade till den äldre strukturen. En framtida flytt behöver därför samordna regler, mallar, hänvisningar, validering och anpassning till verktygsmiljön. Det räcker inte att döpa om mappar. Analysen här innebär inte att några filer har ändrats, flyttats, frysts eller rensats.
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 "En tydligare struktur för tester, dokumentation och beslut i kodprojekt"?
Samla tester som huvudregel, men behåll Go tester i paketet när de behöver åtkomst till icke exporterade delar.
What are the key points to validate first?
Samla tester som huvudregel, men behåll Go tester i paketet när de behöver åtkomst till icke exporterade delar. Låt specifikationer beskriva projektets aktuella krav och ADR:er dokumentera viktiga beslut och avvägningar.
What should I do next in practice?
Skilj mellan en färdig plan och en fryst, ofullständig plan – och återuppta inte en gammal plan utan ny granskning.