Prompt 说"输出 JSON" → 73%。Schema 标志 → 99%

从研究文档提取结构化数据的三种方法，100 次运行的测试：

每层执行增加可量化的可靠性。光 prompt 有 27% 的运行有结构问题。格式标志到 89%。Schema 标志达到 99% 且零意外字段。

两个标志

--output-format json — 确保输出是合法 JSON。不控制字段名、嵌套或结构。Claude 可能用”urgency”代替”priority”——两者都是合法 JSON，但下游仪表板坏了。

--json-schema '{...}' — 在生成时强制精确的字段名、嵌套、必填/可选字段和类型。Schema 说”priority”时 Claude 不能产出”urgency”。支持嵌套对象、条件可选和所有标准 JSON Schema 特性。

两个标志都需要 -p（打印模式）。--json-schema 标志特别只在打印模式可用——不带 -p 使用会产出”flag not recognized”错误。

完整 CI 命令

# 基本 JSON 输出
claude -p "Extract findings" --output-format json > findings.json

# Schema 约束的 JSON 输出
claude -p "Extract ticket metadata" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"ticket_id":{"type":"string"},"priority":{"type":"string"},"category":{"type":"string"},"summary":{"type":"string"}},"required":["ticket_id","priority","category","summary"]}' \
  > metadata.json

为什么 Prompt 指令不够

100 次只用 --output-format json 的 CI 运行：87 次产出了正确 JSON 和期望字段名。13 次用了”urgency”而不是”priority”。同样的 prompt，同样的输入数据。

这不是 bug。语言模型自然替换同义词。“Priority”和”urgency”语义等价——模型看不出区别。但仪表板 API 精确要求”priority”。

--json-schema 通过在结构层面强制精确属性名消除了这种变异。100/100 次运行都产出了指定的”priority”。

详细 prompt 指令（“用字段名’priority’，不是’urgency’“）减少变异但不能保证。结构性执行是唯一的保证。

两种输出，两次调用

当流水线既需要给 API 的结构化 JSON 又需要给 PR 评论的人类可读文本：

# 给 bug tracker API 的结构化 JSON
claude -p "Analyze for bugs" --output-format json --json-schema '{...}' > bugs.json

# 给 PR 评论的人类可读文本
claude -p "Summarize analysis for PR comment" > comment.txt

不要用分隔符在一次调用中合并两种格式。分隔符分隔的混合输出需要脆弱的拆分逻辑，有 JSON 损坏风险。分开的调用配合适当的格式标志产出干净、可预测的输出。

渐进式改进

从简单开始，按需加约束：

1. --output-format json — 确认 JSON 输出在流水线中能用
2. --json-schema — 在字段精度重要时加精确的结构执行
3. Schema 改进 — 随需求演进扩展 schema，加嵌套对象、可选字段和条件

Schema 能表达复杂结构：分组发现的嵌套对象、只在 critical 严重度时出现的可选”suggestion”字段、多结果的数组。JSON Schema 的完整特性集都可用。

不存在的东西

• --format json — 标志名不对。用 --output-format json。
• CLAUDE_FORMAT=json — 环境变量不存在。
• CLAUDE_OUTPUT_FORMAT=json — 环境变量不存在。
• 交互模式的 --json-schema — 只在 -p 下可用。

一句话总结： --output-format json 确保合法 JSON；--json-schema 确保精确的字段名、嵌套和结构——两者结合达到 99% 的 schema 合规率，prompt 单独只有 73%。