Claude Architect · Pelajaran

Output Berstruktur

--output-format json dengan skema untuk penghuraian

Pelajaran 2 daripada 413 langkah

Output Berstruktur ialah pelajaran Claude Architect percuma di CoddyKit. Ini ialah pelajaran 2 daripada 4. Sebanyak 3 pelajaran dalam laluan pembelajaran ini boleh dibaca sepenuhnya secara percuma — selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan praktikal dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Claude Architect, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Claude Architect merangkumi sejumlah 4 pelajaran.

Mengapa Output Berstruktur dalam CI/CD

Apabila anda menjalankan Claude Code dalam saluran paip, manusia tidak membaca hasilnya — skrip yang membacanya. Tugas CI memerlukan jawapan yang stabil dan boleh dihuraikan mesin supaya dapat menggagalkan binaan, menyiarkan komen, atau mengawal percantuman.

Dua bendera menjadikan perkara ini mungkin:

-p (atau --print) menjalankan Claude Code tanpa interaksi — diperlukan dalam mana-mana saluran paip.
--output-format json mengembalikan hasil yang boleh dihuraikan dan bukannya teks bebas.

Pelajaran ini ialah Domain 4 (Kejuruteraan Gesaan & Output Berstruktur) yang bertemu dengan Senario 5 (Claude Code untuk CI/CD).

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

Masalah Dengan Teks Bebas

Jika anda membenarkan model menjawab dalam bentuk prosa, saluran paip anda perlu mengikis prosa itu menggunakan ungkapan nalar — mengira perkataan dan mencari frasa seperti "looks good" atau "found issues". Pendekatan ini rapuh dan merupakan anti-corak klasik.

Peraturan yang sama terpakai pada gelung berasaskan ejen: anda menamatkan proses berdasarkan stop_reason, bukan dengan menghuraikan teks untuk mencari perkataan seperti "done". Dalam CI, tentukan lulus/gagal daripada medan berstruktur, bukan daripada teks bebas.

Output berstruktur menggantikan pengikisan teks yang rapuh dengan kontrak yang boleh dipercayai oleh skrip anda.

Menambahkan Skema

--output-format json memberikan JSON kepada anda, tetapi JSON biasa masih boleh berbeza bentuknya. Gabungkannya dengan Skema JSON supaya output sentiasa mempunyai medan tepat yang dijangka oleh saluran paip anda.

Skema memberikan dua jaminan:

Skema menghapuskan ralat sintaks — tiada JSON separa terbentuk yang boleh menyebabkan penghuraian anda gagal.
Skema menguatkuasakan medan wajib — medan yang anda tandakan sebagai wajib sentiasa wujud.

Output yang dikekang oleh skema menggunakan mekanisme yang sama seperti penggunaan alat: tool_use + Skema JSON ialah cara Claude mengembalikan data berstruktur yang boleh dipercayai.

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

Mereka Bentuk Objek Isu

Jadikan setiap penemuan sebagai objek tepat yang boleh diproses oleh saluran paip. Skema semakan yang baik memberikan setiap isu lokasi, keterukan dan penjelasan — supaya tugas itu boleh menganotasi baris yang tepat.

Gunakan enum untuk keterukan supaya nilainya konsisten merentas pelaksanaan. Keterukan dalam teks bebas seperti "kinda bad" tidak boleh dihuraikan.

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

Medan Wajib: Peraturan Emas

Tandakan medan sebagai required hanya jika medan itu sentiasa wujud. Ini ialah peraturan output berstruktur yang paling kerap diuji.

Jika anda mewajibkan medan yang mungkin tiada — contohnya line untuk penemuan seluruh projek yang tiada baris khusus — model akan mereka-reka nilai untuk memenuhi skema. Nombor baris yang dihalusinasikan itu kemudiannya menghasilkan anotasi CI yang salah.

Dalam babak sebelumnya, line sengaja tidak dimasukkan dalam required: tidak setiap isu boleh dipetakan kepada satu baris.

Enum + Jalan Keluar "other"

Enum memastikan nilai kekal kemas, tetapi enum yang tegar boleh mengehadkan model apabila realiti tidak sepadan dengan mana-mana kategori. Corak boleh diperluas: tambahkan nilai enum "other" bersama medan butiran teks bebas.

Kini model boleh kekal dalam skema untuk kes biasa dan masih melaporkan kes luar jangka tanpa mereka-reka kategori yang salah.

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

Menjamin Struktur Dengan tool_choice

Apabila anda memanggil Claude melalui SDK dan bukannya CLI, anda menjamin output berstruktur dengan menggabungkan alat yang input_schema-nya ialah Skema JSON anda dengan tool_choice yang betul:

"auto" — model boleh menjawab dalam teks OR memanggil alat (tiada jaminan).
"any" — model MUST memanggil sesuatu alat, yang menjamin output berstruktur.
{"type":"tool","name":"X"} — memaksa satu alat tertentu.

Untuk semakan CI yang sentiasa memerlukan objek laporan, paksa alat tepat berdasarkan namanya.

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

Menghuraikan Hasil CI

Dalam saluran paip, anda membaca JSON, kemudian membuat cabang berdasarkan medan — bukan berdasarkan prosa. Ambil muatan berstruktur dan biarkan keputusan menentukan kod keluar.

Oleh sebab skema menandakan verdict dan issues sebagai wajib, kod ini tidak perlu meneka sama ada kunci tersebut wujud.

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)

Sahkan, Kemudian Cuba Semula Dengan Maklum Balas

Walaupun dengan skema, sesuatu nilai boleh salah dari segi semantik (jumlah aritmetik yang salah atau rujukan yang cacat). Sahkan objek yang dihuraikan dengan pemeriksaan gaya Pydantic, dan untuk ralat struktur/format gunakan percubaan semula dengan maklum balas.

Hantar tiga perkara kepada model: input asal, output salah yang dihasilkannya, dan ralat pengesahan tepat. Ini membetulkan kesilapan format, struktur dan aritmetik.

Had penting: percubaan semula TIDAK membantu apabila maklumat itu sememangnya tiada dalam sumber — sebanyak mana pun gesaan semula tidak dapat mencipta data yang tiada.

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

Semak Dalam Sesi Berasingan

Jika perbualan yang sama yang menjana kod turut menyemaknya, penyemak mengekalkan penaakulannya sendiri dan tidak akan mencabar dirinya — semakan kendiri dalam sesi yang sama ialah anti-corak.

Jalankan semakan berstruktur dalam sesi berasingan dan baharu. Contoh bebas jauh lebih baik dalam mengesan kecacatan sebenar. Ini sepadan secara semula jadi dengan output berstruktur: sesi bersih masuk, laporan JSON bersih keluar.

Perhalus gesaan dengan kriteria eksplisit ("flag a comment only when it contradicts the code") untuk meminimumkan positif palsu yang boleh menyekat percantuman yang baik.

Pemeriksaan Menyekat berbanding Audit Semalaman

Pintu gerbang CI prcantum adalah menyekat dan sensitif terhadap masa — jalankannya secara segerak dengan -p --output-format json. Menggunakan API Kelompok Mesej di sini adalah salah: kelompok 50% lebih murah tetapi mempunyai tiada SLA kependaman, tempoh sehingga 24 jam, dan tidak menyokong panggilan alat berbilang giliran.

Simpan API Kelompok untuk tugas yang tidak menyekat — audit seluruh repositori semalaman atau laporan setiap malam — apabila custom_id mengaitkan setiap permintaan dan anda menghantar semula hanya kegagalan.

Pemeriksaan Pantas

Terapkan peraturan output berstruktur pada keputusan saluran paip sebenar.

Jawab dalam pelajaran interaktif

Ringkasan: Output Berstruktur dalam CI/CD

Perkara utama:

Dalam saluran paip, jalankan Claude Code dengan -p (tanpa interaksi) dan --output-format json bersama skema; buat cabang berdasarkan medan, bukan prosa.
Skema JSON menghapuskan ralat sintaks dan menguatkuasakan medan wajib.
Tandakan medan sebagai wajib ONLY jika medan itu sentiasa wujud — mewajibkan medan yang mungkin tiada menyebabkan rekaan nilai.
Gunakan enum dengan nilai "other" + medan butiran untuk kebolehkembangan.
Melalui SDK, tool_choice "any" atau alat yang dipaksa menjamin output berstruktur; "auto" tidak menjaminnya.
Sahkan (gaya Pydantic) dan gunakan percubaan semula dengan maklum balas (asal + output salah + ralat tepat) untuk ralat format — tetapi percubaan semula tidak dapat membekalkan data yang tiada.
Semak dalam sesi berasingan/baharu, bukan sesi yang menjana kod; minimunkan positif palsu dengan kriteria eksplisit.
Pintu gerbang menyekat = segerak; API Kelompok hanya untuk tugas semalaman yang tidak menyekat.

Percuma untuk bermula

Pelajari Python dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 26
Pelajaran: 104

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Output Berstruktur” percuma?

Ya — sebanyak 3 pelajaran dalam laluan pembelajaran Claude Architect, termasuk “Output Berstruktur”, boleh dibaca sepenuhnya secara percuma di web ini. Selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan interaktif dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Kursus Claude Architect merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Output Berstruktur”?

--output-format json dengan skema untuk penghuraian Anda berlatih Claude Architect menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan Claude Architect?

Tiada pengalaman terdahulu diperlukan. Pembelajaran Claude Architect di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 2 daripada 4.

Berapa lamakah pelajaran “Output Berstruktur” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran Claude Architect ini?

Ya. Setiap pelajaran Claude Architect menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

← Kembali ke Claude Architect