Tehdasroolit ja politiikat

Edellisessä oppitunnissa opimme tehtaan rakenteen. Nyt opimme avaintekijän: sama backend, eri politiikka → eri käyttäytyminen. Tehtaat ovat politiikkoja, eivät pelkkiä prompteja.

Politiikka = rooli

Tehdasrooli

Tehdasrooli on politiikka, joka määrittelee mitä agentti saa tehdä, mitä tulosmuotoa odotetaan ja mitkä rajoitteet pätevät. Sama LLM-backend tuottaa radikaalisti erilaista tulosta eri roolilla — analysoija tutkii, suunnittelija suunnittelee, korjaaja korjaa.

Periaate: Tehtaat ovat politiikkoja, eivät vain prompteja. Rooli määrittelee mitä agentti saa tehdä, mitä tulosmuotoa odotetaan ja mitkä rajoitteet pätevät.

Neljä perusroolia

1. Analysoija (Analyzer)

Tehtävä: Tutkii ja raportoi
Oikeudet: Vain luku
Tuotos: Löydökset ja suositukset

Analysoija-roolin politiikkapython

ANALYZER_POLICY = {
  "role": "analyzer",
  "system_prompt": """You are a code analyzer.
Your job is to examine code and report findings.

Rules:
- READ ONLY — never modify any files
- Report findings in structured format
- Prioritize: Critical > High > Medium > Low
- Include file paths and line numbers
- Suggest fixes but don't implement them""",

  "allowed_tools": ["read_file", "search_files", "git_log"],
  "blocked_tools": ["write_file", "run_command"],
  "output_format": "findings_report",
}

2. Suunnittelija (Planner)

Tehtävä: Luo toteuttamiskelpoinen suunnitelma
Oikeudet: Luku + suunnitelman kirjoitus
Tuotos: Vaiheittainen suunnitelma

Suunnittelija-roolin politiikkapython

PLANNER_POLICY = {
  "role": "planner",
  "system_prompt": """You are a planning agent.
Your job is to create step-by-step implementation plans.

Rules:
- Analyze the codebase before planning
- Break the goal into concrete steps
- Identify files to create/modify
- Estimate complexity per step
- List risks and mitigations
- Output a numbered plan, not code""",

  "allowed_tools": ["read_file", "search_files", "git_log"],
  "blocked_tools": ["write_file", "run_command"],
  "output_format": "implementation_plan",
}

3. Korjaaja (Fixer)

Tehtävä: Tekee kohdennettuja muutoksia
Oikeudet: Luku + kirjoitus
Tuotos: Korjattu koodi

Korjaaja-roolin politiikkapython

FIXER_POLICY = {
  "role": "fixer",
  "system_prompt": """You are a code fixer.
Your job is to make targeted changes to resolve issues.

Rules:
- Make minimal, focused changes
- Don't refactor unrelated code
- Write tests for every fix
- Verify fixes by running tests
- Explain what you changed and why""",

  "allowed_tools": ["read_file", "write_file", "run_command",
                    "search_files"],
  "blocked_tools": [],  # Full access, with guardrails
  "output_format": "fix_report",
}

4. Katselmoija (Reviewer)

Tehtävä: Arvioi muutoksen laatua
Oikeudet: Vain luku
Tuotos: Katselmointiraportti + tuomio

Katselmoija-roolin politiikkapython

REVIEWER_POLICY = {
  "role": "reviewer",
  "system_prompt": """You are a code reviewer.
Your job is to evaluate changes against criteria.

Rules:
- Run the 6-pass review (spec, tests, security,
architecture, performance, verdict)
- Never modify code
- Provide actionable feedback
- Give clear verdict: APPROVE / REQUEST_CHANGES / BLOCK""",

  "allowed_tools": ["read_file", "search_files",
                    "run_command"],  # read + test only
  "blocked_tools": ["write_file"],
  "output_format": "review_report",
}

Roolien orkestraatio

Tehtaassa roolit ketjutetaan:

Roolien ketjutext

Tehtävä sisään
→ Analyzer: "Mitä pitää tutkia?"
    → Findings report
→ Planner: "Miten toteutetaan?"
    → Implementation plan
→ Fixer: "Toteuta suunnitelma"
    → Code changes + tests
→ Reviewer: "Onko laatu riittävä?"
    → APPROVE → Julkaise
    → REQUEST_CHANGES → Takaisin Fixerille

Pro-vinkki

Roolien teho tulee rajoituksista, ei vapaudesta. Analysoija joka ei voi muokata koodia tuottaa objektiivisemman raportin. Korjaaja joka ei voi katsella koko koodikantaa tekee kohdennettuja muutoksia. Rajoitukset ovat ominaisuus, eivät haitta.

Sessio ja jatkuvuus

Tehdas voi myös jatkaa aiempaa sessiota:

Session resumepython

# Aloita uusi sessio
session = factory.start(
  role="analyzer",
  task="Inspect the authentication flow"
)
# → session_id: "abc123"

# Jatka samaa sessiota
factory.resume(
  session_id="abc123",
  task="Now propose fixes for the issues found"
)
# Agentti muistaa aiemmat löydökset

Milloin aloittaa uusi vs. jatkaa?

Tilanne	Valinta
Uusi tehtävä, uusi konteksti	Uusi sessio
Saman tehtävän jatko	Resume
Eri rooli, sama aihe	Uusi sessio + kontekstin siirto
Virheen korjaus aiemmasta	Resume

Session state

Session state on tehtaan "muisti" — mitä on tehty, mitä löydetty, mitkä päätökset on tehty. Se mahdollistaa työn jatkamisen keskeytyksestä ja kontekstin siirtämisen roolien välillä. Hyvä session state sisältää vain oleellisen — ei kaikkea.

Tietovisa

Miksi sama AI-backend tuottaa eri tuloksia eri roolilla?

Suunnittele oma tehdasroolikatalogi

Suunnittele 3–4 roolia omalle projektillesi: 1) Nimi ja vastuu, 2) Sallitut ja estetyt työkalut, 3) Tulosmuoto, 4) System prompt (lyhennelmä). Mieti miten roolit ketjutetaan tyypillisessä tehtävässä.

Yhteenveto

Tehdasroolit ovat politiikkoja: sama backend, eri käyttäytyminen
Neljä perusroolia: analysoija, suunnittelija, korjaaja, katselmoija
Roolien rajoitukset tuottavat parempaa laatua
Session state mahdollistaa jatkuvuuden roolien välillä
Seuraavaksi opimme speksilähtöiset automaattiset toimitussilmukat