Tehtaan anatomia

Jokainen ohjelmistotehdas koostuu viidestä kerroksesta: syötteet, pipeline, portit, tuotokset ja oppimiset. Tämä oppitunti käsittelee kunkin kerroksen yksityiskohtaisesti.

Viisi kerrosta

Tehtaan kerrosrakenne

Ohjelmistotehtaan viisi kerrosta ovat: Intake (vastaanotta tehtävä ja rajoitteet), Execution (suorittaa agenttien ja työkalujen kautta), Control (valvoo turvallisuutta ja laatua), Output (tuottaa artefaktit) ja Feedback (kerää oppimiset ja parantaa prosessia).

Tehtaan kerroksettext

Intake (tehtävä/speksi)
→ Planning agent (suunnittelu)
→ Build agent (toteutus)
→ Test/review agent (testaus ja katselmointi)
→ Verification gates (portit ja politiikat)
→ Release artifact (julkaisuartefakti)
→ Retro + learnings (oppimiset)

Kerros 1: Intake — Vastaanotto

Intake-kerros määrittelee mitä tehdas tekee:

Elementti	Kuvaus
Tavoite	Mitä pitää saavuttaa
Rajoitteet	Mitä ei saa tehdä
Konteksti	Taustatieto ja dokumentaatio
Hyväksymiskriteerit	Milloin tavoite on täytetty

Intake-esimerkki (spec.json)json

{
"goal": "Add user authentication to the API",
"constraints": [
  "Use existing Supabase Auth",
  "Don't modify public API endpoints",
  "Maintain backward compatibility"
],
"acceptance_criteria": [
  "Authenticated endpoints return 401 without token",
  "Valid tokens grant access to protected endpoints",
  "All existing tests still pass"
],
"context": {
  "docs": ["docs/subsystems/auth/"],
  "related_code": ["lib/supabase/server.ts"]
}
}

Kerros 2: Execution — Suoritus

Suorituskerros sisältää itse agentit ja niiden työkalut:

Planning Agent

Lukee speksin ja kontekstin
Tuottaa suunnitelman vaiheittain
Tunnistaa riskit ja riippuvuudet

Build Agent

Toteuttaa suunnitelman
Käyttää koodaustyökaluja
TDD: testit ensin, sitten toteutus

Test/Review Agent

Ajaa testit
Tarkistaa koodin laadun
Suorittaa 6-kierroksen katselmoinnin

Pro-vinkki

Jokainen agentti suorituskerroksessa noudattaa samaa periaatetta: sillä on selkeä rooli, rajatut oikeudet ja määritelty tuotos. Tämä on suoraan moduulin 2 aliagenttiperiaatteen laajennus tehdaskontekstiin.

Kerros 3: Control — Valvonta

Valvontakerros estää huonon koodin pääsemästä läpi:

Portti	Tarkistus	Työkalu
Pre-commit hooks	Lint, formatointi	ESLint, Prettier
Testit	Yksikkö-, integraatio-	Vitest, Playwright
Tyyppitarkistus	TypeScript strict	tsc --noEmit
Turvallisuus	Riippuvuudet, salaisuudet	npm audit, trufflehog
Katselmointi	6-kierroksen review	AI Review Agent

spec.json portitjson

{
"checks": [
  {
    "name": "TypeScript",
    "command": "npx tsc --noEmit",
    "required": true
  },
  {
    "name": "Unit Tests",
    "command": "npm test",
    "required": true
  },
  {
    "name": "Lint",
    "command": "npm run lint",
    "required": true
  },
  {
    "name": "Build",
    "command": "npm run build",
    "required": true
  }
]
}

Kerros 4: Output — Tuotokset

Tehdas tuottaa standardoidut artefaktit:

Artefakti	Tyyppi	Tarkoitus
Koodi	.ts/.tsx tiedostot	Itse toteutus
Testit	.test.ts tiedostot	Laadunvarmistus
Dokumentaatio	.md tiedostot	Ymmärrettävyys
Katselmointi	review-report.md	Auditointipolku
Muutosloki	CHANGELOG.md	Muutoshistoria

Kerros 5: Feedback — Palaute

Palautekerros sulkee silmukan:

Retro-kysymykset

Mikä tuotti suurimman tuottavuushyödyn?
Missä AI loi riskin tai sekaannuksen?
Mitkä säännöt/hookit pitäisi standardoida?
Mitä pitäisi automatisoida seuraavaksi?

Tuotokset

Top 5 oivallusta
Top 3 politiikkamuutosta
Tiimin tehdas-playbookin päivitys

Tehtaan palautesilmukka

Palautesilmukka on se mikä erottaa tehtaan kertaluontoisesta prosessista. Jokaisen suorituksen jälkeen tehdas kerää tietoa: mikä toimi, mikä ei, mitä pitäisi muuttaa. Nämä oppimiset päivittävät tehtaan politiikkoja, parantaen seuraavaa suoritusta.

Kerrokset kokonaisuutena

Koko tehdastext

┌──────────────────────────────────────────────────┐
│                    INTAKE                         │
│  spec.json: goal, constraints, ACs, context       │
├──────────────────────────────────────────────────┤
│                   EXECUTION                       │
│  Planning → Building → Testing/Review             │
├──────────────────────────────────────────────────┤
│                    CONTROL                        │
│  Pre-commit → Tests → Types → Security → Review   │
├──────────────────────────────────────────────────┤
│                    OUTPUT                         │
│  Code + Tests + Docs + Review Report + Changelog  │
├──────────────────────────────────────────────────┤
│                   FEEDBACK                        │
│  Retro → Learnings → Policy Updates → Playbook    │
└──────────────────────────────────────────────────┘

Tietovisa

Mikä kerros erottaa ohjelmistotehtaan yksittäisestä agenttikäytöstä?

Suunnittele tehtaan portit

Suunnittele 5 laatuporttia omalle projektillesi. Jokaiselle portille määrittele: 1) Nimi, 2) Tarkistuskomento, 3) Onko pakollinen vai valinnainen, 4) Mitä tapahtuu jos portti ei mene läpi. Kirjoita spec.json-muotoinen konfiguraatio.

Yhteenveto

Tehtaan 5 kerrosta: Intake, Execution, Control, Output, Feedback
Intake vastaa "mitä", Execution "miten", Control "riittääkö laatu"
Portit estävät huonon koodin pääsemästä läpi
Feedback-kerros tekee tehtaasta itseään parantavan
Seuraavaksi opimme tehdasroolit ja politiikat