Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code Skills 설계 시 에러 출력을 JSON 형식으로 구조화해야 하는 이유와 그 이점을 설명합니다. 에이전트가 실패 원인을 정확히 해석하여 다음 행동을 결정할 수 있도록 하는 통신 프로토콜로서의 JSON 활용법을 다룹니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기이 기사는 playpark Blog에서 전재되었습니다.
Claude Code Skills가 늘어나면, "스크립트가 실패했는데도 정상으로 처리되는" 문제가 발생합니다.
AI 에이전트는 스크립트의 출력을 해석하여 다음 행동을 결정합니다. 이때 에러 정보가 구조화되어 있지 않으면:
"에러는 발생했지만, 이유는 알 수 없는" 상황은 인간에게도 시간을 소모하게 만들지만, AI 에이전트에게는 구조화된 데이터가 없으면 말 그대로 해석이 불가능합니다.
| 접근 방식 | 장점 | 단점 |
|---|---|---|
| exit code만 사용 | 구현이 가장 단순함 | 실패 이유를 알 수 없음, 에이전트 측에서 해석 불가 |
| 로그 파일에 기록 | 상세 로그를 남길 수 있음 | 실시간 파악이 어려움, 파일 경로 관리가 필요함 |
| stderr에 JSON 출력 (채택) | 구조화되어 있어 에이전트가 해석 가능, stdout과 분리 가능 | 헬퍼 함수(Helper Function)가 필요함 |
Claude Code의 에이전트는 stdout을 데이터로, stderr를 에러 정보로 구분하여 처리할 수 있습니다. JSON으로 출력함으로써, SKILL.md 측에서 jq를 사용하여 실패 이유를 추출하고, 다음 행동(재시도할지, 다른 접근 방식을 시도할지)을 판단할 수 있습니다.
exit code만으로는 "실패했다"라는 사실만 알 수 있습니다. JSON화하면 "어떤 에러로", "어떤 exit code로" 실패했는지를 즉시 파악할 수 있습니다. 이것이 에이전트 간의 신뢰할 수 있는 통신 프로토콜이 됩니다.
공통 라이브러리에 die_json 헬퍼 함수를 정의합니다:
die_json() {
local msg="$1"
local code="${2:-1}"
...
입력 검증(Input Validation)도 이 패턴으로 통일합니다:
VALID_CATEGORIES="logic state external environment"
local valid=false
for v in $VALID_CATEGORIES; do
...
상태 파일의 초기화에서는 jq -n을 사용하여 스키마를 확정합니다:
jq -n \
--arg target "$target" \
--arg scope "$scope" \
...
version 필드를 넣는 이유는 스키마 변경 시 호출 측에서 "이것은 구형 포맷이다"라고 감지할 수 있도록 하기 위함입니다.
Skill이 다른 Skill로부터 호출되는 구성이거나, AI 에이전트가 스크립트 출력을 해석하여 판단을 내리는 구성이라면, JSON화는 빠른 단계에서 도입할 가치가 있습니다.
Skill이 단독으로 완결되어 인간이 로그를 확인하는 운용 방식이라면 exit code만으로도 충분합니다. 다만, Skill이 10개를 넘어서며 상호 호출이 증가하는 시점이 이 설계를 도입할 임계치(Threshold)의 기준입니다.
이 기사에서는 JSON 계약을 통한 타입 안전성(Type Safety)의 선정 이유를 해설했습니다.
:page_facing_up: :page_facing_up:
【Claude Code】Skills 설계 패턴 상급편 - 타입 안전성·에러 핸들링·Skill 간 연계 구현 에서는 더욱 상세하게:
jq로 deep merge하는 구현)를 다루고 있습니다.
playpark LLC - 업무 자동화·AI 활용·Web 개발