Skill 디렉토리 구조 설계

references·examples·scripts로 리뷰 품질 높이기

보조 파일의 전체 구조

SKILL.md는 500줄 이하로 유지하는 것이 권장됩니다. 상세한 정보는 별도 파일로 분리하여 Skill 디렉토리 내에 서브 디렉토리를 만들어 정리합니다.

공식 문서에서는 examples/와 scripts/가 예시로 제시되어 있지만, 디렉토리 이름에 제약은 없으며 용도에 맞게 자유롭게 생성할 수 있습니다.

.claude/skills/
pr-review/
SKILL.md
examples/ # 입출력의 구체적인 예시 (Few-shot용) ※공식 예시
scripts/ # 실행 가능한 스크립트 ※공식 예시
references/ # 참조용 문서 (규약, 가이드라인 등)
assets/ # 기타 보조 파일 (템플릿 등)

Claude는 Skill 실행 시 이 파일들을 자동으로 참조할 수 있습니다. SKILL.md의 본문에서 명시적으로 언급하면 참조의 확실성이 높아집니다.

각 디렉토리의 활용 예시

보충: examples/와 scripts/는 공식 문서에서 소개된 디렉토리입니다. references/와 assets/는 공식적으로 정의된 것은 아니지만, SKILL.md를 간결하게 유지하기 위한 정리 방법으로 본 책에서 채택하고 있습니다.

왜 SKILL.md에서 분리하는가

SKILL.md 본문에 모든 정보를 집어넣는 것도 가능하지만, 다음과 같은 이유로 별도 파일로의 분리가 권장됩니다.

보수성: 규약 업데이트 시 해당 파일만 수정하면 된다

재사용성: 여러 Skill에서 같은 파일을 참조할 수 있다

가독성: SKILL.md는 실행 절차에 집중하고, 상세 지식은 보조 파일에 위임한다

사이즈 제약: SKILL.md는 500줄 이하 권장. 대량의 정보는 별도 파일로 이동한다

� 한국 팀 개발 환경에서의 활용 팁
팀 내 코딩 규약이나 보안 정책이 Confluence, Notion, 사내 Wiki 등에 이미 정리되어 있다면, 그 내용을 references/에 그대로 가져와 Skill에 통합할 수 있습니다. 규약이 갱신되면 해당 파일만 수정하면 되므로 유지보수 비용이 최소화됩니다.

따라하기

1단계: pr-review에 references 추가

PR 리뷰의 기준이 되는 코딩 규약을 references로 작성합니다.

mkdir -p ~/dev-workflow-skills/.claude/skills/pr-review/references

.claude/skills/pr-review/references/coding-standards.md를 작성합니다.

# 코딩 규약

## 명명 규칙
- 변수·함수: camelCase
- 클래스: PascalCase
- 상수: UPPER_SNAKE_CASE
- 파일명: kebab-case

## 함수 설계
- 1함수는 30줄 이내를 기준으로 한다
- 인수는 4개 이하를 권장
- 조기 리턴을 활용하여 중첩을 3단계 이내로 억제한다

## 에러 핸들링
- try-catch는 구체적인 에러 타입으로 캐치한다
- 에러 메시지에는 원인과 대처 방법을 포함한다
- 비동기 처리에서는 반드시 에러 핸들링을 수행한다

## 보안
- 사용자 입력은 반드시 검증(validation)한다
- SQL 쿼리는 파라미터화(prepared statement)한다
- 기밀 정보를 로그에 출력하지 않는다

.claude/skills/pr-review/references/review-checklist.md를 작성합니다.

# 리뷰 체크리스트

## 필수 체크 항목
- [ ] 로직 에러가 없는가
- [ ] 엣지 케이스(null, 빈 배열, 0, 음수)를 고려하고 있는가
- [ ] 에러 핸들링이 적절한가
- [ ] 보안상의 문제가 없는가 (입력 검증, 인증·인가)
- [ ] 퍼포먼스상의 문제가 없는가 (N+1 쿼리, 불필요한 루프)

## 권장 체크 항목
- [ ] 명명이 적절하고 의도가 전달되는가
- [ ] 함수의 책임이 단일한가 (단일 책임 원칙)
- [ ] 테스트가 추가·업데이트되었는가
- [ ] 문서(주석, README 등)가 업데이트되었는가

다음으로, SKILL.md의 본문에서 references를 명시적으로 참조합니다.

.claude/skills/pr-review/SKILL.md를 업데이트하세요.

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

# PR 리뷰 Skill

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

## 참조해야 할 문서

리뷰 시에는 다음 문서를 기준으로 사용하세요.

- `references/coding-standards.md` - 코딩 규약
- `references/review-checklist.md` - 리뷰 체크리스트

## 리뷰 절차

1. 지정된 파일 또는 직전 변경 차분을 `git diff`로 확인한다
2. `references/review-checklist.md`의 각 항목에 대해 확인한다
3. `references/coding-standards.md`에 위반되는 부분을 특정한다
4. 각 지적에 중요도(Critical / Warning / Info)를 부여한다

## 출력 포맷

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

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

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

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

2단계: pr-review에 examples 추가

리뷰 출력의 품질을 안정시키기 위해 좋은 예와 나쁜 예를 작성합니다.

mkdir -p ~/dev-workflow-skills/.claude/skills/pr-review/examples

.claude/skills/pr-review/examples/good-review.md를 작성합니다.

# 좋은 리뷰 출력 예시

## 리뷰 요약
변경 파일: 3파일 (src/auth/login.ts, src/auth/validate.ts, src/utils/hash.ts)
변경 내용: 로그인 인증 플로우 개선

## 지적 사항

### [Critical] 패스워드 해시 비교가 타이밍 공격에 취약
- 파일: `src/utils/hash.ts` (L15)
- 규약 참조: 보안 > 기밀 정보 취급
- 문제: `===`에 의한 문자열 비교는 타이밍 공격에 취약합니다. 공격자가 응답 시간의 차이로부터 패스워드 해시를 추측할 수 있는 가능성이 있습니다.
- 제안: `crypto.timingSafeEqual()`을 사용하세요.
```typescript
import { timingSafeEqual } from 'crypto';
const isMatch = timingSafeEqual(Buffer.from(hash1), Buffer.from(hash2));
```

### [Warning] 에러 메시지가 너무 구체적
- 파일: `src/auth/login.ts` (L42)
- 규약 참조: 보안 > 에러 핸들링
- 문제: "패스워드가 틀렸습니다"라는 메시지는 사용자명이 유효하다는 것을 공격자에게 시사합니다.
- 제안: "이메일 주소 또는 패스워드가 올바르지 않습니다"로 변경하세요.

### [Info] 함수명 개선 제안
- 파일: `src/auth/validate.ts` (L8)
- 규약 참조: 명명 규칙 > 함수
- 문제: `check()`는 무엇을 체크하는지 불명확합니다.
- 제안: `validateLoginCredentials()`처럼 구체적인 이름으로 하세요.

## 총평
보안상의 Critical 지적이 1건 있으며, 머지 전에 수정이 필요합니다. 인증 플로우의 기본 설계는 적절하지만, 암호화 관련 처리에는 더욱 신중한 구현이 요구됩니다.

.claude/skills/pr-review/examples/bad-review.md를 작성합니다.

# 나쁜 리뷰 출력 예시 (이렇게 쓰지 말 것)

## 문제점

### 구체성이 없는 지적
- 부적합: "이 코드는 좋지 않다"
- 부적합: "더 깔끔하게 써주세요"
- 부적합: "버그가 있을 것 같다"

### 개선안이 없는 지적
- 부적합: "이 함수는 너무 깁니다" (→ 어떻게 분할해야 하는지 제안이 없음)
- 부적합: "명명이 나쁘다" (→ 어떤 이름으로 해야 하는지 제안이 없음)

### 중요도 구별이 없음
- 부적합: 모든 지적을 같은 비중으로 나열한다
- 부적합: 보안상의 문제와 형식 문제를 구별하지 않는다

### 해당 부분이 불명확
- 부적합: 파일명이나 행 번호가 없음
- 부적합: "어딘가에서 에러 핸들링이 부족하다"