클로드 코드 스킬 템플릿: 개발·테스트·리팩터링

파일을 고치기는 하지만 테스트 통과 여부와 변경 범위를 매번 다시 확인해야 한다면, 스킬이 업무 흐름이 아니라 긴 지시문으로 작성된 상태입니다.
가장 빠른 해법은 개발·테스트·코드 리뷰·리팩터링·문서·배포를 각각 하나의 검증 가능한 스킬로 나누고, 모든 템플릿에 입력·중단 조건·검수 결과를 넣는 것입니다.

이 글은 개인 스킬 저장소를 빠르게 만들려는 개발자, 팀의 개발 절차를 통일하려는 연구 책임자, 반복 테스트와 문서 업무를 원격 에이전트에 맡기려는 플랫폼 팀을 위한 안내서입니다. 단순히 복사해 쓰는 문장 모음이 아니라, 실제 프로젝트에 넣기 전에 무엇을 확인해야 하는지에 초점을 둡니다.

최종 업데이트는 2026년 8월 12일입니다. 현재 구조는 에이전트 스킬 형식 사양, 클로드 코드의 공식 사용 안내와 공개된 공식 예시를 기준으로 확인했습니다. 템플릿은 편집 출발점일 뿐이며, 실행 결과를 보장하는 공식 인증서가 아닙니다.

먼저 고정할 스킬 설계 원칙

좋은 클로드 코드 스킬 템플릿은 길지 않습니다. 하나의 스킬이 하나의 작업 흐름만 책임지고, 성공 여부를 파일이나 명령 결과로 확인할 수 있어야 합니다.

스킬마다 다음 다섯 항목을 먼저 적으십시오.

• 적용 범위: 어떤 요청에서 실행하는가
• 입력: 파일, 이슈, 명령, 기준 브랜치는 무엇인가
• 실행 단계: 에이전트가 지켜야 할 순서는 무엇인가
• 중단 조건: 언제 추측을 멈추고 사람에게 물어야 하는가
• 검수 결과: 무엇을 남겨야 완료로 인정하는가

SKILL.md는 스킬 폴더에 반드시 들어가야 하며, 이름과 설명을 담은 앞부분 뒤에 작업 지시를 작성합니다. 형식 사양상 이름은 64자 이내의 소문자와 하이픈 조합이어야 하고, 설명은 1024자 이내여야 합니다. 상세 자료는 별도 참고 파일로 옮기는 편이 좋습니다. 공식 사양은 본문을 500줄 이하로 유지하고, 활성화 전 설명 정보는 약 100토큰, 활성화 뒤 지시문은 5000토큰 미만으로 유지할 것을 권장합니다. (형식과 길이 제한 확인)

짧은 기본 골격

---
name: review-change
description: 변경된 코드를 검토하고 위험과 근거를 보고할 때 사용합니다.
---

## 입력
- 변경 파일 목록
- 기준 브랜치
- 관련 테스트 명령

## 절차
1. 변경 범위를 확인합니다.
2. 위험을 분류합니다.
3. 근거 위치를 기록합니다.
4. 필요한 검증을 실행합니다.

## 중단
- 기준 브랜치가 없습니다.
- 재현 명령이 없습니다.
- 변경 범위가 설명과 다릅니다.

## 결과
- 발견 사항
- 확인한 파일과 위치
- 실행한 명령과 결과
- 남은 위험

이 골격을 그대로 모든 업무에 복사하지 마십시오. 각 상황에 맞게 입력과 검수 기준을 바꿔야 합니다.

개발 작업은 먼저 범위를 잠그십시오

기능 개발 스킬은 가장 쉽게 커집니다. “기능을 구현해 달라”는 요청만 넣으면 에이전트가 관련 파일을 찾는 과정에서 설정, 인터페이스, 테스트 구조까지 함께 바꿀 수 있습니다.

개발용 템플릿에는 다음 제한을 넣는 것이 좋습니다.

• 먼저 요구 사항과 완료 조건을 다시 적습니다.
• 완료 조건이 없으면 구현을 시작하지 않고 질문합니다.
• 수정 가능 폴더와 금지된 폴더를 구분합니다.
• 구현 전에 변경 계획과 예상 파일을 출력합니다.
• 계획 밖의 파일이 필요하면 멈추고 승인을 요청합니다.
• 마지막에는 변경 파일, 실행 테스트, 미실행 검사를 보고합니다.

장점

• 작은 기능을 일정한 절차로 처리할 수 있습니다.
• 요구 사항이 불명확할 때 임의 구현을 줄입니다.
• 나중에 코드 리뷰에 필요한 근거가 남습니다.

단점

• 긴급한 한 줄 수정에는 절차가 오히려 느릴 수 있습니다.
• 프로젝트 규칙 파일이 오래되면 잘못된 제한을 강제할 수 있습니다.
• 승인 단계를 생략하면 템플릿의 안전 장치가 작동하지 않습니다.

실제 업무에서는 기능 개발 스킬을 자동 실행보다 수동 호출에 두는 편이 안전합니다. 요청의 의미가 넓고, 성공 조건이 프로젝트마다 다르기 때문입니다.

테스트 실패는 고치기보다 먼저 재현하십시오

테스트 수정 스킬은 “빨간 결과를 없애는 스킬”이 아닙니다. 실패를 재현하고 원인을 좁힌 뒤 최소한의 코드만 바꾸는 스킬입니다.

권장 흐름은 다음과 같습니다.

1. 실패한 테스트의 정확한 실행 명령을 확인합니다.
2. 같은 환경에서 실패가 반복되는지 확인합니다.
3. 오류 위치와 최근 변경 사항을 연결합니다.
4. 원인에 직접 연결된 최소 수정만 적용합니다.
5. 기존 테스트와 관련 회귀 테스트를 실행합니다.
6. 재현되지 않거나 원인이 여러 가지면 중단하고 부족한 정보를 보고합니다.

다음 문장은 템플릿에 명시적으로 넣어야 합니다.

테스트를 삭제하지 않습니다. 단언문을 약하게 만들지 않습니다. 실행하지 않은 테스트를 통과했다고 보고하지 않습니다.

테스트 수정 스킬의 검수 결과에는 통과한 명령뿐 아니라 실패한 명령도 포함해야 합니다. 실패 로그가 사라졌다는 사실만으로 문제가 해결됐다고 판단하면, 환경 문제나 비결정적 실패를 코드 수정으로 덮을 수 있습니다.

중간 비교: 어떤 스킬을 자동 실행할 것인가

클로드 코드에서는 권한과 실행 방식을 별도로 관리해야 합니다. 공식 명령줄 안내에는 계획 권한 모드, 최대 반복 횟수 제한, 자세한 실행 로그, 권한 확인을 건너뛰는 옵션이 구분되어 있습니다. 특히 권한 확인을 건너뛰는 실행은 주의가 필요하므로, 배포나 삭제 작업용 스킬에 기본값으로 넣지 않는 것이 좋습니다. (명령줄 실행 옵션 확인)

코드 리뷰는 의견과 증거를 분리하십시오

코드 리뷰 Skill은 다음 입력을 고정하면 품질이 안정됩니다.

• 변경 차이와 기준 브랜치
• 프로젝트 규칙 파일
• 테스트와 정적 분석 명령
• 보안상 민감한 경로
• 리뷰 우선순위

출력은 다음 네 단계로 나누십시오.

1. 위험 등급
2. 문제가 있는 파일과 위치
3. 왜 문제가 되는지에 대한 근거
4. 수정 제안과 검증 방법

“더 안전해 보입니다” 같은 정적 의견은 도구로 확인한 발견과 같은 수준으로 쓰면 안 됩니다. 정적 분석에서 찾은 가능성, 실제 테스트에서 재현된 오류, 사람이 추가 확인해야 하는 가설을 각각 표시하십시오.

공식 예시의 코드 리뷰 에이전트도 변경 파일을 찾고, 코드를 읽고, 품질과 보안 위험을 분리해 검토한 뒤 파일과 줄 위치를 포함한 실행 가능한 의견을 내도록 구성되어 있습니다. (공식 코드 리뷰 예시)

리팩터링은 기준 동작을 먼저 기록하십시오

리팩터링 스킬의 핵심은 코드 변경 자체가 아니라 변경 전 동작을 보존하는 것입니다.

첫 단계: 기준선 만들기

먼저 관련 테스트, 실행 명령, 대표 입력과 출력, 공개 함수 또는 API 목록을 기록합니다. 테스트가 충분하지 않다면 “기준선 부족”을 완료 조건에 포함해야 합니다.

다음 단계: 작은 묶음으로 바꾸기

한 번에 하나의 구조만 변경하십시오. 함수 분리, 이름 변경, 모듈 이동을 한 작업에 동시에 넣으면 실패 원인을 찾기 어렵습니다. 각 묶음 뒤에 테스트를 실행하고, 계획에 없는 파일이 생겼는지 확인합니다.

반드시 멈춰야 하는 조건

• 공개 인터페이스 변경이 필요합니다.
• 계획에 없던 모듈이나 설정 파일을 수정해야 합니다.
• 테스트 결과가 기준선과 달라졌습니다.
• 변경 파일 수가 처음 계획보다 늘어났습니다.
• 성능 또는 보안 영향이 측정되지 않았습니다.

통제된 리팩터링은 자동 실행보다 승인형 작업으로 두는 편이 낫습니다. 작은 내부 함수 정리에는 적합하지만, 저장소 전체 구조를 다시 설계하는 용도로 사용하면 원래 목적을 벗어나기 쉽습니다.

문서와 변경 설명은 실제 차이에서 생성하십시오

문서 스킬은 코드를 보고 기능을 상상하는 도구가 아닙니다. 실제 차이, 인터페이스, 실행한 테스트 결과를 바탕으로 변경 설명을 만드는 도구입니다.

템플릿에 다음 조건을 넣으십시오.

• 변경 차이를 먼저 읽습니다.
• 실제로 존재하는 엔드포인트와 명령만 기록합니다.
• 실행하지 않은 예시는 예시로 표시합니다.
• 확인하지 못한 동작은 문서에 단정적으로 쓰지 않습니다.
• 테스트 결과와 알려진 제한을 함께 적습니다.
• 사용자 문서와 내부 변경 기록의 표현을 구분합니다.

이 규칙이 없으면 에이전트가 코드에 없는 기능 설명, 아직 배포되지 않은 설정, 실행하지 않은 예제 명령을 문서에 추가할 수 있습니다.

긴 참고 자료는 SKILL.md에 모두 넣지 말고 references/로 분리하십시오. 공식 개발 안내도 상세 패턴, 고급 사용법, 이전 지침을 참고 파일로 분리하는 방식을 제시합니다. (스킬 개발과 검증 안내)

배포 스킬은 자동화와 승인을 나누십시오

배포용 스킬은 가장 많은 권한을 요구하므로, 한 파일에 모든 명령을 넣기보다 점검 단계와 승인 단계를 분리하는 것이 좋습니다.

배포 스킬은 비밀 정보와 실제 서비스 변경을 직접 다루므로, 자동 실행 범위를 빌드·테스트·보고까지 제한하는 구성이 안전합니다. 실제 배포 명령은 사람이 명시적으로 호출하고, 승인 내용과 대상 환경을 다시 확인하도록 하십시오.

선택 조건으로 개인용 템플릿을 줄이십시오

다음 조건으로 시작하면 템플릿을 과하게 만들지 않을 수 있습니다.

• 요구 사항이 불명확하면 기능 개발 스킬을 실행하지 말고 질문 단계로 돌아갑니다.
• 변경 차이가 있고 위험 검토가 필요하면 코드 리뷰 스킬을 선택합니다.
• 실패 명령과 로그가 있으면 테스트 수정 스킬을 선택합니다.
• 동작 보존이 목적이고 기준 테스트가 있으면 통제된 리팩터링 스킬을 선택합니다.
• 구현 차이와 테스트 결과가 확인됐으면 문서 스킬을 선택합니다.
• 빌드와 테스트가 완료되고 승인자가 정해졌으면 배포 점검 스킬을 선택합니다.
• 기준선이나 로그가 없으면 해당 자동화에서 빠지고 정보 수집 스킬로 되돌립니다.

이 조건은 스킬의 설명 앞부분에 넣는 트리거 문장과도 연결됩니다. 공식 저장소의 예시처럼 어떤 요청에서 스킬이 적용되는지, 어떤 요청에서는 적용하지 않는지 구체적으로 적어야 잘못된 자동 실행을 줄일 수 있습니다. (공식 스킬 저장소와 예시)

자주 묻는 질문

Claude Skills에는 어떤 템플릿부터 만들어야 하나요?

처음부터 모든 업무를 하나의 스킬에 넣지 않는 편이 좋습니다. 코드 리뷰, 테스트 실패 수정, 통제된 리팩터링, 변경 문서, 배포 점검 순서로 나누면 각 작업의 입력과 성공 조건을 확인하기 쉽습니다. 기능 개발 스킬은 요구 사항이 자주 바뀌므로 팀의 기본 템플릿이 안정된 뒤 추가하는 편이 안전합니다.

코드 리뷰 Skill은 어떤 형식으로 작성해야 하나요?

검토 대상, 변경 범위, 위험 분류, 근거 위치, 수정 제안을 반드시 분리해 작성합니다. 파일과 줄 위치를 찾지 못한 의견은 추정으로 표시하고, 정적 분석 결과와 실제 도구 실행 결과도 구분해야 합니다. 비밀 정보, 권한 우회, 입력 검증 누락처럼 배포 위험이 큰 항목을 먼저 확인하도록 순서를 고정하는 것이 좋습니다.

테스트 수정 Skill에는 어떤 단계가 필요합니까?

재현, 실패 위치 확인, 원인 가설, 최소 수정, 회귀 테스트, 결과 보고의 순서가 기본입니다. 테스트를 삭제하거나 단언문을 약하게 만들어 통과시키는 행동은 금지해야 합니다. 재현되지 않는 문제라면 임의로 고치지 말고 실행 명령, 환경, 로그 부족을 보고한 뒤 중단하도록 작성해야 합니다.

리팩터링 Skill이 수정 범위를 넓히지 않게 하려면 어떻게 해야 하나요?

먼저 기존 동작을 확인하는 기준 테스트와 변경 대상 목록을 만들고, 한 번에 하나의 구조만 바꾸도록 제한합니다. 공개 인터페이스나 파일 밖의 호출자를 발견하면 자동 진행을 멈추고 승인받게 해야 합니다. 테스트가 실패하거나 변경 파일이 계획보다 늘어나면 원래 상태로 돌아갈 수 있는 지점에서 중단하는 조건도 필요합니다.

Claude Skills 템플릿을 팀에서 재사용할 때 무엇을 통일해야 하나요?

이름과 설명보다 입력 형식, 실행 명령, 중단 조건, 결과 보고 형식을 먼저 통일해야 합니다. 팀 저장소에는 공통 규칙과 프로젝트별 예외를 분리하고, 모든 스킬을 작은 예제 프로젝트에서 실행해 트리거와 실패 보고를 확인합니다. 변경 이력과 담당자를 함께 기록하면 오래된 템플릿이 배포 절차를 방해하는 일을 줄일 수 있습니다.