Skills가 해결하는 과제

앞 편 Claude Skills란 무엇인가에서 구조를 봤다면, 이 편은 "그래서 무엇이 나아지는가"입니다. Skill 없이 Claude Code를 쓰는 사람이 반복해서 겪는 네 가지 문제를 짚고, 코드 리뷰 기준을 Skill로 만든 사례로 확인합니다. 읽고 나면 내 작업 중 어느 것이 이 네 문제에 걸려 있는지 골라낼 수 있습니다.

핵심 요약

• 같은 설명의 반복, 결과 편차, 컨텍스트 낭비, 사람에게 묶인 지식. 네 문제는 원인이 하나입니다. 절차가 파일이 아니라 사람 머릿속에 있다는 점입니다.
• Skill은 절차를 파일로 꺼내고, 필요할 때만 로드하며, 팀이 같은 파일을 쓰게 합니다.
• 코드 리뷰 기준처럼 "매번 같아야 하는 판단"이 가장 먼저 Skill이 되어야 합니다.

문제 1: 매번 설명해야 한다

원구연 과정 5주차의 "좋은 요청 황금 문장"은 "원인 분석, 최소 수정, 변경 정리" 순서입니다. 문제는 매 세션 첫 요청에 이걸 다시 타이핑해야 한다는 점입니다. 잊으면 Claude는 원인 분석 없이 바로 고칩니다. Skill로 만들어 두면 "버그 고쳐 줘"라는 말에 description이 반응해 그 순서가 자동으로 붙습니다.

문제 2: 결과에 편차가 생긴다

같은 요청을 월요일과 수요일에 하면 결과가 다릅니다. 그날 설명을 어디까지 했느냐가 다르기 때문입니다. 우리 팀의 배포 절차가 그랬습니다. 어떤 날은 빌드 확인 후 배포했고, 어떤 날은 확인을 건너뛰었습니다. 절차를 Skill 본문에 번호로 박아 두자 순서가 고정됐고, "정지 규칙은 증거"라는 원칙대로 마지막 단계에 헬스체크 응답 코드 확인을 넣어 성공 판정도 같아졌습니다.

문제 3: 컨텍스트를 낭비한다

편차를 없애려고 CLAUDE.md에 절차를 전부 적으면 세션마다 전부가 읽힙니다. 공식 문서가 CLAUDE.md의 섹션이 절차로 자라났을 때 Skill로 옮기라고 하는 이유입니다. Skill 본문은 호출 전까지 로드되지 않으므로 열 개의 절차 중 지금 쓰는 하나만 비용을 냅니다.

문제 4: 지식이 사람에게 묶인다

"배포는 원구연만 할 줄 안다"는 상태는 그 사람이 없을 때 시스템이 멈춥니다. 절차를 .claude/skills/에 두고 커밋하면 팀 전원의 Claude가 같은 절차를 씁니다. 사람이 판단을 쥐되, 판단 기준은 파일에 남깁니다.

사례: 코드 리뷰 기준

BizPlan CRM 공동 개발에서 결제 코드는 반드시 두 번째 모델의 교차 리뷰를 거칩니다. 처음에는 리뷰 요청 때마다 "서버가 금액을 정하는지, 클라이언트 금액을 신뢰하지 않는지, 트랜잭션 제거로 생긴 구멍은 없는지"를 매번 적었습니다. 이를 Skill로 옮겼습니다.

---
name: payment-review
description: 결제·주문 코드 diff를 검토합니다. "결제 코드 리뷰", "주문 API 검토", "교차 리뷰" 요청 시 사용합니다.
---

diff를 받으면 아래 불변 규칙이 유지되는지 번호별로 판정합니다.

1. 결제 금액은 서버가 정한다. 클라이언트가 보낸 금액을 신뢰하는 코드가 있으면 실패.
2. 환불 규정이 없는 상품은 주문 생성을 거부해야 한다.
3. 비동기·트랜잭션 변경으로 생긴 경쟁 조건을 찾는다.
4. 판정은 "통과" 또는 "수정 필요(항목 번호)"로만 끝낸다.

리뷰 요청이 한 줄로 줄었고, 언제 리뷰하든 같은 네 항목이 검사되며, 새로 합류한 사람도 첫날부터 같은 기준을 씁니다.

정리

• 네 문제의 공통 원인은 절차가 사람에게 있다는 것이고, Skill은 그것을 파일로 옮깁니다.
• 반복 설명은 description 매칭으로, 편차는 번호 절차로, 낭비는 지연 로딩으로, 사람 종속은 저장소 커밋으로 풉니다.
• "매번 같아야 하는 판단"부터 Skill로 만드세요. 코드 리뷰 기준이 대표적입니다.

다음 레슨

다음 편 도메인 지식과 컨텍스트에서는 전문 분야 지식을 Skill에 담을 때 무엇을 문서로, 무엇을 스크립트로 쓸지 나누는 기준을 다룹니다.

자주 묻는 질문