Claude Code workflow schema: agent 결과를 JSON으로 안정화하는 법 | DAKER 커뮤니티

Claude Code workflow schema: agent 결과를 JSON으로 안정화하는 법

Claude Code workflow schema란, workflow 안의 agent({schema}) 결과를 정해진 JSON 구조로 받도록 만드는 방식입니다. 2026년 6월 24일 기준 changelog 2.1.187은 --json-schema와 workflow agent({schema}) structured output의 반복 호출 문제를 수정했으므로, 팀 자동화 결과 수집 방식을 다시 점검할 만합니다.

클로드 코드 workflow schema로 subagent 결과를 표준 JSON으로 모으는 대표 카드.

Claude Code workflow schema는 언제 필요한가요?

한 줄 요약: 여러 subagent가 낸 결과를 사람이 읽는 문장 대신 프로그램이 검증 가능한 필드로 모을 때 필요합니다.

팀 자동화에서 "리뷰 요약해줘", "테스트 결과 정리해줘"라고만 하면 결과 형식이 매번 조금씩 달라집니다. 사람에게는 괜찮아도 CI, 대시보드, 이슈 생성, 품질 게이트로 넘기려면 status, findings, files, next_actions처럼 고정 필드가 필요합니다. workflow schema는 이 구간에서 결과를 JSON 계약으로 고정하는 역할을 합니다.

DAKER의 Claude Code subagent hooks는 agent 시작과 종료 시점을 묶는 법을 다뤘고, Claude Code MCP 재연결 점검은 외부 도구 상태를 분류하는 법을 다뤘습니다. 이번 글은 그 다음 단계로, 여러 agent 결과를 기계가 읽기 쉬운 구조로 받는 방법에 집중합니다.

2.1.187에서 구조화 출력은 무엇이 안정화됐나요?

공식 changelog 2.1.187은 두 가지를 명시합니다. --json-schema와 workflow agent({schema}) structured output에서, 성공 후 모델이 StructuredOutput을 무한히 다시 호출할 수 있던 문제가 수정됐고, follow-up turn에서도 구조화 출력이 더 안정적으로 반환되도록 고쳐졌습니다.

상황

구조화 전

schema 사용 후

리뷰 결과 수집

문장형 요약이 매번 달라짐

severity, file, line, recommendation 필드로 정리

테스트 자동화

"대체로 통과" 같은 애매한 표현 가능

passed, failed, command, evidence 필드로 분리

보안 점검

위험 항목이 본문 속에 섞임

risk_level, secret_paths, required_action으로 분리

후속 자동화

사람이 다시 읽고 복사해야 함

JSON을 파싱해 이슈, PR 코멘트, 리포트로 연결

단, schema는 사실을 만들어 주지 않습니다. agent가 실행한 명령, 읽은 파일, 공식 문서 확인 여부 같은 evidence가 있어야 JSON 필드도 신뢰할 수 있습니다.

단계별 사용법: schema 결과를 어떻게 설계하나요?

  1. 먼저 사람이 실제로 쓸 필드를 정합니다. 예: status, summary, findings, evidence, next_actions.

  2. 필수 필드와 선택 필드를 나눕니다. 모든 agent에게 모든 필드를 강제하면 불필요한 빈값이 늘어납니다.

  3. enum은 적게 둡니다. 예: status는 pass, needs_fix, blocked 정도면 충분합니다.

  4. subagent에게 "모르면 null"과 "추정 금지"를 명시합니다.

  5. workflow에서는 agent별 JSON을 합친 뒤, 최종 요약은 별도 단계에서 만듭니다.

  6. schema validation 실패가 반복되면 자동 재시도만 늘리지 말고 prompt와 필드를 줄입니다.

  7. 최종 결과에는 실행한 테스트와 실행하지 못한 검증을 분리해 남깁니다.

schema 설계, subagent 실행, JSON 검증, 재시도 한계 기록을 나누는 workflow 체크리스트.

짧은 예시: 코드 리뷰 결과 schema는 어떻게 잡나요?

코드 리뷰 subagent 결과를 다음 필드로 반환하게 설계한다.

status: "pass" | "needs_fix" | "blocked"
summary: 한 문장 요약
findings: 문제 목록
evidence: 실행한 명령, 읽은 파일, 확인한 문서
next_actions: 사람이 바로 할 일

규칙:
- 확인하지 못한 내용은 추정하지 않는다.
- severity는 high, medium, low 중 하나만 쓴다.
- line 정보가 없으면 file까지만 적고 line은 null로 둔다.

실제 workflow에서는 이 계약을 prompt와 schema 양쪽에 맞춰야 합니다. schema만 만들고 prompt가 "자유롭게 설명해줘"에 머물면 출력이 흔들릴 수 있습니다.

팀 적용 체크리스트는 무엇인가요?

공식 출처는 어디에서 확인했나요?

2026년 6월 24일 기준 Claude Code CHANGELOG.md 2.1.187, Agent SDK TypeScript reference의 Workflow tool 설명, Common workflows documentation을 확인했습니다. 공개 본문에는 DAKER 운영 정책에 맞춰 DAKER 내부 링크만 연결했습니다.

FAQ

workflow schema는 output style과 같은 기능인가요?

아닙니다. output style은 Claude의 응답 방식과 톤을 바꾸는 설정이고, schema는 결과 데이터 구조를 고정하는 계약에 가깝습니다.

모든 subagent 결과를 JSON으로 받아야 하나요?

아닙니다. 사람이 읽고 끝나는 조사나 설명은 자연어가 더 낫습니다. 자동화, CI, 리포트, 대시보드로 넘길 결과만 schema로 고정하세요.

schema가 있으면 hallucination이 사라지나요?

사라지지 않습니다. schema는 형식을 안정화할 뿐입니다. 근거 없는 값이 들어가지 않도록 evidence 필드, "모르면 null" 규칙, 검증 단계가 필요합니다.

validation 실패가 반복되면 어떻게 하나요?

필드 수를 줄이고 enum을 단순화하세요. changelog 2.1.187은 반복 호출 문제를 고쳤지만, 복잡한 schema 자체가 나쁜 프롬프트를 해결해 주지는 않습니다.

다음 팀 workflow를 만들 때는 먼저 결과 JSON을 받을 사람이나 시스템을 정하고, 그쪽이 실제로 읽을 필드만 schema에 남겨 보세요.

대표 이미지: 클로드 코드 workflow schema JSON 안정화 만화 카드

체크리스트 이미지: agent schema 적용 전후 점검 카드

Redirecting to Claude Code workflow schema: agent 결과를 JSON으로 안정화하는 법 | DAKER 커뮤니티...