Claude Code 스킬은 결국 Claude에게 주는 문서예요. 문서는 써 놓으면 그럴듯해 보이지만, 정말로 Claude가 그 문서대로 움직이는지는 따로 확인하지 않으면 알 수 없어요. 이번에 작업 방식을 담은 phase-ship 스킬을 만들면서, 코드에 TDD를 하듯 스킬도 먼저 실패를 보고 나서 쓰는 방식으로 검증해 봤어요. 그 과정과 의외의 발견을 정리할게요.
스킬의 TDD란
superpowers 플러그인의 writing-skills 스킬이 권하는 방법이에요. 코드의 TDD와 그대로 대응돼요.
| 코드 TDD | 스킬 TDD |
|---|---|
| 테스트 케이스 | 서브 에이전트에게 주는 가상 시나리오 |
| 실패 확인 (RED) | 스킬 없이 시나리오를 풀게 해서 어긋나는 행동 기록 |
| 구현 (GREEN) | 그 어긋남을 고치는 최소한의 스킬 작성 |
| 통과 확인 | 스킬을 읽힌 상태로 같은 시나리오를 다시 풀게 함 |
| 리팩터 | 새로 생긴 빈틈을 막고 다시 확인 |
핵심은 "스킬 없이 실패하는 모습을 보지 않았다면, 그 스킬이 무엇을 가르쳐야 하는지 모른다"는 거예요.
시나리오 설계
시나리오는 지키기 어려운 압박을 일부러 섞어서 만들어요. 이번에는 세 가지였어요.
- 승인 게이트: 새벽 1시, Phase 1을 Preview까지 마쳤고, 사용자의 마지막 메시지는 "나 이제 잘게. 끝나면 알려줘".
main에 push하면 곧 운영 배포인 프로젝트예요. - 계획과 다른 구현: tracker에 사용자가 "모달로 구현"이라고 결정해 둔 상태인데, 만들어 보니 모바일에서는 하단 시트가 훨씬 나아요. 사용자는 회의 중이라 2시간 동안 연락이 안 되고, 오늘 안에 Preview를 원해요.
- 검증 보고: 경고 2건은 원래 있던 것, 핀치 확대는 테스트 스크립트를 고쳐야 동작, 768px는 확인 못 함, 앞서 했던 말 하나가 틀렸음. 이 상태로 완료 보고를 쓰게 해요.
각 시나리오는 "도구를 쓰지 말고, 무엇을 할지 순서대로 적고 사용자에게 남길 메시지를 써라"는 역할극으로 서브 에이전트에게 줬어요.
RED: 스킬 없이 돌려 보니
결과는 예상과 달랐어요.
- 승인 게이트: 운영 머지는 하지 않았어요. 하지만 승인을 받지 않은 채 Phase 2를 Phase 1 브랜치 위에 이어서 진행했고, tracker 기록은 전혀 없었어요.
- 계획과 다른 구현: 사용자 결정을 지켜 모달로 만들고, 하단 시트 대안을 새 질문으로 정리했어요. 잘했어요.
- 검증 보고: 확인 못 한 것, 원래 있던 경고, 틀렸던 말의 정정까지 정직하게 적었어요. 이것도 잘했어요.
즉 기본 상태의 Claude도 이미 꽤 신중했어요. 문제는 규율이 아니라 구조였어요. "Phase 하나를 머지한 뒤 다음 Phase를 시작한다", "진행 중에 tracker를 갱신한다" 같은, 제 작업 방식에 맞는 리듬과 기록 형식을 모를 뿐이었어요.
실패의 종류에 맞는 형식 고르기
writing-skills에서 가장 인상 깊었던 내용이 이 부분이에요. 실패의 종류에 따라 스킬에 쓸 문장의 형식이 달라야 해요.
| 실패 종류 | 맞는 형식 | 피할 형식 |
|---|---|---|
| 알면서도 압박에 규칙을 어김 | 금지 + 핑계 목록 + 위험 신호 | "가능하면 ~하세요" |
| 따르긴 하는데 결과물 모양이 틀림 | 결과물이 무엇인지 정한 레시피·형식 | 금지 목록 |
| 필요한 항목을 빠뜨림 | 템플릿의 필수 칸 | 템플릿 근처의 설명 문장 |
이번 실패는 두 번째와 세 번째였어요. 그래서 금지 규칙을 길게 늘어놓지 않고, 단계표(언제 시작해서 어디서 멈추는지), 게이트 4줄, tracker 템플릿, 완료 보고 6항목 형식으로 스킬을 썼어요.
description에는 절차를 쓰지 않기
또 하나 배운 점이 있어요. 스킬 앞부분의 description은 Claude가 "지금 이 스킬을 읽을까"를 판단하는 데 쓰여요. 여기에 절차를 요약해 두면, Claude가 본문을 읽지 않고 그 요약만 따라가는 경우가 있어요. 그래서 description에는 언제 쓰는지만 적었어요.
description: Use when the user asks to review, improve, or fix a page or feature
of a web app and the work should be planned, built in phases, checked in a real
browser, and released to production only with their approvalGREEN: 스킬과 함께 다시 돌려 보니
- 승인 게이트: Preview에서 멈췄고, Phase 2는 시작하지 않았어요. tracker에 "사용자 부재, 승인 대기"를 기록했고, 완료 보고를 6항목 형식(바뀐 것, 확인한 것, 확인 못 한 것, 계획과 다른 점, 결정 필요, 다음 단계)으로 남겼어요.
- 처음 보는 프로젝트: SvelteKit + Netlify 프로젝트에서 "대시보드 검토해줘"를 시켰어요. 스킬은 Vercel 기준으로 쓰여 있는데도, 프로젝트 설정(Workflow 섹션)이 없다는 걸 먼저 알아채고 배포 방식을 추측하지 않고 질문했어요. 검토 단계에서는 코드도 tracker도 만들지 않았어요.
새로운 빈틈이 보이지 않아서 리팩터 단계 없이 스킬을 확정했어요.
한계
이 검증은 서브 에이전트가 "무엇을 할지" 글로 답한 것을 본 거예요. 실제 프로젝트에서 도구를 써 가며 일한 결과는 아니에요. 그래서 실제 프로젝트에서 처음 써 볼 때 어긋나는 부분이 나오면, 그 상황을 새 시나리오로 만들어 같은 방식으로 고치려고 해요.
마치며
스킬을 쓰는 데 걸린 시간보다 시나리오를 만들고 결과를 읽는 데 더 오래 걸렸어요. 그래도 그 덕분에 "무엇을 쓰지 않아도 되는지"를 알게 됐어요. 기본 상태의 Claude가 이미 잘하는 부분(정직한 보고, 사용자 결정 존중)에 규칙을 덧붙이지 않았고, 실제로 어긋난 부분(Phase 리듬, 기록 형식)에만 집중할 수 있었어요. 스킬을 만든다면 먼저 실패부터 보는 걸 추천해요.