Perusteltu speksilähtöinen kehitys

Moduulissa 1 opit kirjoittamaan speksejä. Nyt opit tekemään niistä perusteltuja — jokaisella väitteellä on lähde todellisessa dokumentaatiossa tai koodissa.

Perusteltu vs. perustelematon

Perusteltu speksi

Perusteltu speksi (grounded spec) on muutosdokumentti, jossa jokainen väite, riippuvuus ja riskiarvio viittaa todelliseen dokumentaatioon tai lähdekoodiin. Se ei perustu oletuksiin, muistiin tai arvauksiin vaan konkreettiseen näyttöön koodikannasta.

Perustelematon speksi	Perusteltu speksi
"Lisää välimuisti API:iin"	Konteksti: ks. `docs/subsystems/api/`
Ei viittauksia, ei dokumentaatiota	AC:t Given-When-Then -muodossa
AI keksii mielikuvituksesta	Tiedostot: tarkat polut listattuna
	Riski: vaikuttaa X-serialisointiin
	Testit: yksikkö + integraatio
	Dokumentaatio: linkit T1, T2, T3

Perustellun speksin rakenne

Perusteltu speksipohjamarkdown

# Feature: [Nimi]

## Yleiskatsaus
- Status: Draft | Review | Approved
- Alajärjestelmät: [lista T2-linkeillä]
- Protokollamuutos: Kyllä/Ei

## Ongelma
[Mikä ongelma? Miksi tarvitaan?]
Viite: [T1/T2-dokumentti joka kuvaa nykytilan]

## Nykyinen käyttäytyminen
[Viittaus T2/T3-dokumentteihin — mitä nykyinen koodi tekee]
Ks. @file lib/api/users.ts rivit 45-67

## Ehdotettu muutos
[Mitä muuttuu ja miksi]

## Hyväksymiskriteerit

### AC1: [Kuvaava nimi]
**Given** [esiehto viitaten nykyiseen käyttäytymiseen]
**When** [toiminto]
**Then** [odotettu tulos]
**Perusteltu:** [T2/T3-linkki tai koodiviite]

### AC2: [Kuvaava nimi]
...

## Tiedostot
| Paketti | Tiedosto | Muutos | Viite |
|---------|----------|--------|-------|
| lib | api/users.ts | Muokkaa query | T3: api-users.md |
| app | api/users/route.ts | Lisää caching | T2: api.md |

## Riskiarvio
- Mikä voi rikkoutua: [viittaa riippuvuuskaavioon T2:ssa]
- Suorituskykyvaikutus: [mittarit jos saatavilla]
- Rollback-suunnitelma: [miten perutaan]

## Testausstrategia
- Yksikkötestit: [komponentit viitaten T3:een]
- Integraatiotestit: [virtaukset viitaten T2:een]
- Kattavuustavoite: [%]

## Liittyvä dokumentaatio (PAKOLLINEN)
- T1: [linkki]
- T2: [linkki]
- T3: [linkki]

Perustelutyypit

1. Koodiviite

Ks. @file lib/users/profile.ts:45-67 — nykyinen validointilogiikka

2. Dokumentaatioviite

Ks. docs/subsystems/auth/ — autentikointivirtaus

3. Testiperusteltu

Nykyinen käyttäytyminen vahvistettu testissä:
@file __tests__/users/profile.test.ts — "should validate email"

4. Dataperusteltu

Tietokanta: guilds-taulussa on 4 riviä, joista 2 on visibility='private'
Ks. migration 20250125000001_guild_config_columns.sql

Pro-vinkki

Jos et löydä perustelua väitteelle, se on joko väärä tai dokumentaatio puuttuu. Palaa DOCUMENT-vaiheeseen ja täydennä dokumentaatio ennen kuin jatkat speksiin.

Valmiustarkistuslista

Ennen kuin speksi on valmis toteutettavaksi:

Jokainen AC on testattavissa
Tiedostolista on realistinen ja polut oikein
Riskiarvio viittaa todellisiin riippuvuuksiin
Testausstrategia kattaa kaikki AC:t
Kaikki 3 tasoa dokumentoitu (T1, T2, T3 linkit)
Jokainen AC:n Given-ehto viittaa todelliseen tilaan
Rollback-suunnitelma on realistinen

AI speksiagenttina

Speksiagentti on AI-rooli, jolla on selkeät rajat:

Saa	Ei saa
Lukea koodia	Muokata koodia
Lukea dokumentaatiota	Ajaa testejä
Kirjoittaa speksejä	Toteuttaa mitään
Ehdottaa tiedostolistaa	Muuttaa lähdekoodia

Tietovisa

Mikä tekee speksistä 'perustellun' (grounded)?

Muunna perustelematon speksi perustelluksi

Ota tämä perustelematon speksi ja tee siitä perusteltu: 'Lisää dark mode -tuki sovellukseen. Käyttäjä voi vaihtaa teeman. Tallenna valinta.' Lisää: 1) Viittaukset todellisiin tiedostoihin, 2) Given-When-Then AC:t, 3) Tiedostolista, 4) Riskiarvio.

Yhteenveto

Perusteltu speksi viittaa aina todelliseen tietoon — ei oletuksiin
Neljä perustelutyyppiä: koodiviite, dokumentaatio, testi, data
Jos perustelua ei löydy, palaa dokumentointivaiheeseen
Valmiustarkistuslista estää keskeneräisten speksien etenemisen
Seuraavaksi opimme katselmoinnin, auditoinnin ja korjaustyönkulun