레슨 4: 테스트와 디버깅: 스킬이 제대로 동작하게 만들기

학습 목표:

• 스킬을 테스트하는 기본 방법 익히기
• 실제로 마주치게 될 실패 진단하기
• 반복 루프 이해하기
• 스킬이 정말 유지할 가치가 있는지 확인하는 법 알기

전제: << 레슨 3 | 다음: 레슨 5 >>

첫 스킬은 제대로 동작하지 않는다

첫 스킬을 작성하고 실행해 보면 이런 것들이 눈에 들어왔을 겁니다.

• 일부 작업은 아예 인식되지 않았다
• 우선순위가 잘못 나왔다
• 출력 형식이 엉망이었다
• 아니면 Claude가 애초에 스킬을 로드하지도 않았다

그게 정상입니다.

스킬은 코드와 같습니다. 한 번 실행되게 만드는 것은 출발선이지 결승선이 아닙니다. 실제로 쓸모 있는 스킬은 모두 몇 차례의 개정을 거쳐 그 자리에 도달했습니다.¹

이 레슨에서는 그런 문제를 찾아내고 고치는, 반복해서 쓸 수 있는 방법을 알려 드립니다.

테스트 방법 1: 직접 호출하기

가장 단순한 테스트는 직접 호출해 보는 것입니다. /skill-name으로 한 번 불러 보고 무엇이 나오는지 관찰합니다.²

테스트 케이스 준비하기

무언가를 호출하기 전에, 입력을 3~5개 적어 둡니다.

통상 케이스:

분기 보고서 마무리하기PR #234 금요일 전까지 리뷰하기내일 로그인 버그 고치기

엣지 케이스:

(빈 입력)

무의미한 케이스:

이것은 할 일이 하나도 들어 있지 않은, 전혀 무관한 산문 한 단락입니다asldfkjasldfj!@#$%

테스트 실행하기

Claude Code에서 하나씩 입력해 봅니다.

/task-organizer
분기 보고서 마무리하기PR #234 금요일 전까지 리뷰하기내일 로그인 버그 고치기

세 가지를 관찰합니다.

1. Claude가 스킬을 로드하기는 했는가? (그렇지 않다면 문제는 description에 있습니다.)
2. 출력 형식이 올바른가? (엉망이라면 문제는 출력 형식 섹션에 있습니다.)
3. 내용이 기대한 대로인가? (분류가 틀렸다면 문제는 처리 단계에 있습니다.)

무슨 일이 있었는지 기록하기

작은 표 하나면 충분합니다.

테스트 방법 2: 로딩 동작 관찰하기

문제가 지시문이 아니라 프론트매터에 있는 경우도 있습니다.

문제: Claude가 스킬을 스스로 로드하지 않는다

증상: "이 작업들 좀 정리해 줘"라고 했는데 Claude가 task-organizer 스킬을 무시합니다.

가능한 원인:

1. description이 너무 뭉뚱그려져 있다

   수정: 트리거가 될 단어를 넣습니다.

2. 실제로 입 밖에 내는 말이 description에 들어 있지 않다

   "이 할 일들 좀 정리해 줘"라고 말하는데 description 어디에도 "할 일"이라는 말이 없다면, Claude는 그 스킬을 아예 떠올리지 못할 수 있습니다.³

   수정: 사용자가 말할 법한 표현을 description에 적어 넣습니다.

문제: Claude가 엉뚱한 스킬을 로드한다

증상: task-organizer를 원했는데 Claude가 다른 것을 집어 듭니다.

가능한 원인: 다른 스킬의 description이 입력과 더 잘 맞아떨어집니다.

수정: /task-organizer로 호출을 강제하거나, 경쟁하는 스킬보다 더 구체적이 되도록 description을 벼립니다.

흔한 실패 진단하기

문제 1: 출력 형식이 어긋난다

증상: 스킬이 실행되기는 하는데 서식이 틀어집니다.

예:

긴급: 로그인 버그 고치기 - 내일중요: PR #234 리뷰 - 금요일

이모지와 제목으로 그룹이 나뉜 섹션을 원했는데, Claude는 밋밋한 텍스트 목록을 내놓았습니다.

원인: 출력 형식 섹션이 충분히 구체적이지 않거나, 예시가 없습니다.

수정: SKILL.md의 "출력 형식" 섹션에 완전한 예시를 넣습니다.

"반드시 이 형식을 정확히 따를 것"이라고 쓴 다음, 전체를 보여 줍니다.

문제 2: 인식이 부정확하다

증상: 일부 작업이 누락되거나, 엉뚱한 분류에 들어갑니다.

예:

입력:

내일 그 버그를 고쳐야 함금요일 전까지 데모 준비하기

출력:

### ⚪ 보통- 내일 그 버그를 고쳐야 함 - 마감일 언급 없음- 금요일 전까지 데모 준비하기 - 마감일 언급 없음

둘 다 마감일이 분명한데, 둘 다 마감일 없음으로 표시되었습니다.

원인: 처리 단계의 시간 인식 규칙이 충분한 경우를 다루지 못합니다.

수정: 채워 넣습니다.

요점: 떠올릴 수 있는 표현을 하나도 빠짐없이 적어 두는 것입니다.

문제 3: 엣지 케이스가 빠져나간다

증상: 통상적인 입력은 괜찮은데, 특이한 입력이 들어오면 스킬이 이상하게 동작합니다.

예:

입력: 빈 문자열

출력: Claude가 멈추거나, 의미 없는 텍스트를 잔뜩 만들어 냅니다.

원인: "Notes" 섹션에 빈 입력을 어떻게 처리할지 적어 두지 않았습니다.

수정:

반복 루프

좋은 스킬은 한 번에 써지지 않습니다. 테스트 → 수정 → 테스트의 루프에서 나옵니다.¹

1. 첫 버전 작성 (핵심 동작만)2. 테스트 케이스 3~5개로 실행3. 무엇이 잘못됐는지 기록4. SKILL.md 수정5. 다시 테스트6. 모든 테스트 케이스가 통과할 때까지 3~5 반복7. 일주일 동안 실제로 사용8. 새로운 문제 발견9. 4단계로 돌아가기

버전 1이 맞을 거라고 기대하지 마세요. 먼저 돌아가게 만들고, 그다음 올바르게 만들고, 그다음 좋게 만듭니다.

그 스킬은 정말 쓸모가 있는가?

올바르게 동작하게 되면 더 큰 질문이 하나 남습니다. 이 스킬이 정말 시간을 아껴 주고 있는가?¹

A/B로 비교하기

비교는 단순합니다. 같은 작업을 스킬 있이, 스킬 없이 여러 번 실행하고 양쪽 시간을 잽니다.

스킬 없이:

시간을 잽니다. 당신이 손으로 과정을 설명하고 Claude가 실행합니다 — 평균 얼마나 걸립니까?

스킬로:

시간을 잽니다. 당신이 스킬을 호출하고 Claude가 실행합니다 — 평균 얼마나 걸립니까?

스킬 쪽이 더 빠르지 않거나 품질이 더 나쁘다면, 그 스킬은 아직 손볼 데가 있습니다.

일주일 동안 써 보기

진짜 시험은 실제 사용입니다.⁴

다음 숫자를 기록합니다.

• 몇 번이나 호출했는가
• 손대지 않고 그대로 쓸 수 있었던 결과가 몇 번이었는가
• 다시 실행하거나 출력을 손으로 고쳐야 했던 횟수
• 시간을 얼마나 아꼈는가

일주일에 세 번 미만으로 호출했다면, 그 작업은 스킬을 만들 만큼 반복적이지 않을 가능성이 큽니다.

디버깅 치트시트

스킬이 동작하지 않을 때는 로딩 실패 점검부터 시작합니다. 아래 표를 따라가며 파일 경로, 프론트매터 형식, 트리거 키워드 순으로 하나씩 배제해 나갑니다.

정리

• 첫 스킬은 제대로 동작하지 않는다 — 테스트 → 수정 → 테스트의 루프를 거쳐야 그 자리에 도달한다
• 테스트 방법: 직접 호출, 로딩 동작 관찰, 테스트 케이스 사전 준비
• 흔한 실패: description이 너무 뭉뚱그려짐, 출력 형식 지정 부족, 인식 규칙 불완전, 엣지 케이스 미처리
• 디버깅 흐름: 기대와 실제를 기록, 진단, SKILL.md 수정, 재테스트
• 가치 증명: 스킬 있이/없이 시간·품질·일관성을 비교하고, 일주일 써 보며 호출 횟수를 센다

다음 레슨에서는 완전한 코드 리뷰 스킬을 처음부터 끝까지 살펴보며, 더 복잡한 워크플로를 다루는 법을 배웁니다.

>> 레슨 5: 케이스 스터디: 코드 리뷰 스킬 만들기