Claude Code /goal 명령어 완전 분석: 2026년 가장 과소평가된 AI 기능

"이거 다 끝내라"고 말하고 자러 갔어요. 아침에 일어났더니 테스트 14개 다 통과. 커밋 정리. 배포까지 끝나 있더라고요. 근데 다음 날엔 토큰이 폭주했습니다.

Claude Code 의 /goal 명령어는 강력함과 위험함이 공존하는 자율 실행 기능입니다. 2026-05-11 Anthropic 공식 출시 이후 커뮤니티에서 "2026년 가장 과소평가된 AI 기능"이라 불리고 있지만, 잘못 쓰면 토큰을 폭주시키는 부비트랩이기도 합니다.

본 글은 /goal 의 출시 배경, 작동 메커니즘, 6가지 활용 패턴, 실제 사고 사례, 그리고 4대 사용 규칙까지 docs.anthropic.com 1차 출처를 교차검증해 정리한 완전 가이드입니다.

1. 출시 배경 — 커뮤니티 흡수 패턴의 전형

/goal 의 역사는 흥미롭습니다. Anthropic 이 처음 만든 기능이 아니에요.

2026-04-30: OpenAI Codex CLI v0.128.0 이 /goal 명령어를 먼저 출시 (OpenAI Codex changelog, 접속 2026-05-27). 조건을 걸어두면 AI 가 알아서 끝까지 실행한다는 아이디어가 처음 세상에 등장한 시점입니다.

그러자 Claude Code 커뮤니티에서 반응이 왔습니다. "우리도 이거 넣어주세요." 라는 요청이 쏟아졌고, 한 개발자가 claude-goal 이라는 프로젝트를 직접 만들었습니다. Claude Code 의 Stop hook 시스템을 활용해 Codex 스타일의 /goal 을 자체 구현한 것이죠.

2026-05-11 ~ 05-15 (Week 20): Anthropic 이 /goal 을 공식 기능으로 흡수 (Anthropic Week 20 release notes, 접속 2026-05-27).

Codex 출시 11일 후의 follow. 전형적인 오픈소스 흡수 패턴입니다. 커뮤니티가 먼저 만들고 회사가 공식 채택한 케이스.

Codex 와 Claude Code 의 /goal 가장 큰 차이는 실행 환경입니다.

• Codex /goal: 클라우드 샌드박스에서 실행
• Claude Code /goal: 로컬 컴퓨터에서 실행

로컬이라서 기존 프로젝트 환경 변수, 테스트 환경을 그대로 활용할 수 있다는 게 장점입니다.

2. 작동 메커니즘 — 분리된 평가자가 핵심

/goal 의 진짜 강력함은 평가자 분리에 있습니다.

Anthropic 공식 docs (code.claude.com/docs/en/goal, 접속 2026-05-27)의 인용:

"The '/goal' command functions as a wrapper around a session-scoped prompt-based Stop hook. After each turn, the goal condition and conversation are sent to a configured small, fast model (defaulting to Haiku) for a yes-or-no decision and a reason."

작동 흐름:

1. 사용자가 /goal "테스트 다 통과할 때까지" 입력
2. Claude 가 코드를 읽고 테스트를 돌리고 수정 작업 진행
3. 매 턴 종료 시 Haiku 모델이 별도로 conversation 을 받아 yes/no 판정
4. "yes" 면 자동 종료, "no" 면 다음 턴 자동 실행

여기서 중요한 건 평가자 분리 입니다. Claude 가 자기 평가하면 self-assessment bias 가 생깁니다. 자기가 잘했다고 착각하게 되죠. Haiku 라는 별도 모델이 평가하면 객관성이 살아납니다.

또 다른 이점은 비용 효율. Haiku 가 작업 모델보다 훨씬 저렴해서 평가 비용이 메인 작업 대비 미미합니다.

3. /goal vs /loop — 마라톤과 러닝머신

/goal 과 비슷해 보이는 명령어로 /loop 가 있습니다. 둘은 완전히 다른 도구예요.

/goal 은 결승선이 있는 마라톤. /loop 는 정해진 시간 동안 반복하는 러닝머신.

명확한 종료 조건이 있으면 /goal. 주기적 모니터링이 필요하면 /loop. 이 둘을 헷갈리면 안 됩니다.

4. 6가지 활용 패턴

영상 사용자(정상록, 시스템을 만드는 남자)의 실무 사례 기준 6가지 패턴입니다.

4-1. 테스트 전부 통과

/goal Run pytest tests/ until exit code 0. Stop after 20 turns.

가장 기본적인 패턴. Claude 가 알아서 테스트를 만들고 돌리고 고치고 반복합니다.

4-2. API 마이그레이션

v1 에서 v2 로 바뀌어야 할 파일이 수십 개. 하나씩 바꾸고 타입 체크하고 테스트 돌리는 작업이 자동화됩니다.

4-3. DESIGN.md 구현

디자인 문서를 만들 때 조건으로 넣어 구현 완료까지 자동.

4-4. 대형 파일 분할

모노리스 파일 하나를 200줄 이하 모듈로 쪼개면서 import 가 정상인지 확인.

4-5. CI 연동 (가장 강력)

claude --headless --goal "Upgrade deprecated dependencies, run npm test. All tests must pass. Stop after 30 turns."

비대화 모드 + cron 으로 야간 자동 실행. Make.com / n8n 같은 자동화 프로세스를 Claude Code 만으로 만들 수 있습니다.

4-6. GitHub 이슈 백로그

다수 이슈를 한 번에 자동 해결. --auto 모드까지 켜면 도구 호출도 자동 승인되어 완전 자율 에이전트가 됩니다.

5. 실제 사고 사례 — "후속 작업 모두 직접 진행하라"

영상 사용자가 실제로 경험한 사고. 시스템 글로벌 룰에도 2026-05-22 일자로 기록된 실제 사례입니다.

사고 흐름

1. 사용자 입력: /goal "후속 작업 모두 직접 진행하라"
2. 8개 항목 중 6개가 Claude 권한 밖
   • 시크릿 추출 (Supabase Service Role Key / Paddle / Stripe / OpenAI / Upstash)
   • 결제 웹훅 Phase 8
   • Plan Stop Condition S1 (사용자 명시 승인)
3. Haiku 평가자가 매 응답마다 "Goal not yet met... continuing" 판정
4. 무한 cycle 진입 — 9회 반복 후 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP (default 8) 도달
5. 강제 종료. 그 사이 토큰 폭주
6. 구독 요금이라 다행이었지만 API 호출이었다면 $100+ 손실

근본 원인 4중 결함

6. 4대 사용 규칙

사고 학습 결과 도출된 4대 규칙입니다.

의무 1 — Universal Quantifier 금지

다음 단어는 시스템 제약을 무시하는 표현입니다.

의무 2 — Claude 권한 밖 조건 금지

다음 영역은 condition 에 포함되면 영원히 충족 불가:

• 시크릿 추출 (API 키 / 토큰 / 패스워드)
• 외부 계정 의존 (Paddle / Stripe / OpenAI 신규 키 발급)
• 사용자 명시 승인 Stop Condition (배포 / 계약 / 송금)
• 법적 책임 사안
• 재화 / 돈 이동

의무 3 — 측정 가능한 종료 조건

condition 은 binary 평가가 가능해야 합니다.

❌ 나쁜 예: "완벽하게 처리해줘"
   → "완벽" 의 기준이 LLM 평가마다 달라짐 → 영원히 미충족

✅ 좋은 예: "Plan Phase 1-10 (Claude 실행 가능 범위) 완료 또는 Plan STATUS COMPLETED 마킹"
   → 명확한 종료 시점

✅ 좋은 예: "pytest tests/auth.py 종료 코드 0"
   → yes/no 답이 결정론적

의무 4 — 턴 제한 안전장치

공식 docs 의 권장 팁:

조건 끝에 "stop after 20 turns" 같은 문구를 추가하면 무한 루프를 방지할 수 있습니다.

CLAUDE_CODE_STOP_HOOK_BLOCK_CAP 환경변수 (default = 8) 가 추가 안전장치로 작동하지만, condition 자체에 명시적 턴 제한이 더 깔끔합니다.

7. 좋은 조건 vs 나쁜 조건 패턴 모음

실전에서 자주 마주치는 사례별 패턴.

패턴: 좋은 조건은 숫자 또는 종료 코드. yes/no 로 답이 나오는 것.

8. 정리 — /goal 의 핵심 한 줄

• 2026-05-11 출시, 4,000자 condition (공식 미확인이지만 영상 주장)
• 세션당 활성 goal 1개 만 가능 (If a goal is already active, the new one replaces it)
• 평가자: Haiku default, 매 턴 yes/no
• 별칭 6종: clear, stop, off, reset, none, cancel
• 세션 끊김 시: --resume 또는 --continue 로 미완료 goal 자동 복원
• /clear 주의: 대화와 함께 goal 도 사라짐. goal 만 유지하려면 절대 사용 금지

대부분 사용자가 Claude Code 를 턴식 대화 도구로만 쓰고 있습니다. 하지만 /goal 에 워크플로 / 에이전트 / 스킬 / 하네스 엔지니어링을 얹으면 차원이 달라집니다. 자율 에이전트가 됩니다.

잘 쓰면 밤새 코딩하는 AI 비서. 못 쓰면 토큰 먹는 하마.

핵심 한 줄: 측정 가능한 종료 조건이 가장 중요합니다.

영상 풀버전 보기

본 글은 영상의 핵심 내용을 글로 재구성한 것입니다. 실제 명령어 시연 화면, 사고 발생 시점의 토큰 폭주 모습, 그리고 추가 활용 패턴은 영상 풀버전에서 확인하실 수 있습니다.

유튜브 풀버전: https://youtu.be/DjNPsYn0Rwg

자율 에이전트 시스템 / 하네스 엔지니어링에 관심 있으시면 댓글에 "AI 에이전트" 남겨주세요. 자료 보내드립니다.

참고자료

© 2026 퀀텀점프클럽 정상록. 본 글은 AI 보조 작성으로 정리된 정보입니다. 최종 명령어 사용 시 docs.anthropic.com 공식 문서를 함께 확인해 주세요.