Codex가 2026년 4월에 /goal을 출시한 이후, Anthropic도 5월 Claude Code 2.1.139 업데이트를 통해 동일한 이름의 명령어를 선보였습니다. 이는 Claude가 「목표를 달성할 때까지 멈추지 않는」 새로운 워크플로우입니다. 대화 중에 완료 조건을 작성하기만 하면, Claude는 매 라운드가 끝날 때마다 소형 고속 모델을 자동으로 호출하여 목표 달성 여부를 판단합니다. 목표가 달성되지 않으면 다음 라운드를 계속 진행하고, 조건이 충족되면 비로소 제어권을 사용자에게 반환합니다.
이 글에서는 Claude Code goal 모드의 6가지 핵심 포인트를 체계적으로 설명합니다. 평가기 루프 작동 메커니즘, /loop 및 Stop hook과의 차이점, 효과적인 조건 작성법, 3가지 모드(interactive / -p / Remote Control), 그리고 리스크와 모범 사례까지 모두 다룹니다.
핵심 가치: 이 글을 읽고 나면 10분 안에 팀의 코드 마이그레이션, 이슈 정리, 문서 검수 등 장기적인 작업을 Claude Code goal 모드에 맡겨 자동화할 수 있게 되며, 어떤 상황에서 다른 자율 워크플로우를 사용해야 할지 명확히 알게 될 것입니다.
Claude Code goal 모드 핵심 포인트
본격적으로 시작하기 전에, Claude Code goal 모드의 6가지 핵심 사실을 먼저 짚고 넘어가죠. 이 6가지 포인트는 여러분이 작성하는 조건이 제대로 실행될지, 그리고 다른 자율 워크플로우 대신 /goal을 선택하는 것이 맞는지 결정하는 기준이 됩니다.
| 포인트 | 내용 | 영향 |
|---|---|---|
| 명령어 형식 | /goal <condition> |
대화 중 직접 설정, 설정 파일 불필요 |
| 평가기 | 기본 Haiku 소형 고속 모델 | '다른 모델'이 완성도를 판단하며, 작업 모델과 독립적 |
| 범위 | 현재 세션 (session-scoped) | 다른 세션에 영향을 주지 않으며, 임시 작업에 적합 |
| 트리거 주기 | 매 라운드 종료 후 즉시 평가 | 완료 시 종료, 미완료 시 새 라운드 시작 |
| 조건 제한 | 최대 4000자 | 상세한 검수 기준 포함 가능 |
| 종료 방식 | 평가 통과 / /goal clear / Ctrl+C |
3가지 종료 경로, 능동 + 수동 결합 |
많은 사용자가 처음 /goal을 접하면 일반적인 루프 명령어를 떠올리지만, 본질적으로는 Anthropic이 prompt-based Stop hook을 세션 단위의 단축 명령어로 캡슐화한 것입니다. 이러한 근본적인 설계 덕분에 기존의 cron 스타일 자동화와는 확연히 다른 차이를 보입니다.
만약 팀에서 아직 Claude Code의 고급 Hook 메커니즘을 사용해 본 적이 없다면, 먼저 APIYI(apiyi.com) 플랫폼을 통해 Claude Sonnet / Opus / Haiku API를 경험하며 Anthropic의 툴체인 생태계에 익숙해진 뒤, Claude Code의 goal 모드로 업그레이드하는 것을 추천합니다. 훨씬 수월하게 활용하실 수 있을 거예요.
Claude Code goal 모드 작동 원리 상세 분석
/goal을 제대로 활용하려면 각 라운드마다 어떤 일이 일어나는지 정확히 이해해야 합니다. 공식 문서에서는 이 메커니즘을 "각 라운드 종료 후 평가기(Evaluator)를 추가하는 방식"이라고 간단히 설명하지만, 세부적인 동작 방식이 실제 성능의 한계를 결정합니다.
대규모 언어 모델(메인 모델)은 작업을 수행하고, 작고 빠른 모델은 완료 여부를 판단합니다. 모델을 분리하면 평가자가 중립을 유지하고 더 저렴한 비용으로 의사결정을 내릴 수 있다는 장점이 있습니다. 반면, 평가기는 대화 내용만 볼 수 있어 파일 시스템이나 외부 명령어의 실제 상태를 직접 확인하지 못한다는 단점이 있습니다.
매 라운드 종료 후의 판단 과정은 4단계로 나뉩니다:
- 컨텍스트 패키징: 현재 상태와 전체 대화 기록을 평가기로 전송합니다.
- 모델 의사결정: 평가기가 yes/no 결과와 그 이유(reason)를 반환합니다.
- 라우팅 분기: 'no'인 경우 이유를 가이드 삼아 메인 모델이 작업을 계속하고, 'yes'인 경우 목표를 자동으로 지우고 '달성됨(achieved)'으로 표시합니다.
- 지표 새로고침: UI의
◎ /goal active영역에 경과 시간, 턴 수, 토큰 사용량이 표시됩니다.
조건을 설정할 때는 1단계의 제약을 반드시 기억하세요. 평가기는 대화 기록만 확인하므로, 조건은 "메인 모델이 대화 내에서 증명할 수 있는 것"이어야 합니다. 예를 들어 "npm test 종료 코드가 0"은 좋은 조건입니다. 메인 모델이 테스트를 실행하고 결과를 대화창에 붙여넣기 때문이죠. 반면 "운영 환경 데이터베이스에 더러운 데이터가 없음"은 대화 기록만으로 검증할 수 없으므로 나쁜 조건입니다.
평가기 비용은 보통 무시할 수 있는 수준입니다. Haiku 모델은 Sonnet/Opus보다 훨씬 저렴하며, 매 라운드 대화 요약만 평가하므로 전체 세션에서도 토큰 소모가 적습니다. 평가기 비용을 더 낮추고 싶다면 APIYI(apiyi.com)를 통해 Claude Code의 소형 모델을 Haiku 4.5나 3.5로 연결하고 워크스페이스별로 할당량을 제어할 수 있습니다.
Claude Code goal 모드와 다른 자율 워크플로우 비교
Claude Code는 대화를 자동으로 이어가는 4가지 메커니즘을 제공합니다. 초보자는 이들을 혼동하기 쉬운데, 아래 표를 통해 트리거 조건, 중단 조건, 적합한 시나리오를 비교해 보세요.
| 메커니즘 | 트리거 주기 | 중단 조건 | 적합한 시나리오 |
|---|---|---|---|
/goal |
라운드 종료 즉시 | 평가기 조건 달성 | 명확한 검수 기준이 있는 긴 작업 |
/loop |
고정 시간 간격 | 사용자 수동 또는 Claude 판단 | 주기적 폴링, 상태 확인 |
| Stop hook | 라운드 종료 즉시 | 사용자 스크립트 또는 프롬프트 | 팀 단위, 세션 간 적용 |
| Auto mode | 라운드 내 도구 호출 | 도구 시퀀스 종료 시 | 도구 호출 시마다 확인창 생략 |
핵심은 /goal과 Stop hook이 거의 같은 일을 하지만, /goal은 현재 세션에만 적용되며 터미널에서 즉시 입력 가능하다는 점입니다. 반면 Stop hook은 설정 파일에 작성하며 해당 범위의 모든 세션에 적용되므로 팀 단위의 엄격한 제약에 더 적합합니다.
Auto mode와 /goal은 상호 보완적입니다. Auto mode는 "라운드 내 도구 확인창" 문제를 해결하고, /goal은 "여러 라운드에 걸친 작업"을 해결합니다. 긴 작업에서 이 두 메커니즘을 함께 사용하면 거의 무인 자동화가 가능합니다. Claude Code를 직접 환경에 구축하기 전이라면, APIYI(apiyi.com)를 통해 Claude를 로컬 스크립트에 연결하여 동일한 루프 로직을 테스트해 본 뒤 전체 도구 도입을 결정하는 것을 추천합니다.
Claude Code goal 모드의 성공을 위한 3가지 핵심 요소
조건을 제대로 설정하지 못하는 것이야말로 /goal 기능이 실패하는 주된 원인입니다. Anthropic 공식 문서에 따르면, 수십 번의 루프를 안정적으로 견뎌낼 수 있는 좋은 조건은 반드시 다음 3가지 요소를 갖춰야 합니다.
첫째, 측정 가능한 종료 지점입니다. 종료 지점은 테스트 종료 코드, 파일 개수, 큐에 남은 항목 수, 빌드 성공 여부와 같이 이산적이고 관찰 가능한 사건이어야 합니다. 모호한 지표를 사용하면 평가기가 '예/아니오' 사이에서 갈팡질팡하며 /goal이 무한 루프에 빠질 수 있습니다.
둘째, 명확한 검증 방식입니다. 조건 내에 Claude가 목표 달성 여부를 어떻게 증명할지 구체적으로 명시해야 합니다. 예를 들어 "npm test 출력에 PASS 포함", "git status 결과가 비어 있음"과 같이 작성하세요. 검증 방식이 구체적일수록 평가기가 모호한 표현에 속지 않습니다.
셋째, 변경 불가능한 제약 조건입니다. 특정 파일이나 설정이 절대 바뀌어서는 안 된다면 조건에 직접 명시하세요. 예를 들어 " tests/legacy/ 하위 파일은 절대 수정하지 말 것"처럼요. 이렇게 하면 모델이 목표 달성을 위해 무리하게 코드를 수정하는 부작용을 막을 수 있습니다.
이 3가지 요소를 조합하면 다음과 같은 고품질의 /goal 조건이 완성됩니다: "tests/auth 하위의 모든 테스트 통과 및 npm run lint 종료 코드 0 확인, tests/legacy/ 파일은 수정 금지, 최대 20회 실행". 마지막의 "최대 20회 실행"은 극한 상황에서 /goal이 무한 루프에 빠지는 것을 방지하는 안전장치입니다.
조건은 최대 4,000자까지 지원하므로 미니 PRD(제품 요구사항 문서)를 통째로 넣어도 충분합니다. APIYI(apiyi.com) 플랫폼을 통해 Claude 모델을 호출하여 에이전트를 운영 중이라면, 이 방식을 참고해 자체 평가기 프롬프트를 설계해 보세요. 에이전트의 중단 조건을 훨씬 명확하고 측정 가능하게 만들 수 있습니다.
Claude Code goal 모드의 3가지 실전 운영 방식
/goal은 대화형(interactive), 비대화형(-p), 원격 제어(Remote Control) 세 가지 호출 방식을 모두 지원합니다. 이 세 가지를 숙달해야 CI, 로컬 스크립트, 원격 협업 워크플로우에 제대로 적용할 수 있습니다.
대화형 모드 시작하기
# Claude Code 세션에서 직접 입력
/goal all tests in test/auth pass and the lint step is clean, or stop after 20 turns
설정 후 UI에 ◎ /goal active 표시기가 나타나며 elapsed(경과 시간), turns(회차), tokens(토큰) 세 가지 지표가 실시간으로 표시됩니다. 언제든 /goal을 인자 없이 입력하면 상태를 확인할 수 있고, /goal clear(또는 stop, off, reset, none, cancel)를 입력하면 즉시 종료할 수 있습니다.
비대화형 모드 (CI 환경용)
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week, or stop after 15 turns"
-p 모드는 조건이 충족되거나 사용자가 Ctrl+C로 중단할 때까지 /goal을 계속 실행합니다. GitHub Actions, GitLab CI, Jenkins 파이프라인 등 자동화 프로세스에 넣기 딱 좋습니다. APIYI(apiyi.com)를 통해 Claude API를 통합 관리하고 있다면, 이 루프 패턴을 자체 스크립트로 캡슐화하여 Claude Code 클라이언트가 아닌 환경에서도 동일한 기능을 구현할 수 있습니다.
세션 복구
claude --resume <session-id>
# 또는
claude --continue
세션을 복구하면 활성화된 goal 상태도 함께 불러옵니다. 다만 turns / timer / token 카운트는 0부터 다시 시작됩니다. 이 기능은 장기 리팩토링 작업에 매우 유용합니다. 주말에 퇴근할 때 중단 걱정 없이 끄고, 월요일에 바로 이어서 작업하세요.
자주 사용하는 목표 조건 템플릿 보기 (클릭)
# 템플릿 1: 코드 마이그레이션
/goal migrate all usages of legacy_api.* to new_api.* in src/, run npm test until exit 0, do not modify tests/legacy/, or stop after 30 turns
# 템플릿 2: Issue 백로그 정리
/goal close all GitHub issues labeled "needs-triage" by either resolving or relabeling, run gh issue list --label needs-triage and verify the output is empty, or stop after 25 turns
# 템플릿 3: 설계 문서 검수
/goal implement every acceptance criterion in docs/design.md, prove each by referencing the exact section, do not edit docs/design.md itself, or stop after 40 turns
# 템플릿 4: 파일 분할
/goal split src/megafile.ts into modules under src/parts/ where each file is < 300 lines, run npm run typecheck until exit 0, or stop after 20 turns
Claude Code goal 모드 위험 요소 및 모범 사례
/goal 모드는 의사결정 권한을 모델에게 위임하기 때문에 기존 명령과는 완전히 다른 위험 요소가 존재합니다. 아래 표는 현재 가장 주의해야 할 4가지 위험 요소와 그에 따른 완화 조치를 정리한 것입니다.
| 위험 | 트리거 조건 | 완화 조치 |
|---|---|---|
| 비용 통제 불가 | 평가기의 오판 또는 조건이 너무 느슨함 | 조건에 'or stop after N turns' 상한 추가 |
| 평가기 환각 | 조건이 전사(transcription)로 검증 불가 | 'X 명령을 실행하여 Y 출력을 검증하라'는 식의 관찰 가능한 문구 사용 |
| 파괴적 변경 | 주 모델이 목표 달성을 위해 수정해서는 안 될 파일 수정 | 조건에 'do not modify …' 제약 추가 |
| 워크스페이스 오용 | 신뢰할 수 없는 환경에서 의도치 않게 트리거 | 신뢰 대화 상자(trust dialog) 수락 필수; disableAllHooks로 즉시 비활성화 가능 |
첫 번째 위험이 가장 직접적입니다. Codex와 Claude Code 모두 현재 '목표별 지출 상한'을 설정하는 공식 기능이 없으므로, 긴 작업이 통제 불능 상태가 되면 예상보다 훨씬 많은 토큰이 소모될 수 있습니다. 가장 안전한 방법은 턴(turns) 상한을 조건에 직접 명시하고, 플랫폼 차원의 예산 알림을 병행하는 것입니다.
평가기를 위해 안정적인 소형 모델을 준비하는 것도 매우 중요합니다. 만약 가벼운 모델로 Haiku를 사용한다면 평가 속도와 비용을 효과적으로 제어할 수 있지만, Sonnet과 같은 대형 모델을 사용하면 /goal 평가 비용이 크게 증가합니다. 개발팀은 APIYI(apiyi.com) 플랫폼을 통해 Haiku 전용 base_url과 할당량을 설정하여 평가기와 주 모델의 비용을 분리해 모니터링할 수 있습니다.
마지막으로 규정 준수 사항입니다. /goal은 Anthropic의 Hook 시스템에 의존하므로 워크스페이스가 신뢰 대화 상자를 수락한 상태여야 하며, disableAllHooks 또는 allowManagedHooksOnly가 설정되어 있지 않아야 합니다. 팀 차원에서 관리 정책으로 Hook을 차단했다면 /goal 역시 함께 비활성화되며, 명령 실행 시 조용히 실패하는 대신 이유를 알려줍니다.
자주 묻는 질문(FAQ)
Q1: /goal과 직접 작성한 while 루프 스크립트의 차이점은 무엇인가요?
모델 기반의 독립적인 평가기가 추가된다는 점입니다. 직접 작성한 while 루프는 사용자가 직접 정지 조건을 정의하고 코드로 판별해야 하지만, /goal은 소형 모델에 판별을 맡겨 '모델이 대화를 읽고 완료 여부를 판단하게 하는' 식의 비프로그래밍적 시나리오도 처리할 수 있습니다.
Q2: /goal을 사용하면 토큰이 너무 많이 소모되지 않나요?
위험은 존재하지만 통제 가능합니다. 두 가지 제안을 드립니다. 첫째, 조건에 턴(turns) 상한을 강제로 명시하고, 둘째, 평가기를 Haiku와 같은 소형 모델로 고정하세요. APIYI(apiyi.com)를 통해 Claude API를 연동할 때 평가기 전용 할당량을 별도로 신청하면 세밀한 모니터링이 가능합니다.
Q3: /goal과 /loop 중 무엇을 선택해야 하나요?
작업에 명확한 '완료 상태'가 있다면 /goal을, 주기적인 상태 확인(예: 10분마다 배포 진행 상황 확인)이 필요하다면 /loop를 선택하세요. 두 기능은 근본적인 메커니즘이 다르므로 혼용하면 정지 조건이 모호해질 수 있습니다.
Q4: 국내에서도 Claude Code의 /goal 모드를 사용할 수 있나요?
네, 가능합니다. /goal은 Claude Code 클라이언트 명령이므로 클라이언트가 Anthropic 모델에 연결만 되면 됩니다. 개발자들은 보통 APIYI(apiyi.com)와 같은 API 중계 서비스를 통해 Claude API를 연동하며, 환경 설정이 완료되면 해외 사용자와 동일하게 /goal을 사용할 수 있습니다.
Q5: Codex /goal과 Claude Code /goal 중 무엇이 더 나은가요?
두 기능이 지향하는 워크플로우가 다릅니다. Codex /goal은 '지속적인 워크플로우'를 강조하며 프로세스 간 재시작이 가능합니다. Claude Code /goal은 세션 단위로 작동하며 --resume 옵션을 통해 일 단위 복구가 가능합니다. 복잡한 장기 작업에는 Codex를, 일반적인 1~2일 단위의 반복 작업에는 Claude Code를 사용하는 것이 더 효율적입니다.
요약
Claude Code의 goal 모드는 Anthropic이 기존 Hook 설정 파일에 묶여 있던 '평가자 루프(Evaluator Loop)'를 분리하여, 어떤 세션에서든 즉시 사용할 수 있는 한 줄의 명령어로 만든 것입니다. 이 기능이 해결하는 핵심 문제는, 여러 번의 턴이 필요한 복잡한 작업을 수행할 때 사용자가 매번 터미널 앞에서 엔터키를 누를 필요 없이, 소형 고속 모델을 '판관'으로 세워 Claude가 언제 작업을 완료했는지 스스로 판단하게 하는 것입니다.
실무 적용을 위한 3단계 제안은 다음과 같습니다. 먼저 '종료 조건 + 검증 + 제약 사항 + 턴 제한'이라는 4가지 요소를 완벽하게 작성하고, 상황에 맞춰 interactive, -p, 또는 Remote Control 모드 중 하나를 선택하세요. 마지막으로 APIYI(apiyi.com)와 같은 플랫폼을 활용해 평가자 모델의 할당량과 메인 모델의 사용량을 분리하여 모니터링하세요. 이렇게 하면 자율 워크플로우의 효율성을 챙기면서도 토큰 비용을 효과적으로 제어할 수 있습니다.
저자: APIYI 기술팀
문의: APIYI(apiyi.com)를 통해 Claude 전체 모델 및 Claude Code 연동 지원을 받아보세요.
업데이트 시간: 2026-05-13
