<div align="center">
<a href="https://nurettincoban.github.io/ai-prd-workflow/"><img src="https://raw.githubusercontent.com/nurettincoban/ai-prd-workflow/HEAD/.github/social-preview.png" width="820" alt="AI PRD Workflow: decide what to build before your agent builds it"></a>
📋 AI PRD 워크플로우
에이전트가 구축하기 전에 무엇을 만들지 결정합니다.
아이디어 또는 기존 코드 → 검증된 PRD(제품 요구사항 정의서) → 기능(features) → 규칙(rules) → 순차적인 RFCs(구현 사양서) → 검토 및 테스트된 코드
CI
License: MIT
GitHub stars
Claude Code
Agent Skills
🌐 웹사이트 · 실제 실행 사례 보기 · 빠른 시작 · 작동 방식 · 이유 · 증거 · 설치 옵션
English · 简体中文 · Türkçe · 日本語 · 한국어 · Español
<sub>RFC 기반으로 운영 시작: <a href="https://github.com/nurettincoban/ai-prd-workflow/commit/0993e28"><b style="font-weight: bold">2025년 3월</b></a> — Claude Code나 Cursor가 플랜 모드를 갖추기 전, 그리고 Kiro나 Spec Kit이 존재하기 전.</sub>
</div>
AI 코딩 에이전트는 코드를 잘 작성합니다. 하지만 무엇을 만들지 결정하고, 어제의 결정을 기억하며, 두 문서가 서로 모순되는지 알아차리는 능력은 떨어집니다. 이 워크플로우는 그 부분을 처리합니다. 아이디어 또는 이미 존재하는 코드베이스를 받아 검토된 제품 요구사항 정의서(PRD), 우선순위가 지정된 기능(features), 프로젝트 규칙(rules), 그리고 종속성 순서에 따른 작은 구현 사양서(RFCs)로 만듭니다. 그런 다음 이들을 하나씩 구현하고 검토합니다.
모든 단계는 다음 단계가 읽을 수 있는 마크다운 파일을 작성하므로, 결정 사항들이 채팅 세션을 넘어서 지속됩니다. 스크립트는 파일들이 서로 일치하는지 확인합니다. 학습할 CLI도, 채택할 프레임워크도, 종속성(lock-in)도 없습니다. 명령어는 단순한 프롬프트이며, Claude Code, Codex, Copilot, Cursor, Gemini CLI, OpenCode, Devin을 위한 스킬로 설치됩니다.
한 번의 실행 결과물
완성된 것처럼 보이는 작은 URL 단축기(URL shortener)의 사양을 제공하고 명령어를 실행했습니다. 코드가 존재하기 전에 세 가지 문제를 발견했습니다:
| 사양이 명시한 내용 | 워크플로우가 수행한 작업 |
|---|
| "HTTP 301을 통해 단축된 URL을 원본 URL로 리디렉션" | /verify-prd: 브라우저는 301을 캐시하므로, 반복적인 클릭은 카운트되지 않으며 삭제된 링크는 계속 리디렉션됩니다. 수정된 사양은 302로 리디렉션하며, RFC-003 테스트는 "절대 301 아님"을 검증합니다. |
| ... | |
수동으로 작성한 문제 중 10개 중 10개를 /verify-prd가 목록을 보지 않고 찾아냈습니다. 13개 중 12개의 문서 간 문제를 /workflow-status가 발견했습니다. 12개의 RFC와 203개의 계획된 테스트가 생성되었으며, 각 RFC는 먼저 두 번째 모델에 의해 검토되었습니다. 인간의 개입 없이 Claude Opus 5.5에서 약 한 시간 분량의 에이전트 시간이 소요되었습니다. 전체 실행 보기 → | |
빠른 시작
Claude Code에서 플러그인을 설치하고, Claude Code를 재시작한 다음 인터뷰를 시작하세요:
/plugin marketplace add nurettincoban/ai-prd-workflow
/plugin install prd-workflow@ai-prd-workflow
/prd-workflow:create-prd # 그 다음 /prd-workflow:verify-prd
<details>
<summary><b>Codex, GitHub Copilot, Cursor, Gemini CLI, OpenCode, Devin, 또는 모든 채팅 비서</b></summary>
프로젝트에 스킬을 설치하세요:
cd your-project
curl -fsSL https://raw.githubusercontent.com/nurettincoban/ai-prd-workflow/main/install.sh | bash -s -- .
Codex에서는 /create-prd 대신 $create-prd를 입력합니다. 채팅 비서(ChatGPT, Claude.ai 등)에서는 명령어 테이블에서 프롬프트를 복사하여 붙여넣으세요.
</details>
⚠️ [중요] 설치 후 AI 도구를 재시작하세요. 실행 중인 세션은 새로운 스킬을 인식하지 못하므로, 첫 번째 명령에서 'Unknown skill' 오류가 발생합니다. 이는 설치가 잘못된 것처럼 보이지만 실제로는 오래된(stale) 세션일 뿐입니다.
그런 다음 명령을 순서대로 실행합니다 (플러그인 사용 시, 각 명령어는 이름이 있습니다: /prd-workflow:verify-prd):
/create-prd # interview → PRD.md (기존 코드가 있나요? 이 경우 /document-existing를 사용하세요)
/verify-prd # gaps and contradictions → improved PRD.md + PRD-REVIEW.md
/extract-features # → FEATURES.md
...
다음에 무엇을 해야 할지 확신이 서지 않을 때는 언제든지 /workflow-status를 실행하고, 요구사항이 변경될 때는 /manage-changes를 사용합니다. 처음 두 단계부터 시작하세요: 인터뷰는 약 10분이 소요되며, /verify-prd를 통해 이 워크플로우가 자신에게 적합한지 몇 분 안에 알 수 있습니다.
또는 예제에서 시도해 보세요. before/ 폴더는 완전해 보이지만 그렇지 않습니다. 비교를 위해 원본을 유지하려면 복사하세요:
git clone https://github.com/nurettincoban/ai-prd-workflow.git
cp -r ai-prd-workflow/examples/url-shortener/before linksnip
ai-prd-workflow/install.sh linksnip
AI 도구에서 linksnip을 열고, /workflow-status나 /verify-prd를 실행한 다음, 그 결과를 수동으로 발견한 문제점 및 저희가 실행한 결과의 결과와 비교해 보세요.
작동 방식 (How it works)
flowchart TB
subgraph define [1 · 무엇을 구축할지 정의하기]
direction LR
...
| 명령어 | 기능 | 생성 파일 | 프롬프트 |
|---|
/create-prd | 아이디어에 대해 인터뷰를 진행하며, 한 번에 몇 가지 질문을 합니다 | PRD.md | view |
| ... | | | |
몇 가지 규칙이 전체 흐름을 유지하게 해줍니다:
- 계획하고, 승인한 후 코딩합니다.
/implement-rfc는 계획 단계에서 멈추고 사용자 입력을 기다립니다.
- 새로운 시각으로 검토합니다.
/review-rfc는 동일한 대화창에서 작성된 코드를 검토하지 않습니다. Claude Code에서는 자동으로 별도의 컨텍스트(context)에서 실행됩니다.
- ID는 절대 변경되지 않습니다. 요구사항(Requirements), 기능(features), 규칙(rules), 그리고 RFC들은 ID로 서로를 인용합니다.
scripts/trace-check.py는 인용이 깨지거나 필수 기능(Must-have feature)에 대한 RFC가 없을 경우 실패하며, 이 명령어가 이를 대신 실행해 줍니다.
- 파일 간 내용이 불일치할 때,
PRD.md가 FEATURES.md보다 우선하고, FEATURES.md가 RULES.md보다 우선하며, 그 다음으로 RFC들이 우선합니다. 해당 명령어들은 어떤 파일을 따랐는지 알려주고, 나머지 파일에 대한 수정을 요청합니다.
이 워크플로우를 사용하는 이유 (Why this workflow)
사용자의 코딩 에이전트(coding agent)는 아마도 계획 모드(plan mode)를 가지고 있을 것입니다. 계획 모드는 하나의 작업만 계획합니다. 반면, 이 워크플로우는 제품 자체를 계획합니다: 무엇을 만들지, 누구를 위해 만드는지, 그리고 범위 밖의 것은 무엇인지 정의합니다.
| 내장 계획 모드 (Built-in plan mode) | 이 워크플로우 (This workflow) |
|---|
| 하나의 작업만 계획합니다: "이걸 어떻게 만들까요?" | 제품을 계획합니다: 무엇을, 누구를 위해, 그리고 범위 밖의 것은 무엇인가요? |
| ... | |
두 가지는 함께 작동합니다. /generate-rfcs가 다음 작업을 결정하고, /implement-rfc는 에이전트 플래너에게 작고 잘 정의된 작업(small, well-defined task)을 전달합니다.
다음과 같은 경우에 사용하세요: 여러 주에 걸친 빌드나 AI를 이용해 실제로 무언가를 만들 때, 범위가 늘어나거나 결정 사항이 잊히는 것이 코드 품질보다 더 큰 문제가 될 수 있습니다. 한 줄 수정만 할 때는 건너뛰세요.
명세 주도 개발(spec-driven development) (GitHub Spec Kit, Amazon Kiro)을 알고 있다면, 이는 동일한 아이디어입니다. 다만 작업의 단위가 RFC이며, 채택해야 할 CLI나 프레임워크가 없고, 문서 간의 일치 여부를 확인하는 스크립트가 있다는 차이점이 있습니다.
근거 (Evidence)
이 섹션에서 확인할 수 있는 모든 것은 여기서 확인할 수 있습니다:
- URL 단축기 예시 — v2.0 사양, 수동으로 발견한 문제점들, 그리고 현재 명령어들을 해당 사양에 전체적으로 실행한 결과입니다. 저희 목록을 본 적 없는 신규 컨텍스트(Fresh-context) 실행만으로도 10개의 PRD 문제점 중 10개(
/verify-prd)와 13개의 문서 간 교차 문제점 중 12개(/workflow-status)를 발견했으며, 우리가 놓쳤던 여러 문제들도 찾아냈습니다. 두 번째 모델이 이 예시에서 수동으로 실행한 콜드 리드(Cold reads)는 생성된 RFC들이 구현자에게 추측을 요구했을 만한 장소를 150곳 이상 발견했습니다. 해당 보고서는 보고서에서도 확인할 수 있습니다. 이들은 단일 모델의 단일 실행 결과입니다.
- todo-cli 예시 — 터미널 할 일 목록을 위한 10줄짜리 아이디어를 검토된 코드 386줄과 통과 테스트 66개까지 발전시킨 사례이며, 이 모든 과정은 질문에 답하는 사람이 아무도 없는 상태에서 Claude Sonnet 5.5를 통해 진행되었습니다. 이는 기능이 손상되었을 때도 통과했을 테스트들을 포함하여 각 명령어가 무엇을 포착했는지 보여주며, 실행 결과가 여러분에게 열어둔 하나의 결정 사항도 제시합니다.
- 평가 스위트 — 사용자의 계정에서 워크플로우 유무에 따라 동일한 검사를 실행하여 스스로 차이를 측정할 수 있게 합니다. 이 도구는 10개의 PRD 문제점과, 정규 표현식(regular expression)이 안정적으로 인식할 수 있는 13개의 문서 간 교차 문제점 중 7개를 채점합니다.
<p align="center">
<img src="https://raw.githubusercontent.com/nurettincoban/ai-prd-workflow/HEAD/.github/demo-workflow-status.svg" width="860" alt="/workflow-status가 v2.0 예시를 감사하는 과정: F7에 RFC가 없고 RFCS.md 파일이 누락되어 추적성 검사(traceability check)가 실패하며, 문서를 서로 읽어보면 UI를 구축한 RFC 부재나 HTTP 301 캐싱으로 인해 클릭 카운트가 깨지는 등 20개의 불일치함이 발견됨">
</p>
<p align="center"><sub style="font-size: smaller;">v2.0 예시에 대한 실제 <code style="font-family: monospace;">/workflow-status</code> 실행 결과 요약본. <a href="examples/url-shortener/workflow-status-on-before.md">전체 보고서</a></sub></p>
각 단계는 프로젝트를 다른 각도에서 살펴보고, 각각은 다른 단계가 포착할 수 없는 문제를 잡아냅니다. 저희는 이 워크플로우를 사용하여 TypeScript 라이브러리를 처음부터 끝까지 구축하는 과정에서 이를 확인했습니다. 해당 라이브러리는 공개된 것이 아니므로, 이 표는 증거라기보다는 현장 보고서로 간주해 주십시오:
| 단계 | 포착한 문제점 | 오직 이 단계만이 포착할 수 있었던 이유 |
|---|
/verify-prd | PRD 자체의 컨벤션에 모순되는 함수; 명시되지 않은 색상 공간; 숨겨진 렌더링 의존성 | 사양을 참조 구현과 비교했기 때문 |
| ... | | |
| 가장 인상적인 결과는 다음과 같습니다. 코드가 존재하기 전에도, RFC의 예외 케이스 섹션은 빌드 플러그인이 아직 TypeScript 7을 지원하지 않을 것이라고 예측했고, 폴백(fallback) 버전을 명시했습니다. 실제로 정확히 그렇게 되었습니다. 타입 검사(Type-checking)는 전체적으로 통과했지만, 빌드를 실행했을 때만 그 사실이 드러났습니다. | | |
ID도 마찬가지였습니다. PRD가 프로젝트 중간에 변경되었을 때, 새로운 에이전트가 /extract-features를 다시 실행하여 번호를 재지정하는 대신 새 기능을 끝 부분에 추가했습니다. 이는 RFC에서 기능을 번호로 인용하기 때문에 지시받지 않았음에도 불구하고 이루어졌습니다.
설치 옵션 (Install options)
install.sh는 각 도구가 스킬을 찾는 위치에 해당 스킬들을 배치합니다:
| 도구 | 폴더 | 실행할 명령어 |
|---|
| Claude Code | .claude/skills/, 또는 플러그인 | /create-prd |
| ... | | |
| 이 저장소(repository)를 클론한 상태에서: | | |
./install.sh /path/to/your/project
./install.sh /path/to/your/project --claude
./install.sh /path/to/your/project --agents
install.sh는 사용자가 편집한 스킬을 절대 덮어쓰지 않습니다. --force를 사용하면 백업본 저장 후 덮어씁니다.
--ref v3.0.0은 특정 버전을 설치합니다. curl URL에 동일한 태그를 사용하십시오.
- v2에서 업그레이드하나요?
--remove-legacy를 추가하여 이전 명령어 파일들을 백업 폴더로 이동시키세요.
- 복사/붙여넣기를 선호하시나요?
./copy-prompt.sh --list는 프롬프트를 보여주며, ./copy-prompt.sh <파일>은 하나를 클립보드에 복사합니다.
팁 (Tips)
- 질문에 답하세요. 인터뷰 명령어는 에이전트의 추측보다는 실제 결정과 함께 작동할 때 가장 효과적입니다.
- 다음으로 넘어가기 전에 각 파일을 읽으세요. PRD를 수정하는 것은 몇 분밖에 걸리지 않지만, 잘못된 PRD를 기반으로 구축된 코드를 수정하는 것은 며칠이 걸립니다.
- 규칙을 컨텍스트에 유지하세요. 에이전트 설정(
CLAUDE.md, AGENTS.md, 또는 .cursor/rules/)에서 RULES.md를 참조하세요. /generate-rules가 방법을 제안합니다.
- 가능하다면 병렬화하세요. RFC는 선언된 전임 작업(predecessors)이 완료되는 즉시 시작할 수 있습니다. 단독으로 작업하는 경우, 단순히 번호를 따르세요.
기여하기 (Contributing)
CONTRIBUTING.md를 참조하세요. 루트에 있는 프롬프트 파일들이 원본이며, 다른 모든 것은 여기서 생성되거나 확인됩니다.
감사의 글 (Acknowledgments)
이 프로젝트를 지원하고 오픈 소스 프로그램에 초대해 준 Anthropic에 감사드립니다.
라이선스 (License)
MIT — LICENSE를 참조하세요.
<p align="center">이 워크플로우가 잘못된 것을 구축하는 것에서 당신을 구했다면, 별 하나(⭐)는 다른 사람들이 이것을 찾도록 돕습니다.</p>