PDD
PDD란 무엇인가
PDD에서는 프롬프트(Prompts)와 스토리(Stories)를 작성합니다. 이 프롬프트가 프로그램의 근원입니다. PDD 인터프리터는 코드로 작용하는 AI를 사용하여 프롬프트를 실행하므로, 실제 코드가 존재하기 전에 프로그램을 확인하고 테스트할 수 있습니다. 그런 다음 에이전트가 승인된 프롬프트를 기반으로 코드를 작성합니다.
flowchart LR
P["Prompt<br/>the source"] --> S["Story<br/>what a user can do"]
S --> C["Test<br/>pdd test"]
...
PDD는 pdd 명령어와 에이전트를 위한 일련의 스킬 세트입니다. 사용자의 에이전트는 프롬프트, 스토리, 테스트 그리고 코드를 작성합니다. PDD 인터프리터가 검사 및 시뮬레이션을 실행합니다. 최종 승인은 사용자만 합니다.
설치
Node.js 22.20 이상, Git, 그리고 gh auth login으로 로그인된 GitHub CLI가 필요합니다. 또한 스킬을 사용할 수 있는 에이전트와 PDD 인터프리터 접근 권한(아래 Access 참조)이 필요합니다. PDD는 macOS 및 Linux에서 테스트되었습니다.
npm install -g github:promptdriven/pdd
npx skills add promptdriven/pdd -g
pdd --version
...
npm install -g github:promptdriven/pdd는 pdd 명령어를 설치합니다.npx skills add promptdriven/pdd -g는 에이전트를 위한 PDD 스킬을 추가합니다. 이 설치 프로그램은 컴퓨터에 있는 에이전트를 찾거나, 어떤 에이전트에 스킬을 부여할지 사용자에게 요청합니다. 전역 스킬을 가질 수 없는 에이전트의 경우 'Failed to install' 메시지가 표시될 수 있지만, 해당 에이전트는 여전히 스킬을 받습니다.pdd --version은 반드시 0.1.18을 출력해야 합니다. 사용자의 스킬 버전이 pdd보다 오래된 경우, 업데이트하는 명령어 또한 함께 출력합니다.pdd setup은 AGENTS.md에 짧은 PDD 블록을 추가하거나, 리포지토리에 해당 파일이 있는 경우 CLAUDE.md에 추가합니다. 이렇게 하면 리포지토리 내의 모든 에이전트 채팅에서 프로젝트가 PDD를 사용한다는 것을 알게 됩니다. 두 번째 실행에서는 아무것도 변경되지 않습니다.
업데이트하려면, 2개의 설치 명령어를 다시 실행하고 pdd setup을 다시 실행한 다음 새 에이전트 채팅을 시작하십시오. npx skills add 이후에는 npx skills update -g도 스킬을 업데이트합니다.
[!IMPORTANT]
npm install -g pdd 또는 npm update -g를 실행하지 마십시오. npm 레지스트리에는 'pdd'라는 이름의 다른 패키지가 있습니다.
PDD 루프
my-story, tests/my-story.json, 그리고 NAME과 같은 이름은 플레이스홀더입니다. 실제 이름은 프로젝트에서 가져옵니다.
1. 에이전트에게 요청하기
저장소(repo)에서 에이전트를 열고, pdd-feature 스킬을 사용하여 기능을 요청합니다:
/pdd-feature <the feature, in one or two sentences>
스킬을 호출하는 방법은 에이전트에 따라 다릅니다. 또한 "pdd-feature 스킬을 사용하여 ...를 추가하세요"와 같이 작성할 수도 있습니다.
| 스킬 | 사용 용도 |
|---|
pdd-feature | 새로운 동작(behavior) 추가 |
| ... | |
에이전트는 다음 파일들을 프롬프트 공간(prompt space)에 작성합니다:
| 파일 | 설명 |
|---|
prompts/NAME.prompt.md | 프롬프트: 프로그램의 한 부분을 구성하는 원본 자료입니다. |
| ... | |
사용자는 채팅에서 스토리(Stories)를 읽고 승인합니다. 예상 값은 실행(run)이 아닌 사용자 자신과 스토리로부터 나옵니다.
채팅 환경에서는 사용자가 '예'라고 말할 때만 에이전트가 풀 리퀘스트(pull request)를 엽니다. 풀 리퀘스트가 포함된 전체 실행을 위해서는 GitHub 이슈에서 시작합니다: pdd workflow run feature 42 (여기서 42는 이슈 번호입니다). 실행에는 Herdr가 필요합니다. pdd는 Herdr에서 에이전트 채팅을 열어주며, 사용자는 동일한 단계를 따릅니다.
[!WARNING]
워크플로우 실행(workflow run) 중에는 에이전트가 전체 접근 권한으로 실행됩니다. 승인을 요청하기 위해 멈추지 않습니다. 사용자 계정으로 파일을 변경하고 명령을 실행할 수 있습니다.
2. 테스트
pdd lint은 AI 호출 없이 파일 형식을 확인합니다. pdd test는 PDD 인터프리터에서 모든 스토리(Story)의 테스트를 실행합니다. 특정 스토리만 확인하려면, 예를 들어 pdd test my-story other-story와 같이 이름을 지정할 수 있습니다. 출력 형태는 다음과 같습니다:
Story Test Result Checks Time
My story tests/my-story.json passed 20/20 41.4 s
Other story tests/other-story.json passed 34/34 89.1 s
...
| 표시되는 내용 | 의미 |
|---|
✓ | 모든 검사를 통과했음. |
| ... | |
모든 검사가 통과하면 ✓가 표시되고, 검사 실패 시에는 ✗가 표시됩니다. 실패한 검사가 없으면 거부된(refused) 검사 옆에 있더라도 보류 중인 작업은 running으로 표시됩니다. 다른 검사가 통과했거나 또한 바쁜 경우, 바쁜(busy) 검사는 busy를 표시합니다. 기타 거부되거나 실행되지 않았거나 알 수 없는 검사는 no verdict를 표시합니다. 종료 코드는 이 순서를 사용합니다: 3, 5, 4, 1, 0. 실패한 검사가 더 높은 종료 코드 옆에 있을 경우, pdd가 그 이유를 설명해 줍니다. | |
3. 시뮬레이션 (Simulate)
pdd simulate (단축명: pdd sim)을 사용하면 PDD 시뮬레이터에서 프로그램을 수동으로 사용할 수 있습니다. 코드는 없으며, 인터프리터가 프롬프트(prompts)를 실행합니다.
| 프로그램 | 명령어 | 수행 내용 |
|---|
| 화면 (Screen) | pdd simulate STORY | pdd가 브라우저에서 PDD 시뮬레이터를 엽니다. Screen 탭에서 Open the app을 클릭한 후 사용합니다. |
| ... | | |
my-program이라는 이름의 명령줄과 /api/items 경로를 가진 API가 있다고 가정해 봅시다: | | |
pdd simulate my-story --cli
export PATH=/path/to/your-repo/.pdd/try/bin:"$PATH"
my-program --help
pdd simulate my-story --serve 8091
curl http://127.0.0.1:8091/api/items
서버는 계속 실행되므로, 두 번째 터미널에서 요청을 보내세요. 명령줄과 API는 동일한 시뮬레이션 데이터를 사용합니다.
각 명령어 또는 요청은 코드가 없는 인터프리터에서 실행됩니다. 약 10~20초가 소요되며 시뮬레이션 예산(simulation budget)에서 AI 호출을 사용합니다. 시뮬레이션은 한 번에 하나의 명령어를 실행합니다. 에이전트가 네트워크 접근 권한을 가지고 있고 리포지토리 외부 파일에 대한 샌드박스 차단이 없는 경우, PATH 라인 이후의 동일한 명령어들을 실행할 수 있습니다.
시뮬레이터에서 Ask your agent 패널은 pdd simulate가 터미널에서 실행되는 동안 컴퓨터의 에이전트와 연결됩니다. 이 패널은 필드를 설명하고 채웁니다. 액션 실행을 요청하면 시뮬레이션 예산을 사용하여 실행하며, 그렇지 않으면 Run 버튼을 누릅니다. 사용할 에이전트를 선택하려면 --agent NAME을 추가하세요.
- 예산(Budget). 새로운 시뮬레이션은 400개의 AI 호출을 가집니다. 더 많은 호출이 필요하면 Simulator에서 **제한 상향(Raise the limit)**을 클릭하거나,
pdd simulate STORY --new --max-calls 600으로 새로운 시뮬레이션을 시작하세요. --new는 신선한 데이터로 시작합니다.
- 케이스 저장(Save a case). Simulator에서 **테스트로 저장(Save as test)**을 클릭하거나,
--cli 명령 실행 후 pdd simulate --save-last를 실행하세요. pdd는 해당 케이스를 Story의 테스트 파일에 추가합니다.
- 링크 비공개 유지(Keep the link private). 시뮬레이터 링크는 비공개로 유지해야 합니다. 이 링크를 가진 사람은 누구나 이를 사용하고 AI 호출을 소모할 수 있습니다.
- 중지(Stop it). 시뮬레이션은 24시간 후에 종료됩니다. 그 이전에 중지하려면
pdd simulate --stop STORY를 실행하세요.
4. 승인(Approve)
프로그램이 원하는 대로 작동하면, 채팅 또는 터미널에서 각 프롬프트를 승인하세요:
pdd approve prompts/NAME.prompt.md
게이트(gate)를 보여준 후, 자신의 말로 에이전트에게 답장하세요. 에이전트는 이 호출 하나에 해당 게이트와 모든 초안 프롬프트에 대한 사용자의 승인을 기록합니다. 질문이나 변경 요청은 게이트를 열어둡니다.
안전한 명령어, 프롬프트 스냅샷 및 터미널 또는 엄격 모드 승인에 대해서는 [채팅 승인 기록(Record a chat approval)]을 참조하세요. PR 1의 승인이 나중에 나오는 코드-또는-중지 게이트를 자동으로 승인하는 것은 아닙니다.
5. 코드 공간(Code space)
코드 공간은 PDD 컴파일러입니다. 에이전트가 승인된 프롬프트로부터 코드를 작성하고, 동일한 테스트를 해당 코드에 실행합니다. 워크플로우 실행 시 pdd는 두 개의 풀 리퀘스트(pull requests)를 엽니다:
- 프롬프트 공간(Prompt space). 프롬프트, 스토리, 그리고 테스트가 포함됩니다. 풀 리퀘스트 텍스트는
Prompt tests 라인과 보고서 링크로 시작합니다.
- 코드 공간(Code space). 코드가 포함됩니다. 이를 얻으려면 채팅에서 요청하거나,
pdd workflow approve 42를 실행하세요. 에이전트는 프롬프트 공간의 변경되지 않은 테스트를 코드에 실행하고, 그 결과를 기록하며, 뮤테이션 제어(mutation control) 및 형식 검사(formal check)를 수행합니다. pdd는 소스 식별자 및 보고서 구조를 검증하고 누락되거나 오래된 증거를 BLOCKED로 표시합니다. 이는 에이전트가 보고한 결과일 뿐, 독립적인 실행 증명은 아닙니다.
pdd는 절대 병합(merge)하지 않으며 병합 명령도 없습니다. 에이전트에게 병합을 요청하려면 [RUNBOOK §2]를 따르세요.
명령어(Commands)
| 명령어 | 기능 설명 |
|---|
pdd setup | PDD를 위해 이 저장소를 설정합니다. |
| ... | |
| The CLI 참조에는 모든 명령어와 옵션이 있습니다. | |
핵심 아이디어
프롬프트 공간과 코드 공간. 사용자의 프로그램은 먼저 프롬프트 공간에 존재합니다: 즉, 프롬프트, 스토리(Stories), 그리고 테스트입니다. 여기서 확인하고, 시도해보고, 변경할 수 있습니다. 원하는 대로 작동하면, 프롬프트를 승인하고 코드 공간의 코드가 이를 따릅니다.
스토리(Stories). 스토리는 사용자가 수행할 수 있는 하나의 기능입니다. 이 스토리의 수용 기준은 사람이 체크할 수 있는 번호가 매겨진 목록입니다. 테스트 파일에는 각 기준에 대해 최소한 하나 이상의 정확한 확인 절차가 포함되어야 합니다.
작은 테스트 단계. 각 테스트 단계는 작게 유지하세요: 한 가지 동작, 또는 약 10가지 동작의 짧은 실행 정도입니다. 서버는 10분이 지나면 단계를 중지합니다.
초안 및 승인됨. 프롬프트는 초안(draft)으로 시작합니다. 초안은 확인하고 시도해 볼 수 있습니다. 오직 사람만이 프롬프트를 승인할 수 있습니다. 승인된 프롬프트가 변경되면, 다시 초안 상태로 돌아갑니다.
AI 호출 예산. 예산은 가격이 아니라 한계입니다. 실행되는 호출에 대해서만 비용을 청구합니다. 확인(check) 기능은 각 테스트 파일의 단계당 12개의 호출을 제공하며, 최소 18개에서 최대 1000개까지 가능합니다. 새로운 시뮬레이션은 400개의 호출이 필요합니다. --max-calls N은 확인 또는 새로운 시뮬레이션을 위한 또 다른 제한(1부터 1000)을 설정합니다.
모의 환경(Fakes). 인터프리터는 실제 데이터베이스, 파일 또는 서비스에 절대 접근하지 않습니다. 프롬프트가 각 요소를 리소스로 선언하고, 테스트가 시작 데이터를 제공하면, 인터프리터가 이를 모방합니다. RUNBOOK §5를 참조하세요.
범위 지정 업로드. 확인 기능은 선택된 스토리에 필요한 파일만 전송합니다. 각 파일은 Git에서 보이도록 되어 있어야 합니다. pdd는 비밀번호와 같은 이름의 파일을 거부합니다. pdd test --files가 목록을 보여줍니다.
접근 권한
pdd test와 pdd simulate는 호스팅된 PDD 인터프리터를 사용합니다. 이 인터프리터는 PDD Cloud가 귀하의 GitHub 계정을 승인할 때 사용할 수 있습니다. 접근 권한을 얻으려면, gh가 사용하는 것과 동일한 GitHub 계정으로 promptdriven.ai/login에서 가입하세요. 승인 후 1분 이내에 접근이 가능합니다. 접근 관련 질문은 GitHub 로그인 정보를 사용하여 팀에게 문의하세요.
스킬(skills)과 다른 명령어들은 사용자의 컴퓨터에서 실행됩니다.
오류 발생 시
| 확인되는 내용 | 조치 사항 |
|---|
아직 PDD 인터프리터 접근 권한이 없습니다. GitHub로 https://promptdriven.ai/login에서 가입하세요. 계정이 승인되면 인터프리터를 사용할 수 있습니다. (종료 코드 5) | PDD Cloud가 귀하의 GitHub 계정을 승인하지 않았습니다. 접근(Access)을 확인하세요. |
| ... | |
더 자세한 내용은 사용 가이드를 참고하세요.
문제 보고하기
docs/ISSUES.md를 따르세요. 에이전트(agent)도 이를 따를 수 있으므로, 에이전트에게 문제 보고를 요청할 수 있습니다.
pdd --version을 실행하세요. 반드시 0.1.과 숫자가 출력되어야 합니다.- 오픈 이슈(open issues)를 검색하세요. 동일한 문제가 있는 이슈가 있다면, 해당 이슈에 댓글을 추가하세요.
- 그렇지 않다면, 이슈 양식(issue form)을 작성하세요: 문제 하나, 정확한 명령어와 출력 결과만 포함합니다. 토큰, 시뮬레이터 링크 또는 개인 코드는 절대 붙여넣지 마세요.
링크
라이선스
MIT.