블로그로 돌아가기튜토리얼

Claude Code /goal 명령어 완벽 가이드 — 자율 작업 자동화의 핵심 도구

7분 읽기0

Claude Code /goal 명령어 완벽 가이드: 자율 작업 자동화의 핵심 도구

/goal 명령어란 무엇인가

2026년 5월 12일, Anthropic이 Claude Code v2.1.139를 공식 출시하면서 /goal 슬래시 커맨드가 빌트인으로 추가됐습니다. 이 명령어는 사용자가 한 번 완료 조건을 정의하면, Claude가 그 조건이 충족될 때까지 스스로 점검하면서 작업을 계속하는 자율 실행 모드입니다.

원래 OpenAI Codex에 있던 비슷한 기능을 커뮤니티가 먼저 fork로 만들었는데(jthack/claude-goal, itsuzef/goalkeeper, tolibear/goalbuddy 등), Anthropic이 이를 공식판으로 흡수·정식화한 형태입니다.

핵심은 단순합니다. 사용자가 /goal <완료 조건>을 입력하면, 매 턴이 끝날 때마다 별도의 작은 모델(기본값: Haiku)이 대화 transcript를 읽고 "완료됐는가? yes / no + 짧은 이유"를 판정합니다. no라면 그 이유가 다음 턴 가이드로 주입되고, Claude는 계속 작업합니다.

작동 메커니즘 자세히 보기

/goal은 세션 스코프의 prompt-based Stop hook으로 구현되어 있습니다. 매 턴 종료 시점에 다음 흐름이 발생합니다.

  1. Main Claude가 한 턴을 마치고 메시지를 출력합니다.
  2. Stop hook이 트리거되어 transcript를 evaluator(Haiku)에게 전달합니다.
  3. Evaluator가 "완료 조건이 transcript 안에서 증명됐는가"를 판정합니다.
  4. 판정 결과가 yes면 사용자에게 제어권이 돌아갑니다. no면 그 이유가 main Claude의 다음 턴 시스템 가이드로 주입됩니다.
  5. UI에는 ◎ /goal active 인디케이터 + 경과시간/턴/토큰이 라이브로 표시됩니다.

중단은 /goal clear로 합니다. alias로 stop, off, reset, none, cancel 모두 같은 효과입니다.

CRITICAL 제약 — Evaluator는 transcript만 읽는다

가장 중요한 제약입니다. Evaluator는 파일을 직접 열거나 명령을 실행할 수 없습니다. 오직 main Claude와 사용자가 주고받은 대화 transcript만 읽습니다.

따라서 완료 조건은 반드시 main Claude의 발화 안에서 증명 가능한 형태여야 합니다.

좋은 완료 조건나쁜 완료 조건
npm test exit code is 0 (테스트 결과를 paste 가능)DB에 dirty data가 없다 (대화로 검증 불가)
모든 acceptance criteria가 체크됨 (체크리스트가 transcript에 등장)프로덕션이 안정적이다 (외부 모니터링 필요)
outputs/2026-05-14-*/에 thread.txt + card-news/ 존재 확인됨 (Claude가 ls 출력 paste 가능)사용자가 만족한다 (주관 평가 불가)

이 제약 때문에 완료 조건은 "Claude가 무엇을 출력해야 evaluator가 yes를 낼 수 있는가"를 미리 설계해서 적어야 합니다.

Anthropic 공식 권장 4대 활용 사례

공식 docs(code.claude.com/docs/en/goal)에는 4가지 권장 use case가 명시되어 있습니다.

1. 모듈을 새 API로 마이그레이션

/goal src/legacy-auth.ts의 모든 호출처가 신규 OAuth2 API로 전환되고, npm test exit code 0이 출력됨

호출처를 하나씩 찾아 바꾸고, 매번 테스트를 돌리고, 깨지면 고치는 작업은 사람이 손으로 돌리면 지루합니다. /goal로 wrap하면 Claude가 알아서 끝까지 갑니다.

2. Design doc 구현

/goal docs/spec-2026-05.md의 모든 acceptance criteria 항목이 체크박스 ✓로 표시되고, 각 항목에 대응하는 테스트가 통과함

PRD나 design doc을 읽고 그대로 구현하는 작업입니다. Claude가 각 criterion을 하나씩 체크하면서 진행합니다.

3. 대형 파일을 작은 모듈로 분할

/goal src/app.ts (현재 1200줄)를 각각 300줄 미만의 파일들로 분할하고, 기존 import 경로가 모두 정상 작동함

리팩토링 자동화입니다. size budget 같은 정량 기준이라 evaluator가 쉽게 판정합니다.

4. 라벨링된 이슈 백로그 처리

/goal `gh issue list --label "good-first-issue"` 결과가 빈 배열이 될 때까지 이슈를 하나씩 해결

큐 기반 작업입니다. 큐가 비었음이 transcript에 명시되면 완료입니다.

한국 자동화 시스템 통합 패턴

본 블로그를 운영하는 콘텐츠 자동화 시스템(content-automation)에도 /goal을 직접 통합할 수 있습니다. 권장 패턴은 다음과 같습니다.

패턴 A: 직접 호출

/goal /research --auto 완료 + outputs/2026-05-14-*/에 thread.txt + card-news/ + linkedin-post.txt 3종 존재 확인

/research --auto를 그대로 트리거하되, 모든 산출물이 실제로 생성됐는지를 goal로 검증합니다.

패턴 B: -p headless 모드 (무인 자동화)

claude -p "/goal 리서치 리포트가 artifacts/에 저장되고 출처 5개+ 표시됨" "리서치 주제: ..."

cron이나 launchd에서 무인으로 돌릴 때 효과적입니다.

패턴 C: 커스텀 슬래시 커맨드로 wrap

.claude/commands/research-with-goal.md 같은 커스텀 커맨드를 만들어서 /goal을 내부적으로 호출하면, 팀원 모두가 같은 검증 조건을 공유할 수 있습니다.

함께 쓰면 좋은 도구

도구 / 스킬통합 패턴
TodoWrite완료 조건을 TodoWrite 체크리스트로 만들고 "모든 todo가 completed 상태"를 goal로
plan.md (HARD-GATE)plan APPROVED → /goal "plan.md의 모든 acceptance criteria 충족"
agent-router자동 라우팅된 에이전트의 최종 산출물 검증을 goal로 wrap
publish_orchestrator.py9채널 발행 결과 verdict를 goal로 검증

주의사항과 한계

Stop hook 충돌 가능성

/goal 자체가 Stop hook으로 구현됩니다. 따라서 기존 Stop hook 시스템(예: content-automation의 notification-hooks.md, hook-guard.sh)과 충돌 가능성이 있습니다. 사전에 작은 goal로 호환성을 테스트하는 것을 권장합니다.

disableAllHooks / allowManagedHooksOnly 설정 시 작동 안 함

조직 보안 정책으로 Stop hook을 막아둔 환경에서는 /goal이 작동하지 않습니다. 2.1.139 이전 버전에서는 이 경우 silent hang(조용히 멈춤) 버그가 있었는데, 2.1.139에서 명시적 에러 메시지로 fix됐습니다.

부분 성공 정책과의 충돌

content-automation처럼 "9채널 중 7채널 성공도 PARTIAL로 인정" 정책을 쓰는 경우, goal 완료 조건에 verdict in [APPROVE, PARTIAL]을 명시해야 합니다. 그렇지 않으면 일부 채널 실패만으로 goal이 영영 yes를 못 받는 상황이 생깁니다.

비용

Haiku evaluator의 평가 비용은 무시 가능한 수준이라고 공식 명시되어 있습니다. 매 턴 transcript 요약만 보내기 때문입니다. 긴 세션에서도 부담은 거의 없습니다.

한국 사용자에게 의미하는 것

2026년 5월 14일 기준, 한국어 블로그 / velog / 티스토리 / Medium 한국어 매체 어디에서도 /goal을 단독으로 다룬 후기를 찾기 어렵습니다. 출시 2-3일차이기 때문입니다.

이 말은 두 가지를 의미합니다.

첫째, 한국 개발자 커뮤니티에 /goal을 한국어로 처음 소개하는 콘텐츠가 검색 결과 상단을 선점할 수 있는 시기입니다. SEO 관점에서 유리합니다.

둘째, Claude Code를 이미 한국에서 활용 중인 개인 개발자나 1인 기업, 자동화 운영자에게 /goal을 빠르게 적용하면 동종업계 대비 2-3주 정도의 우위를 점할 수 있습니다.

마무리

/goal은 "Claude를 한 번 켜고 자리를 비워라"라는 한 문장으로 요약됩니다. 매 턴마다 사람이 다음 단계를 일러주는 대신, 완료 조건을 한 번 적고 떠나는 패턴입니다.

다만 evaluator의 transcript-only 제약을 이해하지 못한 채로 모호한 조건을 적으면 goal이 영영 끝나지 않을 수 있습니다. 완료 조건을 "Claude가 무엇을 출력해야 evaluator가 yes를 낼 수 있는가"의 관점에서 설계하는 습관이 핵심입니다.

작은 작업부터 시작해서 패턴을 익히고, 점차 PRD 구현이나 대규모 리팩토링 같은 장기 작업으로 확장해 보시기 바랍니다.

참고 자료