Ai 마법서

02_commands

7 min read

모듈 2: Commands - 커스텀 명령어

학습 목표

  • Claude Code 커스텀 명령어의 개념을 이해한다
  • /generate-prp와 /execute-prp의 역할과 차이를 설명할 수 있다
  • 프로젝트에 맞는 커스텀 명령어를 작성할 수 있다

Commands란?

.claude/commands/ 폴더의 마크다운 파일들입니다. 각 파일이 하나의 슬래시 명령어(/명령어이름)가 됩니다.

.claude/commands/
├── generate-prp.md    ->  /generate-prp
├── execute-prp.md     ->  /execute-prp
└── primer.md          ->  /primer

명령어를 실행하면 해당 마크다운 파일의 내용이 AI에게 전달되는 프롬프트가 됩니다.

왜 커스텀 명령어가 필요한가?

반복 작업의 표준화

팀마다 코드 생성 시 반복적으로 요청하는 패턴이 있습니다:

# 매번 이렇게 요청하면...
"HmEG API 확인하고, 기존 예제 패턴 따르고,
 CLAUDE.md 규칙 지키고, 빌드 확인하고,
 CAD 특화 안전 조치도 적용해서 구현해줘"

# 커스텀 명령어로:
/execute-prp PRPs/my_feature.md

generate-prp 명령어 분석

호출 방법

/generate-prp PRPs/INITIAL.md

역할: 기능 요청서 → 구현 설계서 변환

[INITIAL.md: 기능 요청]
"3D 단면 뷰어 기능을 추가해주세요.
 X/Y/Z 축으로 단면을 자를 수 있어야 합니다."
        |
        v
/generate-prp
        |
        v
[PRPs/cross_section_prp.md: 구현 설계서]
- 필요한 API 카테고리 식별
- 파일 구조 설계
- 구현 단계별 체크리스트
- 위험 요소 및 롤백 계획

generate-prp가 수행하는 4단계

Phase 1: Research & Analysis
- INITIAL.md 기능 요청 분석
- examples/ 디렉토리 패턴 파악
- 의존성, 충돌, 통합 지점 식별
 
Phase 2: API Category Identification
- 필요한 CAD API 카테고리 식별
- [API 조회 필요] 마커 표시
  (실제 API는 execute-prp 시점에 조회 - 컨텍스트 절약)
 
Phase 3: Blueprint Creation
- 파일 구조 정의
- 단계별 구현 계획
- 검증 게이트 정의
 
Phase 4: Risk Management
- 위험 요소 식별
- 롤백 절차
- CAD 특화 문제 대응 계획

PRP 파일 출력 예시

# PRPs/cross_section_prp.md
 
## 개요
CrossSection 기능: EGViewport에서 X/Y/Z 단면 뷰 제공
 
## API 조회 항목
- [API 조회 필요: CrossSectionPlane Constructor]
- [API 조회 필요: EGViewport.CrossSection 속성]
 
## 아키텍처
src/ui/ViewModels/CrossSectionViewModel.cs  <- 신규
src/ui/Views/CrossSectionView.xaml          <- 신규
 
## 구현 단계
Step 1: CrossSectionViewModel 기본 구조
Step 2: [API 조회 필요: CrossSectionPlane] 적용
Step 3: View 바인딩
Step 4: 빌드 및 Warning 0 확인

execute-prp 명령어 분석

호출 방법

/execute-prp PRPs/cross_section_prp.md

역할: 설계서 → 실제 코드 구현

[PRPs/cross_section_prp.md]
        |
        v
/execute-prp
        |
        v (API Lazy Loading)
[API 조회 필요] 마커 수집
        |
        v
hmeg-api Skill 호출 (각 카테고리별)
        |
        v
실제 코드 구현 + 빌드 검증

execute-prp가 수행하는 단계

Pre-execution:
1. PRP 파일 완전 독해
2. [API 조회 필요] 마커 전체 수집
3. 상세 TODO 체크리스트 작성

API Lookup Phase (Lazy Loading):
4. 마커를 카테고리별로 그룹화
5. 각 카테고리별 hmeg-api Skill 호출
   - 실제 API 시그니처 획득
   - C# 예제 코드 획득
   - Citation으로 정확성 보장

Execution Loop:
6. 체크리스트를 하나씩 구현
7. 각 단계 후 즉시 검증 게이트 실행
8. 실패 시 최대 3회 수정 시도

Safety Measures (CAD 특화):
- 검증 게이트 절대 건너뛰지 않음
- Transaction Commit 또는 Abort 보장
- DocumentLock using 블록 처리

두 명령어의 관계

[기능 요청 단계]                [구현 단계]

사용자가 INITIAL.md 작성
         |
         v
/generate-prp INITIAL.md  ---> PRPs/feature_prp.md
         |                              |
         v                              v
    (검토/수정)              /execute-prp PRPs/feature_prp.md
                                        |
                                        v
                               실제 코드 + 빌드 성공

왜 2단계로 나누는가?

  1. 검토 시점 제공: 개발자가 PRP를 보고 방향 수정 가능
  2. API 할루시네이션 방지: generate 시 API 코드 작성 금지, execute 시 Skill로 조회
  3. 컨텍스트 절약: generate 시 API 세부 정보 불필요 (의도만 기술)

primer 명령어

/primer

세션 시작 시 프로젝트 맥락을 AI에 주입하는 간단한 명령어입니다. 긴 세션 후 AI가 맥락을 잃었을 때 재주입하는 용도로 사용합니다.

커스텀 명령어 작성 방법

파일 생성

# 새 명령어 만들기
# 파일명 = 명령어 이름
.claude/commands/my-command.md

파일 내용 구조

# Role: [AI의 역할 정의]
 
# Task: [수행할 작업 설명]
 
[단계별 지시사항...]
 
**Output Format:**
[출력 형식 지정]

$ARGUMENTS 변수

# 명령어 파일에서 인자 사용
Task: Read the feature request from `$ARGUMENTS`
# 사용자가 호출 시
/generate-prp PRPs/INITIAL.md
# $ARGUMENTS = "PRPs/INITIAL.md"

실습: 새 커스텀 명령어 작성

다음 명령어를 작성해보세요: /review-code

# .claude/commands/review-code.md
 
# Role: C# Code Reviewer
 
# Task: Review the code in `$ARGUMENTS` against CLAUDE.md rules
 
1. CLAUDE.md 필수 규칙 준수 여부 확인
   - HmEG 객체 using/Dispose 처리 확인
   - try/catch 예외 처리 확인
   - 빌드 경고 가능성 검토
 
2. MVVM 패턴 준수 여부 확인
 
3. 리뷰 결과를 다음 형식으로 출력:
   - 통과 항목: [목록]
   - 개선 필요: [목록 + 수정 방안]

핵심 정리

명령어입력출력역할
/generate-prpINITIAL.mdPRPs/*.md기능 요청 → 설계서
/execute-prpPRPs/*.md실제 코드설계서 → 구현
/primer없음맥락 주입세션 재시작
  • Commands는 팀 표준 프롬프트를 코드로 관리하는 방법
  • $ARGUMENTS로 동적 인자 전달 가능
  • 팀원 모두가 git으로 동일한 명령어 사용

Graph View