Document → Spec → Develop → Audit

Brownfield-kehityksessä tarvitaan kurinalainen prosessi. AGENTS.md määrittelee neljä vaihetta, joita toistetaan jokaisessa muutoksessa. Tämä oppitunti käsittelee koko prosessin yksityiskohtaisesti.

4-vaiheinen prosessisilmukka

DSDA-prosessi

Document → Spec → Develop → Audit on iteratiivinen prosessi, jossa jokainen muutos kulkee neljän vaiheen läpi. Dokumentointi luo pohjan, speksi määrittelee muutoksen, kehitys toteuttaa sen TDD:llä, ja auditointi varmistaa laadun. Tätä silmukkaa toistetaan jokaisessa ominaisuudessa.

Prosessisilmukkatext

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  DOCUMENT   │───▶│    SPEC     │───▶│   DEVELOP   │───▶│    AUDIT    │
│             │    │             │    │             │    │             │
│ Skannaa vs  │    │ Luo         │    │ TDD: Red →  │    │ 6-kierroksen│
│ suunnittele,│    │ perusteltu  │    │ Green →     │    │ katselmointi│
│ generoi     │    │ speksi + AC │    │ Refactor    │    │ + portit    │
│ 3-tasoinen  │    │             │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
     │                  │                  │                  │
     ▼                  ▼                  ▼                  ▼
 tutkimus +          speksi            tdd +             katselmointi +
 dokumentaatio      workflow          kehitys            auditointi

Vaihe 1: DOCUMENT

Ensimmäinen vaihe on ymmärtäminen ja dokumentointi. Ennen kuin kirjoitat riviäkään koodia, sinun pitää tietää mitä muutat.

Dokumentointiagentin tehtävät

Lue olemassa oleva dokumentaatio (content-plan.md)
Skannaa tiedostojärjestelmä vs. suunnitelma
Generoi tai päivitä 3-tasoinen dokumentaatio
Päivitä content-plan.md

Dokumentointiagentin säännötmarkdown

Role: Documentation Agent

Can:
- Read all source code
- Write to docs/ directory only
- Run read-only analysis commands

Cannot:
- Edit source code
- Modify tests
- Run destructive commands

Output: Scan report + updated docs

Vaihe 2: SPEC

Dokumentoinnin jälkeen kirjoitat perustellun speksin. Perusteltu tarkoittaa, että jokainen päätös viittaa todelliseen dokumentaatioon.

Speksiagentin tehtävät

Tutki dokumentaatio (pohjustus)
Luo speksi pohjasta
Täytä AC:t, tiedostot, riskit, testit
Aja valmiustarkistuslista

Speksiagentin säännötmarkdown

Role: Spec Agent

Can:
- Read docs and source code
- Write to specs/ directory

Cannot:
- Implement code
- Run tests
- Modify source files

Output: Grounded spec ready for development

Pro-vinkki

Perusteltu speksi eroaa perustelemattomasta yhdellä tavalla: jokainen väite on jäljitettävissä todelliseen koodiin tai dokumentaatioon. "Lisää välimuisti API:iin" on perustelematon — "Lisää välimuisti GET /api/users endpointiin (ks. docs/subsystems/api/)" on perusteltu.

Vaihe 3: DEVELOP

Kehitys seuraa TDD-sykliä: Red → Green → Refactor. Speksin AC:t ohjaavat testejä.

Prosessi

Valitse seuraava AC speksistä
Kirjoita failaava testi (Red)
Toteuta minimikoodi (Green)
Refaktoroi (testien suojassa)
Toista seuraavalle AC:lle

Vaihe 4: AUDIT

Auditointi on laadunvarmistuksen vaihe. Se koostuu 6 kierroksesta.

6-kierroksen katselmointi

Kierros	Fokus	Kysymys
1	Speksien noudattaminen	Täyttyvätkö kaikki AC:t?
2	Testikattavuus	Onko jokaiselle AC:lle testi?
3	Turvallisuus	Input-validointi, autentikointi, salaisuudet?
4	Arkkitehtuuri	Noudatetaanko malleja ja riippuvuussääntöjä?
5	Suorituskyky	Kyselyt, välimuisti, bundle-koko?
6	Tuomio	HYVÄKSY / PYYDÄ MUUTOKSIA / ESTÄ

Auditointiportti

Auditointiportti on viimeinen tarkistuspiste ennen kuin muutos hyväksytään. Se varmistaa, että kaikki AC:t täyttyvät, testit ovat kattavat, turvallisuus on huomioitu ja arkkitehtuuri noudattaa projektimalleja. Portti on joko PASS tai FAIL — ei "melkein valmis".

Katselmoijan säännötmarkdown

Role: Review Agent

Can:
- Read everything
- Write review reports

Cannot:
- Modify implementation code
- Skip audit passes

Output: Review report + PASS/FAIL verdict

Agenttien vastuunjako

Kriittinen periaate: yksi agentti, yksi vastuu.

Agentti	Saa tehdä	Ei saa tehdä
Dokumentointiagentti	Lukea koodia, kirjoittaa dokumentteja	Muokata koodia
Speksiagentti	Lukea dokumentteja, kirjoittaa speksejä	Toteuttaa koodia
Kehitysagentti	Toteuttaa koodia, kirjoittaa testejä	Ohittaa speksiä
Katselmointiagentti	Lukea kaikkea, kirjoittaa raportteja	Muokata toteutusta

Tietovisa

Miksi DSDA-prosessissa dokumentointi tulee ENNEN speksiä?

Suorita DSDA-sykli

Valitse pieni muutos olemassa olevaan projektiin ja suorita koko DSDA-sykli: 1) Dokumentoi muutettava alue (1 sivu), 2) Kirjoita perusteltu speksi (viittaa dokumentaatioosi), 3) Toteuta TDD:llä, 4) Auditoi 6-kierroksen mallilla. Kirjaa ylös kuinka kauan kukin vaihe kesti.

Yhteenveto

DSDA on 4-vaiheinen silmukka: Document → Spec → Develop → Audit
Jokainen vaihe on oma agentin vastuualue
Dokumentointi perustaa speksin todellisuuteen
Auditointi on 6-kierroksen laadunvarmistus
Seuraavaksi opimme 3-tasoisen dokumentaatiorakenteen