오늘만 무료

Skill 종합 연습

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

Mar 22. 2026 brunch_membership's

배경 지식

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
---





# 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
---




# 테스트 생성 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
---




# 문서 생성 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를 작성합니다.

cat > src/utils/calculator.ts << 'EOF'
/**
* 기본적인 계산 유틸리티
*/

export function add(a: number, b: number): number {
return a + b;
}

export function subtract(a: number, b: number): number {
return a - b;
}

export function multiply(a: number, b: number): number {
return a * b;
}

export function divide(a: number, b: number): number {
if (b === 0) {
throw new Error('Division by zero');
}
return a / b;
}

export function percentage(value: number, total: number): number {
if (total === 0) {
throw new Error('Total cannot be zero');
}
return (value / total) * 100;
}
EOF

Git에 커밋합니다.

cd ~/dev-workflow-skills
git add src/
git commit -m "feat: 계산 유틸리티를 추가"

Claude Code에서 3가지 스킬을 순서대로 사용하여 개발 워크플로우 전체를 체험합니다.

cd ~/dev-workflow-skills
claude

1단계: 테스트 생성

> /test-gen src/utils/calculator.ts

기대되는 결과:

src/utils/calculator.test.ts가 생성된다

각 함수의 정상계·이상계·경계값 테스트가 포함된다 (divide by zero, percentage total=0 등)

references/test-guidelines.md의 가이드라인에 따른 내용

2단계: 문서 생성

> /doc-gen src/utils/calculator.ts

기대되는 결과:

docs/calculator.md가 생성된다

assets/api-doc-template.md의 포맷에 따른 내용

각 함수의 파라미터·반환값·사용 예시·예외 정보가 포함된다

3단계: PR 리뷰

> /pr-review src/utils/calculator.ts

기대되는 결과:

코딩 규약에 기반한 리뷰 코멘트

보안 가이드라인에 기반한 체크

중요도(Critical / Warning / Info)가 붙은 지적 사항

4단계: 출력 품질의 평가

각 Skill의 출력을 다음 품질 기준으로 평가합니다.

pr-review의 평가 기준:

test-gen의 평가 기준:

doc-gen의 평가 기준:

5단계: 새로운 Skill을 제로부터 작성

여기까지의 학습한 내용을 토대로 새로운 Skill을 처음부터 작성합니다.

과제: commit-msg - 커밋 메시지 생성 Skill

스테이징된 변경을 분석하여 Conventional Commits 형식의 커밋 메시지를 제안하는 Skill입니다.

� 한국 팀에서의 배경
Conventional Commits는 GitHub Actions 연동 자동 릴리스 노트 생성, Jira 이슈 연동, 시맨틱 버저닝 자동화 등에서 활용됩니다. 한국의 많은 스타트업과 IT 기업에서 사내 커밋 규약으로 채택하고 있습니다.

5-1단계: 요건 정리

5-2단계: 디렉토리 생성

mkdir -p ~/dev-workflow-skills/.claude/skills/commit-msg/references
mkdir -p ~/dev-workflow-skills/.claude/skills/commit-msg/examples

5-3단계: SKILL.md 작성

.claude/skills/commit-msg/SKILL.md를 작성합니다.

cat > .claude/skills/commit-msg/SKILL.md << 'EOF'
---
name: commit-msg
description: |
다음 중 하나의 상황에서 사용한다:
- 커밋 메시지의 작성을 요청받았을 때
- 스테이징된 변경의 요약을 요청받았을 때
- Conventional Commits 형식의 메시지를 생성해달라고 할 때
- "커밋 메시지 뭐로 하면 좋을까" 등 커밋 메시지 관련 질문을 받았을 때
커밋의 실행(git commit) 자체는 하지 않는다.
argument-hint: "[추가 컨텍스트 (임의)]"
allowed-tools: Read, Grep, Glob, Bash(git *)
---




# 커밋 메시지 생성 Skill

스테이징된 변경을 분석하여 Conventional Commits 형식의 커밋 메시지를 제안합니다.

## 참조 문서

- `references/conventional-commits.md` - 커밋 메시지의 규약

## 출력 품질의 기준

- `examples/sample-messages.md` - 이 예시와 같은 품질의 메시지를 생성한다

## 절차

1. `git diff --staged`를 실행하여 스테이징된 변경을 확인한다
2. `git diff --staged --stat`으로 변경 파일의 개요를 확인한다
3. 변경 내용을 분석하여 `references/conventional-commits.md`에 따라 메시지를 생성한다
4. 메시지를 3가지 패턴으로 제안한다 (간결판 / 표준판 / 상세판)

## 출력 포맷

\```
## 제안 1 (간결판)
feat: add calculator utility

## 제안 2 (표준판)
feat: add calculator utility for basic arithmetic operations

## 제안 3 (상세판)
feat: add calculator utility for basic arithmetic operations

- Add add, subtract, multiply, divide functions
- Include percentage calculation
- Add error handling for division by zero
\```

## 안전성에 관한 제약

- `git commit`은 절대로 실행하지 않는다 (메시지의 제안만)
- 파일의 작성·편집·삭제는 하지 않는다
- Bash의 사용은 `git` 커맨드에 한정한다 (`Bash(git *)` 로 자동 실행을 git 커맨드만으로 제한 완료)
EOF

5-4단계: references의 작성

.claude/skills/commit-msg/references/conventional-commits.md를 작성합니다.

cat > .claude/skills/commit-msg/references/conventional-commits.md << 'EOF'
# Conventional Commits 규약

## 포맷

\```
<type>(<scope>): <description>
[optional body]

[optional footer(s)]
\```

## type 목록

| type | 용도 |
|------|------|
| feat | 새로운 기능 |
| fix | 버그 수정 |
| docs | 문서만의 변경 |
| style | 코드의 의미에 영향을 주지 않는 변경 (공백, 포맷 등) |
| refactor | 버그 수정도 새로운 기능도 아닌 코드 변경 |
| perf | 퍼포먼스 개선 |
| test | 테스트의 추가·수정 |
| chore | 빌드 프로세스나 보조 툴의 변경 |

## 규칙

- description은 명령형, 동사 원형으로 시작 (「Added」가 아니라 「Add」)
- description은 50자 이내를 기준
- body는 변경의 이유나 배경을 설명 (what이 아닌 why)
- 파괴적 변경이 있는 경우는 `BREAKING CHANGE:`를 footer에 기술

## 한국 팀에서의 활용
- GitHub Actions의 release-please와 연동하여 자동 릴리스 노트 생성 가능
- Jira 이슈 번호를 footer에 포함: `Refs: PROJ-123`
- 시맨틱 버저닝과 연동: feat → minor, fix → patch, BREAKING CHANGE → major
EOF

5-5단계: examples 작성

.claude/skills/commit-msg/examples/sample-messages.md를 작성합니다.

cat > .claude/skills/commit-msg/examples/sample-messages.md << 'EOF'
# 커밋 메시지의 예시

## 좋은 예시
\```
feat(auth): add JWT token refresh mechanism

Implement automatic token refresh when the access token expires.
The refresh token is stored in httpOnly cookie for security.
\```

\```
fix(api): handle null response from payment gateway

The payment gateway occasionally returns null instead of an error
object. Added null check to prevent TypeError in production.

Fixes #423
Refs: PROJ-789
\```

\```
refactor(utils): extract validation logic into separate module

Move email, phone, and address validators from UserService
to dedicated validation module for better reusability.
\```

## 나쁜 예시

\```
# 오류: type이 없다
updated some files

# 오류: description이 모호하다
fix: fix bug

# 오류: 한국어로 작성된 description (영어 통일 권장)
feat: 계산기 기능 추가

# 오류: 너무 길다 (50자 초과)
feat: add new authentication system with JWT tokens and OAuth2 support and session management
\```
EOF

5-6단계: 동작 확인

cd ~/dev-workflow-skills
git add .claude/skills/commit-msg/
claude

> /commit-msg

6단계: commit-msg의 동작 확인

5단계에서 작성한 commit-msg가 올바르게 동작하는지 다음 관점에서 확인합니다.

스테이징된 변경이 없는 경우는 그에 맞는 표시가 됩니다. git add 후 재시도하면 git diff --staged의 내용을 취득하여 커밋 메시지가 3가지 패턴으로 제안됩니다. 안전성 제약대로 git commit이 실행되지 않는 것을 반드시 확인하세요.

7단계: Git에 최종 커밋

모든 작업이 완료되면, 최종 상태를 커밋합니다.

cd ~/dev-workflow-skills
git add .claude/skills/
git add src/
git add docs/
git commit -m "feat: 개발 워크플로우 표준 스킬셋 완성 (pr-review, test-gen, doc-gen, commit-msg)"

최종적인 디렉토리 구조를 확인합니다.

find ~/dev-workflow-skills/.claude/skills -type f | sort

기대되는 출력:

.claude/skills/commit-msg/examples/sample-messages.md

.claude/skills/commit-msg/references/conventional-commits.md

.claude/skills/commit-msg/SKILL.md

.claude/skills/doc-gen/assets/api-doc-template.md

.claude/skills/doc-gen/SKILL.md

.claude/skills/pr-review/examples/bad-review.md

.claude/skills/pr-review/examples/good-review.md

.claude/skills/pr-review/references/coding-standards.md

.claude/skills/pr-review/references/review-checklist.md

.claude/skills/pr-review/references/security-guidelines.md

.claude/skills/pr-review/scripts/get-diff.sh

.claude/skills/pr-review/SKILL.md

.claude/skills/README.md

.claude/skills/REVIEW_CHECKLIST.md

.claude/skills/test-gen/examples/sample-test.md

.claude/skills/test-gen/references/test-guidelines.md

.claude/skills/test-gen/SKILL.md

더 나아가기

업무 Skill의 설계와 구현

commit-msg를 참고로, 자신의 팀 업무에 맞는 새로운 Skill을 설계해보세요.

아이디어 예시:

Skill 연계 시나리오의 설계

여러 Skill을 연계하는 표준 개발 워크플로우를 팀의 README.md나 사내 Wiki에 문서화하세요.

## 표준 개발 워크플로우

1. 기능 구현 완료 후
- `/test-gen {파일}` — 테스트 코드 자동 생성
- `/doc-gen {파일}` — API 문서 갱신
2. PR 작성 전
- `/commit-msg` — Conventional Commits 형식의 메시지 생성
- `/pr-review` — 자기 리뷰 실시
3. PR 머지 후
- (자동) GitHub Actions로 릴리스 노트 생성