테스트하고 다듬기

셰프는 반드시 맛을 봅니다

세계 어느 레스토랑을 가도, 셰프의 철칙이 하나 있어요.

"음식을 손님에게 내기 전에, 반드시 맛을 본다."

아무리 레시피대로 만들어도, 오늘 재료의 상태가 다를 수 있고, 불 세기가 미묘하게 달랐을 수 있고, 소금을 한 꼬집 더 넣었을 수도 있어요. 그래서 항상 확인해요.

AI 스킬도 마찬가지예요.

SKILL.md를 아무리 잘 써도, 실제로 돌려보면 "어? 이건 기대와 다른데?"라는 순간이 반드시 와요. AI는 여러분의 마음을 100% 읽을 수 없으니까요.

이번 챕터에서는 스킬을 제대로 테스트하고, 문제를 찾고, 반복적으로 개선하는 방법을 배워요.

테스트 4단계

스킬 테스트는 4단계로 진행해요. 순서가 중요하니까 차례대로 따라가세요.

1단계: 설치 확인

가장 먼저, 스킬이 제대로 설치됐는지 확인해요.

# 스킬 폴더 확인
ls -la .claude/skills/your-skill-name/

# 필수 파일 존재 확인
cat .claude/skills/your-skill-name/SKILL.md

확인할 것:

• 폴더가 올바른 위치에 있는가?
• SKILL.md 파일이 있는가?
• 프론트매터(---)가 올바른 형식인가?
• description 필드가 있는가?

2단계: 해피 패스 테스트 (기본 동작)

"해피 패스(Happy Path)"란 "모든 게 계획대로 잘 될 때"를 말해요. 가장 일반적인 사용 시나리오를 테스트하는 거예요.

예를 들어, 챕터 8의 인사하기 스킬이라면:

# 테스트 1: 기본 인사
안녕!

# 테스트 2: 다른 형태의 인사
좋은 아침이에요

# 테스트 3: 영어 인사
hello

각각의 테스트에서 확인할 것:

• 스킬이 활성화됐는가? (인사 전문가처럼 응답하는가?)
• 지정한 형식을 따르는가? (인사 + 재미있는 사실 + 응원)
• 톤이 맞는가? (친근하지만 예의 바른가?)

3단계: 엣지 케이스 테스트 (예외 상황)

"엣지 케이스(Edge Case)"란 "일반적이지 않은 상황"이에요. 사용자가 예상 밖의 행동을 할 때 스킬이 어떻게 반응하는지 확인하는 거예요.

엣지 케이스에서 스킬이 이상하게 동작하면, SKILL.md에 해당 상황에 대한 지시를 추가하면 돼요.

4단계: 프레시 아이즈 테스트 (다른 사람에게 써보게 하기)

이게 가장 중요한 테스트예요.

여러분이 만든 스킬은 여러분에게는 완벽해 보여요. 왜냐하면 여러분이 만들었으니까요. "내 아이가 제일 예쁘다" 현상이에요.

다른 사람에게 아무 설명 없이 스킬을 써보게 해보세요. 그러면 놀라운 일이 일어나요:

• "이거 어떻게 쓰는 거야?" — description이 불명확한 거예요
• "왜 이렇게 나와?" — 기대와 결과가 다른 거예요
• "이것도 돼?" — 여러분이 생각 못 한 사용법을 발견해요

다른 사람의 피드백은 금이에요. 불편하더라도 받아들이세요.

흔한 문제와 해결법

테스트하다 보면 자주 만나는 문제들이 있어요. 미리 알아두면 당황하지 않아요.

문제 1: "스킬이 활성화가 안 돼요"

원인: description 필드가 비어있거나, 사용자의 의도와 매칭이 안 되는 거예요.

해결법:

# 나쁜 description (너무 모호)
description: "유용한 스킬"

# 좋은 description (구체적)
description: "사용자에게 따뜻한 한국어 인사와 오늘의 재미있는 사실을 전해주는 스킬"

description은 "이 스킬이 언제 활성화돼야 하는지"를 Claude Code에게 알려주는 열쇠예요. 최대한 구체적으로 쓰세요.

문제 2: "도구 사용 에러가 나요"

원인: allowed-tools에 필요한 도구가 빠져있는 거예요.

해결법:

# 파일을 읽어야 하는 스킬인데 Read가 없으면 에러!
# 이렇게 추가:
allowed-tools: ["Read", "Glob", "Grep"]

에러 메시지를 잘 읽어보면, 어떤 도구가 필요한지 힌트가 있어요.

문제 3: "결과가 매번 달라요"

원인: 프롬프트가 모호해서 AI가 매번 다르게 해석하는 거예요.

해결법: 챕터 9로 돌아가세요! 구체성을 높이고, 예시를 추가하고, 출력 형식을 고정하면 일관성이 올라가요.

# 모호한 지시 (결과가 매번 다름)
"요약해주세요"

# 구체적인 지시 (일관된 결과)
"정확히 3문장으로 요약하세요.
 첫 문장은 주제, 둘째 문장은 핵심, 셋째 문장은 시사점."

문제 4: "너무 느려요"

원인: 스킬이 너무 많은 작업을 한 번에 시키는 거예요.

해결법:

• 불필요한 단계를 제거하세요
• "모든 파일을 분석해"보다 "src/ 폴더의 .js 파일만 분석해"처럼 범위를 좁히세요
• references/ 파일이 너무 크면 핵심 내용만 남기세요

반복의 마법: 테스트 → 수정 → 테스트

완벽한 스킬은 한 번에 나오지 않아요. 반복이 핵심이에요.

이 사이클이 지루하게 느껴질 수도 있어요. 근데 생각해보세요. 좋은 요리사도 레시피를 수십 번 테스트해요. 좋은 작가도 원고를 여러 번 퇴고해요. 다듬기는 프로의 과정이에요.

품질 체크리스트

스킬을 다른 사람에게 공유하기 전에, 이 체크리스트를 통과하는지 확인하세요.

기본 품질:

• [ ] description이 명확하고 구체적인가?
• [ ] 기본 사용 시나리오(해피 패스)에서 잘 작동하는가?
• [ ] 최소 3가지 다른 입력으로 테스트했는가?
• [ ] 출력 형식이 일관적인가?

안정성:

• [ ] 예상치 못한 입력에 대해 적절히 반응하는가?
• [ ] allowed-tools에 필요한 도구만 포함되어 있는가?
• [ ] 에러가 발생하는 경우가 없는가?

완성도:

• [ ] 톤과 스타일이 일관적인가?
• [ ] 모든 지시사항이 명확하고 모호하지 않은가?
• [ ] 하드코딩된 개인 경로(예: /Users/myname/)가 없는가?
• [ ] 개인 정보(API 키, 비밀번호 등)가 포함되어 있지 않은가?

사용성:

• [ ] 다른 사람이 설명 없이도 사용할 수 있는가?
• [ ] references/ 파일의 이름이 내용을 잘 설명하는가?

실제 개선 과정 엿보기

이론만 말하면 와닿지 않으니, 실제로 스킬을 개선하는 과정을 보여드릴게요.

상황: 인사하기 스킬을 테스트하는데, 밤 11시에 "안녕"이라고 했더니:

원인 분석: SKILL.md에 "시간대에 맞는 인사"라고만 적었지, AI가 실제 시간을 어떻게 아는지에 대한 지시가 없었어요. AI는 시계가 없거든요!

해결:

## 시간 판단
- 사용자가 시간을 언급하면 그에 맞게 인사
- 시간 언급이 없으면, "안녕하세요!" 같은 시간 중립적 인사 사용
- 절대로 시간을 추측하지 마세요

수정 후 테스트:

문제 해결! 이렇게 테스트에서 발견한 문제를 하나씩 고치는 것이 스킬을 다듬는 과정이에요.

축하합니다 — 스킬이 완성됐어요!

여기까지 오신 분들, 정말 대단해요.

돌아보면, 여러분이 해낸 것들이에요:

1. 챕터 8: 첫 스킬(인사하기)을 직접 만들었어요
2. 챕터 9: 프롬프트 엔지니어링으로 스킬 품질을 높였어요
3. 챕터 10: 도구를 연결해서 스킬에 초능력을 줬어요
4. 챕터 11: references로 지식을 체계적으로 정리했어요
5. 챕터 12: 템플릿으로 효율적으로 스킬을 만드는 법을 배웠어요
6. 챕터 13: 테스트하고 다듬어서 완성도를 높였어요

여러분은 이제 AI 스킬을 만들 줄 아는 사람이에요. 더 이상 "AI를 쓰는 사람"이 아니라, "AI에게 새로운 능력을 부여하는 사람"이에요.

근데 아직 한 가지가 남았어요.

챕터 3에서 오픈소스 이야기 기억나시죠? "만든 걸 공유하면, 한 사람의 해결이 만 명의 해결이 된다"고요.

준비되셨나요? 이제 여러분의 스킬을 세상에 내보낼 시간이에요.