Factory-arkkitehtuuri — 7 kerrosta

Tehdas ei ole "yksi iso prompt". Se on orkestroitu pipeline, jolla on selkeät vastuukerrokset. Tunnetaan rakenne — voit suunnitella, debuggata ja skaalata sitä.

7 kerrosta

┌──────────────────────────────────────────────────────────┐
│ 7. Integration       │ CI/CD, repot, issue trackers       │
├──────────────────────────────────────────────────────────┤
│ 6. Observability     │ Lokit, traces, kustannusseuranta   │
├──────────────────────────────────────────────────────────┤
│ 5. Validation        │ Testit, hookit, hyväksyntäportit   │
│    & Guardrails      │                                    │
├──────────────────────────────────────────────────────────┤
│ 4. Memory & Context  │ RAG, session state, learnings      │
├──────────────────────────────────────────────────────────┤
│ 3. Tools & Execution │ CLI, MCP, APIt, sandboxit          │
├──────────────────────────────────────────────────────────┤
│ 2. Agent Layer       │ Planner, Builder, Reviewer ...     │
├──────────────────────────────────────────────────────────┤
│ 1. Orchestration     │ Spec intake, routing, loops        │
└──────────────────────────────────────────────────────────┘

Mappi sessioihin

Kerros	Mitä se tekee	Missä sessio se opittiin
7. Integration	Yhteys CI/CD:hen, GitHubiin, Lineariin, Slackiin	Sessio 4 (uusi)
6. Observability	Mittaa: kustannus, latenssi, success rate, decisions	Sessio 4 (uusi)
5. Validation & Guardrails	Testit, lintit, blocked patterns, hyväksyntäportit	Sessio 1 (TDD), Sessio 3 (guardrails)
4. Memory & Context	Working / episodic / RAG-knowledge	Sessio 3 (RAG, muisti)
3. Tools & Execution	CLI vs MCP, sandbox-suoritus	Sessio 3 (tools)
2. Agent Layer	Roolit: planner, builder, reviewer	Sessio 2 (sub-agents), Sessio 3 (full agents)
1. Orchestration	Spec intake, routing, loop control	Sessio 4 (uusi)

Kerros 1: Orchestration — uusi taso

Tämä on tehtaan "äiti-prosessi". Se päättää:

Mikä spec tulee sisään? (intake — käyttäjä, ticket, automation trigger)
Mikä agentti hoitaa? (routing — analyzer? planner? builder?)
Milloin lopetaan? (loop control — max-iteraatiot, success criteria)

Orchestration layer

Orchestration-kerros on tehtaan single source of truth: kaikki agentit raportoivat sille, kaikki päätökset menevät sen läpi. Ilman tätä kerrosta saat bag-of-agents -antipatternin: agentit konfliktoivat, duplikoivat työtä, kukaan ei tiedä kuka on vastuussa.

Esimerkki: minimaalinen orchestratorpython

class FactoryOrchestrator:
  def __init__(self, spec_path: str):
      self.spec = load_spec(spec_path)
      self.agents = {
          "analyzer": AnalyzerAgent(allowed_tools=["read", "grep"]),
          "planner":  PlannerAgent(allowed_tools=["read", "grep"]),
          "builder":  BuilderAgent(allowed_tools=["read", "edit", "bash"]),
          "reviewer": ReviewerAgent(allowed_tools=["read"]),
      }
      self.max_iterations = self.spec.get("max_iterations", 5)

  def run(self) -> dict:
      # Routing — orchestrator päättää järjestyksen
      analysis = self.agents["analyzer"].run(self.spec)
      plan     = self.agents["planner"].run(self.spec, analysis)

      for i in range(self.max_iterations):
          implementation = self.agents["builder"].run(plan)
          verdict        = self.agents["reviewer"].run(implementation, self.spec)

          if verdict["status"] == "approved":
              return {"status": "success", "iterations": i + 1}
          plan = self._adjust_plan(plan, verdict)

      return {"status": "max_iterations_exceeded"}

Kerros 6: Observability — uusi taso

Mitä et mittaa, et voi parantaa. Factoryn observability on välttämätön — ei "nice to have".

Mitä mitataan

Metriikka	Miksi
Cost per run ($)	Paljastaa agentin liikakulutuksen heti
Wall-time per run (s)	Käyttökokemus + ROI
Success rate (%)	Lähtee kontrollista hiljaa
Iterations to converge	Spec-laatu — paljon iteraatioita = huono spec
Decision trace	Compliance + debuggaus
Tool usage histogram	Mikä tool maksaa, mikä epäonnistuu

Esimerkki: structured log per iterationjson

{
"run_id": "run_2026-05-01T10:23:45_abc123",
"iteration": 3,
"agent": "builder",
"timestamp_ms": 1714553025123,
"decision": "edit_file",
"rationale": "Added timeout to fetch() per spec AC2",
"tool_call": {
  "name": "edit",
  "args": {"path": "src/api.ts", "diff_size": 42}
},
"tokens_in": 1284,
"tokens_out": 312,
"cost_usd": 0.0089,
"duration_ms": 1872
}

Pro tip

Tee structured logging päivänä 1. Älä lisää sitä jälkikäteen — se on aina liian myöhäistä. Kun bugi ilmenee tuotannossa, et halua arvuutella, mitä agentti teki — haluat grep-yhtä JSON-loki-rivistöstä.

Kerros 7: Integration — uusi taso

Tehdas elää siellä missä työ tapahtuu: Github, Slack, Linear, CI/CD.

Integraatio	Mitä se mahdollistaa
GitHub webhook → factory	PR open → factory ajetaan → status check
Slack /factory command	Käyttäjä laukaisee factoryn chatistä
Linear webhook → factory	Issue assigned → factory analyysoi + ehdottaa fixiä
CI/CD → factory	Failing build → factory triagaa ennen kuin developer herää

Factory on tuottava vain kun se istuu työnkulussa. Erillinen "AI-työkalu" jota pitää muistaa avata = ei käytetä.

Quick check — Mitä jo rakensit?

Quiz

Mihin kerrokseen Sessio 3:n RAG-memory-skill kuuluu?

Quiz

Tiimisi PR-katselmointi-agentti palauttaa joskus eri verdiktin samalle PR:lle eri ajoilla. Mikä kerros ratkaisee tämän?

Yhteenveto

🏗️ Factory on 7 kerrosta, ei "yksi prompt"
🆕 Sessio 4 lisää 3 uutta: Orchestration, Observability, Integration
📊 Observability ennen tuotantoa — ei jälkikäteen
🔌 Integration sinne missä työ tapahtuu — älä rakenna erillistä "AI-portaalia"
✅ Aiemmat sessiot rakensivat keskimmäiset kerrokset (2–5)

Seuraavassa oppitunnissa: Roolit ja policyt — miten sama backend tuottaa eri käyttäytymistä ja miksi se on factoryn säätimen ydin.