Workbranch › Ohjeet

Näin käytät subagentteja Claude Codessa

Pitkät haut ja runsas testituloste täyttävät Claude Code -keskustelusi nopeasti. Subagentit vievät tämän työn erilliseen kontekstiin ja palauttavat yhteenvedon. Tämä ohje kertoo, mitä ne ovat, miten teet omasi ja milloin niistä on hyötyä.

Päivitetty 30. lokakuuta 2026

Alla olevat tiedot perustuvat Anthropicin Claude Code -dokumentaatioon lokakuussa 2026. Claude Code muuttuu usein, joten aja claude update, jos jotain tässä kuvattua puuttuu.

Mitä subagentit ovat

Kun Claude kohtaa tehtävän, joka vastaa subagentin kuvausta, se voi delegoida sen. Subagent aloittaa puhtaalta pöydältä: se ei näe keskusteluasi, vain ohjeet, jotka Claude sille välittää. Se tekee työnsä, kuten lukee kymmeniä tiedostoja tai ajaa testisarjan, ja lähettää takaisin yhteenvedon. Pääkeskustelusi pysyy lyhyenä.

Claude Coden mukana tulee valmiita subagentteja, muun muassa:

• Explore: nopea, vain luku -tilassa toimiva koodikannan haku ja analyysi.
• Plan: vain luku -tutkimus, kun olet plan modessa.
• General-purpose: monivaiheiset tehtävät, jotka vaativat sekä tutkimista että muutoksia.

Näitä ei tarvitse määrittää; Claude käyttää niitä, kun ne sopivat.

Luo oma subagent

1. Päätä laajuus. Jos koko tiimin pitää voida käyttää subagenttia yhdessä repositoriossa, luo projektiin kansio .claude/agents/. Jos haluat sen mukaasi kaikkiin projekteihin, käytä kansiota ~/.claude/agents/.
2. Luo kansioon Markdown-tiedosto, esimerkiksi code-reviewer.md.
3. Aloita tiedosto frontmatterilla kahden ----rivin välissä. Tiedoston ensimmäisen rivin on oltava ---.
4. Lisää kaksi pakollista kenttää: name (yksilöllinen tunniste, esimerkiksi code-reviewer, ilman kaksoispistettä) ja description (milloin Clauden pitää käyttää sitä, esimerkiksi Reviews code for quality and best practices. Use after code changes.).
5. Halutessasi lisää tools rajataksesi, mitä se saa käyttää, esimerkiksi Read, Glob, Grep vain lukevalle tarkastajalle, ja model (mallin alias, kuten sonnet tai haiku, koko mallin tunniste tai inherit).
6. Kirjoita sulkevan ----rivin alle subagentin ohjeet selkokielellä: sen rooli, mitä tarkistetaan ja mitä palautetaan.
7. Tallenna tiedosto. Claude Code huomaa muutokset olemassa olevassa agents-kansiossa sekunneissa; jos loit kansion istunnon aikana, käynnistä Claude Code uudelleen.

Käytä subagenttia

• Anna Clauden valita: Claude vertaa pyyntöäsi kunkin subagentin description-kuvaukseen. Kuvauksen sanat, kuten "use proactively", rohkaisevat sitä delegoimaan.
• Pyydä nimellä: esimerkiksi Use the code-reviewer subagent to check my recent changes.
• Mainitse se: kirjoita @ ja valitse subagent. Näin varmistat, että juuri se hoitaa tehtävän.
• Koko istunnoksi: aja claude --agent code-reviewer.

Milloin subagenteista on hyötyä ja milloin ei

Anthropicin ohjeistus tiivistettynä:

Hyvä tietää

• Jos kahdella subagentilla on sama nimi, korkeamman prioriteetin sijainti voittaa: hallinnoidut asetukset, sitten --agents-valinta, sitten projektin kansio, sitten käyttäjäkansiosi ja lopuksi pluginit.
• Subagent ei näe keskusteluhistoriaasi eikä tiedostoja, jotka Claude on jo lukenut, joten se nojaa Clauden antamiin ohjeisiin.
• Oletuksena enintään 20 subagenttia voi olla käynnissä samanaikaisesti.
• Kenttien nimet ovat camelCase-muodossa (esimerkiksi disallowedTools, maxTurns), ja tuntemattomat kentät ohitetaan hiljaa, joten tarkista kirjoitusasu.
• Projektin subagent-tiedostot voi commitoida, jolloin koko tiimi saa samat apulaiset.

Jos se ei toimi

• Claude ei löydä uutta subagenttia: jos agents-kansiota ei ollut olemassa istunnon alkaessa, käynnistä Claude Code uudelleen.
• Tiedosto ohitetaan hiljaa: yleisiä syitä ovat puuttuva name tai description, virheellinen YAML tai se, ettei --- ole ensimmäisellä rivillä. Aja claude --debug ja lue debug-loki, tai aja claude plugin validate .claude/agents löytääksesi tiedostot, joiden frontmatter ei jäsenny.
• Claude ilmoittaa virheestä, jossa mainitaan tunnistamattomia työkaluja: kun mikään tools-listan kohta ei vastaa todellista työkalua, Claude Code ei yleensä käynnistä subagenttia. Korjaa työkalujen nimien kirjoitusasu.
• Väärä malli: aja /tasks nähdäksesi, mitä mallia kukin subagent todella käyttää.

Säilytä tulokset, ei vain yhteenvetoa

Subagentin raportti päätyy istuntoosi, joka katoaa näkyvistä, kun istunto suljetaan. Workbranchin Claude Code -pluginilla voit sanoa "save this to Workbranch", jolloin istunnon tehtävät, päätökset ja avoimet kysymykset tallentuvat projektiin, ja seuraava istunto samassa kansiossa alkaa siitä, mikä on vielä auki. Katso Workbranch for Claude. Jos istunnosta loppui tila, ohje Claude Code -istunnon jatkamisesta kertoo, miten pääset takaisin.

Lähteet

• Use Claude Code with your Pro or Max plan (Claude Help Center, tarkistettu 30.10.2026)
• Create custom subagents (Claude Code docs, tarkistettu 30.10.2026)

Usein kysytyt kysymykset