스킬 사용 가이드

| 스킬 | 호출 | 한줄 설명 | |------|------|----------| | Planning | `/planning` | 작업 계획 수립 (Plan Mode) | | Design Doc | `/design-doc` | 설계 문서 작성 (AD

guide docs/guide/SKILL_GUIDE.md

11개 스킬의 용도, 사용 시점, 워크플로우 내 위치를 안내한다. 스킬은 /스킬명으로 호출한다. (예: /tdd, /commit)

스킬 카탈로그

스킬	호출	한줄 설명
Planning	`/planning`	작업 계획 수립 (Plan Mode)
Design Doc	`/design-doc`	설계 문서 작성 (ADR/DESIGN.md)
TDD	`/tdd`	테스트 선행 개발 (RED-GREEN-REFACTOR)
Debugging	`/debugging`	반복 오류 체계적 진단
Refactoring	`/refactoring`	안전한 코드 구조 개선
Code Review	`/code-review`	PR 전 2단계 리뷰
Commit	`/commit`	커밋 + push 안전 프로세스
PR Create	`/pr-create`	PR 생성 + 충돌 확인
Daily Scrum	`/daily-scrum`	일일 현황 리포트
Weekly Report	`/weekly-report`	주간 보고서
Self Improve	`/self-improve`	규칙 자기 개선 루프

언제 어떤 스킬을 쓰는가

개발 흐름별 스킬 매핑

요청 접수
  │
  ├─ 설계가 필요한가? (DB/API 변경, 대안 비교)
  │   └─ YES → /design-doc → 승인 후 다음
  │
  ├─ 구현 계획이 필요한가? (20줄+, 3파일+)
  │   └─ YES → /planning → 승인 후 다음
  │
  ├─ 새 기능 구현
  │   └─ /tdd (테스트 먼저 → 구현 → 리팩터링)
  │
  ├─ 기존 코드 구조 개선
  │   └─ /refactoring (Blast Radius 분석 → 단계별 변경)
  │
  ├─ 오류 반복 (2회+)
  │   └─ /debugging (진단 → 스냅샷 → 1회 수정 → 검증)
  │
  ├─ 구현 완료 → 커밋
  │   └─ /commit (브랜치 확인 → diff → 커밋 → push)
  │
  ├─ PR 생성 전
  │   └─ /code-review (spec-reviewer → code-reviewer)
  │   └─ /pr-create (충돌 확인 → PR 생성)
  │
  ├─ 보고
  │   ├─ /daily-scrum (매일)
  │   └─ /weekly-report (매주)
  │
  └─ 규칙 개선
      └─ /self-improve (위반 패턴 → 규칙 보강)

상황별 빠른 선택

"새 기능을 만들어야 한다"

단계	스킬	조건
1	`/design-doc`	DB/API 변경이 있으면 필수
2	`/planning`	20줄+ 또는 3파일+ 이면 사용
3	`/tdd`	새 함수/모듈 구현 시 권장
4	`/commit`	구현 완료 후
5	`/code-review` → `/pr-create`	PR 생성 시

"버그를 고쳐야 한다"

단계	스킬	조건
1	`/tdd` (Regression-First)	버그 재현 테스트 먼저 작성
2	`/debugging`	같은 오류 2회 반복 시 전환
3	`/commit`	수정 완료 후

"코드를 리팩터링해야 한다"

단계	스킬	조건
1	`/planning`	영향 범위가 클 때
2	`/refactoring`	실행 — Blast Radius 분석 → 단계별 변경
3	`/commit`	완료 후 (리팩터링과 기능 변경은 별도 커밋)

"PR을 올려야 한다"

단계	스킬
1	`/code-review` — spec-reviewer가 범위 검증, code-reviewer가 품질 검증
2	`/pr-create` — 충돌 확인 → PR 생성 → 브랜치 상태 보고

"현황을 보고해야 한다"

스킬	주기	산출물
`/daily-scrum`	매일	`reports/daily/YYYY-MM-DD.md`
`/weekly-report`	매주	`reports/weekly/YYYY-WNN.md`

스킬 간 연결 관계

/design-doc ──승인──→ /planning ──승인──→ 구현
                                          │
                              ┌────────────┤
                              │            │
                           /tdd      /refactoring
                              │            │
                              └────────────┤
                                           │
                                    /debugging (오류 2회 시)
                                           │
                                       /commit
                                           │
                                    /code-review
                                           │
                                     /pr-create

게이트 연동

게이트	연결 스킬	역할
G1 (계획→설계)	`/planning`	작업 의도 + 범위 확인
G2 (설계→구현)	`/design-doc`	DB/API 설계 승인
G3 (구현→리뷰)	`/commit` + `/code-review`	타입 체크 + lint + 리뷰 통과
G4 (리뷰→배포)	`/pr-create`	PR 생성 + 병합

자동 진입 조건

일부 스킬은 조건 충족 시 에이전트가 자동으로 사용한다:

스킬	자동 진입 조건
`/planning`	변경 예상 20줄+ 또는 3파일+
`/debugging`	동일 오류 2회 반복
`/design-doc`	DB 스키마 또는 API 시그니처 변경 포함
`/code-review`	PR 생성 전 (에이전트 PR은 필수)

나머지는 사용자가 명시적으로 호출한다.

스킬 설계 원칙

모든 스킬은 아래 공통 구조를 따른다:

When to use — 언제 이 스킬을 쓰는가
실행 순서 — 단계별 프로세스 (Step 1, 2, 3...)
변명 방지 테이블 — 에이전트가 빠지기 쉬운 함정과 올바른 행동
완료 기준 또는 보고 형식 — 스킬 종료 조건

스킬의 진짜 가치는 목록이 아니라 내부의 구체적 실패 사례와 체크리스트다.