Claude Architect · Lektion

Strukturerad utdata

--output-format json med ett schema för parsning.

Lektion 2 av 413 steg

Strukturerad utdata är en gratis lektion i Claude Architect på CoddyKit. Detta är lektion 2 av 4. Du kan läsa vilka 3 lektioner som helst i den här lärvägen kostnadsfritt i sin helhet – därefter låser CoddyKit PRO upp alla lektioner, plus praktisk övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Den ingår i lärvägen för Claude Architect, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i Claude Architect innehåller totalt 4 lektioner.

Varför strukturerad output är viktigt i CI/CD

När du kör Claude Code i en pipeline är det inte en människa som läser resultatet – det är ett skript. Ett CI-jobb behöver ett stabilt, maskinläsbart svar så att det kan underkänna bygget, publicera en kommentar eller blockera en merge.

Två flaggor gör detta möjligt:

-p (eller --print) kör Claude Code icke-interaktivt – vilket krävs i alla pipelines.
--output-format json returnerar ett tolkningsbart resultat i stället för fri text.

Den här lektionen är Domain 4 (Prompt Engineering & Structured Output) i kombination med Scenario 5 (Claude Code for CI/CD).

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

Problemet med fri text

Om du låter modellen svara i löptext måste pipelinen skrapa texten med reguljära uttryck – räkna ord och leta efter fraser som "looks good" eller "found issues". Det är skört och ett klassiskt antimönster.

Samma regel gäller den agentiska loopen: avsluta baserat på en stop_reason, aldrig genom att tolka text efter ord som "done". I CI avgör du godkänt/underkänt utifrån strukturerade fält, aldrig utifrån fri text.

Strukturerad output ersätter skör textsökning med ett kontrakt som ditt skript kan lita på.

Lägga till ett schema

--output-format json ger dig JSON, men vanlig JSON kan fortfarande variera i struktur. Kombinera den med ett JSON Schema så att outputen alltid innehåller exakt de fält som pipelinen förväntar sig.

Ett schema ger två garantier:

Det eliminerar syntaxfel – ingen ofullständig JSON som får din parser att krascha.
Det framtvingar obligatoriska fält – fälten du markerar som obligatoriska finns alltid med.

Schemabegränsad output är samma mekanism som driver verktygsanvändning: tool_use + JSON Schema är hur Claude returnerar tillförlitliga strukturerade data.

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

Utforma issue-objektet

Gör varje fynd till ett exakt objekt som pipelinen kan agera på. Ett bra granskningsschema ger varje problem en plats, en allvarlighetsgrad och en förklaring – så att jobbet kan annotera den exakta raden.

Använd en enum för allvarlighetsgrad så att värdena förblir konsekventa mellan körningar. Allvarlighetsgrader i fri text, som "kinda bad", kan inte tolkas.

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

Obligatoriska fält: den gyllene regeln

Markera ett fält som required endast om det alltid finns. Det här är den regel för strukturerad output som testas allra oftast.

Om du kräver ett fält som kan saknas – exempelvis line för ett projektomfattande problem som inte gäller någon specifik rad – kommer modellen att fabricera ett värde för att uppfylla schemat. Det påhittade radnumret leder sedan till en felaktig CI-annotering.

I föregående scen lämnades line avsiktligt ut från required: alla problem kan inte kopplas till en enda rad.

Enum + en reservväg med "other"

Enum håller värden rena, men en strikt enum kan begränsa modellen när verkligheten inte passar in i någon kategori. Det utbyggbara mönstret är att lägga till enum-värdet "other" samt ett detaljfält i fri text.

Modellen kan då hålla sig inom schemat i de vanliga fallen och ändå rapportera det oväntade utan att hitta på en felaktig kategori.

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

Garantera struktur med tool_choice

När du anropar Claude via SDK:t i stället för CLI:t garanterar du strukturerad output genom att kombinera ett verktyg vars input_schema är ditt JSON Schema med rätt tool_choice:

"auto" – modellen kan svara med text ELLER anropa ett verktyg (ingen garanti).
"any" – modellen MÅSTE anropa något verktyg, vilket garanterar strukturerad output.
{"type":"tool","name":"X"} – tvingar fram ett specifikt verktyg.

För en CI-granskning där du alltid behöver rapportobjektet ska du tvinga fram det exakta verktyget med namn.

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}],
)

Tolkar CI-resultatet

I pipelinen läser du JSON och förgrenar sedan baserat på ett fält – aldrig på löptexten. Hämta den strukturerade nyttolasten och låt resultatet avgöra exit-koden.

Eftersom schemat markerade verdict och issues som obligatoriska behöver den här koden aldrig gissa om nycklarna finns.

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)

Validera och försök sedan igen med feedback

Även med ett schema kan ett värde vara semantiskt fel (en felaktig aritmetisk totalsumma eller en felaktigt formaterad referens). Validera det tolkade objektet med kontroller av Pydantic-typ och använd retry-with-feedback vid strukturella fel eller formatfel.

Skicka tre saker till modellen: den ursprungliga indata, den felaktiga output som den producerade och det exakta valideringsfelet. Detta åtgärdar formatfel, strukturella fel och aritmetiska fel.

Viktig begränsning: retry hjälper INTE när informationen helt enkelt saknas i källan – ingen mängd nya promptar kan hitta på data som inte finns där.

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))

Granska i en isolerad session

Om samma konversation som genererade koden också granskar den behåller granskaren sitt eget resonemang och kommer inte att ifrågasätta sig själv – självgranskning i samma session är ett antimönster.

Kör den strukturerade granskningen i en isolerad, ny session. En oberoende instans är mycket bättre på att upptäcka verkliga fel. Detta passar naturligt ihop med strukturerad output: en ren session in, en ren JSON-rapport ut.

Finjustera prompten med tydliga kriterier ("flagga en kommentar endast när den motsäger koden") för att minimera falska positiva resultat som annars skulle blockera bra merningar.

Blockerande kontroller kontra granskningar över natten

En CI-kontroll före merge är blockerande och tidskänslig – kör den synkront med -p --output-format json. Det är fel att använda Message Batches API här: batchar är 50 % billigare men har ingen latens-SLA, ett tidsfönster på upp till 24 timmar och saknar stöd för flerturnsverktygsanrop.

Reservera Batch API för icke-blockerande jobb – en granskning av hela kodarkivet över natten eller en nattlig rapport – där custom_id kopplar ihop varje begäran och du skickar in endast misslyckanden på nytt.

Snabbkontroll

Tillämpa reglerna för strukturerad output på ett verkligt beslut i en pipeline.

Besvara frågan i den interaktiva lektionen

Sammanfattning: Strukturerad output i CI/CD

Viktiga slutsatser:

Kör Claude Code i pipelines med -p (icke-interaktivt) och --output-format json samt ett schema; förgrena baserat på fält, aldrig på löptext.
Ett JSON Schema eliminerar syntaxfel och framtvingar obligatoriska fält.
Markera ett fält som obligatoriskt ENDAST om det alltid finns – om du kräver ett fält som kan saknas leder det till fabricering.
Använd enum med värdet "other" + ett detaljfält för utbyggbarhet.
Via SDK:t garanterar tool_choice "any" eller ett framtvingat verktyg strukturerad output; "auto" gör det inte.
Validera (med Pydantic-liknande kontroller) och använd retry-with-feedback (ursprunglig indata + felaktig output + exakt fel) vid formatfel – men nya försök kan inte tillföra data som saknas.
Granska i en isolerad, ny session, inte i den session som genererade koden; minimera falska positiva resultat med tydliga kriterier.
Blockerande kontroll = synkron; Batch API endast för icke-blockerande jobb över natten.

Gratis att börja

Lär dig Python med en AI-lärare – gratis

Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.

Kurser: 26
Lektioner: 104

Börja lära dig gratis Visa hela kursen

Vanliga frågor

Är lektionen ”Strukturerad utdata” gratis?

Ja – du kan läsa vilka 3 lektioner som helst i lärvägen Claude Architect, inklusive ”Strukturerad utdata”, kostnadsfritt i sin helhet här på webben. Därefter låser CoddyKit PRO upp alla lektioner, plus interaktiv övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Kursen i Claude Architect innehåller totalt 4 lektioner.

Vad lär jag mig i ”Strukturerad utdata”?

--output-format json med ett schema för parsning. Ni övar på Claude Architect med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.

Behöver jag någon erfarenhet för att börja lära mig Claude Architect?

Du behöver inga förkunskaper. Utbildningen i Claude Architect på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 2 av 4.

Hur lång tid tar lektionen ”Strukturerad utdata”?

De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.

Kan jag skriva och köra kod i den här Claude Architect-lektionen?

Ja. Varje Claude Architect-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.

Alla lektioner i den här kursen

← Tillbaka till Claude Architect