n개월 동안 견적서 발행 웹을 만들었다. 이메일 자동 발송, 다양한 템플릿, 클라이언트 댓글, 승인·거절, 결제 연동까지 모두 넣었다. 클라이언트에게 보여주자 한 마디가 돌아온다. “그냥 카카오톡으로 보내는 게 편한데요.” 스타트업이 실패하는 가장 큰 이유는 시장이 원하지 않는 제품을 만들었기 때문이다. Claude Code로 코드를 빠르게 짤 수 있어도 첫 단추를 잘못 끼우면 결과는 같다. PRD(Product Requirements Document)를 어떻게 작성하느냐가 프로젝트의 성패를 결정한다. 이 글에서는 MVP 관점의 PRD를 Claude Code로 만드는 가장 실용적인 흐름을 정리한다
왜 MVP PRD인가
MVP는 Minimum Viable Product의 약어로, 제품의 핵심 가치를 검증하기 위해 최소한의 기능만 구현한 시제품을 뜻한다. 모든 기능을 다 넣고 출시하는 대신 핵심 가설을 검증할 만큼만 만든다. 시장에서 검증한 뒤 다음 핵심 기능을 추가하는 짧은 주기의 반복 개발, 즉 애자일 방법론과 짝을 이룬다
PRD를 작성할 때도 같은 원칙을 따른다. 처음부터 모든 요구사항을 담은 두툼한 문서를 만들면 Claude Code가 컨텍스트 토큰을 비효율적으로 쓴다. MVP PRD는 핵심 가치 검증에 필요한 명세만 담는다
bypass permissions 모드는 1인 개발에서만 쓴다
claude --dangerously-skip-permissions
이 모드는 모든 도구 호출을 자동 승인한다. 혼자 개발할 때는 빠르게 진행할 수 있지만 회사 프로젝트나 공동 작업에서는 위험하다. 별도의 승인 없이 코드가 수정되기 때문이다. 1인 개발 한정으로 사용한다
bypass 모드에서는 Claude Code가 몇 분씩 혼자 작업하는 시간이 길어지므로, Stop 훅에서 Slack Webhook으로 작업 완료 알림을 보내도록 설정해 두면 다른 일을 하다가도 끝난 시점을 놓치지 않는다
# 프로젝트 루트 .env SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
알림이 필요 없다면 .claude/settings.json의 Stop 훅 정의만 제거하면 된다
일반 PRD 프롬프트는 추상 명세를 양산한다
Claude Code에 단순히 “PRD를 작성해줘”라고 요청하면 페르소나, 비즈니스 목표, 기술적 목표, Lighthouse 점수, 페이지 로딩 시간 같은 성공 지표까지 빠짐없이 담은 문서가 나온다. 좋아 보이지만 1인 개발자가 Claude Code로 빠르게 만드는 상황에서는 대부분 잉여 정보다
성능 지표는 개발이 끝난 뒤 측정해도 늦지 않는다. PRD에 모든 항목을 두면 모든 항목이 컨텍스트로 잡혀 토큰을 갉아먹는다. PRD를 만들 때는 “취할 것은 취하고 놓을 것은 놓는” 전략이 필요하다
메타 프롬프트로 PRD 작성 프롬프트부터 만든다
PRD를 직접 요청하기 전에, PRD 작성 프롬프트를 먼저 만들어 두는 두 단계 접근을 권장한다. 같은 아이디어가 Anthropic 콘솔의 prompt generator에도 구현되어 있다. 짧은 설명만 입력하면 구조가 잡힌 프롬프트 초안을 자동으로 생성해 주는 도구로, Claude Code 안에서도 비슷한 흐름을 그대로 적용할 수 있다
당신은 Claude Code 프롬프트 엔지니어입니다. 노션을 사용해서 입력한 견적서 내용을 클라이언트가 웹으로 확인하고 PDF로 다운받을 수 있는 MVP PRD 문서를 작성하는 메타 프롬프트를 생성해주세요. 참고사항: @CLAUDE.md 파일위치: docs/PRD_PROMPT.md
@CLAUDE.md로 기술 스택을 첨부하고 결과 저장 경로를 지정한다. docs/PRD_PROMPT.md가 만들어지면 그 내용을 그대로 다시 Claude Code에 붙여 PRD를 생성하게 한다. 두 단계로 나누면 메타 프롬프트와 결과 PRD 모두 파일로 남아 재사용·개선이 쉬워진다
일반 PRD에서 잘라낼 영역
생성된 PRD를 위에서 아래로 훑으면서 다음 영역은 우선 제거 대상으로 본다
| 영역 | 제거 이유 |
|---|---|
| Lighthouse 점수, 로딩 시간 같은 성능 지표 | 개발 완료 후 측정해도 늦지 않다 |
| 일반 페르소나, 시장 분석 | 1인 MVP에는 과도한 추상이다 |
| 거시적 비즈니스 목표 | 코드 생성에 직접 영향을 주지 않는다 |
| 장기 개발 로드맵 | ROADMAP 문서로 분리하는 편이 깔끔하다 |
남길 영역은 사용자 여정, 핵심 기능 명세, 데이터 모델, 외부 API 연동 정보처럼 곧바로 코드로 옮길 수 있는 정보다
prd-generator 서브에이전트로 실용 PRD를 표준화한다
매번 사람이 잉여 정보를 잘라내는 것보다, 처음부터 실용 명세만 뽑는 서브에이전트를 두는 편이 빠르다. 서브에이전트의 시스템 프롬프트에 다음 두 가지를 명시한다
- 절대 생성하지 말아야 할 것 (성능 지표, 페르소나, 거시 목표 등)
- 출력 템플릿(output template) — 결과 문서의 정확한 구조
출력 템플릿은 결과물을 일관되게 만드는 가장 강력한 장치다. Claude 공식 문서도 더 나은 결과를 얻기 위한 방법으로 출력 형식 명시를 권장한다
서브에이전트 파일은 .claude/agents/prd-generator.md에 둔다. 현재 Claude Code는 .claude/agents/ 직하위의 마크다운 파일만 인식하므로 하위 디렉터리에 두지 않는다. 사용할 때는 새 세션을 띄운 뒤 다음과 같이 호출한다
@.claude/agents/docs/prd-generator.md 노션을 사용해서 입력한 견적서 내용을 클라이언트가 웹으로 확인하고 PDF로 다운받을 수 있는 MVP PRD 문서를 생성해주세요.
결과 PRD에는 핵심 정보 두 줄, 사용자 여정, 핵심 명세 표(ID 열 포함), 데이터 모델, 외부 API 연동 명세 정도만 남는다. 누락 가능성을 줄이기 위해 명세에는 항상 ID를 부여한다
도메인 분석은 별도 서브에이전트로 분리한다
PRD를 잘 쓰려면 해당 도메인 지식이 필요하다. 견적서 웹은 Notion API에 의존하므로 Notion 데이터베이스 조회·매핑 방식을 먼저 분석해야 한다. 이때도 메인 컨텍스트에서 처리하는 대신 도메인 전문 서브에이전트를 만든다
--- name: notion-api-database-expert description: 웹에서 Notion API 데이터베이스를 다루는 전문가. 적극 활용할 것. model: opus --- 당신은 웹에서 Notion API 데이터베이스를 다루는 전문가입니다.
분석·계획·복잡한 로직에는 Opus, 일반 구현에는 Sonnet을 쓰는 것이 합리적이다. 분석은 plan mode로 호출해 코드 수정을 막는다
@agent-notion-api-database-expert 에이전트를 사용해서 Notion API로 데이터베이스를 조회하는 방법을 분석해주세요. (plan mode)
서브에이전트는 별도 컨텍스트에서 작업한 뒤 요약만 메인 대화에 돌려준다. 메인 대화는 PRD 설계라는 본래 목표에서 벗어나지 않는다
prd-validator로 환각 명세를 차단한다
PRD가 그럴듯하게 보여도 실제로는 구현이 불가능한 경우가 있다. 예를 들어 “Instagram API로 Reels를 자동 업로드한다”라는 명세는 해당 API가 자동 업로드를 실제로 지원하는지 공식 문서에서 검증해야 한다. AI는 이런 부분에서 환각(hallucination)을 일으키기 쉽다
prd-validator 서브에이전트는 PRD를 기술적으로 검증하는 역할을 맡는다. 시스템 프롬프트의 환각 방지 원칙은 다음과 같이 명시한다
- API 기능을 추측하지 않는다
- 모든 외부 API 호출은 공식 문서에서 지원 여부를 확인한 뒤 OK 표시를 한다
- 지원 여부를 확신할 수 없으면 “확인 필요”로 표시한다
검증은 사람이 한 번, 서브에이전트가 한 번 — 두 차례 크로스체크하는 것이 안정적이다. 첫 단추는 한 번 잘못 끼우면 뒤에서 풀기 어렵다
전체 흐름 한 장 요약
위 단계를 하나로 묶으면 다음과 같다
[프로젝트 시작]
│
├─ 스타터킷 clone → invoice-web
│
├─ npm install (의존성 설치)
│
├─ 메타 프롬프트 생성 ──▶ docs/PRD_PROMPT.md
│
├─ @agent-prd-generator ──▶ docs/PRD.md (실용 명세)
│ │
│ └─ 도메인 분석 필요 시
│ └─ @agent-notion-api-database-expert (plan mode)
│
└─ @agent-prd-validator ──▶ 환각·누락 검증
↑
사람 검토 (크로스체크)
코드를 짜기 전에 이 단계를 한 번만 잘 거치면 이후 구현 단계에서 Claude Code가 흔들리지 않는다
정리
정리하면 Claude Code의 첫 산출물은 코드가 아니라 PRD다. 일반 프롬프트는 추상 명세를 양산하므로, MVP에 맞춘 prd-generator 서브에이전트와 도메인 분석·검증 전문 서브에이전트를 미리 두고 메인 컨텍스트는 비워둔다. 첫 단추가 정확해야 마지막 단추까지 깔끔하게 채워진다