Skill 종합 연습

통합 테스트부터 commit-msg 자동화까지 실무 워크플로우

배경 지식

3가지 스킬의 완성형

1장부터 6장을 통해 다음 3가지 스킬을 단계적으로 구축해왔습니다.

.claude/skills/
pr-review/
SKILL.md # 1장에서 작성, 2-5장에서 개선
references/
coding-standards.md # 4장에서 추가
review-checklist.md # 4장에서 추가
security-guidelines.md # 6장에서 추가
examples/
good-review.md # 4장에서 추가
bad-review.md # 4장에서 추가
scripts/
get-diff.sh # 4장에서 추가
test-gen/
SKILL.md # 1장에서 작성, 2-5장에서 개선
references/
test-guidelines.md # 4장에서 추가
examples/
sample-test.md # 4장에서 추가
doc-gen/
SKILL.md # 1장에서 작성, 2-5장에서 개선
assets/
api-doc-template.md # 4장에서 추가

통합 테스트의 중요성

개별 Skill이 동작하는 것은 확인했지만, 실업무에서는 여러 Skill을 조합하여 사용합니다. 통합 테스트에서는 다음을 확인합니다.

각 Skill이 다른 Skill과 간섭하지 않는가

description의 자동 실행 판정이 올바르게 분기되는가

출력 품질이 업무 요건을 충족하는가

따라하기

1단계: 3가지 스킬의 최종판 확인

먼저, 3가지 스킬의 SKILL.md가 최신 상태인지 확인합니다. 1장~6장까지에서 단계적으로 개선해온 내용이 모두 반영되어 있어야 합니다.

cd ~/dev-workflow-skills

pr-review/SKILL.md의 최종버전

---
name: pr-review
description: |
다음 중 하나의 상황에서 사용한다
- PR(풀 리퀘스트) 리뷰, 코드 리뷰를 요청받았을 때
- GitLab MR(Merge Request) 리뷰를 요청받았을 때
- 변경 차분(diff) 확인이나 피드백을 요청받았을 때
- git diff 내용을 분석해달라고 할 때
코드 수정, 리팩토링, 버그 수정 요청에는 사용하지 않는다.
테스트 작성이나 문서 작성 요청에는 사용하지 않는다.
argument-hint: "[대상 파일 경로 또는 변경 내용 설명]"
allowed-tools: Read, Grep, Glob
---

<!-- Version: 1.2.0 -->
<!-- Last Updated: 2026-03-08 -->
<!-- Changelog:
1.2.0 - 보안 리뷰 가이드라인 추가
1.1.0 - description 최적화, 부정 조건 추가
1.0.0 - 초판 릴리스
-->

# PR 리뷰 Skill

당신은 시니어 엔지니어로서, 코드 변경의 리뷰를 수행합니다.

## 참조해야 할 문서

- `references/coding-standards.md` - 코딩 규약
- `references/review-checklist.md` - 리뷰 체크리스트
- `references/security-guidelines.md` - 보안 리뷰 가이드라인

## 출력 품질의 기준

- `examples/good-review.md` - 이 예시처럼 구체적·실용적인 리뷰를 출력한다
- `examples/bad-review.md` - 이 예시와 같은 모호·불완전한 리뷰는 피한다

## 리뷰 절차

1. `scripts/get-diff.sh`를 실행하여 변경 차분을 취득한다 (인수로 베이스 브랜치 지정 가능)
2. `references/review-checklist.md`의 각 항목에 대해 확인한다
3. `references/coding-standards.md`에 위반되는 부분을 특정한다
4. `references/security-guidelines.md`의 보안 관점으로 체크한다
5. 각 지적에 중요도(Critical / Warning / Info)를 부여한다

## 출력 포맷

### 리뷰 요약
변경 파일 수와 리뷰 범위의 개요

### 지적 사항
각 지적은 다음 포맷으로 출력한다:

### [중요도] 지적 제목
- 파일: path/to/file.ts (L행번호)
- 규약 참조: 해당 규약 항목 (있으면)
- 문제: 구체적인 문제의 설명
- 제안: 개선안의 코드 예시

### 총평
전체적인 품질 평가와 개선 우선순위

## 안전성에 관한 제약
- 파일의 작성·편집·삭제는 절대로 하지 않는다
- Bash의 사용은 `scripts/` 디렉토리 내의 스크립트 실행과 `git` 커맨드에 한정한다
- 외부 네트워크에 접속하는 커맨드는 실행하지 않는다
- `.env`, `.env.local` 등 환경 파일이나 인증 정보를 포함하는 파일은 읽지 않는다

test-gen/SKILL.md의 최종버전:

---
name: test-gen
description: |
다음 중 하나의 상황에서 사용한다:
- 테스트 코드의 신규 작성을 요청받았을 때
- 기존 코드에 대한 유닛 테스트·통합 테스트의 추가를 요청받았을 때
- 테스트 커버리지의 향상을 요청받았을 때
- Jest, Vitest, Mocha 등의 테스트 파일 생성을 요청받았을 때
기존 테스트의 수정·디버그에는 사용하지 않는다.
테스트 실행(npm test, yarn test, npx jest 등)의 요청에는 사용하지 않는다.
argument-hint: "[대상 소스 파일 경로]"
allowed-tools: Read, Write, Edit, Grep, Glob
---

<!-- Version: 1.1.0 -->
<!-- Last Updated: 2026-03-08 -->

# 테스트 생성 Skill

지정된 소스 코드에 대해 테스트 코드를 생성합니다.

## 참조 문서

- `references/test-guidelines.md` - 테스트 작성 가이드라인에 따라 생성할 것
- `examples/sample-test.md` - 이 예시의 품질과 망라성을 기준으로 할 것

## 절차

1. 대상 파일을 읽어 함수·클래스의 구조를 파악한다
2. **안전 확인**: 대상 파일의 경로를 확인하고, 테스트 대상임을 검증한다
3. 기존 테스트 파일이 있으면 확인하여 테스트 프레임워크와 기법을 맞춘다
4. `references/test-guidelines.md`의 커버리지 목표에 기반하여 테스트 케이스를 설계한다
5. **안전 확인**: 쓰기 대상이 테스트 파일(*.test.*, *.spec.*)임을 확인한다
6. `examples/sample-test.md`의 포맷에 맞추어 테스트 코드를 생성한다
7. 테스트 파일을 적절한 위치에 배치한다

## 테스트 파일 배치

- 기존 테스트 파일과 동일한 디렉토리 구성에 맞춘다
- 테스트 디렉토리가 없는 경우, 대상 파일과 같은 디렉토리에 `*.test.*`로 배치한다

## 안전성에 관한 제약

- 소스 코드(테스트 대상 파일)는 절대로 변경하지 않는다
- Write / Edit의 사용은 테스트 파일(*.test.*, *.spec.*)의 작성·편집에 한정한다
- 기존 테스트 파일을 덮어쓰기 전에, 반드시 기존 내용을 확인한다
- `node_modules/`, `dist/`, `.git/` 하위의 파일에는 절대로 손대지 않는다

## 주의 사항
- 기존 테스트 프레임워크(Jest, Vitest, pytest 등)에 맞춘다
- 목은 `references/test-guidelines.md`의 목 방침에 따른다
- 테스트는 독립적으로 실행 가능하게 한다

doc-gen/SKILL.md의 최종버전:

---
name: doc-gen
description: |
다음 중 하나의 상황에서 사용한다:
- 코드의 문서·API 레퍼런스 생성을 요청받았을 때
- README의 작성·업데이트를 요청받았을 때
- 모듈이나 클래스의 사용 가이드 작성을 요청받았을 때
- JSDoc, TSDoc, docstring 등의 인라인 문서 추가를 요청받았을 때
- Wiki, Confluence, Notion 등에 올릴 기술 문서 초안 작성을 요청받았을 때
코드 수정이나 테스트 생성에는 사용하지 않는다.
코드 리뷰나 PR 분석에는 사용하지 않는다.
argument-hint: "[대상 파일 또는 모듈 경로]"
allowed-tools: Read, Grep, Glob, Write, Edit
context: fork
---

<!-- Version: 1.1.0 -->
<!-- Last Updated: 2026-03-08 -->

# 문서 생성 Skill

지정된 코드 또는 모듈에 대해 Markdown 형식의 문서를 생성합니다.

## 템플릿

- `assets/api-doc-template.md` - API 문서는 이 템플릿에 따라 생성할 것

## 절차

1. 대상 코드를 읽어 공개 API·함수·클래스를 특정한다
2. 기존 문서가 있으면 포맷과 스타일을 따른다
3. `assets/api-doc-template.md`의 포맷에 따라 문서를 생성한다
4. 사용 예시는 실제로 동작하는 코드로 기술한다
5. `docs/` 디렉토리에 배치한다

## 출력처

- 문서는 `docs/` 디렉토리에 배치한다
- 파일명은 대상 모듈명에 맞춘다 (예: `docs/auth-module.md`)
- 기존 `docs/` 디렉토리가 없으면 생성한다

## 품질 기준

- 모든 공개 함수·클래스를 커버한다
- 파라미터의 타입과 설명을 생략하지 않는다
- 사용 예시를 최소 1개 포함한다
- 반환값의 설명을 반드시 포함한다

## 안전성에 관한 제약

- 소스 코드는 변경하지 않는다
- Write / Edit의 사용은 `docs/` 디렉토리 내의 Markdown 파일에 한정한다
- `.env` 파일이나 인증 정보를 포함하는 파일은 읽지 않는다

2단계: 통합 테스트 - 자동 실행의 분기

3가지 Skill이 올바르게 분기되는지를 체계적으로 테스트합니다.

cd ~/dev-workflow-skills
claude

다음 프롬프트를 순서대로 시험해보고, 결과를 기록하세요.

분기 테스트 표:

모든 프롬프트가 기대대로 분기되면 description의 설계는 성공입니다.

필자 환경에서의 결과:

#9 "git diff 확인해줘" → pr-review가 발화하지 않는 이유

원인 분석:

description에는 "git diff 내용을 분석해달라고 할 때"라고 쓰여 있지만

"확인해줘"는 단순한 확인 동작이며 "분석·리뷰"와는 다르게 인식될 수 있다

프롬프트를 "git diff 내용을 분석해줘"로 변경하면 pr-review가 발화합니다.

� 교훈: description의 표현에는 팀 멤버가 실제로 사용하는 자연스러운 한국어 말투를 의식하여 작성하는 것이 중요합니다. "확인", "봐줘", "체크해줘" 등 구어체 표현도 description에 포함시키면 발화 정확도가 높아집니다.

description 개선 예시 (한국어 구어체 대응):

description: |
다음 중 하나의 상황에서 사용한다:
- PR(풀 리퀘스트) 리뷰, 코드 리뷰를 요청받았을 때
- 변경 차분(diff) 확인, 체크, 검토를 요청받았을 때 ← "확인"도 포함
- git diff 내용을 분석, 확인해달라고 할 때 ← "확인"도 포함

3단계: 통합 테스트 - 실업무 시나리오

실제 개발 워크플로우를 모의하여 3가지 스킬을 연계하여 사용하는 시나리오를 테스트합니다.

시나리오: 새로운 기능의 개발 플로우

테스트용 소스 파일을 작성합니다.

mkdir -p ~/dev-workflow-skills/src/utils

src/utils/calculator.ts를 작성합니다.