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로 위임하지 마세요; 잘 정의되고 반복 가능한 작업에 에이전트 위임을 제한하세요

자주 묻는 질문

PRD 기반 개발이란 무엇입니까

PRD 기반 개발은 AI 에이전트가 자율적으로 구현할 수 있을 만큼 구체적으로 작업을 정의한 Product Requirements Document를 중심으로 진행하는 워크플로우입니다. PRD에는 사용자 스토리, 인수 기준, 파일 위치, 제약 조건, 테스트 기대치가 포함됩니다. 에이전트가 격리된 git worktree에서 작업하는 동안 여러분은 다른 작업을 계속할 수 있습니다. 이 패턴은 CRUD 엔드포인트, 테스트 추가, 기존 패턴을 따르는 UI 컴포넌트처럼 잘 정의되고 반복 가능한 작업에서 가장 잘 작동합니다.

워크플로우를 신뢰하기까지 PRD를 몇 개나 작성해야 합니까

테스트 추가나 데이터베이스 마이그레이션처럼 기대 출력에 확신이 있는 단일 카테고리에서 PRD 3~5개로 시작하십시오. 제 경험상 이러한 카테고리의 성공률은 약 90%입니다. 템플릿이 예측 가능한 결과를 낸다는 점을 검증한 뒤에 UI 컴포넌트(성공률 약 85%)와 버그 수정(약 80%)으로 확장하십시오. 새로운 기능은 성공률이 약 50%이므로 PRD 기반 개발의 출발점으로 삼아서는 안 됩니다.

Claude Code에서 사용하는 PRD에는 어떤 형식이 가장 적합합니까

가장 효과적인 PRD 형식은 다섯 개 섹션으로 구성됩니다. 인수 기준 체크박스가 있는 사용자 스토리, 구체적인 경로를 담은 “Files to Modify” 목록, 제외 목록인 “Files NOT to Modify”, 구체적인 시나리오를 명시한 테스트 기대치, 그리고 제약 조건(새로운 의존성 추가 금지, 기존 패턴 사용)입니다. 그중에서도 제외 목록이 제 템플릿에 가장 큰 개선을 가져왔으며, 에이전트가 작업 범위 밖의 코드를 “친절하게” 수정하는 일을 막아 줍니다.

PRD 기반 개발이 사람의 코드 리뷰를 대체할 수 있습니까

아닙니다. PRD 기반 개발이 대체하는 것은 구현 단계이지 리뷰 단계가 아닙니다. 완료된 PRD는 병합 전에 반드시 인수 기준에 따라 사람이 검토해야 합니다. 제 워크플로우에서는 에이전트가 완료되면 알림이 도착하고, 각 기준에 대해 diff를 검토합니다. 품질 루프와 독립적인 테스트 검증은 보완 장치일 뿐이며, 아키텍처 적합성과 정확성에 대한 사람의 판단을 대체하지는 않습니다.

AI 에이전트가 PRD 제약 조건을 무시하는 이유는 무엇입니까

에이전트는 제약 조건이 학습 데이터의 패턴과 충돌할 때 그 제약을 무시합니다. PRD에 “새로운 의존성 추가 금지”라고 적혀 있어도, 모델의 학습 데이터가 해당 작업을 특정 라이브러리와 연결하고 있다면 모델은 그 라이브러리를 설치해 버릴 수 있습니다. 해결책은 명시적 제외입니다. “Files NOT to Modify”와 “설치 금지” 목록은 일반적인 지침이 아니라 구체적인 경계를 에이전트에게 제시하므로, 긍정형 제약보다 더 잘 작동합니다.

참고 자료