Vuorovaikutteinen ja headless-tila

Vuorovaikutteinen tuloste on tarkoitettu ihmisten luettavaksi. Headless-tuloste on tarkoitettu koneiden jäsennettäväksi. Käyttäkää valitsinta --output-format json, jotta seuraava vaihe voi käsitellä tulosta ohjelmallisesti.

Yhdistäkää tähän JSON Schema, jotta rakenne on taattu eikä putken toiminta koskaan rikkoudu vapaamuotoisen tekstin vuoksi.

Syvin ero liittyy siihen, kuka ohjaa toimintaa.

• Vuorovaikutteisessa tilassa ihminen korjaa suuntaa tehtävän aikana, hyväksyy muokkaukset ja ratkaisee epäselvyydet vastaamalla kysymyksiin.
• Headless-tilassa ketään ei ole paikalla vastaamassa. Kehotteen on oltava itsenäinen, onnistumiskriteerien selkeät, ja epäselvä syöte on käsiteltävä itse kehotteessa eikä jatkokysymyksellä.

Jos tehtävä todella edellyttää ihmisen harkintaa kesken työn, headless on väärä valinta.

Plan Mode kuuluu vuorovaikutteiseen työskentelyyn. Käyttäkää sitä suuriin muutoksiin, useita mahdollisia lähestymistapoja sisältäviin tehtäviin tai arkkitehtuuripäätöksiin: Claude tutkii tilanteen ja ehdottaa suunnitelmaa, minkä jälkeen se odottaa hyväksyntäänne ennen muokkaamista.

Hyväksyntävaihe on ihmisen tarkistuspiste. Sillä ei ole merkitystä headless-ajossa, jossa ketään ei ole hyväksymässä suunnitelmaa. Yhden tiedoston korjauksissa tai selkeän pinon jäljityksessä Plan Mode ohitetaan ja suoritus tehdään suoraan.

Tyypillinen headless-käyttötapaus on automaattinen koodintarkistus jokaiselle pull requestille. Työ suoritetaan valitsimella -p, tuloste tuotetaan JSON-muodossa ja skripti muuntaa havainnot kommenteiksi tai tarkistusportiksi.

Suorittakaa tämä tarkistus ehdottomasti eristetyssä istunnossa, jotta mikään aiempi generointikonteksti ei vääristä tulosta. Uudessa instanssissa tehty tarkistus on parempi kuin samassa istunnossa tehty itsearviointi, jossa tekijä säilyttää oman päättelynsä eikä haasta itseään.

Headless-tarkistaja, joka hälyttää turhaan, mykistetään pian. Antakaa sille epämääräisten ohjeiden sijaan täsmälliset kriteerit: ”ilmoita kommentista vain, jos se on ristiriidassa koodin kanssa” on parempi kuin ”ole täsmällisempi”.

Kun suoritatte tarkistuksen uudelleen myöhemmän pushin jälkeen, sisällyttäkää aiemmat tulokset ja ilmoittakaa vain uudet tai korjaamattomat ongelmat, jotta samaa hälyä ei toisteta jokaisessa commitissa.

Älkää sekoittako headless-tilassa tehtävää estävästi toimivaa tarkistusta Message Batches API -rajapintaan. Ne ratkaisevat eri ongelmia.

• Headless -p CI:ssä: synkroninen, palauttaa tuloksen heti ja estää yhdistämisen tarvittaessa.
• Batch API: 50 % edullisempi, käytettävissä enintään 24 tunnin aikaikkunassa, ei latenssi-SLA:ta eikä monikierroksista työkalukutsua.

Käyttäkää Batchia estämättömiin yön yli suoritettaviin tehtäviin, kuten raportteihin tai auditointeihin. Älkää käyttäkö sitä ennen yhdistämistä tehtävään tai aikakriittiseen tarkistukseen, jonka on vastattava heti.

Vuorovaikutteinen työskentely on keskustelevaa ja jatkettavaa. --resume <name> jatkaa nimettyä istuntoa, ja fork_session luo haaran jaetusta kohdasta vaihtoehtojen kokeilemista varten.

Yksi varoitus: jatketun istunnon työkalutulokset voivat olla vanhentuneita, jos koodikanta on muuttunut sillä välin. Joskus uusi istunto, jolle annetaan rakenteinen yhteenveto, on parempi kuin vanhentuneen istunnon jatkaminen.

Molemmat tilat lukevat saman projektimäärityksen, joten hyvin määritetty repositorio toimii yhdenmukaisesti riippumatta siitä, käynnistääkö sen ihminen vai putki.

• ./CLAUDE.md (projektitasoinen, versionhallinnan kautta jaettu) tuo käytännöt jokaiseen ajokertaan.
• .claude/skills/ ja komennot tarjoavat uudelleenkäytettäviä, rajattuja toimintatapoja.

Huomaa: käyttäjätason ~/.claude/CLAUDE.md on henkilökohtainen eikä sitä jaeta versionhallinnan kautta, joten CI-ajolla ei ole sitä käytettävissään. Sijoittakaa kaikki headless-työn edellyttämä projektitason määritykseen.

Kun valitsette tilaa, kysykää:

• Onko paikalla ihminen hyväksymässä ja ohjaamassa? Kyllä -> vuorovaikutteinen. Ei -> headless.
• Tarvitseeko skripti jäsentää tuloksen? Kyllä -> headless ja --output-format json.
• Onko kyseessä estävä, aikakriittinen tarkistus? Käyttäkää synkronista headless-tilaa, ei Batchia.
• Suuri tai arkkitehtoninen muutos, joka vaatii ensin hyväksynnän? Vuorovaikutteinen Plan Mode.
• Automaattinen PR-tarkistus? Headless, eristetty istunto ja täsmälliset kriteerit.

Sovittakaa tila siihen, kuka osallistuu prosessiin ja mikä käyttää tulostetta.

Tärkeimmät opit:

• Vuorovaikutteinen = keskusteleva, ihminen mukana silmukassa; tukee Plan Mode -hyväksyntöjä sekä jatkettavia ja haarautettavia istuntoja.
• Headless = -p/--print, suoritetaan kerran ja lopetetaan; pakollinen CI/CD:ssä, jossa ihminen ei ole paikalla.
• Lisätkää --output-format json (sekä skeema), jotta tulokset ovat koneen jäsennettävissä.
• Automaattinen tarkistus on suoritettava eristetyssä istunnossa täsmällisin kriteerein, ja raportoitava vain uudet tai korjaamattomat ongelmat.
• Molemmat tilat jakavat projektitason määrityksen (./CLAUDE.md, .claude/), mutta eivät henkilökohtaista ~/.claude-määritystä.
• Headless-tilan estävät tarkistukset EIVÄT ole Batch API: Batch on edullisempi, mutta sillä ei ole latenssi-SLA:ta eikä monikierroksista työkalukutsua.