AnswersPublished14 sources
Testit, speksit ja ADR:t: selkeämpi projektirakenne ilman turhaa jäykkyyttä
Keskitä testit oletuksena tests/ hakemistoon, mutta jätä Go koodin valkoisen laatikon testit tarvittaessa samaan pakettiin kuin testattava koodi. Pidä nykyiset vaatimukset ja sopimukset spekseissä, arkkitehtuurivalintojen perustelut ADR:issä ja yleiset työohjeet omana tasonaan.
JulkaisijaKuvat luotu mallilla GPT Image 2
Research answer
Key takeaways
- Keskitä testit oletuksena tests/ hakemistoon, mutta jätä Go koodin valkoisen laatikon testit tarvittaessa samaan pakettiin kuin testattava koodi.
- Pidä nykyiset vaatimukset ja sopimukset spekseissä, arkkitehtuurivalintojen perustelut ADR:issä ja yleiset työohjeet omana tasonaan.
- Erota valmiiksi arkistoitu suunnitelma keskeneräisenä jäädytetystä: jäädyttäminen ei todista työn valmistumista.
- Kokoa väliaikainen aineisto .scratch/ hakemistoon, mutta älä poista ainoaa lähdettä, johon keskeneräinen päätelmä tai hyväksyntä perustuu.
![[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
Uusi hakemistorakenne voi helpottaa projektin ylläpitoa, mutta siisti puumainen rakenne ei yksin takaa selkeää työnkulkua. Testien siirtämiselle, speksien ja päätösten suhteelle sekä vanhan aineiston siivoamiselle tarvitaan rajat.
Alla on kuusi käytännön suositusta. Mainitut uudet polut ovat ehdotuksia: niitä ei ole vielä luotu tai otettu käyttöön.
1. Testit keskitetysti – mutta kielten käytännöt huomioiden
Keskitetty tests/ on hyvä oletus, ei ehdoton sääntö, jonka mukaan testit eivät koskaan saa sijaita lähdekoodin vieressä.
- Python: testit kannattaa yleensä koota
tests/-hakemistoon. Siirrossa on tarkistettava muun muassa tuonnit, testien löytyminen, testifixturet ja CI-putki. Tämän projektin CI käyttää jo keskitettyä testipolkua. - Go: saman paketin testaava valkoisen laatikon testi voi tarvita pääsyn paketin viemättömiin tunnisteisiin. Tällöin testi kuuluu yleensä testattavan paketin hakemistoon. Ulkoisen testipaketin, eri komponentteja kattavien testien ja päästä päähän -testien voi olla luontevaa sijaita keskitetymmin. Go kääntää testit pakettikohtaisesti, ja testit voidaan kirjoittaa joko samaan pakettiin tai erilliseen
_test-päätteiseen ulkoiseen testipakettiin.14
Myös Go:n internal-hakemiston tuontirajoitus ja pääsy paketin viemättömiin tunnisteisiin ovat eri asioita. Sisäisen paketin tuontioikeus määräytyy hakemistopolun perusteella; viemättömiin tunnisteisiin pääsy taas liittyy pakettirajaan.10
16
Siksi vaatimus, että kaikki Go-testit siirretään pois tuotantokoodin hakemistoista mutta valkoisen laatikon testaus ja kapselointi säilyvät ennallaan, ei sovi yleiseksi säännöksi. Sisäistä tilaa ei pidä viedä julkiseksi vain hakemistorakenteen siistimisen vuoksi.
Tavoitteena kannattaa olla turhien, irrallisten tarkistusten ja päällekkäisen testauksen vähentäminen – ei hyödyllisten testitiedostojen poistaminen. Jatkuvasti tarvittavat regressiotestit kuuluvat versionhallintaan; kertaluonteiset kokeilut voi sijoittaa väliaikaiseen tilaan.
2. Speksit, ADR:t ja yleiset työohjeet ovat eri asioita
Projektin specs/-hakemistoa ei kannata määritellä kaikkien ADR:ien yleiseksi yhteenvedoksi. Kolmella dokumentaatiotasolla on eri tehtävät:
| Taso | Mihin se vastaa? | Mitä se sisältää? |
|---|---|---|
| Yleinen toimintamalli | Miten työ analysoidaan, varmistetaan ja toimitetaan? | Menetelmän ylläpitäjän määrittelemät yleiset käytännöt |
Projektin AGENTS.md |
Miten juuri tässä projektissa työskennellään? | Vahvistetut projektikohtaiset rajat ja käytännön työohjeet |
Projektin specs/ |
Mitä nykyisen toteutuksen pitää tehdä tai noudattaa? | Vaatimukset ja sopimukset, joiden pohjana ovat käyttäjän tarpeet, hyväksytyt päätökset ja hyväksytyt muutokset |
docs/adr/ |
Miksi tietty ratkaisu valittiin? | Arkkitehtuurin kannalta merkittävät valinnat, niiden perustelut ja vaihtoehdot |
Cline dokumentoi pysyvien sääntöjen mekanismin, jolla ohjeita voidaan säilyttää keskustelujen välillä.4 Saatavilla oleva tieto ei kuitenkaan osoita, että Cline kirjoittaisi automaattisesti tietynlaisia tiedostoja projektin speksihakemistoon. Sellainen toimintatapa olisi projektin oma käytäntö, ei tässä vahvistettu Cline-ominaisuus.
Speksejä ei tarvitse kirjoittaa kokonaan käsin eikä niiden syntymistä tarvitse odottaa siihen asti, että jokin työ törmää ongelmaan. Käytännöllinen eteneminen on seuraava:
- Projektin alussa voidaan laatia ehdotus spekseistä käyttäjän tarpeiden ja repositorion näyttöön perustuvien tietojen pohjalta. Tuntemattomat asiat merkitään tuntemattomiksi.
- Tehtävän aluksi tarkistetaan siihen liittyvät speksit ja päätökset sekä sovitaan hyväksymisehdoista ja tarvittavista tarkistuksista.
- Uusi ADR laaditaan, kun syntyy merkittävä uusi arkkitehtuurivalinta. Jos aiempi päätös jo kattaa tilanteen, siihen viitataan sen sijaan, että sama päätös kirjattaisiin uudelleen joka suunnitelmaan.
- Testien tulokset voivat osoittaa toteutuksen täyttävän vaatimukset tai paljastaa speksin puutteita. Ne eivät kuitenkaan itsessään anna lupaa muuttaa vaatimuksia.
- Kun uusi päätös on hyväksytty ja speksiä saa päivittää, nykyinen sopimus kirjataan speksiin ja siihen liittyvään ADR:ään viitataan. Koko päätöshistoriaa ei tarvitse kopioida.
Tiivistettynä: speksi kuvaa nykyisen sopimuksen, ADR päätöksen perustelut ja testi tarkistaa toteutusta. Ne liittyvät toisiinsa, mutta eivät korvaa toisiaan. Projektikohtaista havaintoa ei myöskään pidä nostaa yleiseksi säännöksi ilman erillistä harkintaa.
3. ADR:ille yksi oletuspolku
Uusien päätöstietueiden oletuspaikaksi voi sopia docs/adr/. Kyse on projektin omasta nimeämiskäytännöstä, ei väitteestä, että polku olisi ainoa oikea alan standardi.
Päätöskäytännön kannattaa silti säilyä ennallaan:
- talteen voidaan kirjata ehdotetut, hyväksytyt, hylätyt ja korvatuiksi tulleet päätökset;
- tehtävässä käytetään soveltuvaa voimassa olevaa ADR:ää sen sijaan, että sama päätös tehtäisiin uudestaan;
- korvattu päätös linkitetään seuraajaansa, mutta alkuperäistä perustelua ei kirjoiteta jälkikäteen uusiksi;
- testien läpäisy ei yksinään tarkoita, että ADR olisi hyväksytty.
Jos vanhoja tiedostoja siirretään, samalla pitää päivittää todelliset viittaukset, reititys ja käyttöoikeusrajaukset. Pelkkä tiedostojen siirtäminen ei riitä.
4. Suunnitelmat samaan hakemistoon, mutta jäädyttäminen erilleen valmistumisesta
plans/-hakemisto voi olla yksitasoinen. Pienelle määrälle vanhoja suunnitelmia ei tarvitse tehdä alihakemistoja vain rakenteen vuoksi. Mahdollinen nimeämismalli voisi olla:
| Tarkoitus | Ehdotettu tiedosto | Merkitys |
|---|---|---|
| Aktiivinen suunnitelma | plans/pending_implementation_plan.md |
Oletusarvoinen ja ainoa aktiivinen sisääntulopiste |
| Valmis suunnitelma | plans/plan-20261022-example-id.md |
Valmis ja arkistointiin hyväksytty |
| Keskeneräisenä jäädytetty suunnitelma | plans/plan-20261022-example-id-frozen.md |
Keskeneräiset tehtävät säilyvät, mutta suunnitelmaa ei oletusarvoisesti jatketa |
Jäädyttäminen ei vaadi uutta hakemistoa tai välitöntä uutta tilaa. Nykyinen tarkistin tukee jo taukotilaa; sitä voi käyttää, kun jäädytettyyn tiedostoon kirjataan tauon syy, jäljellä olevat tehtävät ja jatkamisen ehdot.
Ero on tärkeä:
- Valmis ja arkistoitu: vaaditut hyväksymisehdot täyttyvät ja arkistointiin on saatu lupa.
- Jäädytetty: suunnitelma poistuu aktiivisesta työjonosta, mutta sitä ei merkitä valmiiksi. Vahvistamattomat ehdotukset eivät muutu tosiasioiksi.
- Hylätty: kirjataan, ettei työtä toteuteta ja mitä seurauksia päätöksellä on. Pelkkä “toistaiseksi tauolla” ei tarkoita hylkäämistä. Virallinen lopetustila vaatisi erillisen sopimusmuutoksen.
Oletuksena luetaan vain aktiivinen suunnitelma eikä kaikkia hakemiston historiallisia tiedostoja. Vanhaan suunnitelmaan palataan, kun palauttamista tai historiaa erikseen tarvitaan. Jäädytetyn työn uudelleen käynnistäminen edellyttää uutta lupaa, alkuperäiseen suunnitelmaan linkitettyä toteutusversiota ja uusia tarkistuksia. Vanhaa hyväksyntää ei voi siirtää sellaisenaan uuteen tilanteeseen. Tämä vastaa nykyisiä elinkaarisääntöjä.
Tiedoston uudelleennimeäminen on tallennustoimi, ei todiste hyväksymisehtojen täyttymisestä. Yliajaminen pitää estää, keskeneräiset asiat säilyttää ja viittaukset käsitellä. Aktiivista suunnitelmatiedostoa ei myöskään pidä luoda väkisin tyhjänä vain siksi, että kiinteä polku olisi olemassa.
5. Testien ja koodin välinen kartta on moni-moneen-suhde
Yksi kooditiedosto yhtä testitiedostoa kohti ei ole hyvä yleissääntö. Testi voi kattaa useita komponentteja, ja yksi komponentti voi tarvita yksikkö-, ominaisuus- ja integraatiotestejä.
Aloita mieluummin näin:
- järjestä
tests/-hakemisto moduulien tai vastuualueiden mukaan; - kirjaa vastaavaan speksiin tärkeimmät invariantit, olennaiset testit ja rajatut tarkistuskomennot;
- lisää erillinen
tests/test-map.yamlvasta, jos yhteyksien löytäminen on muuten aidosti vaikeaa.
Mahdolliseen karttaan riittävät moduulin tai sopimuksen tunniste, lähdekoodin alue, testien alue ja käytettävä tarkistuskomento. Koko hakemistorakennetta ei kannata kopioida eikä testien tilaa ylläpitää toisessa, helposti vanhentuvassa luettelossa.
Kartta on hyödyllinen vain, jos sen polut ja komennot pysyvät voimassa. Kartan olemassaolo ei todista testikattavuutta eikä sitä, että testit ovat läpäisseet.
6. Väliaikainen aineisto omaan paikkaan, mutta ei summittaisesti roskiin
Kertaluonteiset luonnokset, tilapäiset skriptit ja tutkimusraportit voi koota .scratch/-hakemistoon. Niitä ei kuitenkaan pidä käsitellä automaattisesti epäluotettavina tai aina turvallisesti poistettavina vain sijaintinsa perusteella.
- Mallin tekemä tutkimusyhteenveto on toisen käden tulkintaa, eikä sitä pidä käsitellä itsenäisenä faktana.
- Alkuperäinen testituloste tai todellinen diagnostiikkatietue voi olla ensikäden näyttöä myös väliaikaisessa hakemistossa. Sen luotettavuus riippuu muun muassa lähteestä, ympäristöstä, ajankohdasta ja tallenteen täydellisyydestä.
- Aineistoa ei pidä poistaa, jos se on ainoa näyttö, johon keskeneräinen suunnitelma, päätös tai hyväksyntä nojaa. Ennen siivousta tärkeä alkuperäisaineisto säilytetään tai siihen nojaava päätelmä perutaan selvästi.
- Keskeisistä havainnoista säilytetään näyttöön johtavat viitteet, soveltamisala ja avoimet kysymykset. Tiivistäminen ei saa muuttaa oletusta faktaksi.
Myös docs/-hakemiston vanhoille raporteille ja arkkitehtuurikaavioille kannattaa erottaa kolme luokkaa: nykyiset ylläpidettävät dokumentit, selvästi historialliset aineistot ja tarkistusta odottavat materiaalit. Vanhuus ei yksin ole syy hävittää aineistoa.
Nykyinen dokumentti kertoo soveltamisalansa ja tarkistetaan asiaan liittyvän sopimuksen muuttuessa. Vanhentunut kaavio tai hylätty ehdotus merkitään historialliseksi, vanhentuneeksi tai korvatuksi, eikä sitä käytetä oletusarvoisena nykytilan kuvauksena. Prosessiaineiston, jolla ei ole pitkäaikaista arvoa eikä riippuvaisia viittauksia, voi siirtää väliaikaiseen tilaan tai poistaa hyväksynnän jälkeen.
Säilyttäminen ja oletuksena lukeminen ovat eri asioita. Tarpeellinen historia voidaan pitää tallessa ilman, että se ladataan jokaisella työvuorolla. Kontekstin rajaamiseen sopivat rajattu tiedonhaku ja selkeät voimassaolomerkinnät paremmin kuin näytön hävittäminen.
Yhteenveto: rakenne palvelee työtä, ei päinvastoin
Ehdotettu rakenne on käyttökelpoinen, kun siihen liitetään neljä rajaa: testit keskitetään mahdollisuuksien mukaan mutta kielikohtaiset poikkeukset sallitaan; speksit kuvaavat nykyisiä sopimuksia eivätkä kertaa kaikkia ADR:iä; keskeneräisen työn jäädyttäminen ei tarkoita valmistumista; eikä väliaikaisen aineiston siivous saa tuhota ainoaa tarpeellista näyttöä.
Projektin nykyinen oletussuunnitelman polku ja sallitut hakemistot sekä analyysitilan muokkausrajat viittaavat edelleen vanhaan rakenteeseen. Mahdollinen siirtymä edellyttää myös sääntöjen, mallien, viittausten, tarkistinten ja käyttöympäristön päivitystä. Hakemiston uudelleennimeäminen ei yksin muuta käytäntöä voimaan. Tässä tarkastelussa ei ole kirjoitettu, siirretty, jäädytetty eikä siivottu mitään projektin aineistoa.
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 "Testit, speksit ja ADR:t: selkeämpi projektirakenne ilman turhaa jäykkyyttä"?
Keskitä testit oletuksena tests/ hakemistoon, mutta jätä Go koodin valkoisen laatikon testit tarvittaessa samaan pakettiin kuin testattava koodi.
What are the key points to validate first?
Keskitä testit oletuksena tests/ hakemistoon, mutta jätä Go koodin valkoisen laatikon testit tarvittaessa samaan pakettiin kuin testattava koodi. Pidä nykyiset vaatimukset ja sopimukset spekseissä, arkkitehtuurivalintojen perustelut ADR:issä ja yleiset työohjeet omana tasonaan.
What should I do next in practice?
Erota valmiiksi arkistoitu suunnitelma keskeneräisenä jäädytetystä: jäädyttäminen ei todista työn valmistumista.