Claude Code 골잡이 사용법: PRD를 /goal 실행 계약으로 바꾸기

Claude Code의 /goal은 여러 턴에 걸친 작업을 스스로 이어간다. 하지만 “무엇을 만들라”는 PRD만으로는 완료 여부를 정확히 판정하기 어렵다. 골잡이(goaljaby)는 PRD와 /goal 사이를 문서 다섯 개로 연결하는 도구다.

/goal이 있어도 골잡이가 필요한 이유

Claude Code 공식 문서에 따르면 /goal은 매 턴이 끝날 때 별도의 빠른 모델로 완료 조건을 평가한다. 조건이 충족되지 않으면 다음 턴이 자동으로 시작된다. 한 세션에는 하나의 골만 활성화할 수 있으며 조건은 최대 4,000자다. (code.claude.com)

평가 모델은 저장소를 직접 탐색하거나 테스트를 실행하지 않는다. 대화에 드러난 명령 결과와 설명을 읽고 판단한다. “기능을 완성하라”보다 “지정된 테스트가 통과하고 다른 모듈은 바뀌지 않아야 한다”가 좋은 조건인 이유다.

골잡이는 이 조건을 즉석에서 길게 쓰지 않고 PRD에서 구조화한다. 완료 증거와 수정 금지 범위, 실패 뒤 재시도 방법을 먼저 정한 다음 /goal 본문을 만든다. PRD가 제품 요구사항이라면 골잡이의 산출물은 작업 세션을 위한 실행 계약에 가깝다.

써본 사람들 사이에서는 계획 파일과 명시적인 완료 조건이 큰 작업의 이탈을 줄인다는 반응이 있다. 반대로 검증 기준이 모호하면 긴 루프가 같은 수정을 반복하거나 토큰만 쓸 수 있다는 불만도 나온다. 골잡이가 자동 실행보다 검증 설계에 많은 단계를 둔 배경이다.

설치하고 PRD 폴더를 넘기는 과정

2026년 9월 27일 기준 최신 공개 버전은 0.6.3이다. 9월 4일 변경 기록에는 요청 언어 자동 감지 정책과 README 설명을 일치시킨 수정이 담겼다. 한국어와 영어는 제목까지 규칙으로 검사한다. 다른 언어는 필수 섹션 존재 여부를 확인하는 방식으로 폴백한다. (github.com)

Claude Code에서 설치하는 순서는 다음과 같다.

1. /plugin marketplace add https://github.com/fivetaku/gptaku_plugins.git
2. /plugin install goaljaby
3. Claude Code를 다시 시작한다.
4. /goaljaby /절대경로/프로젝트/PRD/를 실행한다.

마켓플레이스는 플러그인을 보관하는 앱스토어가 아니라 설치 위치를 나열한 카탈로그다. Anthropic 문서는 플러그인이 사용자 권한으로 코드를 실행할 수 있다고 안내한다. 설치 전 저장소와 설정 스크립트를 검토해야 한다. (code.claude.com)

입력 폴더에는 Markdown 문서가 하나 이상 있어야 한다. Acceptance Criteria와 non-goals, 미해결 질문이 포함될수록 결과가 구체적이다. PRD가 없으면 show-me-the-prd에 작성을 맡기거나 한 줄 목표로 간소화된 구성을 만들 수 있다. (github.com)

다섯 파일이 완료와 실패를 나눠 맡는다

골잡이는 PRD를 읽은 뒤 작업 유형과 검증 방법을 확인한다. 기능 구현, 버그 수정, UI, 문서, 마이그레이션, eval 개선에 따라 질문과 검증 항목이 달라진다. 이후 PRD 폴더에 다음 파일을 만든다.

• VALIDATION.md: 필수 검사와 Acceptance Criteria의 대응 관계
• RECOVERY.md: 실패 루프, 재시도 한계, scope 잠금과 되돌리기 규칙
• PLAN.md: 목표, 참고 문서, 최대 다섯 개 마일스톤
• PROGRESS.md: 현재 상태, 검증 결과, 다음 단계와 인수인계 정보
• goal-command.md: 실제로 실행할 /goal 조건문

중요한 건 파일 수가 아니라 역할 분리다. VALIDATION.md는 무엇을 증명할지 정한다. RECOVERY.md는 실패했을 때 어디까지 고칠지 제한한다. PROGRESS.md는 컨텍스트가 압축되거나 세션을 다시 열 때 진행 상태를 복원하는 표면이 된다.

goal-command.md가 4,000자를 넘으면 공백 정리, 세부 규칙 외부화, 파일명 축약, 마일스톤 요약을 순서대로 적용한다. 정지 조건과 scope 잠금, 세 번의 시도 제한, 문서 참조, 진행 기록 갱신은 삭제하지 않는다. 마지막에는 문자 수와 보호 조항, Acceptance Criteria 매핑을 명령으로 다시 검사한다. (github.com)

작은 수정에는 무겁고 경계가 많은 작업에는 유용하다

버튼 색상 한 곳을 고치거나 함수 이름을 바꾸는 작업에는 이 절차가 과하다. 직접 실행한 테스트 하나로 끝을 확인할 수 있다면 기본 /goal이나 일반 프롬프트가 짧다.

완료 기준이 여러 층으로 나뉠 때 효과가 커진다. 결제 모듈을 교체한다면 기존 API 호환과 회귀 테스트, 데이터 마이그레이션과 롤백을 함께 확인해야 한다. UI 구현은 화면 크기별 캡처와 디자인 참조 보존을 검증 항목으로 넣을 수 있다.

1인 개발자에게는 다음 세션에서 작업을 복원할 기록이 생긴다. 소규모 팀은 PRD의 요구사항이 어느 테스트로 증명됐는지 함께 검토할 수 있다. 다만 생성된 문서를 읽지 않고 승인한다면 파일만 늘어난다. 자동화의 이점도 사라진다.

승인을 거친 뒤에만 장기 루프가 시작된다

골잡이는 파일을 만든 직후 작업을 시작하지 않는다. 목표와 마일스톤, 검증 명령, 제외 범위와 남은 결정을 대화창에 보여준다. 사용자가 승인해야 응답 마지막 줄에 /goal 본문이 나오고 다음 턴부터 실행된다. (github.com)

이 승인 단계는 장식이 아니다. /goal은 권한 모드를 바꾸지 않지만 Auto mode와 함께 쓰면 도구 호출과 다음 턴 진행이 연속으로 이뤄진다. 실행 전에 테스트 명령이 실제 프로젝트에 맞는지 살펴야 한다. 수정 금지 범위가 빠지지 않았는지도 확인해야 한다.

골잡이는 코드의 정확성을 보증하지 않는다. 공식 /goal의 판정도 대화에 제시된 증거에 의존한다. 골잡이의 가치는 Claude Code를 더 오래 움직이는 데 있지 않다. 멈춰도 되는 순간을 사람이 먼저 작성하게 만드는 데 있다.