pdd-kit이 코딩 에이전트와 제품 모델을 공유한다

pdd-kit은 제품의 기능과 규칙을 코드 저장소 안에 문서화해 사람과 코딩 에이전트가 함께 검토하고 확인할 수 있도록 하는 오픈소스 도구다. 기존 저장소의 코드를 바탕으로 제품 모델을 만들거나, 아이디어와 사전 검토된 청사진에서 시작할 수 있다.

제품의 정의는 문서, 코드, 티켓, 채팅과 사람들의 지식에 흩어져 있고 구조가 없거나 불완전할 수 있다. pdd-kit은 제품 정의를 product-model/ 폴더에 마크다운 파일로 정리한다. 제작자는 코딩 에이전트가 제품을 매번 새로 추측하는 대신, 사람과 에이전트가 함께 읽고 검토하는 기준을 두는 방식이라고 설명한다.

• 설치 명령은 npx pdd-toolkit install이다.
• 기존 코드가 있는 저장소에서는 /pdd-map으로 모델을 만들고, 아직 코드가 없다면 /pdd-ideate로 아이디어를 정리한다.
• 모델은 일반 .md 파일로 저장되며, lint로 파일을 검사하고 pdd-verify로 코드와 모델의 차이를 확인할 수 있다.

제품 모델과 활용 대상

제품 모델은 제품이 무엇을 하는지 한곳에 기록하는 정의다. 제품을 구현하는 방법과 분리해 코드 옆에 두며, 다음 항목으로 구성된다.

• 엔티티(Entities): 제품이 보관하는 정보와 그 정보에 작용하는 주체다. 예를 들어 주문, 고객, 결제 제공자가 있다.
• 인터페이스(Interfaces): 사람과 시스템이 제품에 접근하는 경로다. 웹 앱, 모바일 앱, 파트너 API 등이 해당한다.
• 도메인(Domains): 주문, 카탈로그, 결제처럼 제품을 나누는 주제 영역이다.
• 기능(Capabilities): 결제, 주문 취소, 환불처럼 사용자가 제품으로 할 수 있는 일이다.
• 여정(Journeys): 둘러보고 구매하기, 가입하기, 다시 주문하기처럼 여러 기능을 거쳐 달성하는 목표다.
• 비즈니스 규칙(Business Rules): 주문당 최대 3개, 환불은 관리자만 가능, 합계에 세금 포함처럼 항상 지켜야 할 조건과 권한이다.
• 변형(Variations): 기능 플래그, 요금제 등급, A/B 테스트처럼 제품이 여러 방식으로 동작하는 지점이다.

pdd-kit은 문서, 설계 자료, 코드와 사람에게서 얻은 지식을 제품 모델에 모으고, 각 정보 출처가 맡을 일을 분명히 하도록 제안한다. 사용자 문서는 제품 사용법을 안내하고, 내부 문서는 아키텍처와 설계 결정, 온보딩 정보를 기록한다. 설계·아키텍처 자료는 제품의 모양과 동작을 설명하며, 코드와 테스트는 구현과 검증을 담당한다. 티켓, 채팅과 사람은 맥락, 요청, 문서화되지 않은 지식을 전달한다. 제작자는 제품 모델을 명확히 하면 각 출처를 더 간결하고 목적에 맞게 유지할 수 있다고 설명한다. 제품 모델을 두는 이유에서 관련 FAQ를 볼 수 있다.

제작자는 에이전트가 제품에 대한 설명보다 빠르게 코드를 작성하면서 빈틈을 추측으로 채우고, 그 추측이 실제 제품에 반영될 수 있다고 지적한다. 제품 모델을 두면 제품 정의를 티켓과 문서 등에 흩어 놓지 않고 코드 옆에서 관리할 수 있으며, 에이전트는 여정, 시나리오와 규칙을 참고해 무엇을 구현할지 파악한다. 승인된 모델과 코드가 맞는지 확인하고, 동작이 바뀔 때 모델과 코드의 차이도 살펴볼 수 있다. 모델과 코드 변경은 하나의 풀 리퀘스트에서 함께 검토한다.

칸반 보드 청사진 예시

저장소에는 코드가 포함되지 않은 개념적 제품 모델인 칸반 보드 청사진이 있다. 이 예시는 소규모 팀이 열과 카드가 있는 공유 보드에서 일을 계획하고, AI 에이전트가 다음 카드를 제안하는 제품을 다룬다. 아래 정보는 모두 해당 모델에서 가져온 것이다. 칸반 보드 제품 모델을 온라인으로 보기에서 확인하거나, 다음 명령으로 컴퓨터에 내려받아 볼 수 있다.

npx pdd-toolkit blueprint pull kanban-board
npx pdd-toolkit view

모델에는 엔티티 9개와 기능 23개, 비즈니스 규칙 32개가 있다. 예를 들어 카드 제안 기능은 제안 카드를 만들지만 실제 보드 카드를 만들지는 않는다. 제안 수락 기능이 제안 카드를 보드의 카드로 바꾸며, 제안을 거절하면 제안만 변경되고 보드는 그대로 유지된다.

인터페이스와 기능의 연결을 보면 에이전트 연결은 카드 제안 기능 하나만 제공한다. 카드 변경은 모두 구성원이 보드 웹 애플리케이션에서 수행한다. 제안 카드는 연결된 AI 에이전트만 만들 수 있고, 보드 구성원만 이를 수락하거나 거절할 수 있다. 제안 카드를 따로 삭제할 수는 없으며 보드를 삭제할 때 함께 제거된다.

제안 카드 엔티티에는 제목, 설명, 이유, 제안된 열 등 네 가지 정보가 기록된다. 상태는 제안됨에서 수락됨 또는 거절됨으로 바뀐다. 생성됨과 제거됨은 수명 주기의 시작과 끝을 나타낸다. 어떤 상태에서도 제안 카드만 따로 제거할 수 없고, 보드를 삭제하면 카드도 제거된다.

카드 제안 기능에는 네 가지 시나리오가 있다. 목표를 이루기 위한 카드 제안, 진행이 막힌 카드의 다음 단계 제안, 그리고 두 가지 거절 상황이다. 예를 들어 AI 에이전트가 직접 카드 이동을 시도하면 제품이 이를 거절한다. 시나리오의 각 단계에는 행위자, 읽는 정보와 위치, 적용되는 비즈니스 규칙이 기록된다. 에이전트가 카드를 편집·삭제·생성하거나 자신의 제안을 수락하려는 경우도 같은 방식으로 거절된다.

설치와 시작 방법

저장소에서는 다음 명령으로 설치한다.

npx pdd-toolkit install

npm 패키지 이름은 pdd-toolkit이며, 설치하면 pdd-kit 명령을 사용할 수 있다. 전역 설치를 원하면 npm install --global pdd-toolkit을 실행한 뒤 pdd-kit install을 사용한다.

설치 과정은 감지한 코딩 에이전트(Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot)에 맞춰 기술을 추가한다. 에이전트를 찾지 못하면 Claude Code와 Codex를 대상으로 설치한다. 대상 선택은 변경할 수 있다. Codex에서는 명령어 앞에 / 대신 $를 사용한다.

이미 코드가 있는 저장소라면 기존 저장소 매핑을 권장한다. 에이전트 안에서 다음 명령을 실행한다.

/pdd-map

매핑 기능은 코드를 실행하지 않고 읽는다. 코드만으로 답할 수 없는 내용을 질문하고, 사용자가 승인한 뒤 product-model/을 작성한다. 결과 모델은 다음 명령으로 볼 수 있다.

npx pdd-toolkit view

자세한 내용은 기존 저장소에서 시작하기를 참고한다.

코드가 아직 없다면 제품 아이디어를 입력해 시작한다.

/pdd-ideate I want to build a booking app for dog walkers

사용자는 몇 가지 제품 형태 중 하나를 고른 뒤 모델을 승인한다. 아이디어에서 시작하기에서 절차를 확인할 수 있다.

익숙한 유형의 제품을 만들 때는 검토된 청사진을 활용할 수 있다. 청사진 목록을 보고 원하는 모델을 내려받는다.

npx pdd-toolkit blueprint list
npx pdd-toolkit blueprint pull <name>

청사진 목록과 청사진에서 시작하기에서 자세한 정보를 확인할 수 있다.

개발 흐름과 기능

개발 흐름은 아이디어 구체화, 구현, 검증으로 이뤄진다. /pdd-ideate 단계에서 에이전트는 변경 사항을 먼저 모델에 기록하며, 사용자가 승인하기 전에는 아무것도 작성하지 않는다. 구현은 계획 모드, SDD 도구 또는 별도의 자유 형식 작업 방식으로 진행할 수 있고, pdd-kit은 구현 방법을 바꾸지 않는다. /pdd-verify 단계에서는 에이전트가 코드와 모델을 대조해 차이를 보고하고, 사용자가 선택한 문제를 수정한다.

원한다면 pdd-kit이 구현과 검증의 반복 작업을 조정하도록 설정할 수 있다. 이때 verify가 작업을 단계별로 계획하고 에이전트가 각 단계를 구현하며, 다음 단계로 넘어가기 전에 verify가 결과를 확인한다. 다음 명령으로 이 기능을 켜거나 AGENTS.md에 한 문장으로 설정할 수 있다.

npx pdd-toolkit install --orchestrate=on

자세한 설명은 verify를 사용한 구현을 참고한다.

pdd-kit은 Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot용 에이전트 기술을 제공한다. 모든 리소스는 저장소 안의 일반 .md 파일로 관리하고 풀 리퀘스트에서 검토할 수 있다. npx pdd-toolkit lint는 파일을 검사하며, pdd-verify는 코드를 모델과 대조한다. npx pdd-toolkit view는 브라우저에서 모델을 열고 편집 내용을 반영한다. 검토된 청사진으로 빈 문서에서 시작하지 않을 수도 있다.

도구는 로컬 우선 방식으로 동작하며 계정이나 호스팅 서비스를 요구하지 않는다. 에이전트 기술은 코드를 읽지만 실행하지 않는다. pdd-kit은 MIT 라이선스로 공개된 오픈소스다.

pdd-kit은 자체 개발에도 pdd-kit을 사용한다고 밝힌다. 저장소의 product-model/ 폴더에 자체 제품 모델이 있으며, 다음 명령으로 열 수 있다.

npx pdd-toolkit view itai-gendler/pdd-kit

명령줄 도구(CLI)는 install, update, lint, view와 blueprint 명령을 제공한다. 전체 명령과 옵션은 CLI 참고 문서 또는 npx pdd-toolkit --help에서 확인할 수 있다. 도입 방법과 제품 모델의 범위, 도움말은 FAQ에 정리돼 있다. pdd-kit은 MIT 라이선스로 배포되며, 저작자 표시 조건을 따른다. 자세한 내용은 라이선스를 참고한다.