Cmd. /goal
완료 조건을 설정해 Claude가 조건이 충족될 때까지 여러 턴에 걸쳐 계속 작업하도록 하는 명령
핵심 요약
- 완료 조건을 달성할 때까지 지속되는 goal 설정
- 입력 위치·지원 조건을 확인한 뒤 아래 실행 예를 사용합니다.
역할
완료 조건을 달성할 때까지 지속되는 goal 설정
/goal [condition|clear]사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 내장 명령 |
| 상태 | 현재 공식 표 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-09-22 · Claude Code 2.1.278 |
설치본의 명령 메뉴와 계정·조직 설정에 따라 사용할 수 있는 항목이 달라집니다.
사용 예
/goal Finish the migration and keep the tests green조건을 지정해 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은 턴별 승인을 없앱니다.
실행 결과와 유지 범위
현재 스레드에 목표를 연결해 여러 턴에 걸쳐 유지합니다. 작업 범위가 바뀌면 목표도 갱신하거나 해제합니다.
/goal은 세션에 완료 조건(completion condition) 을 거는 명령입니다. 조건을 지정하면 Claude는
사람이 매 단계 지시하지 않아도 그 조건을 향해 계속 작업합니다. 턴이 끝날 때마다 별도의 작고 빠른
모델(small fast model, 기본값 Haiku) 이 충족 여부를 판정하고, 아직 충족되지 않았으면 제어권을
사용자에게 돌려주는 대신 다음 턴을 곧바로 시작합니다. 조건이 충족되면 goal은 자동으로 풀립니다.
인수 없이 /goal만 실행하면 현재 활성 goal 또는 세션 내에서 가장 최근에 달성한 goal의 상태를 보여줍니다.
내부적으로
/goal은 세션 범위(session-scoped)의 프롬프트 기반 Stop hook을 감싼 래퍼입니다. 별도의 hook 설정 파일을 만들지 않고도 한 세션 동안만 동작하는 종료 평가기를 즉석에서 붙이는 것과 같습니다.
세션당 활성 goal은 하나입니다. 같은 명령이 인수에 따라 설정·조회·해제 역할을 모두 수행합니다.
오류 후 복구
API 오류·네트워크 단절·token 또는 사용량 한도 뒤 /goal이 조용히 멈추던 문제가 수정됐습니다. backoff 재시도 또는 사유를 표시하는 일시정지로 바뀌며 사용량 reset 대기도 포함합니다. 완료 판단은 goal 상태와 산출물을 함께 확인하세요.
공식 Changelog · 2026-09-12 KST
주의사항
- "좋게 만들어줘"처럼 관찰 불가능한 조건은 피하세요. 평가기는 대화에 드러난 내용만 보고, 도구를 호출하거나 파일을 직접 읽지 않습니다.
- background shell이나 subagent가 남아 있는 작업에서는 해당 작업까지 완료 조건에 포함하세요.
- goal이 잘못 잡혔으면
clear,stop,off,reset,none,cancel인수로 조기 종료합니다. 비대화형 실행은 Ctrl+C로 중단할 수 있습니다. - 평가 토큰은 provider에 설정된 작고 빠른 모델에 과금되는데, 보통 본 턴 비용에 비하면 무시할 수준입니다.
- 요구 조건:
/goal은 hook 시스템의 일부라 신뢰(trust) 대화상자를 수락한 워크스페이스에서만 동작합니다. 또한 어느 설정 레벨에서든disableAllHooks가 켜져 있거나 managed settings에allowManagedHooksOnly가 설정된 경우 사용할 수 없으며, 이때 명령이 그 이유를 알려줍니다.
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록