검증 스킬

검증 스킬을 가장 먼저 만들어야 하는 이유

Claude의 작업을 평소 어떻게 확인하는지 생각해 보세요. 무언가를 리팩터링하도록 요청하면 작업이 끝나고, 그러면 다시 확인하는 것을 기억해야 합니다. 테스트를 실행해 달라고 요청할 수도 있습니다. 직접 diff를 읽어볼 수도 있습니다. 문제는 확인 작업이 여러분이 그것을 요청하는 것을 기억하는 데 의존한다는 점입니다. 한 번이라도 그 단계를 건너뛰면 잘못된 코드가 그대로 통과됩니다.

검증 스킬은 이러한 의존성을 없애줍니다. 그 구조는 다음과 같습니다. Claude에게 무언가를 리팩터링하도록 요청합니다. 작업이 끝나면 변경 사항이 스킬의 설명과 일치하므로 스킬이 자동으로 실행됩니다. 그 시점부터 스킬은 다음을 수행합니다:

• 테스트 스위트를 실행합니다.
• diff를 읽습니다.
• 테스트를 통과시키기 위해 테스트가 약화되지 않았는지 확인합니다.
• 증거를 첨부하여 통과 또는 실패를 보고합니다.

이 전체 흐름은 여러분이 요청하지 않아도 실행됩니다. 스킬에 적힌 설명이 이를 트리거하며, 한 번 트리거되면 매번 동일한 단계를 따릅니다.

이 연쇄 과정에서 마지막 확인 항목에 주목하세요. 테스트를 실행해서 초록색(통과)을 보는 것만으로는 충분하지 않습니다. 테스트는 무엇이든 통과하도록 조용히 느슈해질 수 있습니다. 그래서 스킬은 diff를 읽고 테스트가 약화되지 않았는지 확인합니다. "완료"란 diff만 읽고 "코드가 맞는 것 같다"는 것이 아닙니다. 완료란 게이트가 실행되고 관찰되었으며, 그 결과가 명시적으로 기술된 상태를 의미합니다.

이와 같은 구조는 팀이 반복하는 어떤 절차에도 적용됩니다. 릴리스 체크리스트, 마이그레이션 레시피, PR 전 점검 등이 그렇습니다. 기준은 이렇습니다: 같은 다단계 지시를 두 번 입력했다면, 그것은 스킬입니다.

스킬 폴더는 지시사항 이상을 담을 수 있습니다

스킬은 단순히 하나의 SKILL.md 파일이 아닙니다. 그 주변의 폴더는 다른 것들도 담을 수 있으며, 이것이 스킬을 검증에 유용하게 만드는 요소입니다.

• 자세한 자료를 위해 SKILL.md 옆에 reference.md를 두고, SKILL.md에서 그것을 링크하세요. Claude는 그 깊이가 필요할 때만 이를 읽습니다. 메인 파일은 짧게 유지됩니다.
• 스크립트도 폴더에 넣으세요. Claude는 그 내용을 컨텍스트에 불러오는 대신 실행합니다. 즉, 스킬은 모든 게이트를 실행하는 check.sh 같은 자체 도구를 가질 수 있습니다.

핵심은 이렇습니다: SKILL.md 자체는 가볍게 유지하세요. 무거운 자료(긴 설명과 실행 가능한 스크립트)는 별도 파일로 옮기세요. 가벼운 파일은 무엇을 해야 하는지 설명하고, 별도 파일은 깊이와 도구를 담습니다.

어떤 지시 표면이 어떤 규칙을 담당하는가

이제 지시사항을 둘 수 있는 세 가지 장소가 생겼고, 이를 혼동하기 쉽습니다. 이를 명확히 구분하는 간단한 방법을 소개합니다.

항상 적용되는 규칙, 예를 들어 네이밍 규칙이나 파일이 위치할 곳 같은 것은 CLAUDE.md 파일에 속합니다. 특정 종류의 작업에 연결된 절차와 참고 자료는 스킬에 속합니다.

세 번째 경우가 있습니다. Claude가 건너뛸 수 없어야 하는 규칙은 위 두 가지가 아니라 훅(hook)에 속합니다. 그 이유는 CLAUDE.md와 스킬 모두 Claude가 따르는 지시사항인 반면, 훅은 실제로 실행되는 코드이기 때문입니다. 규칙을 건너뛰는 것이 허용되지 않는다면, 그것을 지시 준수 여부에 맡기지 마세요.

요약

스킬은 그 안에 SKILL.md가 있는 폴더입니다: 이름, 이를 트리거하는 설명, 그리고 절차 자체로 구성됩니다. 스킬이 필요해지기 전까지는 설명만 컨텍스트에 로드되므로, 반복하는 모든 절차를 패키징하는 데 드는 비용은 거의 없습니다.

검증부터 시작하세요. 스킬을 만들고 프로젝트의 .claude/skills에 커밋하면, 이제 팀 전체가 같은 방식을 물려받게 됩니다. 모두의 작업이 동일한 방식으로, 자동으로, 누구도 요청을 기억할 필요 없이 확인됩니다.