Täydellinen opas agenttien system promptien kirjoittamiseen — Oppeja Claude Coden takaisinmallintamisesta

Tekoälymaailmassa on juuri nyt käynnissä massiivinen joukkoharha.

Jokainen tutoriaali käskee sinua kirjoittamaan system prompteja ikään kuin laatisit loitsuja — kunhan vain löydät oikean taikasanan, malli tottelee. "Olet ÄÄRIMMÄISEN LAHJAKAS senior-koodari, jolla on 20 vuoden kokemus..." Kuulostaako tutulta?

Olen viettänyt viime kuukaudet rakentaen VibeComia, tekoälypohjaista startup-neuvonantajaa, joka tekee syvällistä markkinatutkimusta ja tuottaa VC-tason analyysejä. Matkan varrella olen takaisinmallintanut (reverse-engineer) Claude Coden system promptin, kahlannut läpi DeepAgentsin middleware-lähdekoodia ja polttanut enemmän API-krediittejä kuin kehtaan myöntää. Suurin opetus? Suurimmalla osalla asioista, joiden ihmiset luulevat merkitsevän system prompteissa, ei ole mitään väliä. Ja niistä asioista, joilla oikeasti on väliä, ei puhu juuri kukaan.

Tämä postaus on se täydellinen pelikirja — ei mikään 5 minuutin pintaraapaisu, vaan kaikki se, mitä olisin toivonut jonkun kertovan minulle ennen kuin aloitin. Nappaa kuppi kahvia.

---

1. Suunnittelufilosofia: Luota malliin

"An agent is a model. Not a framework. Not a prompt chain." — shareAI-lab/learn-claude-code

Tämä ajatus muutti minulle kaiken. LLM osaa jo valmiiksi päätellä, suunnitella ja toteuttaa. System promptisi tehtävä ei ole opettaa sitä ajattelemaan — sen tehtävä on luoda ympäristö, jossa se voi työskennellä.

Mieti sitä kuin palkkaisit senior-kehittäjän. Et anna hänelle 20 vaiheen tarkistuslistaa jokaista tehtävää varten. Sanot hänelle: tässä on se keitä me olemme, tässä ovat rajat, ja tältä näyttää hyvä lopputulos. Sitten siirryt pois tieltä.

System promptillasi on tasan neljä tehtävää:

• Kerro sille, kuka se on — rooli ja identiteetti
• Kerro sille, missä seinät tulevat vastaan — turvallisuusrajat
• Kerro sille, miltä hyvä näyttää — laatustandardit
• Anna sille työkalut — kyvykkyydet ja tieto

Siinä kaikki. Kaikki muu on kohinaa.

Harness-ajattelutapa

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

System promptisi on näiden valjaiden (harness) käyttöohje. Et ole suunnittelemassa jäykkää liukuhihnaa — olet suunnittelemassa ympäristöä, jossa malli voi tehdä parasta työtään autonomisesti.

Älä kirjoita system promptiasi kuin vuokaaviota. Malli päättää suoritusjärjestyksen itse.

---

2. Promptin rakenne ja osioiden järjestys

Suositeltu asettelu (Takaisinmallinnettu Claude Code v2.0.14:stä)

┌─────────────────────────────────────────────┐
│ 1. Identity                                  │  ← Read first, anchors behavior
│ 2. Security & Safety                         │  ← IMPORTANT markers, non-negotiable
│ 3. Tone & Style                              │  ← Controls output format
│ 4. Core Workflow                             │  ← How to do the work
│ 5. Tool Usage Policy                         │  ← Tool selection priorities
│ 6. Domain Knowledge                          │  ← On-demand, not pre-loaded
│ 7. Environment Info                          │  ← Runtime context, dynamically injected
│ 8. Reminders                                 │  ← Re-state critical rules
├─────────────────────────────────────────────┤
│ [Tool Definitions — system-injected]         │  ← Not editable, usually very long
├─────────────────────────────────────────────┤
│ [User Message]                               │
└─────────────────────────────────────────────┘

Miksi tällä järjestyksellä on väliä

LLM:illä on U-kirjaimen muotoinen huomiokäyrä — ne kiinnittävät eniten huomiota promptisi alkuun ja loppuun, ja kadottavat fokuksen keskikohdassa. Tämä on hyvin dokumentoitu "Lost in the Middle" -ilmiö.

• Identiteetti + Turvallisuus ylhäällä: Malli sisäistää roolin ja rajat ensimmäisenä (alkuefekti eli primacy effect).
• Ydin-workflow yläkeskivaiheilla: Tärkein osiosi — miten agentti tekee työnsä.
• Työkalumäärittelyt injektoidaan järjestelmän toimesta promptisi jälkeen: Claude Coden työkalumäärittelyt syövät ~11 438 tokenia. Tämä tarkoittaa, että oma kustomoitu sisältösi päätyy oikeastaan lähemmäs alkua kuin uskoisitkaan — mikä auttaa ohjeiden noudattamisessa.
• Muistutukset pohjalla: Hyödynnä äskeisyysefektiä (recency bias) kriittisten sääntöjen vahvistamiseksi.

---

3. Osioiden kirjoittaminen

3.1 Identiteetti — Kuka tämä agentti on?

Tavoite: Ankkuroi mallin rooli 1-3 lauseella.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

Suuntaviivat:

• Pidä se ytimekkäänä — max 1-3 lausetta.
• Nimeä rooli eksplisiittisesti (auttaa mallia erottamaan kontekstit).
• Kerro ydinvastuu ("auttaa asiassa X"), vältä epämääräistä "olet avulias assistentti" -jargonia.
• Mainitse SDK/alusta, jos se on oleellista ("built on Anthropic's Claude Agent SDK").

Anti-patternit:

• "Olet avulias, harmiton ja rehellinen tekoälyassistentti" — liian geneerinen, ei ankkuroi roolia.
• Kokonainen kappale taustatarinaa ja lorea — haaskaa tokeneita, malli ei tarvitse hahmonkehitystä.

3.2 Turvallisuus ja rajat — Ehdottomat säännöt

Tavoite: Aseta rikkoutumattomat käyttäytymisrajat.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

Suuntaviivat:

• Käytä IMPORTANT: -etuliitettä — Clauden käskyhierarkiakoulutus antaa tälle lisäpainoarvoa.
• Käytä ehdotonta kieltä: NEVER, MUST NOT, Refuse to.
• Kerro sekä se mikä on sallittua ETTÄ se mikä on kiellettyä (kaksisuuntaiset rajoitteet ovat selkeämpiä).
• Sijoita aivan alkuun, älä hautaa keskelle.
• Toista kriittiset turvallisuussäännöt lopussa — Claude Code tekee juuri näin.

Miksi toistaa? Alkuefekti (alku) + Äskeisyysefekti (loppu) = tuplavahvistus. Claude Coden turvallisuusjulistus esiintyy sekä promptin alussa että lopussa. Ei siksi, että insinöörit olisivat olleet hajamielisiä — vaan siksi, että he ymmärtävät U-kirjaimen muotoisen huomiokäyrän.

3.3 Sävy ja tyyli — Tulosteen hallinta

Tavoite: Hallitse tulosteen formaattia ja äänensävyä.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

Suuntaviivat:

• Listaa spesifejä käyttäytymismalleja, ei epämääräistä "ole ammattimainen" -ohjeistusta.
• Jokaisen säännön tulisi olla testattavissa tosi/epätosi-akselilla ("lyhyt ja ytimekäs" vs. "yritä olla lyhytsanainen").
• Sisällytä tulosteen formaattivaatimukset (markdown? JSON? pelkkä teksti?).
• Sisällytä se, mitä EI saa tehdä — monet tyyliongelmat ratkeavat kieltämällä tietty käytös.

Claude Coden helmi — Ammatillinen objektiivisuus:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

Tämä kappale on elintärkeä: se estää mallin taipumuksen miellyttämiseen (jees-mies-syndrooma). Jos agenttisi täytyy antaa objektiivisia arvioita (koodikatselmointi, ideoiden validointi, arkkitehtuuripäätökset), tarvitset ehdottomasti vastaavan lausekkeen.

3.4 Ydin-workflow — Se kaikkein tärkein osio

Tavoite: Opettaa mallille miten työskennellä — metodologiaa, ei jäykkiä proseduureja.

Tämä on vaikein osio kirjoittaa hyvin, ja sillä on suurin vaikutus, kun saat sen osumaan kohdalleen.

Ydinperiaate: anna periaatteita, älä proseduureja.

Kerro LLM:lle miltä hyvä tuloste näyttää ja miksi se on hyvä — anna sen itse keksiä, miten sinne päästään. Vältä määräämästä tarkkoja kenttien määriä, askelsarjoja tai formaatteja, ellei tulostetta syötetä suoraan koneiden luettavaksi myöhemmässä vaiheessa.

Claude Coden lähestymistapa:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

Huomaa sana "recommended" (suositeltu) — ei "sinun on noudatettava näitä tarkkoja askeleita". Tuo yksi sanavalinta antaa mallille tilaa sopeutua.

Hyvä workflow-määrittely:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

Jokaisessa säännössä on implisiittinen "miksi" — malli pystyy ymmärtämään tarkoituksen ja yleistämään sen uusiin skenaarioihin.

Anti-patternit:

• Jäykkä 20 askeleen proseduuri — malli suorittaa sen mekaanisesti ja jäätyy odottamattomien syötteiden edessä.
• "Tee ensin A, sitten B, sitten C" — tuo on prompt-ketju, ei agentti-prompt.
• Yliohjeistaminen asioissa, joissa LLM on jo valmiiksi hyvä — haaskaa tokeneita.

Opin tämän kantapään kautta VibeComin kanssa. Varhaisissa versioissa oli 10 askeleen tutkimus-workflow. Malli suoritti kuuliaisesti kaikki 10 askelta, vaikka askel 3 olisi jo vastannut käyttäjän kysymykseen. Kun vaihdoin periaatteisiin ("tutki kunnes sinulla on riittävästi todisteita, syntetisoi sitten"), laatu parani ja token-kustannukset laskivat.

Poikkeus: Kun tuloste menee koneiden luettavaksi (agenttien välinen kommunikaatio, API-vastausformaatit), sinun pitää määritellä tiukat formaatit. Periaatteet ovat käyttäytymistä varten; skeemat ovat rajapintoja varten.

3.5 Työkalujen käyttöpolitiikka — Epäselvyyksien ratkaiseminen

Tavoite: Kun useampi työkalu voi tehdä saman asian, kerro mallille kumpaa suosia.

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

Suuntaviivat:

• Käytä "instead of" (sijaan) ilmaisemaan prioriteettia (A mieluummin kuin B).
• Selitä miksi tiettyjä työkaluja tulisi suosia ("tarjoaa paremman käyttökokemuksen", "vähentää kontekstin käyttöä").
• Määrittele rinnakkaissuoritusstrategia (riippumattomat → rinnakkain, riippuvaiset → peräkkäin).
• Listaa turvallisuusrajoitteet työkalujen käytölle (polkujen validointi, oikeuksien tarkistukset).

Kriittinen suhde työkalujen ja promptien välillä:

Työkalumäärittelyt injektoidaan yleensä järjestelmän toimesta, etkä voi muokata niitä suoraan. Claude Coden työkalumäärittelyt ovat ~11 438 tokenia. Tämä tarkoittaa:

• Älä toista tietoa, joka on jo työkalumäärittelyissä.
• Käytä system promptia strategiseen ohjaukseen: milloin käyttää mitäkin työkalua, miksi suosia yhtä toisen yli, prioriteettijärjestys.
• Työkalumäärittelyjen laatu vaikuttaa suoraan agentin tehokkuuteen — jos rakennat omaa agenttia, investoi aikaa erinomaisten työkalukuvausten kirjoittamiseen.

3.6 Domain-tieto — Lataa tarvittaessa, ei etukäteen

Tavoite: Tarjoa erikoistunutta tietoa, joka mallin opetusdatasta saattaa puuttua.

Ydinperiaate: asteittainen paljastaminen (progressive disclosure), ei tietodumppeja.

❌ Liitä kaikki 200 API-endpointtia system promptiin → token-räjähdys
✅ Anna mallille työkalu asioiden etsimiseen → "Lataa tietoa kun tarvitset sitä"

Tämän strategian jakavat sekä Claude Coden Skills-järjestelmä että DeepAgentsin Progressive Disclosure -middleware. Molemmat lataavat tietoa tarpeen mukaan työkalukutsujen kautta sen sijaan, että kaikki ladattaisiin etukäteen.

Toteutustavat:

1. Laita osoittimet system promptiin: "Käytä get_api_docs-työkalua hakeaksesi dokumentaatiota tarvittaessa"
2. Käytä CLAUDE.md / AGENTS.md -tiedostoja projektin kontekstiin — ladataan ajonaikaisesti, ei kovakoodattuna
3. Käytä Skills / SKILL.md -tiedostoja kyvykkyyksien löytämiseen — malli näkee valikon saatavilla olevista taidoista ja hakee täydet speksit tarvittaessa

3.7 Ympäristötiedot — Ajonaikainen konteksti

Tavoite: Anna mallille tietoisuus sen suoritusympäristöstä.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

Suuntaviivat:

• Generoi dynaamisesti, älä koskaan kovakoodaa.
• Sisällytä: työhakemisto, alusta, päivämäärä, mallin nimi, git-status.
• Käytä rakenteellista formaattia (XML-tägit tai koodilohkot) helppoa jäsentämistä varten.
• Päivämäärällä on väliä — mallin täytyy tietää mikä on "nyt" voidakseen arvioida tiedon tuoreutta.

3.8 Muistutukset — Viimeinen vahvistus

Tavoite: Toista kaikkein kriittisimmät säännöt promptin lopussa.

Claude Code toistaa turvallisuusrajoitteensa ja TodoWrite-vaatimuksensa pohjalla:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

Suuntaviivat:

• Toista vain 2-3 kaikkein kriittisintä sääntöä — älä duplikoi kaikkea.
• Hyödynnä äskeisyysefektiä — malli muistaa tuoreen sisällön vahvemmin.
• Parhaat ehdokkaat: turvallisuusrajat, useimmin rikotut säännöt, ydin-workflow'n muistutukset.

---

4. Token-budjetti ja kontekstin hallinta

Budjetin allokoinnin viitekehys

Osio	Suositellut tokenit	Huomiot
Identiteetti + Turvallisuus	200-500	Ytimekäs mutta ehdoton
Sävy ja tyyli	300-800	Sääntöjen pitää olla tarkkoja, mutta älä jaarittele
Ydin-workflow	500-2 000	Tärkein osio, investoinnin arvoinen
Työkalujen käyttöpolitiikka	300-1 000	Riippuu työkalujen määrästä
Domain-tieto	0-1 000	Tarpeen mukaan lataaminen suositeltavaa
Ympäristötiedot	100-300	Generoidaan dynaamisesti
Muistutukset	100-300	Toista vain olennaisin
Sinun osuutesi yhteensä	1 500-6 000
Työkalumäärittelyt (järjestelmä)	5 000-15 000	Ei sinun hallinnassasi

Kontekstin rappeutumiskäyrä

Yhteisön testaus (Reddit u/CodeMonke_) on kartoittanut todellisen maailman ohjeiden noudattamisen rappeutumista:

• < 80K tokenia: Promptin noudattaminen pysyy vakaana
• 80K - 120K tokenia: Ohjeiden seuraaminen alkaa heikentyä
• > 120K tokenia: Merkittävä rappeutuminen — malli "unohtaa" varhaiset ohjeet
• > 180K tokenia: Vakava rappeutuminen

Sinun 200K konteksti-ikkunasi ≠ 200K tehokasta kontekstia. Suunnittele sen mukaisesti.

Lievennysstrategiat:

• Pidä system promptisi kevyenä (< 6 000 tokenia omalta osaltasi)
• Käytä tiivistämistä (summarization) keskusteluhistorian pakkaamiseen (DeepAgents laukaisee tämän ~80K merkin kohdalla)
• Sijoita kriittiset säännöt promptin molempiin päihin (U-kirjaimen muotoinen huomio)
• Injektoi <system-reminder> -tägejä kesken keskustelun (lisää tästä osiossa 8)

---

5. Kirjoittamisen periaatteet

5.1 Anna periaatteita, älä proseduureja

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

Periaatteet yleistyvät. Proseduureja voi seurata vain mekaanisesti. Kun malli kohtaa tilanteen, jota et osannut ennakoida, periaatteet ohjaavat oikeaan päätökseen. Proseduurit eivät.

Poikkeus: Kun tuloste menee koneiden luettavaksi (agenttien välinen kommunikaatio, API-formaatit), määrittele tiukat skeemat.

5.2 Käytä ehdotonta kieltä tiukoissa rajoitteissa

Vahvuus	Kieli	Käyttökohde
Ehdoton kielto	NEVER, MUST NOT	Turvallisuus, peruuttamattomat toiminnot
Vahva vaatimus	ALWAYS, MUST	Ydin-workflow'n säännöt
Suositus	recommended, prefer	Parhaat käytännöt poikkeuksineen
Ehdotus	consider, you may	Valinnaiset optimoinnit

Claude Coden esimerkkejä:

• NEVER update the git config — ehdoton kielto
• ALWAYS prefer editing an existing file — vahva, mutta poikkeuksia on
• The following steps are recommended — suositeltu workflow

5.3 Käytä esimerkkejä selitysten sijaan

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

Yksi esimerkki opettaa enemmän kuin 100 sanaa selitystä:

• Mallit oppivat kaavoja esimerkeistä luotettavammin kuin abstrakteista kuvauksista
• Kääri <example> -tägeihin erottaaksesi ne säännöistä
• Tarjoa sekä positiivisia ("tee näin") että negatiivisia ("älä tee näin") esimerkkejä
• Käytä aitoja, spesifejä esimerkkejä — ei "foo/bar" -paikkamerkkejä

5.4 Kaksisuuntaiset rajoitteet

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

Jos sanot vain "tee näin" → malli ei tiedä milloin EI pitäisi tehdä niin. Jos sanot vain "älä tee näin" → malli ei tiedä vaihtoehtoa. Kaksisuuntainen → selkeä ja yksiselitteinen.

5.5 Selitä miksi, älä vain mitä

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

Miksi-kysymyksen selittäminen antaa mallille kyvyn tehdä oikeita päätöksiä rajatapauksissa. Claude Coden git-turvallisuusprotokolla on mestariluokan suoritus — jokainen sääntö sisältää perustelunsa.

5.6 Rakenne voittaa proosan

• Markdown-otsikot (##, ###) — mallit tunnistavat hierarkian
• Luettelomerkit kappaleiden sijaan — jokainen sääntö on itsenäisesti testattavissa
• XML-tägit erikoissisällölle: <example>, <env>, <system-reminder>
• Taulukot vertailuihin ja mäppäyksiin
• Älä koskaan dumppaa rakenteetonta tekstiä — rakenteelliset promptit voittavat luonnollisen kielen proosan säännönmukaisesti noudattamistesteissä

---

6. Anti-patternit, jotka haaskaavat tokeneitasi

Agentiksi naamioidut prompt-ketjut

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

Tämä ei ole agentti-prompt — se on liukuhihnaskripti. Malli suorittaa sen mekaanisesti ja menettää autonomisen suunnittelukykynsä.

Ratkaisu: Kerro mallille tavoite ja rajoitteet. Anna sen päättää askeleet.

Mielistely-promptaus (Flattery Engineering)

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

Kohteliaisuudet ja superlatiivit eivät paranna tulosteen laatua. Mallilla ei ole egoa, jota pitäisi pönkittää. Säästä nuo 15 tokenia oikeaan sääntöön.

Tietodumpit

"Here is the complete API documentation for our 200 endpoints..."

Tämä ahmii konteksti-ikkunasi ja kiihdyttää kontekstin rappeutumista. Korvaa tarpeen mukaan lataamisella:

"Use the get_api_docs tool to retrieve API documentation when needed."

Työkalukuvausten toistaminen

Jos työkalumäärittely sanoo jo "Read tool reads a file from the filesystem", älä sano sitä uudestaan system promptissasi. Lisää vain strategista ohjausta, jota työkalumäärittely ei kata — milloin käyttää sitä, miksi suosia sitä, prioriteettijärjestys.

Puuttuva virheenkäsittely

Ilman eksplisiittistä ohjausta mallit yrittävät epäonnistuneita työkalukutsuja uudelleen ikuisessa luupissa. Sisällytä aina:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

Konteksti-ikkunan rappeutumisen sivuuttaminen

200K konteksti-ikkuna ≠ 200K tehokasta kontekstia. Todellisen maailman testaus osoittaa rappeutumisen alkavan 80K kohdalla. Tarvitset tiivistämisstrategian.

---

7. Injektiopisteet ja prioriteetit

Claude Coden kolme kustomointimetodia

Metodi	Korvaa	Sijainti	Paras käyttökohde
Output Styles	"Tone and style" + "Doing tasks" -osiot	Juuri ennen työkalumäärittelyjä	Vuorovaikutustyylin muuttaminen
--append-system-prompt	Ei mitään (lisäävä)	Output stylen jälkeen, ennen työkaluja	Spesifien käytösten lisääminen
--system-prompt	Koko system promptin	Säilyttää työkalut + yhden identiteettirivin	Täysi kustomointi (järein ase)

Jos käytät useampaa: Output Style → Append Prompt → Tool Definitions

Käskyhierarkia

Claude on erityisesti koulutettu käskyhierarkialla:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Highest priority
2. Custom system prompt additions                               ← High
3. Default system prompt                                        ← Medium
4. Tool definitions                                             ← Reference level

Tämä tarkoittaa:

• CLAUDE.md-säännöt ajavat oletus-system promptin yli
• Käyttäjän suorat pyynnöt ajavat kaiken yli
• Sinun kustomoitu promptisi ajaa oletuspromptin yli

Dynaamiset injektiomekanismit

• <system-reminder> — injektoi mihin tahansa viestiin kesken keskustelun muistuttaaksesi mallia kriittisistä säännöistä
• CLAUDE.md / AGENTS.md — ladataan ajonaikaisesti tiedostoista, lisätään system promptin perään
• Skills / SKILL.md — ladataan tarpeen mukaan työkalukutsuilla, nolla jalanjälkeä system promptissa

---

8. Injektio kesken keskustelun — Salainen ase

System prompt esiintyy vain kerran, aivan viestitaulukon (messages array) alussa. Mutta LLM:t ottavat koko viestitaulukon (vuorotellen user / assistant / tool -viestejä) syötteenä, ja voit injektoida prompteja myös käyttäjän viesteihin ja työkalujen tuloksiin. Claude Code käyttää tätä tekniikkaa raskaasti tuotannossa.

Miksi se on välttämätöntä

Kontekstin mätänemistä vastaan taisteleminen. Kun keskustelut pitenevät, mallin kyky noudattaa system promptin ohjeita heikkenee (huomattavasti 80K+ tokenin kohdalla). Muistutusten injektointi kesken keskustelun = sääntöjen virkistäminen äskeisyysefektin avulla.

Mentaalimalli:

• System prompt = perustuslaki (asetetaan kerran, pitkäaikainen auktoriteetti)
• Käyttäjän viestien muistutukset = muistiot (lähetetään säännöllisesti, ylläpitävät toimeenpanoa)

Kolme injektiopistettä viestitaulukossa

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Appears once, primacy effect
│   (identity, safety, workflow...)   │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← Mid-conversation injection
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← Can inject into tool results too
│ ...                                 │
│ User Message N + <system-reminder>  │ ← Latest message, strongest recency
└─────────────────────────────────────┘

Sijainti	Etu	Haitta
System prompt	Alkuefekti, luetaan ensin	Esiintyy kerran, "unohtuu" pitkissä keskusteluissa
Käyttäjän viestin injektio	Äskeisyysefekti, säännöllinen päivitys	Jokainen injektio maksaa tokeneita
Työkalun tuloksen injektio	Luonnollisin injektiopiste	Toimii vain kun työkaluja kutsutaan

Miten Claude Code oikeasti käyttää tätä

Edellytys — esittele tägit system promptissa:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

Tämä askel on kriittinen: se kertoo mallille, että nämä tägit ovat järjestelmän injektoimia, eivät käyttäjän puhetta.

Käyttötapaus 1: Käyttäytymismuistutukset (säännöllinen sääntöjen virkistys)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

Claude Code käyttää tätä muistuttaakseen mallia suunnittelemaan TodoWriten avulla — koska malleilla on tapana "unohtaa" suunnittelu ja vain aloittaa koodaaminen.

Käyttötapaus 2: Tilan vaihtaminen (Plan Mode)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

Plan modea ei ole toteutettu system promptissa. Se on tägi, joka injektoidaan seuraavaan käyttäjän viestiin. Tämä antaa sinun vaihdella tiloja dynaamisesti muokkaamatta system promptia. Nerokasta.

Käyttötapaus 3: Tiedostojen muutosilmoitukset

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

Kun ulkoinen prosessi (linter, formater, manuaalinen muokkaus) muokkaa tiedostoa, järjestelmä ilmoittaa mallille muistutuksen kautta — estäen päätökset, jotka perustuvat vanhentuneeseen tiedostosisältöön.

Käyttötapaus 4: Dynaaminen konteksti (päivämäärät, projektin säännöt)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

Ajonaikainen konteksti (päivämäärä, git-status, projektin säännöt) injektoidaan käyttäjän viestien kautta, ei kovakoodattuna system promptiin.

Kirjoitusohjeet muistutuksille

• Kääri XML-tägeihin (<system-reminder>) — malli osaa erottaa järjestelmän injektion käyttäjän puheesta.
• Esittele tägit etukäteen system promptissa — muuten malli saattaa yrittää vastata muistutukseen.
• Älä injektoi jokaiseen viestiin — jokainen injektio maksaa tokeneita, injektoi vain tarvittaessa.
• Pidä se lyhyenä — muistutus ei ole toinen system prompt, vain 1-2 kriittistä sääntöä.
• Älä ole ristiriidassa system promptin kanssa — muistutukset täydentävät ja vahvistavat, ne eivät aja yli.
• Käytä dynaamisiin vaihtoihin — plan mode, readonly mode, feature flagit.

Milloin käyttää System Promptia vs. Käyttäjän viestin muistutusta

Skenaario	System Prompt	Käyttäjän viestin muistutus
Roolin määrittely	✅	❌
Turvallisuusrajat	✅ Ensimmäinen julistus	✅ Säännöllinen toisto
Workflow-metodologia	✅	❌
Tilan vaihtaminen (plan mode)	❌	✅
Tiedostojen muutosilmoitukset	❌	✅
Päivämäärä / ympäristötiedot	✅ Alkuperäinen arvo	✅ Päivitetty arvo
Käyttäytymisen korjaaminen	❌	✅
Työkalujen käytön muistutukset	✅ Säännön määrittely	✅ Suorituksen tönäisyt

---

9. Prompt Cache — Säästä 90 % toistuvista tokeneista

Anthropicin prompt-välimuisti (prompt caching) antaa sinun välimuistittaa viestitaulukkosi staattisen etuliitteen (prefix). Kun seuraavat pyynnöt jakavat saman etuliitteen, ne osuvat välimuistiin — säästäen rahaa ja vähentäen latenssia.

Agenttien kohdalla tällä on valtavasti väliä: lähetät system promptin + työkalumäärittelyt uudelleen jokaisella LLM-kutsulla keskustelun sisällä.

Avainluvut

Mittari	Arvo
Välimuistiosuman hinta	10 % normaalihinnasta (90 % säästö)
Välimuistiin kirjoituksen hinta	125 % normaalihinnasta (25 % preemio ekalla kerralla)
Välimuistin TTL	5 minuuttia (vanhenee jos ei pyyntöjä)
Minimi välimuistipituus	1 024 tokenia (Claude 3.5+)
Välimuistin granulaarisuus	Etuliitteen täsmäys — alusta merkittyyn katkoskohtaan
Maksimimäärä katkoskohtia	4

Miten tämä muuttaa promptien suunnittelua

Ydinperiaate: staattinen sisältö ensin, dynaaminen sisältö viimeisenä.

✅ Välimuistiystävällinen asettelu:
  System prompt (staattinen)      ← Välimuistin katkoskohta 1
  Tool definitions (staattinen)   ← Välimuistin katkoskohta 2
  CLAUDE.md / project rules   ← Välimuistin katkoskohta 3 (muuttuu satunnaisesti)
  Conversation history         ← Katkoskohta 4 rullaavalle ikkunalle

❌ Välimuistin tuhoava asettelu:
  System prompt
  DYNAMIC TIMESTAMP            ← Muuttuu joka pyynnöllä, kaikki tämän jälkeen = välimuistihuti
  Tool definitions
  Conversation history

Ansa, josta kukaan ei varoita: Jos laitat dynaamisen aikaleiman keskelle system promptiasi, kaikesta sen jälkeisestä tulee välimuistihuti (cache miss). Joka. Ikinisellä. Pyynnöllä. Yksi aikaleima väärässä paikassa ja maksat täyden hinnan tuhansista tokeneista.

API:n käyttö

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← merkitsee välimuistin katkoskohdan
    }
  ],
  messages: [...]
});

Monen katkoskohdan strategia

Katkoskohta 1: System prompt           ← Ei muutu juuri koskaan
Katkoskohta 2: Tool definitions         ← Ei muutu juuri koskaan
Katkoskohta 3: Project rules / CLAUDE.md ← Muuttuu satunnaisesti
Katkoskohta 4: First N history messages  ← Rullaavan ikkunan välimuisti

Vaikka keskusteluhistoria muuttuu, ensimmäiset 3 katkoskohtaa osuvat silti välimuistiin. 10 vuoron keskustelu säästää karkeasti 40-60 % syötetokenien kustannuksista.

Suunnittelusuositukset

• Ei korkean taajuuden dynaamisia arvoja system promptiin — päivämäärä on ok (muuttuu päivittäin), tarkat aikaleimat eivät ole
• Laita dynaaminen konteksti (git-status jne.) käyttäjän viestien injektioihin — ei system promptiin, tai tuhoat välimuistin
• Pidä työkalumäärittelyt vakaina — älä lisää/poista työkaluja dynaamisesti ajon aikana
• Käytä rullaavaa ikkunaa keskusteluhistorialle — välimuistita ensimmäiset N viestiä, vain uusin viesti on välimuistihuti

---

10. Tarkistuslista

Kun olet kirjoittanut system promptisi, käy se läpi tämän tarkistuslistan avulla:

Rakenne

• Identiteetti on aivan ylhäällä?
• Turvallisuusrajat on merkitty IMPORTANT-sanalla ja toistettu lopussa?
• Selkeä osioiden erottelu otsikoilla?
• Esimerkit on kääritty <example> -tägeihin?

Token-budjetti

• Oma osuutesi < 6 000 tokenia?
• Et toista tietoa, joka on jo työkalumäärittelyissä?
• Domain-tieto ladataan tarpeen mukaan, ei etukäteen?
• Ei monisanaista lorea tai hahmon taustatarinaa?

Sääntöjen laatu

• Jokainen sääntö on testattavissa tosi/epätosi-akselilla?
• Tiukat rajoitteet käyttävät ehdotonta kieltä (NEVER/MUST)?
• Pehmeät ehdotukset käyttävät suosituskieltä (recommended/prefer)?
• Kriittiset säännöt selittävät miksi, eivät vain mitä?
• Kaksisuuntaiset rajoitteet (tee näin + älä tee näin)?

Agentin käyttäytyminen

• Annettu periaatteita, ei jäykkiä askel-askeleelta proseduureja?
• Käsitelty "työkalukutsu evätty" -skenaario?
• Käsitelty "este kohdattu" -strategia (älä yritä väkisin uudelleen)?
• Kontekstin hallintastrategia paikallaan (tiivistämisen kynnysarvo)?

Mitä EI saa tehdä

• Ei mielistelyä tai superlatiiveja?
• Ei turhia "olet avulias tekoäly" -julistuksia?
• Ei kirjoitettu prompt-ketjuksi?
• Ei ylisuunnittelua (ominaisuuksia, joita kukaan ei pyytänyt)?

---

Jos aloittaisin tänään alusta

Tässä on tarkalleen mitä tekisin:

1. Aloita identiteetillä + turvallisuudella ensimmäisellä 3 rivillä. Kaksi lausetta siitä, kuka agentti on. Tiukat rajat NEVER/MUST-sanoilla. Toista turvallisuussäännöt lopussa.

2. Kirjoita ydin-workflow'si periaatteina, ei askeleina. Max 4-5 luettelomerkkiä. Käytä "recommended" ja "prefer" pehmeille säännöille, "NEVER" ja "MUST" tiukoille.

3. Budjetoi 1 500-6 000 tokenia omalle osallesi. Työkalumäärittelyt lisäävät 5 000-15 000 lisää. Jos olet yli 6K:n, dumppaat todennäköisesti tietoa, joka pitäisi ladata tarpeen mukaan.

4. Käytä rakennetta kaikkialla. Markdown-otsikot, luettelomerkit, XML-tägit esimerkeille. Rakenteellinen prompt voittaa luonnollisen kielen proosan joka kerta.

5. Rakenna muistutukset kesken keskustelun sisään heti ensimmäisenä päivänä. Esittele <system-reminder> system promptissasi. Injektoi muistutuksia kriittisistä säännöistä, tilan vaihdoista ja kontekstipäivityksistä.

6. Suunnittele välimuistia varten. Staattinen sisältö ensin, dynaaminen sisältö viimeisenä. Älä koskaan laita muuttuvia arvoja system promptisi runkoon.

---

Kaiken tämän työn ironia? Parhaat system promptit ovat lyhyitä. Claude Coden kustomoidut ohjeet (ilman työkalumäärittelyjä) ovat yllättävän ytimekkäitä. Jokainen rivi ansaitsee paikkansa.

Aiemmin ajattelin, että prompt engineeringissä on kyse ovelien kikkakolmosten löytämisestä. Nyt ajattelen, että siinä on kyse kurinalaisuudesta — sanotaan vähemmän, sanotaan se tarkasti, ja luotetaan siihen, että malli keksii loput. Malli on fiksumpi kuin promptisi. Suunnittele ympäristö, älä käyttäytymistä.

---

Lähteet

Lähde	Avainoivallus
Claude Code v2.0.14 System Prompt	Täysi tuotantoagentin prompt-rakenteen referenssi
Reddit: Understanding Claude Code's 3 System Prompt Methods	Output Styles / --append / --system-prompt syväsukellus, kontekstin mätänemisen data
shareAI-lab/learn-claude-code	"Malli on agentti" -filosofia, harness-suunnittelumetodologia
Anthropic Prompt Engineering Docs	Viralliset promptien parhaat käytännöt
DeepAgents Framework	Tiivistämis-middleware, taitojen asteittainen paljastaminen