Cmd. /goal
완료 조건을 설정해 Claude가 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업하도록 하는 명령
핵심 요약
/goal [condition]은 세션에 완료 조건을 걸어, Claude가 매 턴 사람 지시 없이 그 조건을 향해 계속 작업하게 합니다.- 턴이 끝날 때마다 작고 빠른 모델(기본 Haiku)이 충족 여부를 판정하고, 충족되면 goal이 자동으로 풀립니다.
- 내부적으로는 세션 범위의 프롬프트 기반 Stop hook 래퍼라, trust를 수락한 워크스페이스에서만 동작합니다(v2.1.139 이상).
- 평가기는 도구를 호출하거나 파일을 직접 읽지 않고 대화에 드러난 내용만 봅니다. 조건은 측정 가능한 단일 종료 상태로 적고(최대 4,000자),
or stop after 20 turns같은 한도를 함께 넣으세요. - 인자에 따라 설정·조회(
/goal)·해제(clear/stop/off등)를 모두 수행하며 세션당 활성 goal은 하나입니다.
명령어 원본 선언
/goal [condition|clear]공식 설명 요약
/goal은 세션에 완료 조건(completion condition) 을 거는 명령입니다. 조건을 지정하면 Claude는
사람이 매 단계 지시하지 않아도 그 조건을 향해 계속 작업합니다. 턴이 끝날 때마다 별도의 작고 빠른
모델(small fast model, 기본값 Haiku) 이 충족 여부를 판정하고, 아직 충족되지 않았으면 제어권을
사용자에게 돌려주는 대신 다음 턴을 곧바로 시작합니다. 조건이 충족되면 goal은 자동으로 풀립니다.
인수 없이 /goal만 실행하면 현재 활성 goal 또는 세션 내에서 가장 최근에 달성한 goal의 상태를 보여줍니다.
내부적으로
/goal은 세션 범위(session-scoped)의 프롬프트 기반 Stop hook을 감싼 래퍼입니다. 별도의 hook 설정 파일을 만들지 않고도 한 세션 동안만 동작하는 종료 평가기를 즉석에서 붙이는 것과 같습니다.
세션당 활성 goal은 하나입니다. 같은 명령이 인수에 따라 설정·조회·해제 역할을 모두 수행합니다.
최소 지원 버전
- v2.1.139 이상 (공식 문서
/en/goal페이지의 Note 기준)
사용법
조건을 지정해 goal을 설정합니다. 이미 활성 goal이 있으면 새 goal이 기존 것을 대체합니다. goal을 설정하면
조건 자체가 지시문이 되어 곧바로 한 턴이 시작되므로 따로 프롬프트를 보낼 필요가 없습니다. 활성 상태일 때는
◎ /goal active 표시로 경과 시간을 확인합니다.
/goal all tests in test/auth pass and the lint step is clean현재 상태(조건, 경과 시간, 평가된 턴 수, 토큰 사용량, 평가기의 최근 판정 사유)를 조회합니다.
/goal활성 goal을 조건 충족 전에 조기 해제합니다. stop, off, reset, none, cancel도 clear의 별칭으로
받아들여집니다. 새 대화를 여는 /clear를 실행해도 활성 goal이 함께 제거됩니다.
/goal clear비대화형 모드에서도 동작합니다. -p로 goal을 설정하면 한 번의 호출로 루프가 완료될 때까지 실행됩니다.
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"좋은 사용 예
- 검증 가능한 종료 상태가 있는 작업: 모듈을 새 API로 마이그레이션해 모든 호출부가 컴파일·통과할 때까지, 디자인 문서의 모든 수용 기준이 만족될 때까지 등
- 큰 파일을 크기 예산 이하의 모듈들로 분할, 라벨이 붙은 이슈 백로그를 큐가 빌 때까지 처리
-p(비대화형)나 Remote Control처럼 사람이 매 턴 지시하지 않아도 되는 반복 작업- 긴 디버깅에서 "언제 멈출지"를 Claude에게 명확히 주고 싶을 때
효과적인 조건 작성 — 평가기는 명령을 실행하거나 파일을 직접 읽지 않고, Claude가 대화에 드러낸 내용만으로 판정합니다. 그러니 Claude의 출력으로 입증할 수 있는 조건을 쓰세요. 좋은 조건은 대개 다음을 갖춥니다.
- 측정 가능한 단일 종료 상태: 테스트 결과, 빌드 종료 코드, 파일 수, 빈 큐 등
- 입증 방법 명시: 예) "
npm testexits 0", "git statusis clean" - 지켜야 할 제약: 도중에 바뀌면 안 되는 것, 예) "no other test file is modified"
조건은 최대 4,000자까지 쓸 수 있고, 실행 시간을 제한하려면 or stop after 20 turns처럼 턴/시간 조항을
조건에 함께 넣으면 됩니다.
비슷한 명령어 추천
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/goal | 다음 턴은 이전 턴 종료 시 시작, 모델이 조건 충족을 확인하면 종료 | 종료 조건이 관찰 가능할 때 |
/loop | 다음 턴이 시간 간격마다 시작, 사용자가 멈추거나 Claude가 완료 판단 시 종료 | 조건 충족이 아니라 주기적 재실행이 필요할 때 |
| Stop hook | /goal처럼 매 턴 후 발동하지만 설정 파일에 상주하며 모든 세션에 적용, 스크립트/프롬프트로 직접 판정 | 결정적 검사나 재사용 가능한 평가 로직이 필요할 때 |
auto 모드는 한 턴 내의 도구 호출을 자동 승인하지만 새 턴을 시작하지는 않습니다.
/goal은 매 턴 후 별도의 신선한 모델이 조건을 평가하므로 둘은 상호 보완적입니다 — auto 모드는 도구별 승인을,/goal은 턴별 승인을 없앱니다.
활용 사례
- 마이그레이션 완주: "모든 호출부가 컴파일되고
test/auth의 테스트가 통과할 때까지"를 조건으로 두고 작업. - 백로그 소진: "라벨이
bug인 열린 이슈가 0건이 될 때까지"처럼 큐가 비는 것을 종료 상태로 지정. - 세션 재개: 활성 goal이 남은 채 세션이 끝나도
--resume/--continue로 재개하면 조건이 복원됩니다. 단, 턴 수·타이머·토큰 사용 기준선은 재개할 때 초기화되고, 이미 달성하거나 해제한 goal은 복원되지 않습니다.
주의사항
- "좋게 만들어줘"처럼 관찰 불가능한 조건은 피하세요. 평가기는 대화에 드러난 내용만 보고, 도구를 호출하거나 파일을 직접 읽지 않습니다.
- background shell이나 subagent가 남아 있는 작업에서는 해당 작업까지 완료 조건에 포함하세요.
- goal이 잘못 잡혔으면
clear,stop,off,reset,none,cancel인수로 조기 종료합니다. 비대화형 실행은 Ctrl+C로 중단할 수 있습니다. - 평가 토큰은 provider에 설정된 작고 빠른 모델에 과금되는데, 보통 본 턴 비용에 비하면 무시할 수준입니다.
- 요구 조건:
/goal은 hook 시스템의 일부라 신뢰(trust) 대화상자를 수락한 워크스페이스에서만 동작합니다. 또한 어느 설정 레벨에서든disableAllHooks가 켜져 있거나 managed settings에allowManagedHooksOnly가 설정된 경우 사용할 수 없으며, 이때 명령이 그 이유를 알려줍니다.
출처
- Commands: https://code.claude.com/docs/en/commands
- Keep Claude working toward a goal (
/goal): https://code.claude.com/docs/en/goal