Claude Code나 Cursor가 바로 구현할 수 있는 PRD 작성법

2026년에 PRD가 달라진 이유

20년 동안 PRD는 합의를 위한 문서였습니다. 읽는 사람은 회의에서 질문하고, 잘못된 요구사항에 반론하고, 작은 빈칸은 판단으로 채우는 엔지니어였습니다. 사람이 모호함을 해결해 주었기 때문에 PRD는 모호해도 괜찮았습니다.

코딩 에이전트는 통계적으로 가장 그럴듯한 해석을 골라, 묻지 않고 빠르게 구현하는 방식으로 모호함을 해결합니다. 그것이 문제의 전부입니다. 예전에는 10분짜리 대화면 끝나던 모호함이 이제는 잘못된 구현, 리뷰, 되돌리기, 두 번째 실행이라는 비용이 됩니다. 에이전트로 매일 배포하는 팀들은 2025년에 같은 사실을 발견했습니다. 결과물의 품질은 모델 선택보다 작성된 명세의 품질을 더 가깝게 따라갑니다.

두 오픈소스 프로젝트가 이 전환을 눈에 보이게 만들었습니다. 2025년 9월에 공개된 GitHub의 Spec Kit은 에이전트 작업을 단계별 게이트가 있는 순서로 구조화합니다. 프로젝트 원칙의 헌장, 명세, 기술 계획, 작업 목록, 그리고 그 뒤에야 구현입니다. 2026년 10월 기준 저장소에는 약 143,000개의 스타가 표시됩니다. Eyal Toledano의 Task Master는 더 좁은 일을 합니다. task-master parse-prd your-prd.txt가 PRD를 의존성 순서의 작업 목록으로 바꾸고, Cursor, Windsurf, Claude Code가 이를 차례로 처리합니다. 저장소에는 2026년 10월 기준 약 28,000개의 스타가 표시됩니다. 두 도구 모두 PRD가 팀을 위한 메모가 아니라 에이전트에 대한 인터페이스라고 가정합니다.

전환을 한 문장으로 말하면, PRD는 사람들이 합의하는 문서이기를 멈추고 에이전트가 실행하는 입력이 되었습니다.

에이전트가 PRD에서 필요로 하는 것

에이전트에게 필요한 것은 네 가지이며, 대부분의 PRD는 그중 어느 것도 깔끔하게 제공하지 않습니다.

번호가 붙은 원자적 요구사항. 요구사항당 한 문장, 안정적인 ID(R1, R2, R3)를 붙입니다. "사용자는 이메일로 비밀번호를 재설정할 수 있다"는 요구사항입니다. "사용자는 매끄러운 계정 복구 경험을 갖는다"는 요구사항이 아닙니다. 에이전트, 계획, 작업, 테스트가 모두 ID를 참조하기 때문에 ID가 중요합니다.

에이전트가 테스트할 수 있는 인수 기준. 요구사항마다 통과한 확인이 어떤 모습인지, 에이전트가 실행할 수 있는 용어로 적습니다. HTTP 응답, 데이터베이스 상태, 렌더링된 요소, CLI 종료 코드 같은 것입니다. 확인 방법을 문장으로 쓸 수 없다면 요구사항이 아직 완성되지 않은 것입니다.

명시적인 비목표. 에이전트는 과하게 만듭니다. 내버려 두면 "비밀번호 재설정 추가"는 재설정 흐름에 속도 제한, 감사 로그, 그것들을 설정하는 설정 페이지까지 더해집니다. 비목표 섹션("이번 반복에서는 속도 제한 없음. 관리자 UI 없음. SMS 없음.")은 PRD에 추가할 수 있는 가장 값싼 한 줄이며, 다른 어떤 줄보다 낭비되는 작업을 많이 줄입니다.

제약과 기존 시스템의 형태. 어떤 프레임워크, 어떤 데이터베이스, 인증은 어디에 있는지, 건드리지 말아야 할 파일, 따라야 할 관례. Spec Kit은 이를 헌장이라 부릅니다. Cursor에서는 규칙 파일에, Claude Code에서는 CLAUDE.md에, Codex에서는 AGENTS.md에 있습니다. PRD는 이를 반복하지 말고 참조해야 합니다.

전과 후: 같은 요구사항을 다시 쓰면

아래 표는 우리 PRD에서 가져온 것입니다. 왼쪽은 예전 방식이고, 오른쪽은 에이전트가 행동할 수 있는 방식입니다.

오른쪽 열은 요구사항 하나당은 길지만 전체적으로는 짧습니다. 각 줄을 둘러싸던 모호한 문단이 사라졌기 때문입니다.

템플릿, 섹션별로

우리가 쓰는 뼈대입니다. 모든 에이전트가 Markdown을 읽고 Git에서 diff가 깔끔하게 나오기 때문에 Markdown으로 씁니다. 코드 블록 안에서는 구조가 보이도록 섹션 이름을 제목 대신 굵게 표시했습니다.

**기능:** 이메일을 통한 비밀번호 재설정
**담당자:** (이름)   **상태:** 초안 | 동결   **기준선:** v1 (2026-10-28)

**문제**
비밀번호를 잊은 사용자가 지원팀에 이메일을 보낸다. 지원팀은 2026년 9월에
그런 이메일을 41건 처리했다. 셀프서비스 경로가 없다.

**목표**
로그아웃 상태의 사용자가 누구에게도 연락하지 않고 2분 안에 직접
비밀번호를 재설정할 수 있다.

**요구사항**
R1. 로그아웃 상태의 사용자는 이메일을 입력해 재설정을 요청할 수 있다.
    통과: 알려진 이메일로 POST /auth/reset이 200을 반환하고 30분 뒤
    만료되는 password_reset 행을 하나 만든다.
R2. 알 수 없는 이메일도 같은 200 응답을 반환하고 아무것도 만들지 않는다.
    통과: 알 수 없는 이메일로 POST /auth/reset이 200을 반환하고 행 수는
    변하지 않는다.
R3. 재설정 이메일에는 새 비밀번호와 확인 필드가 있는 폼을 여는 링크가
    하나 들어 있다.
    통과: 캡처한 테스트 이메일의 링크가 /auth/reset/:token으로 연결되고
    두 필드를 렌더링한다.
R4. 유효한 토큰과 일치하는 비밀번호를 제출하면 해시를 갱신하고 토큰을
    삭제하며 사용자를 로그인시킨다.
    통과: 통합 테스트 reset_happy_path가 완료되고 사용자가 /home에 도달한다.
R5. 만료되었거나 사용된 토큰은 "이 링크는 만료되었습니다"와 새 링크를
    요청하는 버튼을 보여준다.

**비목표**
이번 반복에서는 속도 제한 없음. SMS 없음. 관리자 UI 없음. 로그인 폼
변경 없음.

**제약**
CLAUDE.md를 따른다. 기존 메일러(lib/mail)를 사용한다. 의존성을 추가하지
않는다. 토큰은 무작위 32바이트를 16진수로 인코딩한다.

**미결 질문**
Q1. 재설정 시 다른 세션도 로그아웃시켜야 하는가? 결정 담당: (이름),
    기한 2026-10-30. 결정 전까지 구현하지 않는다.

**에이전트 범위 밖**
이메일 본문 문구: 자리 표시자면 충분하다.

선택에 대한 몇 가지 메모입니다.

• 상태와 기준선. 버전과 날짜가 붙은 "동결"은 에이전트가 이 텍스트만을 기준으로 구현하고 더 새로운 것은 보지 않는다는 뜻입니다. 첫 실행 전에 동결하고 요구사항이 바뀌면 버전을 올리므로, 나중의 감사에서 배포된 것과 합의된 것을 비교할 수 있습니다.
• 통과 줄. 별도의 테스트 계획이 아니라 요구사항 옆에 적습니다. 에이전트는 이를 테스트 명세로 읽고, 대부분 테스트를 먼저 작성합니다.
• 결정 담당자가 있는 미결 질문. 담당자 없는 미결 질문은 에이전트가 채워 넣을 빈칸입니다. "결정 전까지 구현하지 않는다"가 그것을 막는 지시입니다.

오후 한나절에 작성하는 방법

1. 실제 숫자 하나를 넣어 문제를 세 문장으로 쓴다. 숫자가 없으면 가서 구합니다. "지원팀이 9월에 재설정 이메일 41건을 처리했다"가 "사용자가 복구에 어려움을 겪는다"보다 낫습니다.
2. 요구사항을 한 문장씩 나열하고 번호를 붙인다. 5~15개를 목표로 합니다. 20개를 넘으면 기능이 둘인 것이니 PRD를 나눕니다.
3. 모든 요구사항 아래에 통과 줄을 쓴다. 쓸 수 없다면 요구사항이 원자적이지 않거나 완료가 어떤 모습인지 아직 모르는 것입니다. 둘 다 에이전트보다 먼저 발견할 가치가 있습니다.
4. 누군가 요구사항을 읽기 전에 비목표를 쓴다. 열의 넘치는 엔지니어가 여기에 무엇을 덧붙일지, 우리가 원하지 않는 것은 무엇인지 묻고 적어 둡니다.
5. 제약 파일을 가리킨다. 다시 쓰지 않습니다. CLAUDE.md, AGENTS.md, Cursor 규칙을 관례의 단일 출처로 유지합니다.
6. 동결한다. 상태를 표시하고 버전을 정하고, 에이전트가 읽을 수 있는 곳에 둡니다. 저장소 안의 파일이거나 MCP 서버를 통해 에이전트가 가져올 수 있는 페이지입니다.
7. 에이전트를 R1에만 실행한다. 나머지를 실행하게 하기 전에 그 결과를 검토합니다. 첫 요구사항에서 에이전트가 PRD를 읽을 수 있는지 자체를 알 수 있습니다.

PRD가 있는 곳과 에이전트가 읽는 방법

Google Doc에 있는 PRD는 Claude Code에게 보이지 않습니다. 작동하는 선택지는 다음과 같습니다.

• 저장소 안의 파일. docs/prd/password-reset.md를 CLAUDE.md나 AGENTS.md에서 참조합니다. 가장 단순하고 버전 관리가 되며 모든 에이전트가 읽을 수 있습니다. Spec Kit과 Task Master 모두 이를 전제로 합니다.
• MCP로 에이전트가 가져오는 페이지. 팀이 저장소가 아니라 워크스페이스 도구에서 PRD를 쓴다면, MCP 서버를 통해 에이전트가 페이지를 직접 읽을 수 있습니다. Atrix는 페이지, 이슈, 사이클을 85개 도구와 OAuth 2.1을 갖춘 MCP 서버로 노출하며, Official MCP Registry와 Glama에 등록되어 있습니다. 실질적인 효과는 코딩 에이전트가 동결된 PRD 페이지를 읽고, 계획된 이슈를 만들고, 끝나면 갱신할 수 있어 도구 사이에서 텍스트를 복사할 필요가 없다는 것입니다. 분명히 말해 둘 한계는, 에이전트는 워크스페이스 객체를 읽고 쓸 뿐 여러분의 코드나 테스트를 실행하지는 않는다는 점입니다.
• 둘 다. 우리는 정본 PRD를 페이지로 두고, 실행 시작 시 에이전트가 동결 버전을 저장소로 복사하므로 커밋에 무엇을 기준으로 구현했는지 정확히 기록됩니다.

Cursor와 Codex에 대해서는 Cursor 연동과 Codex 연동에 설정이 설명되어 있습니다. OAuth 연결 한 번이면 에이전트는 PRD, 백로그, 현재 사이클을 도구로 보게 됩니다.

빼야 할 것

사람에게는 필요하지만 에이전트에게는 필요 없는 모든 것입니다.

• 페르소나와 사용자 리서치. 연결된 페이지에 둡니다. 에이전트에게 필요한 것은 요구사항이지 페르소나가 아닙니다.
• 경쟁사 분석. 마찬가지입니다.
• 목업. 요구사항이 시각적인 경우가 아니면 뺍니다. 시각적이라면 에이전트가 볼 수 있는 스크린샷 한 장이 이를 설명하는 세 문단보다 낫습니다.
• 일정. 에이전트는 스프린트를 계획하지 않습니다. 그것은 사이클의 몫입니다.

기존 PRD는 여전히 존재합니다. 다만 에이전트가 읽는 문서가 아닐 뿐입니다. 이해관계자를 위한 긴 형식이 필요하다면 AI PRD 템플릿 글이 그 버전을 다루고, 사이트의 PRD 템플릿은 복제할 수 있는 호스팅 버전입니다.

자주 묻는 질문

AI 코딩 에이전트용 PRD는 명세 기반 개발의 명세와 같은 것인가요?

거의 같습니다. Spec Kit이 말하는 명세 기반 개발은 명세(무엇을, 왜)와 계획(어떻게, 어떤 스택으로)과 작업(순서가 정해진 일)을 분리합니다. 여기서 설명한 PRD는 명세 계층입니다. 계획과 작업은 에이전트나 Task Master 같은 도구가 그로부터 생성합니다.

Claude Code나 Cursor용 PRD는 얼마나 길어야 하나요?

건드리는 코드와 함께 에이전트의 컨텍스트에 들어갈 만큼 짧아야 합니다. 실제로는 4001,200단어, 번호 붙은 요구사항 515개입니다. 더 길면 기능을 나눕니다.

사용자 스토리는 여전히 필요한가요?

"사용자로서 나는 ~하고 싶다" 형식으로는 필요 없습니다. 에이전트에게 필요한 것은 요구사항과 인수 기준이며, 스토리 포장은 검증 가능한 내용 없이 단어만 늘립니다. 팀이 계획에 스토리를 쓴다면 유지하되, 번호 붙은 요구사항을 먼저 둡니다.

CLAUDE.md나 AGENTS.md에 들어갈 것과 PRD에 들어갈 것은 무엇인가요?

관례는 규칙 파일에 들어갑니다. 스택, 폴더 구조, 테스트 명령, 스타일, 건드리지 말 파일입니다. PRD는 기능별이며 규칙 파일을 참조합니다. 관례를 PRD마다 반복하면 서로 어긋나게 됩니다.

에이전트가 PRD를 써야 하나요?

브리프에서 초안을 만들 수 있고, 그 초안은 아직 결정하지 않은 것들의 체크리스트로 쓸모가 있을 때가 많습니다. Atrix의 에이전트는 Develop 실행에서 이를 수행합니다. 브리프를 넣으면 요구사항, 아키텍처, 계획된 이슈가 나오고, Builder에서는 월 100회 실행할 수 있습니다. 하지만 동결, 비목표, 미결 질문에 대한 결정은 여러분의 몫입니다. 에이전트는 여러분이 무엇을 만들고 싶지 않은지 알지 못합니다.

에이전트가 PRD대로 구현했는지 어떻게 알 수 있나요?

통과 줄을 이용해 결과를 동결된 기준선과 요구사항별로 비교합니다. Atrix의 요구사항 감사는 동결된 페이지를 기준으로 이 비교를 수행하며, 요구사항의 커버리지와 드리프트를 확인하지 코드 자체를 확인하지는 않습니다. 코드는 통과 줄이 함의하는 테스트를 실행하고, 인증과 결제 경로는 직접 검토하세요.

다음 단계

PRD 템플릿을 복사해 R1을 통과 줄과 함께 쓰고, R2를 쓰기 전에 그 한 요구사항만으로 에이전트를 실행해 보세요. PRD가 저장소 밖에 있다면 MCP 서버가 Claude Code, Cursor, Codex가 그것을 읽는 방법입니다.

출처

GitHub Spec Kit 저장소, 스타 수는 2026년 10월 27일 기준; Spec-driven development with AI: get started with a new open source toolkit, GitHub Blog, 2025년 9월; Task Master 저장소, 스타 수는 2026년 10월 27일 기준.