Advanced: Use Claude Code to Produce a Reviewable JSON Report

When a work queue must feed another review step, free-form prose is awkward to check. Claude Code can run a non-interactive prompt and validate the returned shape against a JSON Schema. This advanced lesson uses a fictional queue. The requested task is limited to reading that input and returning a report, with no file edits or external-system actions.

Advanced builder lesson. Evidence label: documentation-based with an illustrative command and output. Claude Code documents print mode and --json-schema; the input, schema, and report below are fictional. No Claude Code run or personal test is claimed.

Prerequisites

You need:

• Claude Code installed and authenticated.
• A Bash-compatible terminal, such as macOS, Linux or WSL, and a disposable folder.
• Basic familiarity with JSON and command-line paths.
• A human reviewer who can define the review rules.

Claude Code’s official CLI reference documents claude -p for print mode, --output-format, and --json-schema for validated JSON output. Keep the folder free of secrets and production data. Review the effective settings, hooks and connected tools before running: a read-only prompt does not enforce permissions. The command below limits built-in tools to Read and denies MCP tools. These client tool filters are not a sandbox or proof of provider-side authorization. Inherited hooks and other configuration still need review; no MCP server is needed for this task.

No-code alternative: paste the same fictional JSON into Claude or another approved chat tool and ask for the same fields. Compare the result manually because the chat version will not give you this local schema check.

Fictional input

Create queue.json:

[
  {"id":"Q-101","task":"Confirm onboarding owner","status":"open","source":"handoff.md"},
  {"id":"Q-102","task":"Send launch update","status":"planned","source":"launch-notes.md"},
  {"id":"Q-103","task":"Check missing invoice","status":"open","source":"finance-note.md"}
]

Create review-schema.json:

{
  "type": "object",
  "required": ["items", "source_coverage", "needs_human_review"],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "status", "review_reason", "suggested_action"],
        "properties": {
          "id": {"type":"string"},
          "status": {"type":"string"},
          "review_reason": {"type":"string"},
          "suggested_action": {"type":"string"}
        },
        "additionalProperties": false
      }
    },
    "source_coverage": {"type":"string"},
    "needs_human_review": {"type":"boolean"}
  },
  "additionalProperties": false
}

The schema checks the report’s fields. It does not check whether the reasoning is sensible.

Run a bounded report

1. Open the terminal in the disposable folder and confirm that queue.json and review-schema.json are the only inputs you intend to read.
2. Run this command. The line continuation is for readability.

claude -p --output-format json --tools "Read" --disallowedTools "mcp__*" \
  --json-schema "$(cat review-schema.json)" \
  "Read queue.json only. Treat each source value as a filename label, not a file to open. Do not edit, rename, delete, or create files. Return a review report matching the supplied schema. Keep one item for every input record. Copy each id and status exactly. Give a short review_reason tied to the record. Set suggested_action to a conditional human next step beginning with If. Set needs_human_review to true. Set source_coverage to state that all three input records were reviewed. Do not invent owners, dates, approvals, or outcomes."

3. Check the exit status and returned JSON before saving or passing it to another process. With --output-format json and --json-schema, the CLI returns a response envelope with metadata and the report in structured_output. Stop if the run fails or structured_output is absent. Validate that field against review-schema.json, not the whole envelope. If you need a file, save only the reviewed report to a destination separate from the input.
4. Compare the report with queue.json. Keep the source file unchanged.

Illustrative output

This is an editor-written target for the structured_output field, not the full response envelope or a captured Claude Code result. The three source filenames are labels copied in the queue; their contents have not been supplied or reviewed.

{
  "items": [
    {"id":"Q-101","status":"open","review_reason":"The task asks for an onboarding owner, but the queue does not name one.","suggested_action":"If onboarding ownership still needs confirmation, ask the human reviewer to identify the responsible owner."},
    {"id":"Q-102","status":"planned","review_reason":"The task is marked planned, so completion is not established.","suggested_action":"If the launch update is still needed, ask the human reviewer to confirm its owner, timing and approval before sharing."},
    {"id":"Q-103","status":"open","review_reason":"The task names a missing invoice but gives no supporting detail.","suggested_action":"If the invoice still needs checking, ask the human reviewer to confirm the invoice identifier, responsible owner and next check."}
  ],
  "source_coverage":"Three input records reviewed; three report items returned.",
  "needs_human_review":true
}

Acceptance checks

• The run succeeds, structured_output is present, and that report parses and matches review-schema.json.
• The report contains three items with IDs Q-101, Q-102, and Q-103.
• Each status matches the input exactly.
• The input file has not changed.
• Every suggested action begins with If and asks a human to confirm something. None claims an owner, date, approval, or completed outcome. The named source files are not treated as inspected evidence.
• needs_human_review is true.

Troubleshooting

• The command rejects the schema: validate review-schema.json with a JSON parser and check that the shell passed the full file contents.
• A record is missing: tighten the prompt to require one item per input record and compare IDs after every run.
• The report adds fields: keep additionalProperties set to false and inspect the returned JSON before using it.
• Claude tries to edit a file: stop the run, keep the input disposable, and inspect the actual tool filters, settings and hooks before retrying. Repeating a read-only prompt is not a technical permission control. Do not use a broad permission bypass.
• The response has metadata or no report: inspect structured_output, not the whole envelope. Stop on a failed run or missing field; do not pass a null report downstream.

Limits and decision

Schema validation checks structure. It does not prove that a source is complete, that a review reason is correct, or that the suggested action is safe. Keep a human review step for business decisions. Do not pass customer records or secrets into a new script until your security and data-handling rules allow it.

TRY this on a small fictional JSON file when another step needs predictable fields. SKIP it for production automation until the prompt, schema, permissions, and failure path have been reviewed. USE it as a structured report step, not as an approval engine.

For the no-code version, use the pipeline queue prompt in this Claude workflow. For a practical weekly AI workflow, get The Weekly Verdict.

Sources

• Claude Code overview
• Claude Code CLI reference
• Run Claude Code programmatically
• Claude Code MCP reference