Strukturert utdata
--output-format json med et skjema for parsing.
Strukturert utdata er en gratis leksjon i Claude Architect på CoddyKit. Dette er leksjon 2 av 4. Du kan lese valgfritt 3 leksjoner fra denne læringsstien gratis i sin helhet – deretter låser CoddyKit PRO opp alle leksjoner, samt praktisk øving med en innebygd kodeeditor og en AI-veileder som er tilgjengelig døgnet rundt. Den er en del av læringsløpet i Claude Architect, og fremdriften din synkroniseres mellom nettet og CoddyKit-appen. Kurset i Claude Architect inneholder totalt 4 leksjoner.
Hvorfor strukturert output i CI/CD
Når du kjører Claude Code inne i en pipeline, er det ikke et menneske som leser resultatet – det er et skript. En CI-jobb trenger et stabilt, maskinlesbart svar slik at den kan feile byggejobben, legge inn en kommentar eller blokkere en sammenslåing.
To flagg gjør dette mulig:
-p(eller--print) kjører Claude Code ikke-interaktivt – nødvendig i alle pipelines.--output-format jsonreturnerer et analyserbart resultat i stedet for friformtekst.
Denne leksjonen er Domene 4 (Prompt Engineering og strukturert output) i møte med Scenario 5 (Claude Code for CI/CD).
claude -p "Review the staged diff for security bugs" \
--output-format jsonProblemet med friformtekst
Hvis du lar modellen svare i løpende tekst, må pipelinen hente ut informasjon fra teksten med regulære uttrykk – telle ord og lete etter formuleringer som «ser bra ut» eller «fant problemer». Det er skjørt og et klassisk antimønster.
Den samme regelen gjelder for agentløkken: Du avslutter basert på en stop_reason, aldri ved å analysere teksten etter ord som «ferdig». I CI avgjør du bestått/ikke bestått ut fra strukturerte felt, aldri ut fra fritekst.
Strukturert output erstatter sårbar tekstanalyse med en kontrakt skriptet ditt kan stole på.
Legge til et skjema
--output-format json gir deg JSON, men ren JSON kan fortsatt variere i struktur. Kombiner det med et JSON Schema, slik at outputen alltid har nøyaktig de feltene pipelinen forventer.
Et skjema gir to garantier:
- Det eliminerer syntaksfeil – ingen ufullstendig JSON som får parseren til å krasje.
- Det håndhever obligatoriske felt – feltene du markerer som obligatoriske, er alltid til stede.
Skjemabegrenset output er den samme mekanismen som driver verktøybruk: tool_use + JSON Schema er måten Claude returnerer pålitelige strukturerte data på.
{
"type": "object",
"properties": {
"verdict": { "type": "string", "enum": ["pass", "fail"] },
"issues": {
"type": "array",
"items": { "type": "object" }
}
},
"required": ["verdict", "issues"]
}Utforme problemobjektet
Gjør hvert funn til et presist objekt pipelinen kan handle på. Et godt gjennomgangsskjema gir hvert problem en plassering, en alvorlighetsgrad og en forklaring – slik at jobben kan kommentere den nøyaktige linjen.
Bruk en enum for alvorlighetsgrad, slik at verdiene forblir konsistente mellom kjøringer. Alvorlighetsgrader i fritekst, som «litt dårlig», kan ikke analyseres.
{
"type": "object",
"properties": {
"file": { "type": "string" },
"line": { "type": "integer" },
"severity": { "type": "string",
"enum": ["blocker", "major", "minor"] },
"message": { "type": "string" }
},
"required": ["file", "severity", "message"]
}Obligatoriske felt: Den gylne regelen
Marker et felt som required bare hvis det alltid finnes. Dette er den mest testede regelen for strukturert output.
Hvis du krever et felt som kan mangle – for eksempel line for et prosjektomfattende funn uten en bestemt linje – vil modellen fabrikere en verdi for å oppfylle skjemaet. Dette hallusinerte linjenummeret fører deretter til en feil CI-kommentar.
I den forrige scenen ble line med vilje utelatt fra required: Ikke alle problemer kan knyttes til én linje.
Enum-er + en «other»-ventil
Enum-er holder verdiene ryddige, men en rigid enum kan begrense modellen når virkeligheten ikke passer i noen kategori. Det utvidbare mønsteret er å legge til enum-verdien "other" sammen med et detaljfelt i fritekst.
Da kan modellen holde seg innenfor skjemaet i vanlige tilfeller og likevel rapportere det uventede uten å dikte opp en feil kategori.
{
"category": {
"type": "string",
"enum": ["security", "performance",
"style", "other"]
},
"category_detail": {
"type": "string",
"description": "Free text when category is 'other'"
}
}Garantere struktur med tool_choice
Når du kaller Claude gjennom SDK-en i stedet for CLI-en, garanterer du strukturert output ved å kombinere et verktøy der input_schema er JSON Schema-et ditt, med riktig tool_choice:
"auto"– modellen kan svare med tekst ELLER kalle et verktøy (ingen garanti)."any"– modellen MÅ kalle et verktøy, noe som garanterer strukturert output.{"type":"tool","name":"X"}– tvinger frem ett bestemt verktøy.
For en CI-gjennomgang der du alltid trenger rapportobjektet, tvinger du frem det nøyaktige verktøyet ved navn.
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}],
)Analysere CI-resultatet
I pipelinen leser du JSON-en og velger deretter gren basert på et felt – aldri på løpende tekst. Hent den strukturerte nyttelasten, og la resultatet avgjøre avslutningskoden.
Fordi skjemaet markerte verdict og issues som obligatoriske, trenger denne koden aldri å gjette om nøklene finnes.
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)Valider, og prøv deretter på nytt med tilbakemelding
Selv med et skjema kan en verdi være semantisk feil (en feil totalsum i et regnestykke eller en ugyldig referanse). Valider det analyserte objektet med kontroller i Pydantic-stil, og bruk retry-with-feedback ved strukturelle feil eller formatfeil.
Send modellen tre ting: det opprinnelige inndataet, den feilaktige outputen den produserte, og den nøyaktige valideringsfeilen. Dette retter format-, struktur- og regnefeil.
En viktig begrensning er at ny kjøring IKKE hjelper når informasjonen ganske enkelt mangler i kilden – ingen mengde nye forespørsler kan finne på data som ikke finnes der.
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))Gjennomgang i en isolert økt
Hvis den samme samtalen som genererte koden også gjennomgår den, holder gjennomgangen fast ved sin egen tankegang og utfordrer ikke seg selv – egenkontroll i samme økt er et antimønster.
Kjør den strukturerte gjennomgangen i en isolert, ny økt. En uavhengig instans er langt bedre til å oppdage reelle feil. Dette passer naturlig sammen med strukturert output: en ren økt inn, en ren JSON-rapport ut.
Juster prompten med eksplisitte kriterier («marker en kommentar bare når den motsier koden») for å minimere falske positiver som ellers ville blokkert gode sammenslåinger.
Blokkerende kontroller vs. revisjoner over natten
En CI-sperre før sammenslåing er blokkerende og tidskritisk – kjør den synkront med -p --output-format json. Det er feil å bruke Message Batches API her: batch-jobber er 50 % billigere, men har ingen SLA for forsinkelse, et vindu på opptil 24 timer og støtte ikke verktøykall over flere turer.
Reserver Batch API for ikke-blokkerende jobber – en revisjon av hele repoet over natten eller en nattlig rapport – der custom_id knytter hver forespørsel til riktig resultat, og du sender inn bare feilene på nytt.
Hurtigsjekk
Bruk reglene for strukturert output på en reell avgjørelse i pipelinen.
Oppsummering: Strukturert output i CI/CD
Viktigste punkter:
- Kjør Claude Code i pipelines med
-p(ikke-interaktivt) og--output-format jsonsammen med et skjema; velg gren basert på felt, aldri på løpende tekst. - Et JSON Schema eliminerer syntaksfeil og håndhever obligatoriske felt.
- Marker et felt som obligatorisk KUN hvis det alltid finnes – å kreve et felt som kan mangle, fører til fabrikering.
- Bruk enum-er med verdien
"other"+ et detaljfelt for utvidbarhet. - Via SDK-en garanterer
tool_choice"any"eller et tvunget verktøy strukturert output;"auto"gjør ikke det. - Valider (i Pydantic-stil) og bruk retry-with-feedback (opprinnelig inndata + feil output + nøyaktig feil) ved formatfeil – men nye forsøk kan ikke fremskaffe data som mangler.
- Gjør gjennomgangen i en isolert, ny økt, ikke i økten som genererte koden; minimer falske positiver med eksplisitte kriterier.
- Blokkerende sperre = synkron; Batch API bare for ikke-blokkerende jobber over natten.
Lær deg Python med en AI-veileder – gratis
Skriv og kjør ekte kode i nettleseren, få umiddelbar hjelp fra en AI-veileder som er tilgjengelig døgnet rundt, og fortsett der du slapp – på nettet eller i appen.
- Kurs
- 26
- Leksjoner
- 104
Ofte stilte spørsmål
Er leksjonen «Strukturert utdata» gratis?
Ja – du kan lese valgfritt 3 av leksjonene i læringsstien Claude Architect, inkludert «Strukturert utdata», gratis i sin helhet her på nettet. Deretter låser CoddyKit PRO opp alle leksjoner, samt interaktiv øving med en innebygd kodeeditor og en AI-veileder som er tilgjengelig døgnet rundt. Kurset i Claude Architect inneholder totalt 4 leksjoner.
Hva lærer jeg i «Strukturert utdata»?
--output-format json med et skjema for parsing. Du øver på Claude Architect med praktisk kode som du kjører direkte i nettleseren, mens en AI-veileder som er tilgjengelig døgnet rundt, svarer på spørsmålene dine mens du jobber deg gjennom leksjonen.
Trenger jeg erfaring for å begynne med Claude Architect?
Ingen tidligere erfaring er nødvendig. Claude Architect på CoddyKit er lagt opp for både nybegynnere og viderekomne, så De kan begynne her eller helt fra start og lære i Deres eget tempo. Dette er leksjon 2 av 4.
Hvor lang tid tar leksjonen «Strukturert utdata»?
De fleste CoddyKit-leksjoner tar omtrent 5–10 minutter. Hver leksjon er kort og interaktiv, slik at De gjør jevne fremskritt og kan fortsette akkurat der De slapp – både på nettet og i appen.
Kan jeg skrive og kjøre kode i denne Claude Architect-leksjonen?
Ja. Alle Claude Architect-leksjoner har en innebygd kodeeditor, slik at De kan skrive og kjøre ekte kode direkte i nettleseren og få umiddelbar tilbakemelding fra AI – uten lokal konfigurering.