goal-prompt-builder

Goal Prompt Builder

Claude Code 네이티브 /goal 기능에 넣을 완료 조건을 설계해 주는 스킬이다. (공식 정본: https://code.claude.com/docs/en/goal — 자세한 검증 사실과 출처는 references/goal-mechanics.md 참고)

왜 이 스킬이 필요한가

/goal <조건>을 걸면 Claude가 매 턴 끝마다 그 조건이 충족됐는지 평가받고, 충족될 때까지 사용자 프롬프트 없이 며칠이고 계속 작업한다. 강력한 만큼 양날의 검이다.

• 좋은 조건을 넣으면 복잡한 작업이 무인으로 끝까지 완수된다.
• 나쁜 조건(주관적이거나, Claude의 출력만으로 증명할 수 없는 조건)을 넣으면 평가자가 영영 "미달성"으로 봐 무한 루프에 빠지거나, 반대로 Claude가 "다 됐다"고 요약만 해도 통과되어 겉만 그럴듯한 헛결과가 나온다.

좋은 완료 조건을 사람이 처음부터 정확히 쓰기는 어렵다. 그래서 **클로드에게 조건 자체를 설계하게 하는 것(메타 프롬프팅)**이 정석이고, 이 스킬이 그 과정을 표준화한다.

/goal이 실제로 어떻게 작동하는가 (이 한 가지는 꼭 기억)

조건을 평가하는 것은 **작고 빠른 모델(기본 Haiku)**이며, 이 평가자는 도구를 실행하거나 파일을 직접 읽지 않는다. 오직 "대화에 드러난 것(transcript)"만 보고 판정한다.

여기서 이 스킬의 모든 설계가 따라 나온다: 완료 조건은 Claude 자신의 출력으로 증명할 수 있는 형태여야 한다. 즉 "테스트가 통과한다"가 아니라 "Claude가 npm test를 실제로 실행하고 그 결과(exit 0)를 대화에 보여준다"가 되어야 한다. 평가자는 Claude가 보여준 것만 믿는다.

언제 작동하는가 / 제외

• 작동: 어떤 작업을 /goal로 무인 완수시키고 싶다는 요청·의도. 장기·복잡·고검증 작업.
• 제외: /goal이 무엇인지 묻는 설명 질문, 이미 걸린 루프를 푸는 트러블슈팅(/goal clear). 또 한 번에 끝나는 단발 작업은 골이 과하니 더 가벼운 방식을 권한다.

워크플로우

1단계 — 작업 의도 파악

사용자의 고수준 작업을 듣는다. 대화에 이미 맥락이 충분하면 그것을 우선 활용한다(불필요하게 다시 묻지 말 것). 다음을 머릿속에 둔다: "이 작업이 '끝났다'를 무엇으로 판정하는가? 그 판정을 Claude가 자기 출력으로 어떻게 보여줄 수 있는가?"

2단계 — 대화형 정제 (측정 가능한 종료 상태로 좁히기)

작업을 측정 가능한 단일 종료 상태로 좁히는 데 필요한 정보가 빠졌으면 AskUserQuestion으로 핵심만 되묻는다. 특히 다음을 확인한다.

• 무엇이 충족되면 끝인가? (테스트 통과 / 빌드 성공 / 파일 N개 / 큐 비움 / 모든 호출부 마이그레이션 등)
• 그걸 어떤 명령·검사로 증명할 수 있는가? (npm test exit 0, git status clean 등)
• 가는 길에 바뀌면 안 되는 것은? (다른 테스트 파일 수정 금지, API 계약 유지 등)
• 무인으로 돌릴 거라면 턴/시간 상한은? (or stop after 20 turns)

한 번에 2~4개만, 결과를 좌우하는 것만 묻는다. "알아서 해줘"라면 합리적 가정을 명시하고 진행한다.

3단계 — 완료 조건 3요소 구성

공식 가이드의 좋은 조건 = 다음 3요소를 자연어 한 문장(필요시 여러 절)으로 결합한 것. 무인 실행이면 턴 절을 더한다.

1. 측정 가능한 종료 상태 — test result / build exit code / file count / empty queue 등
2. 명시적 검증 방법(stated check) — Claude가 어떻게 증명할지 ("npm test exits 0", "git status is clean")
3. 지켜야 할 제약 — 도중에 바뀌면 안 되는 것 ("no other test file is modified")
4. (무인 실행 시) 턴/시간 상한 — "or stop after N turns" (/goal엔 내장 토큰 예산이 없다)