Ai 마법서

06_prps

8 min read

모듈 6: PRPs - 기능 요청서 작성법

학습 목표

  • PRP(Product Requirements Prompt)의 개념을 이해한다
  • 좋은 PRP와 나쁜 PRP의 차이를 설명할 수 있다
  • HmEG 프로젝트에 맞는 PRP를 직접 작성할 수 있다
  • PRP 기반 개발 사이클을 실행할 수 있다

PRP란?

Product Requirements Prompt - AI가 기능을 구현하는 데 필요한 모든 맥락을 담은 구조화된 문서입니다.

단순한 기능 요청서가 아니라, AI가 첫 번째 시도에 올바른 코드를 생성할 수 있도록 설계된 작업 지시서입니다.

PRPs/
├── templates/
│   └── prp_base.md       # PRP 작성 템플릿
└── [feature]_prp.md      # 실제 기능 PRP (generate-prp가 생성)

PRP가 필요한 이유

나쁜 기능 요청 (자연어)

"HmEG 뷰포트에 단면 기능 추가해줘"

AI가 모르는 것들:

  • 어떤 HmEG API를 써야 하나?
  • MVVM 패턴을 어떻게 적용해야 하나?
  • 기존 예제 중 참조할 패턴은?
  • 어떤 단계로 구현하면 되나?
  • 실패 시 어떻게 롤백하나?

결과: 할루시네이션이 있는 코드, 여러 번의 수정 필요

좋은 기능 요청 (PRP)

## 목표
EGViewport에 X/Y/Z 축 CrossSection(단면) 기능 추가
 
## 참조 컨텍스트
- examples/EGViewportSample/ViewModels/CrossSectionViewModel.cs 패턴 따를 것
- HmEG API: [API 조회 필요: CrossSectionPlane] - execute 시 hmeg-api로 조회
 
## 구현 단계
Step 1: CrossSectionViewModel 생성
Step 2: [API 조회 필요: CrossSectionPlane 생성자] 적용
Step 3: CrossSectionView.xaml 바인딩
Step 4: dotnet build (Warning 0 확인)
 
## 검증 게이트
- dotnet build: Warning 0
- CrossSection 토글 동작 확인

결과: 첫 시도에 올바른 코드 생성

PRP 기본 템플릿 구조

## Goal
[무엇을 만들 것인가 - 구체적인 최종 상태]
 
## Why
- [비즈니스 가치]
- [기존 기능과의 연계]
- [해결하는 문제]
 
## What
[사용자가 보는 동작 + 기술 요구사항]
 
### Success Criteria
- [ ] [측정 가능한 완료 기준]
 
## All Needed Context
 
### Documentation & References
- file: examples/EGViewportSample/...
  why: 참조할 패턴
 
### Known Gotchas
# HmEG 객체는 반드시 using 블록 사용
# try/catch 예외 처리 필수
 
## Implementation Blueprint
 
### Tasks
Task 1: ...
Task 2: ...
 
## Validation Loop
 
### Level 1: Build
dotnet build (Warning 0)
 
### Level 2: Unit Tests
dotnet test
 
### Level 3: Integration
[실제 동작 확인 방법]

HmEG 프로젝트 PRP 작성 가이드

1. API 조회 마커 활용

PRP 작성 시 실제 API 코드를 직접 쓰지 마세요:

# 잘못된 방법 (API 코드 직접 작성)
Step 2: CrossSectionPlane 생성
코드: var plane = new CrossSectionPlane(Vector3.UnitX, 0.0);
 
# 올바른 방법 (마커 표시)
Step 2: [API 조회 필요: CrossSectionPlane Constructor] 적용
- 평면 법선 벡터와 오프셋으로 단면 생성

이유: generate-prp 시점에 API 코드를 넣으면 할루시네이션 위험. execute-prp 시점에 hmeg-api Skill이 정확한 API를 제공합니다.

2. 기존 예제 패턴 명시

## All Needed Context
 
### Code Patterns to Follow
- file: examples/EGViewportSample/ViewModels/CrossSectionViewModel.cs
  why: EGViewport 단면 뷰 ViewModel 패턴 (기존 구현 있음)
 
- file: examples/EGViewportSample/ViewModels/ViewportViewModel.cs
  why: EGViewport 초기화 및 MVVM 연결 패턴

3. HmEG 특화 규칙 명시

## Known Gotchas
# CRITICAL: HmEG 객체는 using 블록 필수
using var space = viewport.RootSpace;  // OK
var space = viewport.RootSpace;        // NG - 메모리 누수
 
# CRITICAL: UI 스레드 체크
Application.Current.Dispatcher.Invoke(() => {
    // UI 업데이트는 반드시 Dispatcher를 통해
});
 
# 빌드 경고 0개 목표

INITIAL.md 작성 예시

generate-prp에 입력하는 초기 기능 요청서:

# INITIAL.md: 레이어 관리 기능 요청
 
## 기능 개요
3D 뷰포트에서 레이어별로 오브젝트 표시/숨김을 제어하는 기능
 
## 요구사항
1. 레이어 목록을 트리뷰로 표시
2. 체크박스로 레이어별 On/Off
3. 레이어별 색상 표시
4. 실시간으로 3D 뷰포트에 반영
 
## 참고 사항
- 기존 EGViewportSample의 레이어 구조 참조
- MVVM 패턴 사용
- HmEG LayerTable API 활용
 
## 우선순위
High - 토목 설계 작업에 필수 기능

PRP 생성 및 실행 사이클

Step 1: INITIAL.md 작성

# PRPs/INITIAL.md 작성 후
/generate-prp PRPs/INITIAL.md

Step 2: 생성된 PRP 검토

PRPs/layer_management_prp.md 생성됨

검토 포인트:
- API 조회 마커가 적절히 표시되었나?
- 구현 단계 순서가 논리적인가?
- 검증 게이트가 충분한가?
- 위험 요소가 파악되었나?

Step 3: PRP 수정 (필요시)

# 생성된 PRP에 직접 추가
## Known Gotchas 추가
# LayerTable은 트랜잭션 내에서만 수정 가능
# 레이어 색상은 Color 타입 (System.Drawing.Color와 다름)

Step 4: 구현 실행

/execute-prp PRPs/layer_management_prp.md

Step 5: 검증

dotnet build   # Warning 0 확인
dotnet test    # 테스트 통과 확인

실제 PRP 예시: CrossSection 기능

# PRPs/cross_section_prp.md
 
## 개요
EGViewport에 X/Y/Z 축 단면 뷰(CrossSection) 기능 추가
 
## API 조회 항목
- [API 조회 필요: EGViewport.CrossSectionEnabled]
- [API 조회 필요: CrossSectionPlane Constructor]
- [API 조회 필요: EGViewport.CrossSectionPlane 속성]
 
## 아키텍처
### 신규 파일
src/ui/ViewModels/CrossSectionViewModel.cs
src/ui/Views/CrossSectionView.xaml
src/ui/Views/CrossSectionView.xaml.cs
 
### 수정 파일
src/ui/ViewModels/MainViewModel.cs  <- CrossSectionViewModel 추가
 
## 구현 단계
 
### Step 1: CrossSectionViewModel 기본 구조
- ObservableObject 상속
- EGViewport 생성자 주입
- IsEnabled, Axis, Offset 프로퍼티
 
### Step 2: CrossSection API 적용
- [API 조회 필요: CrossSectionPlane 생성] 구현
- X/Y/Z 축 전환 로직
 
### Step 3: View 구현
- 슬라이더로 단면 위치 조정
- 라디오 버튼으로 축 선택
 
### Step 4: MainViewModel 통합
- CrossSectionViewModel 프로퍼티 추가
- 초기화 코드 추가
 
## 검증 게이트
- [ ] dotnet build (Warning 0)
- [ ] X축 단면 동작 확인
- [ ] Y축 단면 동작 확인
- [ ] Z축 단면 동작 확인
- [ ] 단면 On/Off 토글 동작
 
## 위험 완화
- CrossSectionPlane은 UI 스레드에서만 설정
- 잘못된 Offset 값에 대한 예외 처리 필수

PRP vs 일반 프롬프트 비교

측면일반 프롬프트PRP
API 정확도할루시네이션 위험Skill 조회로 정확
코드 패턴AI 임의 결정기존 예제 명시
구현 순서AI 임의 순서명확한 단계별
검증없음게이트별 체크
실패 대응없음롤백 계획 포함

핵심 정리

  • PRP = AI가 첫 번째 시도에 올바른 코드를 생성하기 위한 구조화된 작업 지시서
  • generate-prp로 생성 → 검토/수정 → execute-prp로 구현
  • [API 조회 필요] 마커: generate 시 API 할루시네이션 방지
  • 기존 examples/ 패턴을 명시적으로 참조
  • HmEG 특화 규칙 (using 블록, try/catch)을 Gotchas에 명시
  • 검증 게이트: 각 단계별 확인 기준 정의

Graph View