Claude Code 사용자라면 한 번쯤 이런 순간을 만납니다. “테스트 다 통과시킬 때까지 그냥 알아서 해줬으면 좋겠는데” 같은 작업. 한 턴에 끝낼 수 없고, 그렇다고 매 턴 직접 다음 단계를 지시하기엔 번거로운 일들. Anthropic이 이 갭을 정확히 메우는 명령어를 추가했습니다. 바로 /goal 슬래시 커맨드입니다.
/goal은 완료 조건을 한 줄로 정의하고, 그 조건이 만족될 때까지 Claude가 자동으로 다음 턴을 이어 가도록 만드는 명령입니다. 매 턴이 끝나면 별도의 빠른 모델이 조건 충족 여부를 판정하고, 충족되면 자동으로 종료합니다.
핵심 요약
/goal은 Claude Code 슬래시 커맨드로, 완료 조건을 설정하면 그 조건이 충족될 때까지 매 턴 자동으로 다음 턴을 이어 갑니다.- 매 턴 종료 후 작은 빠른 모델(기본 Haiku)이 yes/no를 판정합니다. yes면 goal이 자동 클리어되고, no면 이유와 함께 다음 턴이 시작됩니다.
/loop(시간 간격 기반), Stop hook(설정 파일 기반), auto mode(턴 내 도구 자동 승인)와는 종료 트리거가 다릅니다.- 좋은 조건은 측정 가능한 end state, 증명 방법, 변경 금지 제약을 모두 포함합니다. 조건은 최대 4,000자.
- 비대화형으로
claude -p "/goal ..."형태로 실행할 수 있어 CI 파이프라인에도 붙일 수 있습니다.
/goal이 정확히 무엇을 하는가
세션마다 하나의 active goal을 유지할 수 있습니다. /goal 뒤에 조건 문장을 적으면 그 조건이 곧장 첫 턴의 지시문이 되어 작업이 시작됩니다. 별도 프롬프트를 추가로 보낼 필요가 없습니다. 화면에는 ◎ /goal active 인디케이터가 떠 있어 경과 시간을 보여 줍니다.
문서가 제시하는 대표적인 사용 시나리오는 다음과 같습니다.
- 한 모듈을 새 API로 마이그레이션 — 모든 호출 지점이 컴파일되고 테스트가 통과할 때까지
- 디자인 문서 구현 — 모든 수용 기준이 충족될 때까지
- 큰 파일을 작은 모듈로 분할 — 각 모듈이 사이즈 예산을 넘지 않을 때까지
- 라벨 붙은 이슈 백로그 처리 — 큐가 비워질 때까지
공통점이 보입니다. “끝났는지 객관적으로 측정할 수 있는 작업” 이라는 점입니다. 이 객관성이 /goal의 핵심입니다. 평가자 모델이 자기 마음대로 판단하는 게 아니라 Claude가 출력한 결과를 보고 조건을 체크하기 때문입니다.
다른 자동화 방식과의 비교
Claude Code에는 이미 비슷한 흐름을 만드는 도구가 몇 개 있습니다. 차이를 표로 정리하면 다음과 같습니다.
| 방식 | 다음 턴 시작 트리거 | 종료 트리거 |
|---|---|---|
/goal | 이전 턴이 끝나면 | 모델이 조건 충족을 확인하면 |
/loop | 시간 간격이 경과하면 | 사용자가 멈추거나, Claude가 끝났다고 판단하면 |
| Stop hook | 이전 턴이 끝나면 | 사용자가 작성한 스크립트나 프롬프트가 결정 |
/goal과 Stop hook은 둘 다 매 턴 종료 시 평가가 발동된다는 점에서 닮았습니다. 차이는 수명입니다. /goal은 세션 범위의 단축 명령으로, 입력한 그 자리에서 활성화되고 세션이 끝나거나 조건이 충족되면 사라집니다. Stop hook은 설정 파일에 들어가 있어 해당 스코프의 모든 세션에 영구 적용됩니다.
Auto mode와도 헷갈리기 쉽습니다. Auto mode는 단일 턴 안에서 도구 호출을 자동 승인하는 모드입니다. 다음 턴을 시작하지는 않습니다. /goal은 정반대로 한 턴이 끝난 뒤 다음 턴을 자동으로 시작하는 역할입니다. 그래서 둘은 충돌하지 않고 보완적입니다. Auto mode가 턴 내부의 마찰을 없애고, /goal이 턴 사이의 마찰을 없앱니다. 둘을 함께 쓰면 사람 개입을 최소화한 자율 모드가 완성됩니다.
좋은 완료 조건은 어떻게 쓰는가
/goal의 성패는 조건 문장에 달려 있습니다. 평가자 모델이 도구를 실행하거나 파일을 직접 읽지 않기 때문에, Claude의 출력만으로 증명할 수 있는 조건을 써야 합니다.
문서는 좋은 조건의 세 가지 요소를 제시합니다.
- 측정 가능한 end state. 테스트 결과, 빌드 exit code, 파일 개수, 큐가 비었는지 같은 객관적 신호.
- 명시된 증명 방법. “
npm test가 exit 0을 반환한다”, “git status가 깨끗하다” 같은 검증 절차. - 꼭 지켜야 할 제약. “다른 테스트 파일은 수정되지 않는다” 같은 가드레일.
조건은 최대 4,000자까지 쓸 수 있습니다. 길게 쓸 수 있지만 너무 모호하게 풀어 쓰면 평가자가 yes 판정을 내리지 못해 goal이 영원히 끝나지 않습니다. “사용자가 만족할 만큼 깔끔하게 정리한다” 같은 주관적 조건이 가장 위험합니다.
또 하나 중요한 팁이 있습니다. 턴이나 시간 절을 함께 넣어 폭주를 막는 것입니다.
모든 test/auth 테스트가 통과하고 lint가 깨끗할 것.
또는 20턴이 지나면 멈춘다.
이렇게 쓰면 매 턴 Claude가 진행 상황을 보고하고, 평가자는 그 진행 상황을 보고 종료 여부를 판단합니다. 무한 루프 방지장치이자 작업 시간 통제 장치 역할을 동시에 합니다.
동작 원리: 평가자 모델
내부 구조는 단순합니다. /goal은 세션 범위의 prompt-based Stop hook의 wrapper입니다. 매 턴이 끝나면 다음 단계가 자동으로 발동합니다.
- 사용자가 설정해 둔 small fast model(기본 Haiku)이 평가자로 호출됩니다.
- 조건 문장과 지금까지의 대화 전체를 평가자에 전달합니다.
- 평가자가 yes 또는 no를 판정하고 짧은 reason을 함께 반환합니다.
- no면 다음 턴을 시작하면서 reason을 다음 턴의 가이드로 전달합니다.
- yes면 goal을 클리어하고 transcript에 달성 엔트리를 남깁니다.
이 흐름이 의미하는 바는 명확합니다. 평가자는 외부 시스템에 접근할 수 없고, 오직 대화에 surface된 정보만으로 판단합니다. 그래서 “테스트를 돌렸다고 평가자가 알 수 있는 유일한 방법"은 Claude가 실제로 테스트를 돌리고 그 결과를 대화에 출력하는 것입니다.
토큰 비용은 평가자 모델이 빠른 작은 모델이라 메인 턴 비용 대비 거의 무시할 수 있는 수준입니다. 비용 걱정 없이 매 턴 평가를 돌릴 수 있다는 뜻입니다.
상태 확인, 중단, 재개
운영에 필요한 보조 명령들도 같이 정리되어 있습니다.
/goal(인자 없이) — 현재 상태 표시. 조건, 경과 시간, 평가된 턴 수, 토큰 spend, 마지막 reason을 보여 줍니다./goal clear— 미달성 상태에서 강제 종료.stop,off,reset,none,cancel도 alias로 받습니다./clear— 새 대화 시작. active goal도 함께 제거됩니다.--resume또는--continue— 세션 재개 시 active goal이 복원됩니다. 단 턴 카운트, 타이머, 토큰 spend는 리셋됩니다.
비대화형 모드 지원도 의미가 큽니다. claude -p "/goal ..." 형태로 실행하면 한 번의 호출로 조건이 충족될 때까지 루프가 돌아갑니다. CI 파이프라인이나 야간 자동화 작업에 그대로 끼워 넣을 수 있습니다. Ctrl+C로 중단도 가능합니다.
사용 시 요구사항과 한계
/goal은 trust dialog를 승인한 workspace에서만 동작합니다. 평가자가 hooks 시스템의 일부이기 때문입니다. 또 disableAllHooks가 켜져 있거나 managed settings에서 allowManagedHooksOnly가 켜져 있으면 사용할 수 없습니다. 두 경우 모두 명령을 입력하면 이유를 알려 주기 때문에 조용히 실패하지는 않습니다.
가장 현실적인 한계는 앞서 언급한 평가자의 정보 접근 제한입니다. 외부 시스템 상태를 봐야 종료를 판정할 수 있는 작업이라면, 그 상태를 Claude가 자기 출력으로 한 번 더 풀어 줘야 합니다. 그게 안 되는 작업은 /loop이나 직접 작성한 Stop hook을 쓰는 편이 낫습니다.
실무자가 볼 핵심 포인트
/goal이 잘 맞는 작업: 끝났는지 객관적으로 측정 가능한 다단계 작업. 테스트 그린, 빌드 통과, 큐 정리, 마이그레이션 완료 같은 케이스.- **조건 작성이 자동화의 90%**다. 평가자가 Claude의 출력만 보고 판단하므로, 조건은 Claude가 자기 출력으로 증명할 수 있도록 구체적으로 적어야 한다.
- 항상 turn/time cap을 넣어라. “or stop after 20 turns” 같은 절을 추가해 폭주를 막는 게 디폴트가 되어야 한다.
- Auto mode와 함께 쓰면 시너지가 크다. Auto mode는 턴 내 도구 마찰을 없애고,
/goal은 턴 간 마찰을 없앤다. 둘 다 켜면 사람 개입을 최소화한 자율 실행 환경이 만들어진다. - CI 통합도 가능.
claude -p "/goal ..."형태로 비대화형 실행이 되므로 야간 회귀 테스트, 매일 아침 백로그 정리, PR별 자동 수정 같은 워크플로에 끼워 넣을 수 있다. - /loop와의 선택 기준: 시간 기반 폴링이 본질이면
/loop, 자동 검증 가능한 종료 조건이 명확하면/goal. 두 도구는 같은 도구가 아니라 다른 문제를 풀기 위한 도구다.
원문: Keep Claude working toward a goal — code.claude.com docs