Claude Code 스킬, 만들기 전에 사양 md 한 장부터 — 급할수록 돌아가라

조사처럼 시간이 걸리는 작업에 대해 Skill을 만들어 효율화를 꾀하고 있습니다. Skill 만드는 법은 다음과 같아요.

• 베이스는 ClaudeCode에게 만들게 한다
• "이런 걸 하고 싶은데"라는 정보를 넘긴 다음 실제 작업을 진행하고, Skill을 만들게 한다
• 예상과 다른 부분이나 개선점이 있으면 그때그때 수정해 다듬어 간다

실패한 지점

먼저 옛날이야기를 조금 하겠습니다.

과거에 고객과 요건 정의를 할 때, "이런 거 하고 싶은데"라고 대략적인 희망 사항만 듣는 일이 자주 있었습니다. 그래서는 고객이 머릿속에 그리는 사양이 보이지 않으니, 제 나름대로 소화해서 Excel에 정리해 담고 "이런 뜻이 맞나요?" 하고 사양에 어긋남이 없도록 확인하곤 했습니다.

그런데 막상 제가 Claude에게 Skill을 만들게 할 때, 바로 그 "옛날이야기 속 고객"과 똑같은 짓을 하고 있었던 겁니다.

"이런 걸 하고 싶은데"라고 대략적인 요구만 전하고 작업을 시작시킨 결과, Claude는 이쪽이 원하는 아웃풋을 정확히 이해하지 못한 상태였습니다. 그 결과 투입 시간과 컨텍스트는 소비되는데 의도한 것은 좀처럼 만들어지지 않는 악순환에 빠졌습니다.

해결책

작업을 시작하기 전에, 사양으로 md 파일을 한 편 쓰기로 했습니다. 구성은 다음과 같습니다.

이걸 Claude에게 넘기면, "이런 뜻이 맞나요?"의 확인 스텝을 작업 시작 전에 끝내 둔 셈이 됩니다.

결론

키워드는 "급할수록 돌아가라"입니다.

md 파일을 쓰는 수고는 분명 듭니다. 다만 해 보니 다음 같은 이점밖에 없었습니다.

• 내 머리가 정리된다 — 쓰는 과정에서 골과 조사 방법이 정리된다
• 인수인계 자료가 된다 — 다른 멤버가 조사에 합류했을 때 그대로 넘기면 된다
• Claude와 눈높이가 맞춰진다 — 예상과 다른 성과물이 나오는 빈도가 줄고, 투입 시간·컨텍스트 낭비도, 의도대로 움직이지 않는 짜증도 줄어든다

사전 준비를 아끼고 나중에 수정을 반복하기보다, 처음에 사양을 굳히고 나서 움직이는 쪽이 전체로는 압도적으로 빠릅니다.