출력을 고정하는 법: JSON+Markdown 2트랙 표준으로 매번 같은 포맷 받기 — Claude Skills 실전 활용 매뉴얼 4/7

시리즈: Claude Skills 실전 활용 매뉴얼 (총 7편) | 4편

출력을 고정하는 법: JSON+Markdown 2트랙 표준으로 매번 같은 포맷 받기

Claude에게 같은 질문을 해도 매번 다른 형식으로 답이 나와서 후처리에 시간을 낭비하고 있지 않아? 이 글에서는 JSON과 Markdown 2트랙 전략으로 출력 포맷을 완전히 고정하고, 자동화 연동까지 바로 쓸 수 있는 표준 골격을 실전 예시와 함께 정리했어.

Summary

• JSON(기계용)과 Markdown(사람용)을 동시에 출력하면 자동화와 가독성을 둘 다 잡을 수 있어
• 표준 JSON 골격에 status, issues, meta 필드를 넣어두면 결과의 품질까지 추적 가능해
• SKILL.md에 출력 템플릿을 박아두면 Claude가 “빈칸 채우기”처럼 일관된 문서를 만들어줘
• 4가지 출력 패턴(JSON/Markdown/표·CSV/검증 체크리스트)을 상황별로 조합하면 어떤 업무든 커버돼

이 글의 대상

• Claude 출력을 노션, 스프레드시트, 자동화 도구에 바로 연결하고 싶은 사람
• 매번 출력 형식이 달라져서 후처리에 시간 쓰는 게 지긋지긋한 사람
• 스킬을 만들어봤는데 출력 품질이 들쭉날쭉한 사람

목차

1. 왜 출력 포맷을 고정해야 할까?
2. 2트랙 전략이란: 기계용 + 사람용
3. 표준 JSON 골격 뜯어보기
4. 4가지 출력 패턴 라이브러리
5. 운영 필드로 품질 추적하기
6. SKILL.md에 템플릿 박는 실전 예시
7. 흔한 실수와 해결법

---

1. 왜 출력 포맷을 고정해야 할까?

Claude는 똑똑하지만 “같은 형식으로 달라”고 해도 매번 미묘하게 다른 결과를 내놔. 한번은 불릿 리스트, 한번은 문단, 한번은 표… 이러면 후처리할 때마다 사람이 일일이 정리해야 하거든.

출력 포맷을 고정하면 이런 게 달라져:

고정 전	고정 후
매번 형식이 달라서 복붙 후 재가공	바로 복붙해서 사용 가능
자동화 연결 불가능	JSON 파싱으로 바로 연동
누락 항목이 생겨도 모름	필수 필드 빠지면 바로 보임
“지난번처럼 해줘”가 안 통함	템플릿 하나로 항상 동일

핵심은 이거야: 포맷을 고정하면 Claude의 출력이 “작품”에서 “부품”으로 바뀌어. 부품은 조립할 수 있고, 교체할 수 있고, 자동화할 수 있거든.

---

2. 2트랙 전략이란: 기계용 + 사람용

여기서 소개하는 핵심 아이디어가 바로 2트랙 출력이야.

• Part A — JSON: 자동화, 저장, 검색용. 코드나 다른 도구가 바로 파싱해서 쓸 수 있어.
• Part B — Markdown: 사람이 읽고 바로 붙여넣기용. 보고서나 노션에 그대로 가져다 쓰면 돼.

왜 두 개를 동시에 내냐고? 하나만 고르면 반드시 불편한 순간이 와:

상황	JSON만 있으면	Markdown만 있으면
팀원에게 공유	읽기 불편	OK
스프레드시트에 넣기	OK	수동 정리 필요
다음 스킬 입력으로 연결	OK	파싱 어려움
슬랙/노션에 붙여넣기	가독성 최악	OK

둘 다 출력하면 “어디에든 바로 쓸 수 있는 결과물”이 되는 거지.

스킬 프롬프트에 이렇게 적어두면 돼:

출력 형식:
## Part A: JSON
(구조화된 데이터)

## Part B: Markdown 보고서
(사람이 읽는 요약)

---

3. 표준 JSON 골격 뜯어보기

매번 JSON 구조를 새로 짜지 말고, 이 표준 골격을 기본 틀로 쓰면 편해:

{
  "status": "success",
  "message": "요약 및 액션아이템 생성 완료",
  "data": {
    "summary": "...",
    "action_items": []
  },
  "issues": [],
  "meta": {
    "created_at": "2026-03-11T09:00:00+09:00",
    "version": "1.0"
  }
}

각 필드가 하는 일을 정리해볼게:

필드	역할	왜 필요한지
status	결과 상태 표시	자동화에서 성공/실패 분기 처리에 필수
message	사람이 읽는 한줄 요약	로그 확인할 때 바로 맥락 파악
data	실제 결과 데이터	핵심 내용이 여기 들어감
issues	경고/주의 사항 목록	애매한 결과가 왜 나왔는지 추적 가능
meta	생성 시각, 버전	언제 만든 건지, 어떤 버전인지 기록

status 값은 3개면 충분해

복잡하게 만들지 말고 딱 세 가지만 써:

success  — 요청한 대로 완료
partial  — 일부만 완료 (issues에 이유 기록)
failure  — 실패 (issues에 원인 기록)

이렇게 단순화하면 자동화 코드에서 분기 처리가 깔끔해져. if status == "success" 한 줄이면 끝이거든.

issues 필드가 진짜 유용한 이유

issues 배열은 “왜 결과가 완벽하지 않은지”를 기록하는 곳이야:

"issues": [
  {
    "type": "warning",
    "field": "action_items[2].deadline",
    "message": "마감일이 명시되지 않아 추정값 사용"
  }
]

이걸 남겨두면 다음 실행에서 “지난번에 이런 문제가 있었으니 보정해줘”라고 이어갈 수 있어. 일종의 자기 수정 루프를 만드는 거지.

---

4. 4가지 출력 패턴 라이브러리

상황별로 골라 쓸 수 있는 4가지 패턴이야. SKILL.md에 필요한 패턴을 조합해서 넣으면 돼.

패턴 1: JSON 응답 (파싱 안정성 최우선)

자동화 파이프라인에 연결할 때 쓰는 패턴이야. 다른 도구나 코드가 이 결과를 바로 읽어야 할 때 최적이지.

{
  "status": "success",
  "data": {
    "emails_classified": 12,
    "categories": {
      "urgent": 3,
      "normal": 7,
      "spam": 2
    }
  },
  "issues": [],
  "meta": { "created_at": "...", "version": "1.0" }
}

패턴 2: Markdown 보고서 (사람이 바로 쓰기)

보고서, 제안서, 회의록 요약처럼 사람이 읽고 바로 활용할 문서에 쓰는 패턴이야.

## 요약
핵심 내용 3줄 정리

## 상세 분석
### 항목 1
...
### 항목 2
...

## 액션 아이템
| 항목 | 담당 | 마감 |
|------|------|------|
| ... | ... | ... |

패턴 3: 표/CSV (스프레드시트 친화)

구글 시트나 엑셀에 바로 붙여넣어야 할 때 쓰는 패턴이야. 파이프(|) 구분 표나 CSV 형식으로 출력하면 복붙 한 번에 끝나거든.

이름,분류,우선순위,마감일
"프로젝트 A 보고서",보고서,높음,2026-03-15
"클라이언트 미팅 준비",미팅,중간,2026-03-12
"주간 회의록 정리",문서,낮음,2026-03-14

패턴 4: 검증 체크리스트 (별도 JSON)

결과물의 품질을 함께 검증할 때 쓰는 패턴이야. 본문 출력과 별도로 “이 결과가 OK인지” 체크리스트를 JSON으로 따로 뽑아내는 거지.

{
  "validation": {
    "required_sections_present": true,
    "data_sources_cited": true,
    "word_count_in_range": true,
    "tone_consistent": false,
    "issues": ["3번째 섹션에서 격식체 혼재 발견"]
  }
}

이 패턴은 품질 관리 자동화에 아주 좋아. 출력물이 기준에 맞는지 사람이 일일이 확인하지 않아도 되거든.

---

5. 운영 필드로 품질 추적하기

실무에서 스킬을 반복적으로 쓰다 보면 “이 결과가 언제 만들어진 건지”, “어떤 버전 프롬프트로 만든 건지”가 중요해져. 그래서 운영 필드 3종 세트를 꼭 넣어두는 게 좋아:

운영 필드	용도	예시
status	성공/부분/실패 구분	"partial"
issues	경고, 에러, 추정값 사용 등 기록	[{"type":"warning","message":"..."}]
meta	생성 시각, 프롬프트 버전	{"created_at":"...","version":"2.1"}

특히 version 필드는 프롬프트를 수정할 때마다 올려주면, 나중에 “버전 1.0 결과”와 “버전 2.0 결과”를 비교할 수 있어서 스킬 개선 이력을 추적하기 편하거든.

실전 팁: issues로 자기 수정 루프 만들기

1회차: issues에 "마감일 추정값 사용" 기록
    ↓
2회차: "지난번 issues를 참고해서, 마감일이 확실한 것만 넣어줘"
    ↓
3회차: issues 비어있음 → 품질 안정화 확인

이런 식으로 issues 필드를 다음 실행의 입력으로 활용하면, Claude가 스스로 결과를 개선하는 루프를 만들 수 있어.

---

6. SKILL.md에 템플릿 박는 실전 예시

자, 여기가 실전의 핵심이야. SKILL.md 파일에 출력 템플릿을 명시적으로 넣어두면 Claude가 매번 그 형식을 따르게 돼. 빈칸 채우기처럼 동작하는 거지.

예시: 회의록 요약 스킬의 출력 템플릿

## 출력 형식

### Part A: JSON
아래 구조를 정확히 따라 출력해.

\```json
{
  "status": "success | partial | failure",
  "message": "한줄 요약",
  "data": {
    "summary": "3문장 이내 요약",
    "decisions": ["결정사항 1", "결정사항 2"],
    "action_items": [
      {
        "task": "할 일",
        "assignee": "담당자 (불확실하면 '미정')",
        "priority": "상|중|하",
        "deadline": "YYYY-MM-DD (불확실하면 '미정')"
      }
    ]
  },
  "issues": [],
  "meta": {
    "created_at": "ISO 8601",
    "version": "1.0"
  }
}
\```

### Part B: Markdown 보고서

## 회의 요약
(3문장 요약)

## 결정 사항
- 결정 1
- 결정 2

## 액션 아이템
| 할 일 | 담당 | 우선순위 | 마감 |
|-------|------|----------|------|
| ... | ... | ... | ... |

## 주의 사항
(issues가 있으면 여기에 사람이 읽을 수 있는 형태로 기록)

이렇게 SKILL.md에 박아두면 Claude는 “이 빈칸을 채워야 한다”고 인식해서, 실행할 때마다 동일한 구조로 결과를 내놔. 필드 누락도 크게 줄어들어.

템플릿 작성 꿀팁

1. 모든 필드에 예시값을 넣어둬 — Claude가 형식을 오해할 여지가 줄어들어
2. 불확실한 경우의 기본값을 명시해 — “불확실하면 ‘미정’으로 표기”처럼
3. 필수 vs 선택 필드를 구분해 — 필수 필드만 먼저 완성하도록 유도
4. 패턴 4(검증 체크리스트)를 같이 넣으면 — 출력 품질까지 자동으로 확인 가능

---

7. 흔한 실수와 해결법

실수 1: JSON에 설명을 섞어 넣기

// 이렇게 하면 파싱이 깨져!
{
  "summary": "요약입니다",  // 이 주석은 JSON에서 에러남
}

해결: JSON 블록 안에는 순수 JSON만 넣고, 설명은 Part B(Markdown)에 따로 쓰도록 템플릿에 명시해.

실수 2: status 값을 너무 세분화하기

success, partial_success, mostly_done, needs_review… 이러면 자동화 코드가 복잡해지고, Claude도 어떤 상태를 골라야 할지 헷갈려해.

해결: success, partial, failure 딱 3개만 써. 세부 내용은 issues 배열에 기록하면 돼.

실수 3: 템플릿 없이 “지난번처럼 해줘”

대화가 길어지면 Claude가 이전 출력을 정확히 기억하지 못할 수 있어. “아까처럼”은 사람도 기억 못하는데 AI한테 기대하면 안 되지.

해결: SKILL.md에 템플릿을 박아두면 매번 같은 형식이 보장돼. 기억에 의존하지 않는 거야.

---

핵심 정리

1. JSON(기계용) + Markdown(사람용) 2트랙으로 출력하면 어디에든 바로 쓸 수 있어
2. 표준 JSON 골격(status/data/issues/meta)을 기본 틀로 쓰면 일관성이 확보돼
3. 4가지 출력 패턴(JSON/Markdown/표·CSV/검증 체크리스트)을 상황별로 조합해
4. SKILL.md에 출력 템플릿을 명시하면 Claude가 "빈칸 채우기"로 동작해서 포맷이 고정돼

FAQ

Q: JSON과 Markdown을 둘 다 출력하면 응답이 너무 길어지지 않아?

A. 조금 길어지는 건 맞아. 하지만 후처리 시간을 생각하면 훨씬 이득이야. 출력이 길어지는 게 신경 쓰이면 JSON은 핵심 데이터만, Markdown은 요약만 넣도록 템플릿에서 범위를 제한하면 돼. “data 필드에는 상위 5건만”처럼 상한선을 정해주는 것도 방법이야.

Q: 꼭 JSON이어야 해? YAML이나 다른 형식은 안 돼?

A. JSON을 권장하는 이유는 Claude가 JSON 형식에 가장 익숙하고, 파싱 라이브러리도 어떤 언어에든 있어서 연동이 편하기 때문이야. YAML도 가능하긴 한데, 들여쓰기 실수로 깨지는 경우가 종종 있어서 안정성 면에서 JSON이 낫거든.

Q: issues 필드에 뭘 넣어야 할지 모르겠어. 구체적인 예시를 더 알려줘.

A. 대표적인 유형을 정리하면 이래: “입력 데이터에 누락 항목 있음”, “날짜가 명시되지 않아 추정값 사용”, “출처 링크 접근 불가로 요약 생략”, “동일 항목 중복 감지”. 이런 식으로 왜 결과가 100%가 아닌지 사유를 적어두면 돼.

Q: status가 partial일 때 자동화에서 어떻게 처리하면 좋아?

A. “partial이면 issues 배열을 읽어서 사람에게 알림을 보내라”는 식으로 처리하면 돼. 완전 자동화는 success일 때만, partial이면 사람이 확인 후 진행하는 반자동 방식이 안전해.

Q: SKILL.md에 템플릿을 넣었는데 Claude가 가끔 무시해. 왜 그래?

A. 두 가지 원인이 흔해. 첫째, 템플릿이 너무 복잡하면 일부를 생략하는 경향이 있어 — 핵심 필드 10개 이내로 줄여봐. 둘째, 대화 맥락이 길어지면 SKILL.md보다 최근 대화 내용을 우선시할 수 있어 — 이럴 때는 “SKILL.md의 출력 형식을 정확히 따라줘”라고 한 번 더 명시해주면 효과적이야.

Q: 패턴 3(표/CSV)은 언제 쓰는 게 좋아?

A. 결과를 스프레드시트에 바로 넣어야 할 때 최고야. 예를 들어 “이번 달 경비 20건을 분류해줘” 같은 작업에서 CSV로 받으면 구글 시트에 복붙 한 번으로 끝나거든. 반대로 결과를 다른 스킬의 입력으로 쓸 거면 JSON이 더 나아.

Q: 검증 체크리스트(패턴 4)는 매번 넣어야 해?

A. 매번 넣을 필요는 없어. 품질이 중요한 작업(보고서, 제안서, 외부 공유 문서)에만 넣으면 돼. 단순 메모 정리 같은 건 패턴 1+2 조합이면 충분해. 체크리스트는 “실수하면 큰일 나는 작업”에 보험으로 거는 거라고 생각하면 편해.

Q: 기존에 쓰던 프롬프트에 2트랙을 적용하려면 어떻게 수정해?

A. 기존 프롬프트 맨 끝에 “출력 형식” 섹션을 추가하고, Part A(JSON 구조)와 Part B(Markdown 템플릿)를 넣으면 돼. 기존 지시사항은 그대로 두고 출력 형식만 명시하는 거라 큰 수정 없이 적용할 수 있어.

참고 자료 (References)

데이터 출처

출처	설명	링크
Anthropic Best Practices	스킬 작성 모범 사례 공식 문서	Best Practices
Anthropic 가이드 (Gist)	스킬 설계 심화 가이드	Gist 문서
Claude Help Center	스킬 사용법 공식 안내	Use Skills in Claude
Claude Skills 소개	스킬이란 무엇인지 공식 설명	What are Skills
JSON.org	JSON 표준 명세 및 문법 레퍼런스	JSON 공식

핵심 인용

“Skills teach Claude how to complete specific tasks in a repeatable way.”
— Claude Help Center

다음 편 예고

[5편] 개인 생산성 시나리오 7선: 바로 따라 하는 레시피

• 이메일 분류, 회의록 요약, 메모 구조화 등 일상 업무에 바로 적용하는 스킬 레시피 7가지
• 각 시나리오별 입력/출력 템플릿을 그대로 복사해서 쓸 수 있게 정리
• “먼저 2개만 골라 루틴으로 굳히기” 전략으로 실제로 습관 만드는 법