claudekit / guides / goal-command
[ Guide · Practical · 6분 ]

Claude Code `/goal` — 자동 진행을 안전하게 굴리는 법

published · updated

`/goal`은 완료 조건을 한 줄로 적어두면 매 턴 평가 모델이 충족 여부를 판단해 충족 전까지 자동으로 다음 턴을 시작합니다. 명령 자체보다 조건을 어떻게 적어야 평가기를 속이지 않고 무한 진행에 빠지지 않는지가 실전 포인트입니다.

다중 턴 작업의 정상 비용

여러 턴이 필요한 작업에는 매 턴 사이마다 “계속해줘”를 누르거나 다음 지시를 다시 주는 시간이 끼어 있습니다. 검증 가능한 종료 상태가 있는 작업이라면 이 사이 시간은 사실상 낭비입니다. 코드를 마이그레이션해서 모든 호출 지점이 컴파일되고 테스트가 통과하기, 큰 파일을 사이즈 예산 안으로 쪼개기, 라벨이 붙은 이슈 백로그를 비우기 — 이런 작업은 사람이 사이에 끼지 않아도 됩니다.

/goal은 이 사이 시간을 없앱니다. 한 줄로 완료 조건을 입력하면 매 턴 후 평가기가 충족 여부를 판단하고, 충족 전까지 Claude가 자동으로 다음 턴을 시작합니다. 조건이 만족되면 goal은 자동 해제되며, 평가기가 조건을 충족 불가능하다고 판단하거나 사용자가 직접 해결해야 하는 오류로 턴이 실패해도 해제됩니다.

대신 사람이 매 턴 끼지 않는 만큼, 조건이 잘못 적혀 있을 때 비용이 사용자 모르게 누적되는 것이 핵심 위험입니다. 이 가이드는 명령 사용법보다 조건 작성에서 자주 빠지는 함정과 회피법을 정리합니다.

3가지 자동 진행 메커니즘 — 무엇을 언제 쓰나

다음 턴이 언제 시작되는가가 결정 기준입니다.

접근다음 턴이 시작되는 시점멈추는 조건적용 범위
/goal이전 턴이 끝나는 즉시 (대화형 세션에서는 idle check-in이나 자동 재시도 시점에도)평가 모델이 조건 충족 또는 충족 불가를 판단, 해결이 필요한 오류로 턴 실패, /goal clear현재 세션 한정
/loop일정 시간 간격마다사용자 중단 또는 Claude가 작업 종료 판단현재 세션 한정
Stop hook이전 턴이 끝나는 즉시사용자가 짠 스크립트나 프롬프트가 결정settings 적용 범위 전체

/goal은 한 줄짜리 입력만으로 현재 세션에 들어가는 단축 경로입니다. 평가 로직을 더 정교하게 짜고 싶으면 Stop hook을 직접 정의하고, 단순히 시간 기반으로 같은 프롬프트를 반복하고 싶으면 /loop 쪽이 맞습니다. Auto mode는 턴 안의 툴 호출만 자동 승인하고 새 턴을 시작하지는 않으므로, /goal과 조합하면 턴 안과 턴 사이의 프롬프트가 모두 사라집니다 (= 완전 무인 운영). 반대로 /goal은 권한 모드를 바꾸지 않으므로, Manual 모드에서는 허용되지 않은 툴 호출마다 여전히 승인을 묻습니다.

사용법

/goal test/auth 폴더의 모든 테스트가 통과하고 lint가 깨끗할 때까지

입력과 동시에 첫 턴이 시작됩니다 — 별도 프롬프트를 보낼 필요가 없습니다. 활성화된 동안 ◎ /goal active 인디케이터가 경과 시간을 함께 보여주고, 매 턴 후 평가기의 판정이 트랜스크립트에 남습니다. 판정 사유는 Ctrl+O로 볼 수 있고, 상태 화면에도 가장 최근 사유가 표시됩니다. 세션당 goal은 하나이며 새 goal을 설정하면 기존 goal을 대체합니다. 조건은 최대 4,000자까지 쓸 수 있습니다.

상세 명령 표:

명령동작
/goal (인자 없이)현재 또는 가장 최근에 달성된 goal의 조건, 경과 시간, 턴 수, 토큰 사용량, 평가기 사유 표시
/goal clear조건 충족 전 조기 해제 (stop, off, reset, none, cancel 도 동일)
/clear새 대화 시작 — 활성 goal도 함께 제거

세션이 끝났을 때 활성 상태였던 goal은 --continue, --resume, 세션 픽커 등 어떤 경로로 같은 세션을 다시 열어도 조건이 복원됩니다(2.1.239부터 claude --resume 픽커 포함). 단 턴 수, 타이머, 토큰 사용량 기준은 0부터 다시 시작하고, 이미 달성하거나 해제한 goal은 복원되지 않습니다.

조건 작성에서 자주 빠지는 함정 4가지

/goal이 잘못 돌아가는 사례는 거의 모두 조건이 잘못 적혀 있어서 발생합니다.

함정 1 — 평가기는 대화에 드러난 것만 본다

평가기는 별도로 명령을 실행하거나 파일을 읽지 않습니다. Claude가 트랜스크립트에 내놓은 텍스트만 보고 판단합니다.

❌ /goal 모든 단위 테스트가 통과할 때까지

이 조건은 위험합니다. Claude가 테스트를 실제로 돌리지 않고 “테스트를 점검한 결과 모두 통과합니다”라고 자체 보고만 해도 평가기가 그 문장을 보고 “조건 충족”이라 판단할 수 있습니다.

✅ /goal npm test가 exit 0으로 종료되고 그 출력이 트랜스크립트에 보일 때까지

증거의 형태를 조건에 박아두면 우회가 어려워집니다. “어떤 명령을 돌렸고 그 결과 화면이 보인다”까지 조건에 포함해야 평가기가 그 증거를 보고 판단합니다.

함정 2 — 조건이 추상적

❌ /goal 코드 품질이 개선될 때까지

“품질 개선”은 측정 가능한 종료 상태가 아닙니다. 평가기는 매 턴 “아직 미흡함”이라 판단하기 쉽고, Claude는 끝없이 리팩터를 시도하게 됩니다.

✅ /goal src/utils/format.ts 파일이 200줄 이하가 되고 외부에서 import하는 export가 모두 보존되어 있을 때까지

종료 조건은 하나의 측정 가능한 상태 + 유지되어야 하는 제약으로 적습니다.

함정 3 — 종료 안전장치가 없다

평가기가 “아직 미충족”을 내는 동안 goal은 계속 돕니다. 평가기가 조건을 충족 불가능하다고 판단하거나, Claude가 여러 턴 연속 툴을 쓰지 않고 진전이 없을 때는 멈추지만, 조금씩이라도 작업이 이어지는 한 자동으로 멈추지 않습니다. 이때 사용자가 잠시 자리를 비우면 토큰만 누적될 수 있습니다.

조건 자체에 turn 또는 time 절을 박아 안전장치를 둡니다.

/goal test/auth의 모든 테스트가 통과하고 lint가 깨끗할 때까지,
또는 20턴이 지나면 진행 상황을 요약하고 멈출 것

Claude는 매 턴 그 절에 대한 진행도를 보고하고, 평가기는 대화에서 그 절의 충족 여부를 판단합니다.

함정 4 — “변경되면 안 되는 것”이 빠져 있다

❌ /goal users 테이블에 created_at 컬럼이 추가되고 마이그레이션이 통과할 때까지

조건이 통과하더라도 그 사이에 다른 마이그레이션 파일이 임의로 수정될 수 있습니다.

✅ /goal users 테이블에 created_at 컬럼이 추가되고 새 마이그레이션 한 개로만 적용되며, 기존 마이그레이션 파일은 수정되지 않은 상태에서 npm run migrate가 통과할 때까지

영향 범위가 큰 작업일수록 “건드리지 말 것”을 조건에 같이 박아둡니다.

헤드리스 운영

-p 플래그와 결합하면 한 호출에서 조건 충족까지 자동으로 돕니다. 백그라운드 잡이나 cron에서 쓰기 좋습니다.

claude -p "/goal CHANGELOG.md에 이번 주 머지된 모든 PR 항목이 있을 때까지" \
  --permission-mode auto

--permission-mode auto(또는 세션 안에서 auto mode)를 같이 두면 매 툴 승인 프롬프트도 사라져 완전 무인 운영이 됩니다. 중단은 Ctrl+C로 즉시 가능합니다. 기본 텍스트 출력은 루프가 끝날 때 최종 응답만 출력하므로 오래 도는 goal은 멈춘 것처럼 보일 수 있습니다. 진행 중 메시지를 보려면 --output-format stream-json --verbose를 추가합니다.

/goal이 어울리지 않는 작업

  • 탐색과 디자인 결정 — 종료 상태가 합의로만 정해지는 작업은 /goal에 맞지 않습니다. Plan mode + 사용자 검토가 낫습니다.
  • 사용자 확인이 끼어야 하는 다단계 작업 — 매 턴 자동 진행이 오히려 위험합니다.
  • 검증 출력이 없는 작업 — UI 변경처럼 평가기가 결과를 텍스트로 확인할 수 없는 작업은 안전장치(turn 제한)를 강하게 두지 않으면 무한 진행 위험이 큽니다.

평가가 실제로 어떻게 도는가

/goal은 내부적으로 session-scoped prompt-based Stop hook의 래퍼입니다. Claude가 턴을 마칠 때마다 조건과 지금까지의 대화가 small fast model (기본 Haiku)에 전달되어 세 가지 판정 중 하나와 짧은 사유를 반환받습니다.

  • 아직 미충족 — Claude가 계속 작업하고, 사유가 다음 턴의 가이드로 들어갑니다.
  • 충족 — goal이 해제되고 트랜스크립트에 달성 기록이 남습니다.
  • 충족 불가 — 조건을 결코 만족할 수 없다고 판단하면 goal이 해제되고, 사유와 함께 실패 기록이 남습니다. 직접 해제할 필요가 없습니다.

Claude가 여러 턴 연속 툴을 쓰지 않고 평가기에 답만 하며 진전이 없으면, Claude Code가 루프를 멈추고 경고를 표시한 뒤 goal은 유지한 채 제어를 돌려줍니다. 다음 프롬프트를 보내면 평가가 재개됩니다.

턴이 실패했을 때

  • 직접 해결해야 하는 오류 — 인증 실패, 크레딧 소진, 자동 압축으로도 해결되지 않는 컨텍스트 초과, 사용할 수 없는 모델로 턴이 실패하면 goal이 해제되고 Goal cleared after an unrecoverable error 경고가 표시됩니다(2.1.234부터). 원인을 해결한 뒤 /goal <조건>으로 다시 설정합니다.
  • 그 밖의 오류 — goal은 유지됩니다. 대화형 세션(v2.1.269 이상)에서는 서버 과부하나 연결 끊김처럼 저절로 풀리는 오류는 자동 재시도(최대 3회)하고, API rate limit이나 사용량 한도처럼 재시도해도 같은 결과가 나올 오류는 Goal paused로 일시정지하며 원인을 표시합니다.

백그라운드 작업이 있을 때

턴이 끝날 때 subagent나 백그라운드 셸 명령이 아직 실행 중이면 그 턴의 평가를 건너뛰고, 백그라운드 작업 없이 끝난 다음 턴에 평가합니다. 백그라운드 작업 때문에 30분 넘게 대기하면 Claude가 실행 중인 작업을 점검하는 check-in이 돌고, 이후 1시간, 2시간 간격으로 반복됩니다(2.1.234부터). 첫 간격은 CLAUDE_CODE_GOAL_CHECKIN_MINUTES로 바꾸며, 0으로 설정하면 check-in과 자동 재시도가 모두 꺼집니다.

평가 모델과 비용

평가기는 사용 중인 프로바이더의 small fast 모델 위에서 동작합니다. 다른 모델로 평가하려면 ANTHROPIC_DEFAULT_HAIKU_MODEL을 설정합니다. 이 값은 /goal 평가뿐 아니라 haiku 별칭, 세션 제목 생성 등 small fast 모델을 쓰는 모든 곳에 적용되니 주의합니다. 평가 토큰 비용은 메인 턴에 비해 보통 무시할 만한 수준입니다.

사용 요건

  • Claude Code v2.1.139 이상
  • settings 파일의 hooks와 같은 workspace trust 규칙 적용 (평가기가 hooks 시스템의 일부이기 때문)
  • settings 우선순위를 적용한 disableAllHooks 최종값이 true이면 비활성
  • managed settings의 allowManagedHooksOnly가 설정된 환경에서도 비활성
  • 비활성 환경에서는 사유 메시지가 명시적으로 표시됩니다 (조용히 무시되지 않음)

참고

§ 10

자주 묻는 질문

자주 묻는 질문
§ 10.1
`/goal`은 무엇인가요?
완료 조건을 한 줄로 적어두면, 매 턴이 끝날 때마다 small fast 모델이 조건 충족 여부를 평가하고 충족 전까지 Claude가 다음 턴을 자동으로 시작하게 하는 명령입니다. 조건이 만족되거나, 평가 모델이 충족 불가능하다고 판단하거나, 사용자가 직접 해결해야 하는 오류로 턴이 실패하면 자동 해제됩니다.
§ 10.2
어떤 버전부터 사용할 수 있나요?
Claude Code v2.1.139 이상에서 사용할 수 있습니다. 평가기가 hooks 시스템의 일부이므로 settings 파일의 hooks와 같은 workspace trust 규칙을 따릅니다.
§ 10.3
`/loop`과 어떻게 다른가요?
`/loop`은 시간 간격마다 같은 프롬프트를 반복 실행합니다. `/goal`은 이전 턴이 끝나는 즉시 평가가 돌고 조건이 충족되면 멈춥니다. 시간 기반 반복이냐 조건 기반 자동 진행이냐의 차이입니다.
§ 10.4
평가기가 Claude의 자체 보고만 보고 속는 일은 없나요?
평가기는 툴을 호출하지 않고 대화에 이미 드러난 내용으로만 판단합니다. 그래서 "테스트가 통과했다"는 Claude의 서술만으로도 평가가 통과할 수 있습니다. 조건에 "`npm test` 출력에 0 exit code가 보일 것"처럼 증거 형태를 명시해야 우회를 막을 수 있습니다.
§ 10.5
사용 불가한 경우가 있나요?
settings 파일의 hooks가 workspace trust 규칙으로 막히는 폴더, settings 우선순위를 적용한 `disableAllHooks` 최종값이 `true`인 환경, managed settings에 `allowManagedHooksOnly`가 설정된 환경에서 비활성됩니다. 사용 불가일 때는 조용히 무시되지 않고 사유 메시지가 표시됩니다.
§ 10.6
헤드리스 모드에서도 동작하나요?
`claude -p "/goal <조건>"`으로 한 번에 실행하면 goal이 해제될 때까지 자동으로 돌고, Ctrl+C로 중단할 수 있습니다. 기본 텍스트 출력은 끝날 때까지 아무것도 표시하지 않으므로 진행 상황을 보려면 `--output-format stream-json --verbose`를 추가합니다. Desktop 앱과 Remote Control에서도 사용 가능합니다.