Claude Code에게 긴 작업을 맡기면 사람이 매 턴마다 “계속해”, “다시 테스트해”, “아직 실패했으니 고쳐”라고 입력해야 할 때가 있습니다. 작업 내용은 명확한데, 턴이 끝날 때마다 사용자가 다시 시작시켜야 합니다.
/goal ↗은 이 반복을 줄이는 기능입니다. 완료 조건을 한 번 적어 두면 Claude가 각 턴이 끝날 때마다 조건을 평가합니다. 조건이 아직 만족되지 않았으면 다음 턴을 자동으로 시작합니다.
이 글은 작성 시점 2026-06-17의 Claude Code Goals 문서 ↗, scheduled tasks 문서 ↗, hooks 문서 ↗를 바탕으로 정리했습니다.
/goal은 Claude Code v2.1.139 이상에서 사용할 수 있습니다. 현재 세션에 하나의 goal만 활성화할 수 있고, 조건이 만족되면 자동으로 해제됩니다.
/goal은 무엇인가
공식 문서는 /goal을 “completion condition을 설정하고, 그 조건이 만족될 때까지 Claude가 여러 턴에 걸쳐 계속 일하게 하는 기능”으로 설명합니다.
예를 들면 이렇게 씁니다.
/goal all tests in test/auth pass and the lint step is cleangoal을 설정하면 프롬프트를 따로 보내지 않아도 됩니다. 조건 자체가 첫 directive가 되고, Claude는 바로 작업을 시작합니다. 각 턴이 끝나면 작고 빠른 모델(evaluator)이 대화 내용을 보고 조건이 만족됐는지 판단합니다.
flowchart TD
A[사용자: /goal 조건 입력] --> B[Claude가 한 턴 작업]
B --> C[Evaluator가 조건 확인]
C --> D{조건 만족?}
D -->|아니오| E[이유를 다음 턴 지침으로 전달]
E --> B
D -->|예| F[goal 자동 해제 및 완료 기록]/goal은 시간이 되면 다시 실행하지 않습니다. 조건이 아직 안 맞으면 계속 실행합니다.
/loop와 무엇이 다른가
/loop는 시간 기반입니다. 5분마다 배포 상태를 확인하거나, 주기적으로 PR 상태를 살필 때 씁니다.
/goal은 조건 기반입니다. 이전 턴이 끝난 직후 평가가 일어나고, 조건이 아직 아니면 바로 다음 턴이 시작됩니다.
| 기능 | 다음 턴이 시작되는 조건 | 멈추는 조건 |
|---|---|---|
/goal | 이전 턴이 끝남 | evaluator가 조건 만족을 확인 |
/loop | 시간 간격 도달 | 사용자가 멈추거나 Claude가 완료 판단 |
| Stop hook | 이전 턴이 끝남 | 사용자 스크립트나 prompt 판단 |
| Auto Mode | 다음 턴을 시작하지 않음 | 한 턴 안에서 도구 승인만 자동화 |
문서에 따르면 Auto Mode는 per-tool prompt를 줄이고, /goal은 per-turn prompt를 줄입니다. 두 기능은 함께 쓸 수 있습니다.
좋은 goal 조건 쓰기
/goal의 품질은 조건 문장에 달려 있습니다. evaluator는 독립적으로 파일을 읽거나 명령을 실행하지 않습니다. Claude가 대화에 드러낸 결과를 보고 판단합니다.
그래서 조건에는 세 가지를 적습니다.
- 측정 가능한 종료 상태
- Claude가 증명해야 할 확인 방법
- 지켜야 할 제약 조건
예를 들어 이렇게 씁니다.
/goal npm test exits 0, npm run lint exits 0, and no files outside src/auth and test/auth are modified반대로 다음처럼 쓰면 애매합니다.
/goal make the auth code better“더 좋아졌다”는 판단 기준이 없습니다. /goal에는 테스트 결과, 빌드 exit code, 파일 수, 빈 큐, checklist 완료처럼 대화 안에서 확인 가능한 상태가 잘 맞습니다.
or stop after 20 turns를 붙이면 작업이 끝없이 이어지지 않습니다.
상태 확인과 해제
/goal만 입력하면 현재 goal 상태를 볼 수 있습니다.
/goal활성 goal이 있으면 조건, 실행 시간, 평가된 턴 수, token spend, evaluator의 최근 이유가 표시됩니다.
중간에 멈추고 싶으면 /goal clear를 씁니다.
/goal clear문서 기준 stop, off, reset, none, cancel도 clear의 alias로 동작합니다. 새 대화를 시작하는 /clear도 활성 goal을 제거합니다.
resume과 non-interactive mode
goal이 활성화된 상태에서 세션이 끝났다면, --resume이나 --continue로 세션을 되살릴 때 goal 조건도 복원됩니다. 다만 turn count, timer, token-spend baseline은 resume 시점부터 다시 시작됩니다.
/goal은 non-interactive mode에서도 쓸 수 있습니다.
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"이 경우 한 번의 invocation 안에서 goal loop가 완료될 때까지 진행됩니다. 중간에 멈추려면 Ctrl+C로 interrupt합니다.
끝났는지 확인할 수 있는 작업에 씁니다
/goal은 완료 여부를 확인할 수 있는 작업에 맞습니다.
| 작업 | 좋은 goal 조건 |
|---|---|
| 테스트 고치기 | 특정 test suite가 exit 0 |
| 마이그레이션 | 모든 call site가 새 API를 쓰고 build 통과 |
| 파일 분리 | 각 파일이 지정한 line budget 이하 |
| backlog 처리 | 특정 label의 issue queue가 비어 있음 |
| 문서 업데이트 | acceptance criteria checklist가 모두 충족 |
“좋아 보이게”, “더 깔끔하게”, “적당히 리팩터링”처럼 주관적인 조건은 /goal에 맞지 않습니다. 이런 작업은 완료 기준을 먼저 정합니다.
요구사항과 한계
문서에 따르면 /goal은 hooks system 위에 구현되어 있습니다. 그래서 trusted workspace에서만 동작합니다. disableAllHooks가 설정되어 있거나 managed settings에서 allowManagedHooksOnly가 켜져 있으면 사용할 수 없습니다.
/goal은 턴이 끝날 때마다 hook으로 평가 로직을 실행합니다. 그래서 hooks가 막힌 환경에서는 동작하지 않습니다.
마무리
/goal을 쓰면 Claude Code가 조건이 맞을 때까지 스스로 다음 턴을 이어 갑니다.
goal 조건에는 측정 가능한 종료 상태, 확인 방법, 제약 조건을 함께 적습니다. 그러면 “계속해”를 반복하지 않아도 Claude가 목표에 도달할 때까지 작업합니다.
시간 기반 확인은 /loop, 반복 실행의 조건 기반 자동화는 /goal, 도구 승인 피로 완화는 Auto Mode입니다. 이 셋을 구분해서 쓰면 Claude Code 세션이 덜 끊깁니다.