Claude Architect · Oppitunti

Rakenteinen tuloste

--output-format json sekä jäsennystä varten määritetty skeema.

Oppitunti 2/413 vaihetta

Rakenteinen tuloste on ilmainen Claude Architect-oppitunti CoddyKitissä. Tämä on oppitunti 2/4. Voit lukea tästä oppimispolusta kokonaan mitkä tahansa 3 oppituntia ilmaiseksi — sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä käytännön harjoittelun sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Oppitunti kuuluu Claude Architect-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Miksi jäsennelty tulostus on tärkeää CI/CD:ssä

Kun suoritatte Claude Codea putken sisällä, ihminen ei lue tulosta — skripti lukee sen. CI-työ tarvitsee vakaan, koneellisesti jäsennettävän vastauksen, jotta se voi epäonnistuttaa koontiversion, lähettää kommentin tai estää yhdistämisen.

Tämän mahdollistavat kaksi valitsinta:

-p (tai --print) suorittaa Claude Coden ei-interaktiivisesti — sitä tarvitaan kaikissa putkissa.
--output-format json palauttaa jäsennettävän tuloksen vapaamuotoisen tekstin sijaan.

Tässä oppitunnissa yhdistyvät toimialue 4 (kehotteiden suunnittelu ja jäsennelty tulostus) ja skenaario 5 (Claude Code CI/CD:ssä).

claude -p "Review the staged diff for security bugs" \
  --output-format json

Vapaamuotoisen tekstin ongelma

Jos annatte mallin vastata proosamuodossa, putken on poimittava tiedot tekstistä säännöllisillä lausekkeilla — laskettava sanoja ja etsittävä ilmauksia kuten "näyttää hyvältä" tai "ongelmia löytyi". Tämä on hauras ja klassinen haitallinen toimintamalli.

Sama sääntö koskee agenttisilmukkaa: lopettakaa stop_reason-arvon perusteella, älkää koskaan etsimällä tekstistä sanoja kuten "valmis". CI:ssä päätätte läpäisystä tai epäonnistumisesta jäsenneltyjen kenttien perusteella, etteivät vapaan tekstin perusteella.

Jäsennelty tulostus korvaa hauraan tekstin poiminnan sopimuksella, johon skriptinne voi luottaa.

Skeeman lisääminen

--output-format json antaa JSON-muotoisen tuloksen, mutta tavallisen JSONin rakenne voi silti vaihdella. Yhdistäkää siihen JSON Schema, jotta tulosteessa ovat aina täsmälleen putken odottamat kentät.

Skeema tarjoaa kaksi takuuta:

Se poistaa syntaksivirheet — jäsentimen kaatavaa puolivalmista JSONia ei synny.
Se pakottaa vaaditut kentät — pakollisiksi merkitsemänne kentät ovat aina mukana.

Skeeman rajoittama tulostus käyttää samaa mekanismia kuin työkalujen käyttö: tool_use + JSON Schema on tapa, jolla Claude palauttaa luotettavaa jäsenneltyä tietoa.

{
  "type": "object",
  "properties": {
    "verdict": { "type": "string", "enum": ["pass", "fail"] },
    "issues": {
      "type": "array",
      "items": { "type": "object" }
    }
  },
  "required": ["verdict", "issues"]
}

Ongelmaobjektin suunnittelu

Muotoilkaa jokainen havainto täsmälliseksi objektiksi, jonka perusteella putki voi toimia. Hyvä tarkistusskeema antaa jokaiselle ongelmalle sijainnin, vakavuuden ja selityksen — näin työ voi lisätä huomautuksen täsmälleen oikealle riville.

Käyttäkää vakavuudelle enumia, jotta arvot pysyvät yhdenmukaisina suorituksesta toiseen. Vapaamuotoisia vakavuuksia, kuten "vähän huono", ei voi jäsentää.

{
  "type": "object",
  "properties": {
    "file":     { "type": "string" },
    "line":     { "type": "integer" },
    "severity": { "type": "string",
                   "enum": ["blocker", "major", "minor"] },
    "message":  { "type": "string" }
  },
  "required": ["file", "severity", "message"]
}

Vaaditut kentät: kultainen sääntö

Merkitkää kenttä required-kentäksi vain, jos se on aina mukana. Tämä on jäsennellyn tulostuksen tärkeimmin testattu yksittäinen sääntö.

Jos vaaditte kenttää, joka voi puuttua — esimerkiksi line-kenttää koko projektia koskevassa havainnossa, jolla ei ole tiettyä riviä — malli keksii arvon täyttääkseen skeeman vaatimukset. Tämä hallusinoitu rivinumero johtaa sitten väärään CI-huomautukseen.

Edellisessä kohtauksessa line jätettiin tarkoituksella pois required-kentästä: kaikki ongelmat eivät kohdistu yhteen riviin.

Enumit ja "other"-poikkeusreitti

Enumit pitävät arvot siisteinä, mutta jäykkä enum voi rajoittaa mallia, kun todellisuus ei sovi mihinkään luokkaan. Laajennettava malli on seuraava: lisätkää enum-arvo "other" sekä vapaamuotoinen tarkennuskenttä.

Nyt malli voi pysyä skeeman mukaisena tavallisissa tapauksissa ja ilmoittaa silti odottamattomasta tapauksesta keksimättä väärää luokkaa.

{
  "category": {
    "type": "string",
    "enum": ["security", "performance",
             "style", "other"]
  },
  "category_detail": {
    "type": "string",
    "description": "Free text when category is 'other'"
  }
}

Rakenteen takaaminen tool_choice-toiminnolla

Kun kutsutte Claudea SDK:n kautta CLI:n sijaan, takaatte jäsennellyn tulostuksen yhdistämällä työkalun, jonka input_schema on JSON Schema, oikeaan tool_choice-arvoon:

"auto" — malli voi vastata tekstillä TAI kutsua työkalua (takuuta ei ole).
"any" — mallin ON kutsuttava jotakin työkalua, mikä takaa jäsennellyn tulostuksen.
{"type":"tool","name":"X"} — pakottaa käyttämään yhtä tiettyä työkalua.

CI-tarkistuksessa, jossa tarvitsette aina raporttiobjektin, pakottakaa käyttöön täsmälleen nimetty työkalu.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2048,
    tools=[review_report_tool],   # input_schema = your JSON Schema
    tool_choice={"type": "tool", "name": "emit_review"},
    messages=[{"role": "user", "content": diff_text}],
)

CI-tuloksen jäsentäminen

Putkessa luette JSONin ja haarautte sitten kentän perusteella — ette koskaan proosan perusteella. Poimikaa jäsennelty hyötykuorma ja antakaa päätöksen määrittää poistumiskoodi.

Koska skeemassa verdict- ja issues-kentät on merkitty pakollisiksi, tämän koodin ei tarvitse koskaan arvailla, ovatko avaimet olemassa.

import json, subprocess, sys

out = subprocess.run(
    ["claude", "-p", PROMPT, "--output-format", "json"],
    capture_output=True, text=True,
).stdout

report = json.loads(out)
if report["verdict"] == "fail":
    for i in report["issues"]:
        print(f"{i['file']}:{i.get('line','-')} {i['message']}")
    sys.exit(1)

Vahvistakaa ja yrittäkää sitten uudelleen palautteen avulla

Skeemasta huolimatta arvo voi olla semanttisesti väärä (esimerkiksi virheellinen aritmeettinen summa tai väärin muotoiltu viite). Vahvistakaa jäsennetty objekti Pydantic-tyylisillä tarkistuksilla ja käyttäkää rakenteellisessa tai muotovirheessä retry-with-feedback-menetelmää.

Lähettäkää mallille kolme asiaa: alkuperäinen syöte, sen tuottama väärä tuloste ja täsmällinen vahvistusvirhe. Tämä korjaa muotoilu-, rakenne- ja aritmeettiset virheet.

Tärkeä rajoitus: uudelleenyritys EI auta, jos tieto yksinkertaisesti puuttuu lähteestä — mikään määrä uusia kehotteita ei luo tietoa, jota lähteessä ei ole.

from pydantic import BaseModel, ValidationError

class Review(BaseModel):
    verdict: str
    issues: list[dict]

try:
    review = Review.model_validate_json(out)
except ValidationError as e:
    retry(original=diff_text, bad_output=out, error=str(e))

Tarkistus eristetyssä istunnossa

Jos sama keskustelu, jossa koodi tuotettiin, myös tarkistaa sen, tarkistaja pitää kiinni omasta päättelystään eikä haasta itseään — saman istunnon itsearviointi on haitallinen toimintamalli.

Suorittakaa jäsennelty tarkistus eristetyssä, uudessa istunnossa. Riippumaton instanssi havaitsee todelliset virheet paljon paremmin. Tämä sopii luontevasti yhteen jäsennellyn tulostuksen kanssa: puhdas istunto sisään, puhdas JSON-raportti ulos.

Hienosäätäkää kehote täsmällisillä kriteereillä ("ilmoita kommentista vain, jos se on ristiriidassa koodin kanssa") väärien positiivisten tulosten minimoimiseksi, jotta hyvien yhdistämisten eteneminen ei esty.

Estävät tarkistukset ja yön yli suoritettavat auditoinnit

Ennen yhdistämistä suoritettava CI-portti on estävä ja aikakriittinen — suorittakaa se synkronisesti komennoilla -p --output-format json. Message Batches API:n käyttö tässä on väärin: eräajot ovat 50 % halvempia, mutta niillä ei ole latenssi-SLA:ta, käytettävissä on enintään 24 tunnin aikaikkuna eikä monivaiheista työkalukutsua tueta.

Varatkaa Batch API ei-estäviin tehtäviin — esimerkiksi koko repositorion yön yli suoritettavaan auditointiin tai öiseen raporttiin — joissa custom_id yhdistää kunkin pyynnön ja lähetätte uudelleen vain epäonnistuneet pyynnöt.

Pikatarkistus

Soveltakaa jäsennellyn tulostuksen sääntöjä todelliseen putkipäätökseen.

Vastaa interaktiivisessa oppitunnissa

Kertaus: jäsennelty tulostus CI/CD:ssä

Tärkeimmät opit:

Suorittakaa Claude Code putkissa valitsimilla -p (ei-interaktiivinen) ja --output-format json sekä skeemalla; haarautukaa kenttien, älkää koskaan proosan, perusteella.
JSON Schema poistaa syntaksivirheet ja pakottaa vaaditut kentät.
Merkitkää kenttä pakolliseksi VAIN, jos se on aina mukana — mahdollisesti puuttuvan kentän vaatiminen aiheuttaa arvon keksimisen.
Käyttäkää enum-arvoja, joissa on "other"-arvo ja tarkennuskenttä laajennettavuutta varten.
SDK:n kautta tool_choice-arvo "any" tai pakotettu työkalu takaa jäsennellyn tulostuksen; "auto" ei takaa sitä.
Vahvistakaa (Pydantic-tyylisesti) ja käyttäkää muotovirheissä retry-with-feedback-menetelmää (alkuperäinen syöte + väärä tuloste + täsmällinen virhe) — uudelleenyritykset eivät kuitenkaan voi tuottaa puuttuvaa tietoa.
Suorittakaa tarkistus eristetyssä, uudessa istunnossa, ei koodin tuottaneessa istunnossa; minimoikaa väärät positiiviset tulokset täsmällisillä kriteereillä.
Estävä portti = synkroninen; Batch API vain ei-estäviin yön yli suoritettaviin tehtäviin.

Aloita maksutta

Opi Python tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 26
Oppitunnit: 104

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”Rakenteinen tuloste” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Claude Architect-oppimispolun 3 oppituntia, myös oppitunnin “Rakenteinen tuloste”. Sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä interaktiiviset harjoitukset sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”Rakenteinen tuloste”?

--output-format json sekä jäsennystä varten määritetty skeema. Harjoittelet Claude Architect-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Claude Architect-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Claude Architect-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 2/4.

Kuinka kauan ”Rakenteinen tuloste”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Claude Architect-oppitunnilla?

Kyllä. Jokainen Claude Architect-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

← Takaisin: Claude Architect