show-me-the-prd와 골잡이, PRD를 실제 구현으로 잇는 법

아이디어를 PRD로 정리했는데도 Claude Code가 엉뚱한 방향으로 구현한다면 무엇이 빠진 걸까. show-me-the-prd와 골잡이를 잇는 방식은 문서 작성과 실행 제어를 분리해 이 문제에 답한다. 긴 기획서를 만드는 게 핵심은 아니다. 완료를 증명할 조건과 실패 뒤의 행동까지 코드 에이전트가 읽을 수 있는 형태로 넘겨야 한다.

show-me-the-prd는 아이디어를 네 종류의 설계 문서로 바꾼다

show-me-the-prd는 한 문장짜리 아이디어를 받아 구조화된 인터뷰를 진행하는 Claude Code 플러그인이다. 사용자는 제품 범위, 핵심 기능, 데이터 모델, 개발 단계, 기술 스택과 인증 방식을 차례로 고른다. 각 선택지에는 장단점과 구현 난도가 붙는다. 저장소 설명에 따르면 보통 5~6개 질문에 답하면 설계 묶음이 완성된다. (raw.githubusercontent.com)

산출물은 PRD/01_PRD.md, 02_DATA_MODEL.md, 03_PHASES.md, 04_PROJECT_SPEC.md다. README.md는 문서 사이를 안내한다. PRD에는 목표와 사용자 이야기가 담기고, 데이터 문서에는 주요 엔터티와 관계가 정리된다. 단계 문서는 개발 순서와 시작 프롬프트를 제공한다. 프로젝트 명세에는 AI가 지켜야 할 규칙과 금지 사항이 들어간다. (raw.githubusercontent.com)

설치는 Claude Code에서 마켓플레이스를 추가한 뒤 플러그인을 설치하는 순서로 진행한다.

/plugin marketplace add https://github.com/fivetaku/gptaku_plugins.git
/plugin install show-me-the-prd

Claude Code를 다시 시작하고 /show-me-the-prd 사진 정리 앱을 만들고 싶다처럼 실행한다. 기존 메모나 명세가 있다면 먼저 제공해도 된다. 플러그인은 빠진 항목만 질문하는 보완 모드를 지원한다. (raw.githubusercontent.com)

여기까지 만들어지는 것은 좋은 설계 입력이다. 다만 반복 실행을 멈출 기준이나 테스트 실패 뒤의 처리 방식은 아직 충분히 정해지지 않았다.

골잡이는 PRD에 완료 증명과 실패 복구 규칙을 붙인다

골잡이는 show-me-the-prd가 만든 PRD 디렉터리를 입력으로 받는다. 독립적으로 작성한 PRD 폴더도 사용할 수 있다. 설치 후 절대 경로를 넘기는 방식이 권장된다. (raw.githubusercontent.com)

/plugin install goaljaby
/goaljaby /Users/me/my-project/PRD/

골잡이는 PRD에서 완료 기준, 비목표, 작업 유형을 추출한다. 이어 검증 방법과 엄격도, 마일스톤을 묻는다. 그런 다음 VALIDATION.md, RECOVERY.md, PLAN.md, PROGRESS.md, goal-command.md를 만든다. PRD가 무엇을 만들지 설명한다면 이 다섯 파일은 무엇을 확인해야 끝나는지, 실패하면 어디까지 되돌아갈지를 적는다. (raw.githubusercontent.com)

VALIDATION.md에는 필수 검사와 수용 조건의 대응 관계가 들어간다. RECOVERY.md는 재시도 한도와 범위 고정을 맡는다. PLAN.md는 최대 다섯 개 마일스톤으로 작업을 나누고 PROGRESS.md는 세션 사이 인계 기록이 된다. 마지막 파일에는 Claude Code의 /goal에 전달할 조건이 담긴다. 골잡이는 이 명령 본문을 4,000자 이하로 줄인 뒤 보호해야 할 중단 조건과 복구 조항이 남았는지 검사한다. (raw.githubusercontent.com)

문서를 생성해도 코드는 바로 바뀌지 않는다. 사용자가 검토 요약을 읽고 승인해야 골잡이가 /goal 명령을 내보낸다. 설계 단계와 자율 실행 사이에 사람의 승인 지점을 남긴 구조다.

/goal은 작업 목록보다 검증 가능한 종료 조건에 가깝다

Claude Code 공식 문서에서 /goal은 완료 조건을 설정하는 기능이다. 일반적으로 각 턴 뒤 별도의 빠른 모델이 대화에 드러난 증거를 읽는다. 조건이 충족되지 않으면 다음 턴이 시작된다. 충족됐거나 달성 불가능하다고 판정되면 루프가 끝난다. 세션마다 하나의 goal만 활성화할 수 있다. (code.claude.com)

좋은 조건은 “로그인 기능을 완성하라”보다 구체적이다. 인증 테스트 통과, 린트 종료 코드 0, 기존 API 불변처럼 결과와 검사법, 변경 금지 범위를 함께 적는 식이다. 평가 모델은 파일을 직접 열거나 명령을 실행하지 않는다. Claude가 실행 결과를 대화에 남겨야 판단 근거가 생긴다. 골잡이가 별도의 검증 문서와 완료 기준 매핑을 만드는 이유도 여기에 있다. (code.claude.com)

/goal은 권한 설정을 바꾸지 않는다. Manual mode에서는 파일을 수정하거나 명령을 실행할 때 계속 승인이 필요하다. 오래 자리를 비우고 실행하려면 허용 범위를 검토한 뒤 auto mode를 함께 써야 한다. 인증 실패, 크레디트 소진, 해소되지 않은 컨텍스트 초과처럼 사람이 처리해야 할 오류는 goal을 중단시킬 수 있다. (code.claude.com)

써본 사람들 사이에서는 자연어 한 줄로 구현을 맡길 때보다 PRD를 먼저 거치는 편이 결과의 흔들림을 줄였다는 반응이 있다. 문서가 많아질수록 잘못 정한 요구사항까지 단단하게 고정된다는 불만도 나온다. 승인 전에 비목표와 완료 기준을 사람이 읽어야 하는 이유다.

두 도구를 연결하는 실제 순서는 짧고 검토는 길어야 한다

실전 과정은 네 단계로 압축된다. 먼저 저장소 루트에서 show-me-the-prd를 실행해 아이디어와 MVP 범위를 정한다. 생성된 네 설계 문서에서 사용자 흐름, 데이터 구조, 단계별 범위를 확인한다. 그 뒤 /goaljaby에 PRD 폴더를 넘겨 검증·복구 문서를 만들고 요약을 승인한다. 승인이 끝나면 출력된 /goal이 구현과 테스트를 반복한다.

개인 개발자에게 유용한 것은 화려한 기획 문구보다 중단 가능한 실행 기록이다. PROGRESS.md가 남으면 새 세션에서 앞선 판단을 다시 설명할 부담이 줄어든다. 작업에 따라 검증 기준도 달라진다. 버그 수정에서는 재현과 회귀 테스트, UI에서는 화면과 뷰포트 확인, 마이그레이션에서는 동등성 검사와 롤백을 설정한다. (raw.githubusercontent.com)

소규모 팀이 여러 작업을 동시에 돌릴 때는 같은 체크아웃에서 여러 세션이 파일을 고치게 해서는 안 된다. Claude Code는 claude --worktree feature-auth처럼 세션별 Git worktree를 만들 수 있다. 각 작업이 별도 파일과 브랜치를 사용하므로 기능 개발과 버그 수정을 분리할 수 있다. 환경 파일과 의존성 초기화는 worktree마다 따로 확인해야 한다. (code.claude.com)

PRD가 실행 문서가 되려면 실패 조건부터 적어야 한다

show-me-the-prd만 사용하면 제품의 모습과 개발 순서가 선명해진다. 골잡이까지 연결하면 테스트 방법, 범위 잠금, 재시도 한도와 진행 기록이 추가된다. 두 도구의 역할은 겹치지 않는다. 앞쪽은 사람의 모호한 생각을 구조화한다. 뒤쪽은 그 구조를 /goal이 판정할 조건으로 번역한다.

다만 문서 체인이 코드 품질을 보장하지는 않는다. 잘못 고른 데이터 모델이나 허술한 테스트도 자동으로 반복될 수 있다. 이 과정의 성패를 가르는 질문은 “PRD를 얼마나 자세히 썼는가”가 아니다. 실패했을 때 멈추고 수정해야 할 신호를 문서 안에 얼마나 분명히 넣었는가다.