Brownfield-harjoitus: Suroi 114k LOC -koodikanta

Tässä harjoituksessa sovelletaan moduulin aikana oppimiasi tekniikoita: dokumentaatio, speksit, toteutus ja katselmointi.

Tehtävänanto

Valitse jokin seuraavista vaihtoehdoista:

Vaihtoehto A: Oma projekti

Jos sinulla on olemassa oleva projekti (työ- tai harrasteprojekti), tee siihen jokin seuraavista muutoksista:

1. Lisää uusi feature — Pieni, rajattu ominaisuus (esim. uusi API-endpoint, UI-komponentti)
2. Refaktoroi olemassa olevaa koodia — Paranna rakennetta ilman toiminnallisuusmuutoksia
3. Korjaa tekninen velka — Päivitä kirjasto, poista deprecated-koodi, paranna testausta

Vaihtoehto B: Harjoitusprojekti — Suroi

Käytä Suroi-koodikantaa, johon tutustuit jo Sessio 2:n harjoituksessa. Koodikanta on tuttu, joten pääset suoraan tekemään muutoksen — ilman että täytyy oppia uutta projektia.

git clone https://github.com/HasangerGames/suroi.git

Valitse pieni, rajattu muutos — esim. avoin issue, balanssimuutos, tai kompakti uusi feature alijärjestelmälle. Suroi on noin 114 000 riviä koodia, joten älä yritä lukea kaikkea — sovella sen sijaan dokumentointi → speksi → toteutus → audit -prosessia (alla). Käytä content-plan.md:tä ja repo-rakennetta orientoitumiseen.

Prosessi: Document → Spec → Develop → Audit

1. Dokumentoi nykytila (15 min)

Ennen kuin muutat mitään, dokumentoi:

# Nykytilan dokumentaatio

## Mitä koodi tekee nyt?
[Kuvaa lyhyesti nykyinen toiminnallisuus]

## Mikä on muutoksen tarkoitus?
[Miksi tämä muutos tehdään?]

## Mihin tiedostoihin muutos vaikuttaa?
[Listaa tiedostot ja moduulit]

## Mahdolliset riskit
[Mitä voi mennä pieleen?]

2. Kirjoita speksi (20 min)

Käytä speksipohjaa:

# Muutoksen speksi: [Otsikko]

## Tavoite
[Yksi lause, joka kuvaa, mitä halutaan saavuttaa]

## Hyväksymiskriteerit
- [ ] Kriteeri 1: [Testattava vaatimus]
- [ ] Kriteeri 2: [Testattava vaatimus]
- [ ] Kriteeri 3: [Testattava vaatimus]

## Toteutussuunnitelma
1. [Ensimmäinen askel]
2. [Toinen askel]
3. [Kolmas askel]

## Testisuunnitelma
- Yksikkötesti: [Mitä testataan]
- Integraatiotesti: [Mitä testataan]
- Manuaalinen testi: [Mitä tarkistetaan]

## Rajoitukset
- Ei muuteta: [Mihin EI kosketa]
- Ei toteuteta: [Mitä EI tehdä tässä vaiheessa]

3. Toteuta AI-avusteisesti (40 min)

Noudata TDD-sykliä:

1. Red: Kirjoita testi, joka epäonnistuu
2. Green: Toteuta minimaalinen ratkaisu testin läpäisemiseksi
3. Refactor: Paranna koodin rakennetta testien suojassa

Käytä AI-assistenttia speksin pohjalta:

@spec.md Toteuta tämä muutos. Aloita kirjoittamalla testit 
hyväksymiskriteerien perusteella.

4. Katselmoi ja auditoi (15 min)

Käy läpi 6-kohtainen katselmointi:

1. Speksin yhteensopivuus — Vastaako toteutus speksiä?
2. Testikattavuus — Onko kaikki hyväksymiskriteerit testattu?
3. Turvallisuus — Onko injektioita, vuotoja, kovakoodattuja salaisuuksia?
4. Arkkitehtuuri — Noudattaako koodi projektin rakenteita?
5. Suorituskyky — Onko ilmeisiä pullonkauloja?
6. Tuomio — PASS, MINOR_ISSUES vai REJECT?

Palautus

Kun olet valmis, lisää projektiin HARJOITUS.md-tiedosto:

# Brownfield-harjoitus: [Projektisi nimi]

## Muutoksen kuvaus
[Mitä teit]

## Dokumentaatio
[Linkki/polku dokumentaatioon]

## Speksi
[Linkki/polku speksiin]

## Diff/PR
[Linkki/polku muutoksiin]

## Katselmoinnin tulos
[PASS/MINOR_ISSUES/REJECT + perustelut]

## Oppimiset
[Mitä opit? Mikä oli vaikeaa? Mikä onnistui hyvin?]

Lisää projekti portfolioosi ja kirjoita lyhyt kuvaus prosessista.

Vinkkejä

• Aloita pienestä — Parempi tehdä pieni muutos hyvin kuin suuri huonosti
• Dokumentoi matkalla — Älä jätä dokumentointia viimeiseksi
• Kysy Aavalta — Mentori auttaa missä tahansa vaiheessa
• Vertaispalaute — Jaa työtäsi kilta-chatissa ja kysy palautetta

Arviointikriteerit

Onnea harjoitukseen! Muista, että tavoite on oppia prosessi — ei tehdä täydellistä koodia. 💪