Claude Code -aliagentit: rakenne, viisi roolia ja orkestrointi

Mikä Claude Coden aliagentti on, ja miksi se ei ole ”vain toinen Skill”?#

Claude Coden dokumentaatio määrittelee sen näin:

Yrittäjälle ymmärrettävillä termeillä: kuvittele kiinteistönvälitystoimisto. Siellä on johtaja, markkinoija, juristi ja myyntipäälliköitä. Yksi työntekijä, joka vaihtelee kaikkien näiden roolien välillä, ei ole tiimi vaan ylikuormittunut ihminen. Tiimi syntyy, kun jokaisella on oma kontekstinsa ja vastuualueensa, ja johtaja ainoastaan jakaa tehtävät ja kokoaa tulokset.

Claude Coden aliagentit toimivat samalla tavalla. Pääkeskustelu on johtaja. Aliagentti on rajattuun tehtävään erikoistunut asiantuntija, jolla on oma konteksti ja työkalut. Kun tehtävä vastaa asiantuntijan kuvausta, johtaja delegoi sen hänelle eikä juutu yksityiskohtiin.

Anthropicin aliagenteille rakentamat 5 käyttötarkoitusta

Anthropicin dokumentaatiossa luetellaan täsmälleen viisi syytä luoda oma aliagentti:

Tämän listan käytännöllisin kohta muille kuin ohjelmoijille on kustannusten hallinta. Voit lähettää vaativan tutkimustehtävän edulliselle Haiku-mallille ja jatkaa pääkeskustelua Sonnetilla tai Opuksella. Säästetyt tokenit ovat suoraan verrannollisia.

Tarkista sisäkkäisyyden tuki asennetusta versiostasi

Tämän oppaan mallit käyttävät yhtä pääistuntoa, joka delegoi suoraan työntekijöille. Älä käsittele vanhan dokumentaation lausetta ”aliagentit eivät voi käynnistää muita aliagentteja” ajattomana sääntönä. Sisäkkäisyys riippuu asennetusta versiosta ja sallituista työkaluista. Erillinen sisäkkäisten aliagenttien opas käsittelee versiokohtaista reseptiä. Varmista oman asennuksesi tuki ennen syvemmän delegoinnin suunnittelua.

Miten aliagentti eroaa Skillistä, vinoviivakomennosta ja Hookista?#

Aiemmassa Skillejä käsittelevässä oppaassa kerrotaan, että Skillit ja vinoviivakomennot ovat Claude Codessa käytännössä sulautuneet yhteen formaattiin. Aliagentti on kuitenkin eri asia – ei vain ”isompi Skill”.

Yhteenvetotaulukko neljästä mekanismista:

Englanninkieliseen oppaaseen sopii tämä ilmaus: Skillit ovat reseptejä, aliagentit erikoistuneita kollegoita.

Yksinkertaisesti sanottuna: skillit ovat reseptejä ja aliagentit erikoistuneita kollegoita.

Käytännössä tämä toimii näin: Skillit aktivoituvat automaattisesti, kun niiden kuvaus vastaa tehtävää, kun taas aliagentit kutsutaan nimenomaisesti – joko pääkeskustelu päättää delegoida tai sinä kutsut aliagentin nimeltä.

Päätöspuu: ”Minkä valitsen?”

Kun ajattelet: ”Haluan Clauden tekevän X:n”, käy läpi nämä neljä kysymystä:

1. Onko tämä tietoa, jonka pitäisi olla aina saatavilla? Esimerkiksi ”lokalisoimme käyttäjän haluamalle kielelle” tai ”emme käytä ajatusviivoja”. Lisää se tiedostoon CLAUDE.md.
2. Onko tämä menetelmä, jonka suoritat nyt käsin aina, kun se aktivoidaan? Esimerkiksi ”kirjoitan myyntiraportin joka maanantai”. Tee siitä Skill.
3. Kuluttaako tehtävä pääkeskustelun kontekstia vai voiko sen suorittaa rinnakkain? Esimerkiksi ”syvällinen tutkimus 30 lähteestä” tai ”tietoturvatarkastus samalla, kun kirjoitan uutta ominaisuutta”. Tee siitä aliagentti.
4. Tarvitsetko automaattisen vastauksen Claude Coden tapahtumaan? Esimerkiksi ”suorita linter jokaisen Edit-toiminnon jälkeen”. Kirjoita Hook.

90 % yrittäjän tehtävistä kuuluu kahteen ensimmäiseen luokkaan. Aliagentit ovat seuraavan tason työkalu tilanteisiin, joissa siirrytään ”yksi tehtävä kerrallaan” -työstä orkestrointiin.

Missä aliagentit sijaitsevat, ja mikä niistä on etusijalla?#

Aliagenttien hierarkiassa on viisi tasoa, järjestyksessä korkeimmasta etusijasta matalimpaan:

Etusijajärjestys toimii samalla tavalla kuin Skilleissä ja CLAUDE.md:ssä: organisaatio ohittaa CLI:n, CLI ohittaa projektin, projekti ohittaa henkilökohtaiset asetukset ja henkilökohtaiset asetukset ohittavat liitännäisen.

Mitä lataamisesta on hyvä tietää

Aliagentit latautuvat Claude Code -istunnon alkaessa. Jos muokkaat agenttitiedostoa käsin levyllä, muutokset tulevat käyttöön vasta istunnon uudelleenkäynnistyksen jälkeen. Vuorovaikutteisen /agents-käyttöliittymän kautta tehdyt muutokset tulevat voimaan heti.

Kullakin laajuustasolla on yksi aliagentti kutakin nimeä kohti eli yksi tiedosto. Jos .claude/agents/-kansiossa on code-reviewer.md ja toinen samanniminen tiedosto sen rinnalla (esimerkiksi vanhasta varmuuskopiosta), Claude Code ohittaa niistä toisen ääneti. Ilmoitusta ei tule.

Liitännäisten aliagentit ovat eri asia. Niihin liittyy tietoturvarajoituksia: ne eivät tue kenttiä hooks, mcpServers ja permissionMode. Tämä estää kolmannen osapuolen liitännäisen asentamisen niin, että se saisi luvan suorittaa koneellasi mielivaltaista koodia.

Aliagenttitiedoston rakenne: Frontmatter ja runko#

Virallisen dokumentaation minimaalinen esimerkki – vain 9 riviä:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Se riittää. Jos käyttäjä sanoo pääkeskustelussa ”tarkista PR:ni”, Claude yhdistää sanat ”reviewer / code / quality” kuvaukseen ja delegoi tehtävän aliagentille. Aliagentti lukee diff-muutokset, tuottaa kommentteja ja palauttaa pääkeskusteluun yhteenvedon. Pääkeskustelu ei täyty lokeista ja välianalyyseistä.

Frontmatter-skeema kokonaisuudessaan

Kenttä model: haiku on juuri listan viidennen tavoitteen mukainen ”kustannusten hallinta”. Jos sinulla on 50 dokumentaatiosivua lukeva tutkimusagentti, käytä siinä Haikua ja säästä 5–7 kertaa Opukseen verrattuna.

Kenttä isolation: worktree vastaa tärkeään ongelmaan: aliagentti tekee mahdollisesti vaarallisia muutoksia (uudelleenjärjestelyjä, migraatioita), mutta et halua sen koskevan työskentelykopiotasi. Aseta isolation: worktree, niin Claude Code luo tilapäisen git-kopion projektista; aliagentti työskentelee siellä ja palauttaa diffin tarkastettavaksi.

Tiedoston runko on järjestelmäkehote

Frontmatterin jälkeen tulee tavallista Markdownia – aliagentin järjestelmäkehote. Erityistä rakennetta ei vaadita, mutta tämä on hyväksi havaittu malli:

1. Kuka olet – yksi lause: ”olet koodin tarkastaja”, ”olet tietoturva-auditoija”, ”olet dokumentaation ylläpitäjä”.
2. Milloin sinut kutsutaan ja mitä teet ensin – ensimmäiset 2–3 toimenpidettä tehtävän vastaanottamisen jälkeen.
3. Tarkistuslista tarkistuksista tai vaiheista – 5–10 kohtaa, joita aliagentti noudattaa.
4. Mitä palautat – loppuraportin muoto. Tämä on ratkaisevan tärkeää: jos et määritä muotoa, aliagentti tuottaa ”esseen” rakenteisen yhteenvedon sijaan.
5. Mitä ET tee – selkeät rajoitukset. Ilman tätä osiota aliagentti alkaa improvisoida.

Pidä tiedoston runko 200–500 rivin mittaisena. Jos se pitenee, siirrä pitkät viitteet erillisiin lähellä sijaitseviin tiedostoihin ja linkitä niihin kehotteessa.

Miten kirjoittaa kuvaus niin, että Claude varmasti kutsuu aliagenttisi#

Yleinen ongelma on ottaa käyttöön koodintarkistukseen tarkoitettu aliagentti, mutta Claude tekee kaiken itse käyttämättä agenttia. Yleensä siihen on yksi syy: kuvaus on kirjoitettu muodossa ”Apuri koodintarkistukseen”. Claude ei ymmärrä, milloin se pitäisi aktivoida.

Tehokkaan kuvauksen kaava (3 osaa)

Osa 1 – mitä se tekee. Yksi lause tuloksesta, ei prosessista. Ei ”analysoi koodia”, vaan ”löytää koodin haavoittuvuudet ja palauttaa luettelon, jossa on niiden vakavuus ja korjaustapa”.

Osa 2 – milloin se aktivoidaan. 3–5 lainausmerkeissä olevaa fraasia, joilla käyttäjät todella pyytävät asioita. Älä arvaa – katso keskusteluhistoriaasi ja todellisia ilmaisuja.

Osa 3 – milloin sitä EI pidä aktivoida. 1–2 samankaltaista tehtävää, joihin aliagentin ei pitäisi vastata. Ilman tätä osiota kaksi samankaltaista agenttia ovat jatkuvasti ristiriidassa.

Taikasanat ”käytä ennakoivasti”

Anthropicin virallinen dokumentaatio antaa suoran suosituksen:

Toisin sanoen Claude ei oletusarvoisesti ole taipuvainen kutsumaan aliagenttia, jos kuvauksessa ei ole selkeitä merkkejä. Lisää ”käytä ennakoivasti” tai ”käytä heti koodin kirjoittamisen jälkeen”, niin aktivointi lisääntyy huomattavasti.

Vahva kuvaus näyttää tältä

description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code. Returns prioritized list of issues with severity
  and fix recommendations.
  Do not invoke for documentation changes, README edits, or commit
  message rewrites - these are handled by doc-maintainer.

Mikä tässä toimii:

• Verbit ”reviews” + ”returns” määrittelevät konkreettisen tuloksen, eivät prosessia.
• ”Proactively” ja ”immediately after” ovat selkeitä käynnistimiä.
• ”Do not invoke for...” sulkee pois ristiriidan samankaltaisen aliagentin kanssa.
• Englanti kuvauksessa on tavanomaista. Claude osaa yhdistellä asioita paremmin englanniksi.

5 valmista aliagenttiroolia, jotka toimivat 10 minuutissa#

Jokainen alla oleva rooli on yksi tiedosto, .claude/agents/<name>.md. Kun olet luonut tiedoston, käynnistä Claude Code uudelleen, avaa /agents ja tarkista, että uusi agentti näkyy luettelossa. Sen jälkeen voit kutsua sitä komennolla @agent-name.

1. code-reviewer – tarkista koodi jokaisen muutoksen jälkeen

Tämä on Anthropicin dokumentaation virallinen esimerkki, mukautettuna työprosessiin:

---
name: code-reviewer
description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code.
tools: Read, Grep, Glob
model: inherit
color: blue
---

You are a senior code reviewer ensuring high standards of code quality.

When invoked:
1. Read the diff and changed-file list supplied by the main session. If missing, ask the main session to provide them.
2. Use Read, Grep, and Glob to inspect the relevant files.
3. Return findings without changing files or running shell commands.

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Test coverage adequate
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix before merge)
- Warnings (should fix)
- Suggestions (consider improving)

Format: for each issue - file:line + 1 sentence why it's a problem + concrete fix.

Avain on tools: Read, Grep, Glob: tarkastajalla on tiedostonluku- ja hakutyökalut ilman Bash-, Write- tai Edit-pääsyä. Pääistunto valmistelee diffin ja antaa sen tarkastajalle. Pelkkä ohje suorittaa vain git diff ei rajoita kokonaisuudessaan myönnettyä Bash-työkalua.

2. security-auditor – etsi haavoittuvuudet ja vuodot

Rooli käyttää opus-mallia syvempään päättelyyn ja samaa Read-, Grep- ja Glob-rajausta. Pysyvä muisti jätetään tästä vain luku -mallista pois, koska agenttimuistin käyttöönotto antaa sille myös muistiin kirjoittamisen kyvyn:

---
name: security-auditor
description: |
  Security audit specialist. Use proactively to find OWASP Top 10
  vulnerabilities, exposed secrets, injection risks, broken auth.
  Run before any deploy or merge to main.
tools: Read, Grep, Glob
model: opus
color: red
---

You are a security auditor. Find exploitable vulnerabilities, not style issues.

Audit checklist:
- SQL / NoSQL injection
- XSS (stored, reflected, DOM-based)
- CSRF / SSRF risks
- Hardcoded secrets (API keys, tokens, passwords)
- Broken auth / session management
- Insecure deserialization
- Missing input validation
- Path traversal
- Open redirects
- Insecure direct object references (IDOR)

For each finding:
- Severity: Critical / High / Medium / Low
- File:line
- Attack scenario in 1–2 sentences
- Fix recommendation with code example

Skip linter or style noise. Report only exploitable issues.

Työkalut ovat vain lukuun, ja model: opus sopii monimutkaisiin tarkistuksiin, kuten haavoittuvuuksien ketjuihin.

3. research-agent – syvällistä tutkimusta yli 8 lähteestä

Tämä malli kuvataan Anthropicin artikkelissa sen usean agentin tutkimusjärjestelmästä. Olennaista on nimenomainen tulosmuoto ja raakojen tulosten tulostamisen kielto:

---
name: research-agent
description: |
  Deep web research specialist. Use proactively for fact-finding,
  competitive analysis, gathering external documentation, comparing
  approaches across multiple sources.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

You are a research analyst. Goal: synthesized brief, not raw search dumps.

Process:
1. Decompose the question into 3–5 sub-queries
2. WebSearch each sub-query, fetch top 3–5 sources per query
3. Cross-verify claims across at least 2 independent sources
4. Reject SEO-farm and aggregator content; prefer primary sources
5. Quote verbatim with URL attribution for any specific claim
6. Return: TL;DR (3 bullets) + Findings + Sources (8+ domains minimum)

Anti-patterns to avoid:
- Don't cite a fact from a single source
- Don't paraphrase quotes as if they were verbatim
- Don't return raw search result dumps to the parent
- Don't include filler intro / outro ("Hope this helps")

maxTurns: 30 ehkäisee tutkimuksen loputonta jatkumista. Anthropic ilmoittaa tämän luvun usean agentin järjestelmäänsä käsittelevässä artikkelissaan:

Yhdeksänkymmenen prosentin luku koskee tutkimuksen vertailutehtäviä. Käytännössä parannus on liiketoiminnan tehtävissä pienempi, mutta yleinen mittakaava on samankaltainen.

4. doc-maintainer – pidä dokumentaatio ajan tasalla koodin kanssa

Tässä roolissa käytetään model: haiku -mallia – tyypillinen esimerkki ”kustannusten hallinnasta”. Dokumentaatio ei vaadi Opusta; Haiku hoitaa työn kolmanneksella hinnasta:

---
name: doc-maintainer
description: |
  Documentation sync specialist. Use after merging features to update
  README, API docs, CHANGELOG. Reads recent commits, identifies
  undocumented changes, updates docs proactively.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

You maintain documentation in sync with code.

When invoked:
1. Run `git log --since="last release"` to see recent changes
2. Read README.md, docs/, CHANGELOG.md
3. Identify gaps: new features without docs, removed APIs still
   documented, version mismatches

Output:
- Updated files (use Edit, not Write - preserve existing structure)
- CHANGELOG.md entry in Keep-A-Changelog format
- List of changes you made (actual diff summary, not paraphrase)

Style rules:
- Active voice, present tense
- Code examples must be copy-pasteable
- No marketing language ("powerful", "robust", "seamless")
- No filler ("This guide will help you...")

5. refactor-agent – turvallista uudelleenjärjestelyä työpuun kautta

Tässä roolissa käytetään isolation: worktree -asetusta – aliagentti työskentelee erillisessä repositorion kopiossa, ja yhdistät muutokset vain, jos ne ovat kunnossa:

---
name: refactor-agent
description: |
  Safe refactor specialist. Use for renames, extracts, inlines that
  shouldn't touch your working copy until reviewed. Runs in a
  temporary git worktree.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

You refactor code without changing behavior.

Strict rules:
1. Tests must pass BEFORE and AFTER the refactor.
   If pre-refactor tests fail, STOP and report.
2. One atomic refactor per commit (extract, rename, inline).
3. Never change public APIs without explicit instruction.
4. Never modify tests unless they test the refactored implementation
   directly.

Process:
- Run test suite -> baseline
- Make atomic refactor
- Run test suite -> verify
- Commit with conventional message: refactor(scope): what

Return: summary of changes + worktree path so user can diff and merge.

Tämän roolin avulla poistuu kivuliain uudelleenjärjestelyn ongelma – ”rikoin jotain enkä tiedä, miten palauttaa muutokset”: alkuperäinen kopio säilyy koskemattomana, ja aliagentti työskentelee eristetyssä työpuussa.

Haluatko paitsi kopioida valmiita aliagentteja myös koota yhdistelmän, joka tekee Claudesta vakaan työkalun? Aliagentit ovat osa tekoälykloonia: keino antaa Claudelle erikoistunut tiimi, joka työskentelee sinun logiikkasi mukaan. Menetelmän kolme pilaria ovat: tekoälyklooni (Skillit + aliagentit) + Toiset aivot + kontekstisuunnittelu. Tämä yhdistelmä muuttaa Clauden avustajasta, joka arvailee, työkaluksi, joka ajattelee sinun logiikkasi mukaan.

Käynnistä 5 aliagenttia rinnakkain: orkestroija + työntekijät#

Rinnakkaisorkestrointi on ”kapellimestari + orkesteri” -asetelma. Kapellimestari hallitsee suunnitelmaa, ei kirjoita nuotteja ja tarkistaa, mitä muusikot soittavat. Jos joku soittaa väärän nuotin, kapellimestari pyytää häntä soittamaan sen uudelleen sen sijaan, että yrittäisi viimeistellä työn hänen puolestaan.

Yrittäjälle läheisempi vertaus on markkinointitoimisto, joka valmistelee strategiaa uudelle asiakkaalle. Yksi analyytikko tekee SWOT-analyysin, toinen kilpailija-analyysin, kolmas laatii yleisöprofiilin, johtava analyytikko suodattaa budjettiin sopimattomat hypoteesit ja projektipäällikkö kokoaa lopullisen esityksen. Claude Codessa tämä ketju alkaa yhdestä lauseesta – ja kriitikko sisältyy prosessiin sen sijaan, että saapuisi mukaan vasta jälkikäteen.

Orkestrointikehote vähimmillään

Yksi lause pääkeskustelussa riittää:

Käynnistä viisi aliagenttia rinnakkain: kolme tutkimusagenttia eri lähteistä
(Anthropicin dokumentaatio, GitHub-repositoriot, tekoälybloggaajat), yksi kriitikkoagentti karsimaan
heikot johtopäätökset ja yksi yhteenvetoagentti lopullista dokumenttia varten.

Konteksti: Kirjoitan opasta aiheesta X. Tavoitepituus: 2 000 sanaa lähteineen.
Ennen aloittamista jokainen lukee tiedoston CLAUDE.md.

Claude delegoi tehtävät sitten viidelle agentille. Kukin työskentelee omassa kontekstissaan: tutkimusagentit käyttävät omia lähteitään, kriitikko suodattaa ja yhteenvetoagentti kokoaa. Pääkeskusteluun palautuvat vain loppuyhteenvedot.

Milloin rinnakkaisuus kannattaa

Ei aina. Rinnakkaissuoritus on järkevää vain, kun:

1. Tehtävät ovat riippumattomia. Jos tutkimusagentti nro 2 odottaa tutkimusagentin nro 1 tulosta, rinnakkaisuutta ei synny – ne tekevät käytännössä työn peräkkäin.
2. Tehtävät vievät paljon aikaa. ”Poista lopusta välilyönnit” -tehtävän rinnakkaistaminen on turhaa; aliagenttien käynnistämiseen kuluva aika syö hyödyn.
3. Käytettävissä on riittävästi rajoituksia. Tästä lisää omassa osiossaan jäljempänä – rinnakkaiset aliagentit kuluttavat tokeneita nopeasti.

Anthropicin Multi-Agent v2: seuraava askel

Toukokuussa 2026 Anthropic julkaisi Multi-Agent Orchestration v2:n, jossa on kolme tärkeää eroa klassiseen rinnakkaisten aliagenttien käynnistystapaan. Tästä lisää seuraavassa osiossa.

Mitä uutta on Multi-Agent v2:ssa: orkestrointi, Outcomes, Dreaming#

Multi-Agent Orchestration: jaettu tiedostojärjestelmä + tarkistuspisteet työn aikana

Anthropic kuvaa ominaisuutta näin:

Keskeinen ero perinteisiin aliagentteihin on jaettu tiedostojärjestelmä. Aiemmin jokainen aliagentti työskenteli täydellisessä eristyksessä, ja tieto välittyi vain palautetun yhteenvedon kautta. Nyt asiantuntijat voivat kirjoittaa jaettuun kansioon, ja johtava agentti lukee tuloksia työn edetessä eikä vasta lopuksi. Tämä ratkaisee ongelman, jossa ”kaikki työskentelivät koko päivän, mutta lopuksi kävi ilmi, että kahdella ihmisellä oli yhteensopimattomat lähestymistavat”.

Toisena ovat tarkistuspisteet työn aikana. Johtava agentti voi pysähtyä kysymään asiantuntijalta ”miten menee?” ja muuttaa sen jälkeen kokonaissuunnitelmaa. Tämä muistuttaa oikean tiimin johtajan työtä.

Outcomes: onnistumiskriteerit vaiheittaisten ohjeiden sijaan

Outcomes-ominaisuudessa kirjoitat onnistumiskriteerit, ja agentti löytää keinon saavuttaa ne. Erillinen arvioija tarkistaa tuloksen omassa kontekstissaan, joten pääagentin päättely ei ”saastuta” sitä.

Kymmenen prosentin parannus haastavissa tehtävissä on merkittävä. Varsinkin kun tehtävä muotoillaan näin: ”kokoa pitkä artikkeli, joka täyttää nämä laatukriteerit”, eikä näin: ”noudata vaiheita 1–7”.

Dreaming: agentit keräävät kokemusta istuntojen välillä

Tämä on käsitteellisesti uusin ominaisuus. Agentti käy läpi aiempia istuntoja, etsii onnistumisten ja virheiden malleja ja päivittää muistivarastoa. Voit määrittää muutoksille manuaalisen tarkistuksen ennen käyttöönottoa tai antaa agentin muokata muistia itse.

Anthropic kertoo, että Harvey (oikeusteknologiayritys) näki noin kuusinkertaisen parannuksen juridisten asiakirjojen laatimistehtävien onnistumisessa Dreamingin käyttöönoton jälkeen. Tämä toimii jo tuotantokäytössä, eikä ole vain esittely.

Mitä tämä tarkoittaa yrittäjille, jotka eivät ohjelmoi

Multi-Agent Orchestration on tällä hetkellä saatavilla Claude Agent SDK:n kautta, ei suoraan Claude Code CLI:ssä. Suunta on kuitenkin selvä: orkestrointi siirtyy vaiheesta ”käynnistät N aliagenttia käsin” vaiheeseen ”kuvailet tehtävän, ja johtava agentti päättää, kenelle ja miten se delegoidaan”. Jos olet vasta aloittamassa aliagenttien käyttöä, älä vielä huolehdi v2:sta. Opettele ensin klassinen malli ”1 pääkeskustelu + 3–5 eri roolien aliagenttia”, niin 3–6 kuukauden päästä voit siirtyä luontevasti Managed Agentsiin.

7 virhettä, jotka pysäyttävät aliagenttien toiminnan#

Virhe 1. ”X:n apuri” -kuvaukset eivät aktivoi agenttia

Oire: kirjoitit aliagentin, tarkistit rakenteen ja kaikki on kunnossa, mutta Claude ei kutsu sitä käyttäjien pyyntöjen perusteella. Syy on lähes aina sama: kuvaus on abstrakti, esimerkiksi ”Apuri koodintarkistukseen”. Ratkaisu: kirjoita kuvaukseen suoraan 3–5 todellista käyttäjän ilmaisua lainausmerkkeihin ja lisää ”käytä ennakoivasti” / ”käytä heti sen jälkeen”.

Virhe 2. Aliagentin luominen tilanteessa, jossa tarvitaan Skill

Aliagentti maksaa enemmän kuin Skill – se luo oman kontekstinsa, lataa oman järjestelmäkehotteensa ja käyttää enemmän tokeneita. Jos tehtävä on lyhyt, ei kuluta pääkontekstia ja valmistuu yhdellä suorituksella, siitä pitäisi tehdä Skill eikä aliagenttia. Esimerkki vastaesimerkistä: format-validator-aliagentti, joka tarkistaa JSON-skeeman 20 säännön perusteella. Tästä pitäisi tehdä Skill: yksi malli, eristystä ei tarvita eikä ylimääräistä kontekstia ladata.

Virhe 3. ”60 rinnakkaisen agentin” käynnistäminen heti alkuun

Tämä on yleisin harhakuva. Näet twiitin, jossa sanotaan ”minulla on 1 500 agenttia töissä”, ja ajattelet: ”Minunkin pitäisi tehdä niin.” Käytännössä 60 agenttia kuluttaa Pro-tilauksen rajat tunnissa, tuottaa kasan keskenään ristiriitaisia tuloksia, eikä päivän päätteeksi ole mitään valmista.

Mediumin kirjoittaja kuvaa asiaa näin:

Ratkaisu: aloita yhdellä aliagentilla ja yhdellä tehtävällä. Kun hallitset sen, lisää toinen eri roolilla. Kun osaat orkestroida kahta, siirry 3–5 agentin tiimiin. Siirtyminen suoraan ”asensin Claude Coden eilen” -vaiheesta ”20 rinnakkain tänään” -vaiheeseen rikkoo varmasti koodia ja kuluttaa käyttörajat loppuun.

Virhe 4. Kaikille agenteille annetaan kaikki työkalut

Jos koodintarkastajallasi on pääsy Bashiin, Writeen ja WebFetchiin, kyseessä on suuri tietoturva- ja kustannusaukko. Tarkastajalla ei pitäisi olla oikeutta kirjoittaa tiedostoja, saati käyttää internetiä.

Ratkaisu: rajaa tools-kenttä tiukasti. Koodintarkastaja saa vain Read, Grep, Glob. Tietoturva-auditoija saa samat luku- ja hakutyökalut sekä pääistunnon toimittaman diffin. Bashin lisääminen myöntää komentotulkkikyvyn eikä automaattisesti rajaa agenttia git diff -komentoon. Tutkimusagentti saa WebFetch, WebSearch, Read, Write. Älä anna aliagentille enempää oikeuksia kuin se tarvitsee yhtä tiettyä tehtävää varten.

Virhe 5. Aliagentti syöttää raakatuloksia pääkontekstiin

Jos tutkimusagentti palauttaa pääkeskusteluun ”tässä ovat kaikki löytämäni 30 sivua, päättele itse”, olet menettänyt aliagenttien tärkeimmän edun: hälyn eristämisen. Ratkaisu: vaadi aliagentin järjestelmäkehotteessa nimenomainen tulosmuoto. ”Palauta VAIN: 3 kohdan TL;DR + 5 lähteen luettelo. EI kooditulosteita, EI raakoja hakutuloksia.” Muodon pitää olla tiukka – aliagentilla ei pitäisi olla vapautta ”muuttaa sitä esseeksi”.

Virhe 6. Epämääräiset kutsut: delegointipyyntö on epäselvä

Aliagentti ei näe pääkeskustelun historiaa. Se aloittaa puhtaalla kontekstilla + CLAUDE.md:llä ja kaikella, mitä kirjoitit sille nimenomaisesti. Jos kirjoitat ”korjaa todennus”, aliagentti keksii itse loput. Kirjoita sen sijaan: ”Korjaa OAuth-uudelleenohjaussilmukka, jossa onnistuneen kirjautumisen jälkeen käyttäjä ohjataan /login-sivulle eikä /dashboard-sivulle. Tiedosto: src/lib/auth.ts.”

Selkeä nyrkkisääntö: anna aliagentille tehtävää delegoidessasi yhtä paljon kontekstia kuin antaisit uudelle projektiin liittyneelle urakoitsijalle.

Virhe 7. Roolipohjaiset agentit tehtäväpohjaisten sijaan

Houkutteleva malli on: ”luodaan frontend-developer, backend-developer ja qa-engineer ja annetaan heidän työskennellä tiiminä”. Se ei toimi. Jokainen ”rooli” kadottaa kontekstin koko projektista, eivätkä agentit pääse sopuun yksityiskohdista, koska ne eivät näe toistensa työtä.

Ratkaisu: aliagentin pitäisi hoitaa selkeästi tuotokseksi määritelty toistuva tehtävä, ei rooli. Ei ”frontend-developer”, vaan ”explore-ui-tree”, ”refactor-component”, ”audit-accessibility”. Jokainen tehtäväpohjainen aliagentti tekee yhden täsmällisen työn ja palauttaa yhden täsmällisen tuloksen.

Paljonko rinnakkaiset aliagentit maksavat, ja milloin ne kannattavat?#

Pro-tilauksen käyttövara loppuu tunnissa, jos käynnistät viisi rinnakkaista aliagenttia vaativissa tehtävissä. Max 5x ($100) on realistinen vähimmäistaso säännölliseen rinnakkaistyöhön. Tiimien ja Enterprise-tilausten kohdalla rahakysymys ratkaistaan jo työkalubudjetissa.

Lisätietoja tokenien säästämisestä Claude Codessa on erillisessä käyttörajoja käsittelevässä oppaassa. Aliagenteissa keskeinen nyrkkisääntö on, että aliagentti kannattaa tehtävässä, joka vaatii vähintään 10 minuuttia keskittynyttä työtä. Jos tehtävä on lyhyempi, älä luo aliagenttia; tee työ pääkeskustelussa tai Skillillä.

Miten aliagentit integroidaan tekoälyklooniin ja Toisiin aivoihin?#

Aliagentti tarvitsee kolme asiaa, joiden pitäisi olla projektissasi ennen ensimmäisen asiantuntijan luomista:

1. Oikea CLAUDE.md. Aliagentti lukee CLAUDE.md:n ennen aloittamista – se on sen ”työsopimus”. Ilman sitä aliagentti ei tunne projektin kontekstia, rajoituksia eikä äänensävyä. Se keksii asioita.

2. Perus-Skillit. Skill on paketoitu menetelmä. Aliagentti lataa vain tarvitsemansa Skillit, ei kaikkea kerralla. Ilman Skillejä aliagentti toistaa saman työn alusta joka kerta.

3. Toiset aivot: tietorakenne. business/-kansio tai vastaava oman alasi kansio on kirjasto, jota kaikki aliagentit käyttävät. Ilman sitä aliagentti antaa keskinkertaisen ChatGPT-vastauksen, joka ei erotu kenen tahansa muun saamasta vastauksesta.

Järjestyksen kääntäminen tarkoittaa hypeä ilman tuloksia. ”Minulla on 60 rinnakkaista aliagenttia” tyhjän business/-kansion kanssa tarkoittaa 60:tä tavallista ChatGPT-istuntoa samalla lähestymistavalla.

Kokonaisuus – tekoälyklooni + Toiset aivot + kontekstisuunnittelu – muodostaa kolme pilaria, jotka tekevät Claudesta johdonmukaisen. Aliagentit ovat osa tekoälykloonia: keino antaa Claudelle erikoistunut tiimi, joka työskentelee sinun logiikkasi mukaan.

Nopein tapa aloittaa on kopioida ensimmäisen esimerkin code-reviewer tiedostoon .claude/agents/code-reviewer.md, käynnistää Claude Code uudelleen ja kutsua @agent-code-reviewer seuraavan commitin yhteydessä. Viidessä minuutissa tiedät, tarvitsetko aliagentteja vai riittääkö pääkeskustelu.