PRD 기반 개발: 30개 이상의 PRD로 AI 에이전트와 함께 배포하는 방법

SaasMaker의 RalphBlaster 워크플로우는 한 줄짜리 티켓에서 45분 이내에 완전한 풀 리퀘스트를 생성하며, 개발자는 구현 과정에서 코드를 전혀 건드리지 않습니다.¹

저도 이 패턴을 시도해 봤습니다. 효과가 있습니다. 하지만 데모 영상에서는 보여주지 않는 방식으로 실패하기도 합니다.

TL;DR

지난 6개월간 AI 에이전트 작업을 위해 30개 이상의 PRD를 작성했습니다. 이 패턴은 명확한 인수 기준이 있는 잘 정의된 작업에 효과적입니다: CRUD 엔드포인트, 테스트 추가, 기존 패턴을 따르는 UI 컴포넌트 등이 해당됩니다. 반면 모호한 요구사항, 새로운 아키텍처 결정, 반복적인 인간의 판단이 필요한 모든 작업에서는 실패합니다. 제 PRD 템플릿은 단순한 사용자 스토리 형식에서 파일 위치, 테스트 기대치, 제약 조건, 명시적인 “수정 금지” 목록을 갖춘 구조화된 문서로 진화했습니다. 이러한 진화는 에이전트가 모호한 PRD를 예상치 못한 방식으로 해석했기 때문에 일어났습니다.

실제로 사용하는 워크플로우

1단계: 티켓 생성

무엇을 해야 하는지 일상 언어로 정의합니다. 구체성이 처음 생각했던 것보다 훨씬 중요합니다:

모호한 경우 (예측 불가능한 결과 발생):

Add user preference saving to the settings page.

구체적인 경우 (예측 가능한 결과 발생):

Add dark mode toggle to /settings. Persist to user_preferences
table (column: dark_mode, type: boolean, default: false).
Use existing SettingsForm component. Add toggle below the
notification section. No new dependencies.

두 번째 버전은 에이전트를 충분히 제한하여 출력이 기대에 부합합니다. 첫 번째 버전은 새로운 React 컴포넌트, 세 개의 새로운 npm 패키지, 그리고 제가 원했던 데이터베이스 영속화 대신 localStorage 구현이 포함된 설정 페이지를 만들어냈습니다.

2단계: PRD 생성 또는 작성

제 /prd 스킬은 티켓을 사용자 스토리, 인수 기준, 파일 위치, 테스트 기대치가 포함된 구조화된 PRD로 변환합니다.² 일반적인 PRD는 다음과 같습니다:

## Story: Add dark mode toggle
**As a** user
**I want to** toggle dark mode from settings
**So that** I can read comfortably in low light

### Acceptance Criteria
- [ ] Toggle appears in SettingsForm below notifications
- [ ] Persists to user_preferences.dark_mode (boolean)
- [ ] Default: false (light mode)
- [ ] Toggle state reflects current DB value on page load

### Files to Modify
- app/routes/settings.py (add dark_mode to form handler)
- app/templates/settings.html (add toggle component)
- app/models/user.py (add dark_mode column if missing)

### Files NOT to Modify
- app/static/css/styles.css (dark mode CSS already exists)
- app/templates/base.html (already reads dark_mode class)

### Test Expectations
- Test toggle persists to database
- Test default value on new user
- Test toggle reflects current state on reload

“Files NOT to Modify” 섹션이 가장 큰 템플릿 진화였습니다. 이 섹션 없이는 에이전트가 친절하게도 관련 파일을 “개선”하여, 제가 요청하지도 원하지도 않은 변경사항을 도입했습니다.

3단계: 에이전트 구현

에이전트는 격리된 git worktree에서 작업하여 현재 브랜치에 간섭하는 것을 방지합니다:³

# Create isolated worktree for agent task
git worktree add ../worktrees/dark-mode -b feature/dark-mode

# Agent works in ../worktrees/dark-mode/
# I continue working in main workspace

# Review and cleanup after merge
git worktree remove ../worktrees/dark-mode

제 재귀 가드는 에이전트의 스폰 동작을 모니터링합니다. git 안전 가디언은 에이전트가 강제 푸시하거나 자격 증명을 커밋하는 것을 방지합니다. 이러한 훅은 자동으로 실행됩니다. 구현 중에 에이전트를 감독하지 않습니다.

4단계: 리뷰

에이전트가 완료되면 알림이 도착합니다. PRD 인수 기준에 대해 diff를 검토합니다. 모든 기준이 통과하면 병합합니다. 그렇지 않으면 수동으로 수정하거나 업데이트된 컨텍스트로 에이전트를 재시작합니다.⁴

PRD 기반 개발이 효과적인 경우

명확한 데이터 모델이 있는 CRUD 엔드포인트. PRD가 모델, 라우트, 응답 형식을 지정합니다. 에이전트는 기존 패턴에 맞는 보일러플레이트를 생성합니다.

기존 코드에 대한 테스트 추가. “유효한 slug, 유효하지 않은 slug, 누락된 파일을 커버하는 app/content.py의 load_post_by_slug 테스트 작성”은 함수가 이미 존재하고 인수 기준이 객관적이기 때문에 유용한 테스트를 생성합니다.

기존 패턴을 따르는 UI 컴포넌트. “가이드 페이지와 동일한 탭 패턴을 사용하여 블로그 목록 페이지에 카테고리 필터 추가”는 에이전트가 기존 패턴을 참조할 수 있기 때문에 효과적입니다.

정의된 스키마가 있는 데이터베이스 마이그레이션. PRD가 컬럼, 타입, 기본값, 제약 조건을 지정합니다. 에이전트는 마이그레이션을 생성하고 모델을 업데이트합니다.

PRD 기반 개발이 실패하는 경우

모호한 요구사항. “블로그를 더 좋게 만들어 주세요”는 PRD가 아닙니다. 에이전트는 변경을 하겠지만, 여러분의 의도가 명시되지 않았기 때문에 의도와 일치하지 않을 것입니다.

새로운 아키텍처 결정. 숙의 시스템의 합의 모델을 설계해야 했을 때, 어떤 PRD도 그 결정을 담아낼 수 없었습니다. 옵션을 탐색하고, 트레이드오프를 평가하며, 설계를 반복해야 했습니다. 이를 위해서는 PRD가 아닌 제 숙의 스킬이 필요했습니다.

성능 최적화. “페이지 로딩을 더 빠르게 만들어 주세요”는 프로파일링, 측정, 반복적인 조사가 필요합니다. 에이전트는 PRD만으로 프로덕션 트래픽 패턴을 프로파일링할 수 없습니다.

보안에 민감한 코드. 인증 시스템에 대한 PRD는 정상 경로를 처리하는 코드를 생성합니다. 인증의 엣지 케이스(타이밍 공격, 세션 고정, 비표준 흐름에서의 CSRF)는 PRD가 인코딩할 수 없는 인간의 전문 지식이 필요합니다.

PRD 템플릿의 진화 과정

버전 1 (1개월 차): 단순한 사용자 스토리

As a user, I want to save preferences so I can customize my experience.

문제: 너무 모호했습니다. 에이전트가 저장 메커니즘, UI 배치, 범위에 대해 합리적이지만 잘못된 가정을 했습니다.

버전 2 (2개월 차): 파일 위치 추가

## Story: Save preferences
### Files to Modify
- app/routes/settings.py
- app/templates/settings.html

문제: 개선되었지만, 에이전트가 여전히 허락 없이 인접 파일을 “개선”했습니다.

버전 3 (4개월 차): 제약 조건 추가

## Story: Save preferences
### Files to Modify (only these)
- app/routes/settings.py
- app/templates/settings.html
### Constraints
- No new dependencies
- Use existing database models
- Do not modify CSS

문제: 에이전트가 훈련 데이터의 “모범 사례”와 충돌할 때 제약 조건을 무시하는 경우가 있었습니다.

버전 4 (현재): 명시적 제외 목록 + 테스트 기대치

현재 템플릿은 “Files NOT to Modify,” 명시적 테스트 기대치, 인수 기준 체크박스를 추가했습니다. 이 버전은 약 85%의 확률로 예측 가능한 결과를 생성합니다. 나머지 15%는 명확해진 지시사항으로 두 번째 패스가 필요합니다.⁵

30개 PRD 패턴 라이브러리

30개 이상의 PRD를 작성한 후 패턴이 나타났습니다:

새로운 기능의 성공률(50%)은 PRD 기반 개발이 제 워크플로우를 대체하는 것이 아니라 보완하는 이유를 설명합니다. 절반의 경우, 새로운 작업은 PRD가 사전에 담아낼 수 없는 반복이 필요합니다.

핵심 시사점

1인 개발자를 위한 조언: - 잘 정의된 PRD 유형 하나(CRUD, 테스트)로 시작하고, 복잡한 작업으로 확장하기 전에 워크플로우를 검증하세요 - 모든 PRD에 “Files NOT to Modify”를 추가하세요; 에이전트는 친절하게도 요청하지 않은 코드를 “개선”할 것입니다 - 에이전트 작업을 격리하기 위해 git worktree를 사용하세요; 실패한 에이전트 실행의 정리 비용은 git 고고학 세션이 아닌 하나의 명령이어야 합니다

엔지니어링 매니저를 위한 조언: - PRD 품질이 에이전트 출력 품질을 결정합니다; 자율 에이전트 사용을 확장하기 전에 PRD 템플릿과 리뷰 프로세스에 투자하세요 - 워크플로우 성숙도를 측정하기 위해 변경 없이 병합된 비율을 추적하세요; PRD 템플릿이 진화함에 따라 이 비율이 개선되어야 합니다 - 새로운 아키텍처 작업과 보안에 민감한 코드는 PRD로 위임하지 마세요; 잘 정의되고 반복 가능한 작업에 에이전트 위임을 제한하세요

참고 자료