목표를 향해 Claude가 계속 일하게 하기

목표를 향해 Claude가 계속 일하게 하기

/goal 명령으로 완료 조건을 정해두면, Claude가 매 단계마다 프롬프트를 넣지 않아도 그 조건이 충족될 때까지 계속 일해요. 검증 가능한 종료 상태가 있는 규모 있는 작업을 맡길 때 딱이죠. 이 문서에서는 /goal 설정법과 평가가 어떻게 이뤄지는지, 어떤 기준으로 목표가 해제되는지까지 다룹니다.

출처: 공식문서

본문

/goal 명령은 완료 조건을 설정하고, Claude가 매 단계 프롬프트 없이 그 조건을 향해 계속 작업하게 해요. 매 턴이 끝나면 작고 빠른 모델 하나가 조건이 충족됐는지 확인합니다. 모델이 아직 충족되지 않았다고 판단하면 Claude는 제어권을 돌려주지 않고 다음 턴을 시작해요. 목표는 조건이 충족되면, 모델이 조건을 만족시킬 수 없다고 판단하면, 또는 직접 고쳐야 하는 오류로 턴이 실패하면 자동으로 해제돼요.

검증 가능한 종료 상태가 있는 규모 있는 작업에 목표를 쓰세요.

  • 모든 콜 사이트가 컴파일되고 테스트가 통과할 때까지 모듈을 새 API로 마이그레이션
  • 모든 수용 기준이 충족될 때까지 디자인 문서 구현
  • 각각이 크기 예산 아래에 있을 때까지 큰 파일을 집중된 모듈로 분할
  • 큐가 비워질 때까지 라벨 붙은 이슈 백로그 처리

세션을 계속 도는 방식 비교

프롬프트 사이에 현재 세션을 계속 돌리는 방식은 세 가지예요. 무엇이 다음 턴을 시작하게 할지에 따라 고르면 됩니다.

방식 다음 턴이 시작되는 때 멈추는 때
/goal 이전 턴이 끝나거나, 백그라운드 작업이 목표를 기다리게 하는 동안 유휴 체크인이 도래(프롬프트 사이에 목표당 최대 3회) 모델이 조건 충족 또는 불가능을 확인하거나, 직접 고쳐야 하는 오류로 턴이 실패하거나, /goal clear를 실행
/loop 시간 간격이 경과 내가 멈추거나 Claude가 작업 완료라고 판단
Stop 훅 이전 턴이 끝남 내 스크립트나 프롬프트가 결정

/goal과 Stop 훅은 둘 다 매 턴 뒤에 발동돼요. /goal은 세션 범위의 지름길로, 조건을 입력하면 현재 세션에서만 활성화돼요. Stop 훅은 설정 파일에 살아서 해당 범위의 모든 세션에 적용되고, 결정적 검사용 스크립트나 모델 평가용 프롬프트를 실행할 수 있어요.

자동 모드는 단일 턴 안의 도구 호출을 승인하지만 새 턴은 시작하지 않아요. Claude는 작업 완료로 판단하면 멈춰요. /goal은 매 턴 뒤에 조건을 확인하는 별도 평가자를 추가해서, 완료 여부를 일하는 모델이 아니라 새 모델이 결정하게 해요. 둘은 상호 보완적이에요. 자동 모드는 도구별 프롬프트를 제거하고, /goal은 턴별 프롬프트를 제거하죠.

팁: 위 방식은 현재 세션을 계속 돌려요. 열린 세션과 무관하게 도는 작업(야간 테스트, 아침 트리아지 등)은 스케줄링 옵션의 클라우드 루틴·데스크톱 예약 작업을 보세요.

/goal 사용하기

세션당 한 개의 목표가 활성화될 수 있어요. 같은 명령이 인자에 따라 설정·확인·해제를 수행합니다.

목표 설정

/goal 뒤에 충족시키고 싶은 조건을 입력해요. 이미 활성 목표가 있으면 새 것으로 교체돼요.

/goal test/auth의 모든 테스트가 통과하고 lint 단계가 깨끗한지

목표를 설정하면 조건 자체를 지시로 해서 바로 턴이 시작돼요. 별도 프롬프트를 보낼 필요가 없죠. 목표가 활성인 동안 ◎ /goal active 표시가 목표가 얼마나 돌았는지 보여줘요.

목표는 권한 모드를 바꾸지 않아요. 목표 턴을 무인으로 돌리려면 자동 모드에서 /goal을 실행하세요. 수동 모드에서는 설정이 이미 허용하지 않는 도구 호출(위 테스트 명령 등)은 여전히 Claude가 물어봐요.

목표가 활성인 동안 트랜스크립트는 평가자가 반환하는 각 판정을 보여주고, Ctrl+O를 누르면 그 이유를 볼 수 있어요. 상태 뷰도 가장 최근 이유를 보여줘서, Claude가 다음에 무엇을 향해 작업할지 알 수 있어요.

효과적인 조건 쓰기

평가자는 Claude가 대화에서 표면화한 내용을 기준으로 조건을 판단해요. 명령을 직접 실행하거나 파일을 독립적으로 읽지 않으므로, 조건은 Claude의 출력이 스스로 증명할 수 있는 형태로 쓰세요. "test/auth의 모든 테스트가 통과"는 Claude가 테스트를 실행하고 결과가 트랜스크립트에 남아 평가자가 읽을 수 있으니 잘 작동해요.

많은 턴에 걸쳐 유지되는 조건은 보통 다음을 갖춰요.

  • 측정 가능한 종료 상태 하나: 테스트 결과, 빌드 종료 코드, 파일 수, 빈 큐
  • 명시된 확인 방법: Claude가 어떻게 증명할지. 예를 들어 "npm test가 0으로 종료" 또는 "git status가 깨끗"
  • 중요한 제약: 그 과정에서 바뀌면 안 되는 것. 예를 들어 "다른 테스트 파일은 수정되지 않음"

조건은 최대 4,000자까지 가능해요.

목표가 얼마나 도는지 한정하려면 조건에 턴·시간 절을 넣으세요. 예를 들어 or stop after 20 turns. 그러면 Claude가 매 턴 그 절에 대한 진행 상황을 보고하고 평가자가 대화에서 판단해요.

상태 확인

인자 없이 /goal을 실행하면 현재 상태를 볼 수 있어요.

/goal

목표가 활성이면 상태는 다음을 보여줘요.

  • 조건
  • 실행된 시간
  • 평가된 턴 수
  • 현재 토큰 지출
  • 평가자의 가장 최근 이유

턴 수와 가장 최근 이유는 첫 평가가 실행된 뒤에 나타나요.

활성 목표는 없지만 세션에서 더 일찍 목표를 달성했다면, 상태는 달성된 조건과 기간·턴 수·토큰 지출을 보여줘요.

목표 해제

활성 목표를 해소되기 전에 제거하려면 /goal clear를 실행하세요.

/goal clear

Claude는 Goal cleared: 뒤에 조건을 출력해 확인하거나, 활성 목표가 없으면 No goal set을 출력해요.

stop, off, reset, none, cancel은 clear의 별칭으로 허용돼요. 새 대화를 시작하는 /clear 실행도 활성 목표를 제거해요.

활성 목표로 재개

세션을 재개하면 Claude Code는 세션이 끝날 때 아직 활성이던 목표를 복원해요. --continue, 세션 ID·이름·트랜스크립트 파일 경로로 하는 --resume, 세션 피커 등 모든 재개 경로에서 복원돼요. v2.1.239 이전에는 claude --resume 피커를 제외한 모든 경로에서 복원했어요.

Claude Code는 조건은 이어가지만 턴 수·타이머·토큰 지출 기준치는 초기화해요. 이미 달성됐거나 해제된 목표는 복원하지 않아요.

비대화형으로 실행

/goal은 비대화형 모드, 데스크톱 앱, 리모트 컨트롤에서 동작해요. -p로 목표를 설정하면 단일 호출에서 루프를 끝까지 돌려요.

claude -p "/goal 이번 주에 머지된 모든 PR에 대한 항목이 CHANGELOG.md에 있는지"

기본 텍스트 출력에서는 실행이 끝날 때까지 아무것도 출력되지 않아서, 여러 턴을 도는 목표는 멈춘 것처럼 보일 수 있어요. --output-format stream-json --verbose를 추가하면 루프가 도는 동안 각 메시지를 내보내요.

비대화형 목표를 해소되기 전에 멈추려면 Ctrl+C로 프로세스를 중단하세요.

평가가 어떻게 이뤄지는지

/goal은 세션 범위의 프롬프트 기반 Stop 훅을 감싼 래퍼예요. Claude가 매 턴을 끝낼 때마다 Claude Code는 조건과 지금까지의 대화를 설정된 작고 빠른 모델에 보내는데, Claude API에서는 기본적으로 Haiku예요. 타사 프로바이더에서는 프로바이더 페이지에서 플랫폼 기본값을 확인하세요. 모델은 각각 짧은 이유가 딸린 세 가지 판정 중 하나를 반환해요.

  • 아직 충족 안 됨(Not yet met): Claude가 계속 작업하고 그 이유를 다음 턴의 지침으로 삼아요.
  • 충족(Met): Claude Code가 목표를 해제하고 트랜스크립트에 달성 항목을 기록해요.
  • 불가능(Impossible): 평가자가 조건이 절대 충족될 수 없다고 판단했어요. Claude Code가 목표를 해제하고 트랜스크립트에 이유와 함께 실패 항목을 기록해요. 직접 해제할 필요가 없어요.

Claude가 진행 없이 평가자에게 계속 응답하면(여러 턴 연속 도구 사용 없음) Claude Code는 루프를 멈추고 경고를 출력하며, 목표는 설정된 채로 제어권을 돌려줘요. 다음 프롬프트 후 평가가 재개돼요. 훅 가이드가 기본 메커니즘을 설명해요.

직접 고쳐야 하는 오류가 목표를 해제해요

턴이 직접 고치지 않으면 풀리지 않는 오류로 실패하면, Claude Code는 목표를 해제하고 원인을 짚는 경고를 출력해요. 경고는 Goal cleared after an unrecoverable error로 시작하고 Run /goal again to continue로 끝나요. 원인을 고친 뒤 /goal <condition>으로 목표를 다시 설정하세요. 네 가지 실패가 목표를 해제해요.

  • Claude Code가 자체 자격 증명을 관리할 때의 인증 실패. 데스크톱 앱·VS Code 확장·클라우드 세션처럼 호스트가 자격 증명을 관리하면, 호스트가 스스로 접근을 복원하므로 Claude Code는 목표를 활성으로 남겨둬요.
  • 크레딧 잔액 소진
  • 자동 컴팩션으로 해결되지 못한 컨텍스트 오버플로
  • 사용할 수 없는 모델

속도 제한·서버 과부하 같은 일시적 오류를 포함한 다른 모든 실패에서는 Claude Code가 목표를 활성으로 남겨둬요.

백그라운드 작업은 평가를 미뤄요

턴이 끝날 때 서브에이전트나 백그라운드 셸 명령이 아직 실행 중이면, Claude Code는 그 턴의 평가를 건너뛰고 백그라운드 작업 없이 끝나는 다음 턴 끝에서 평가해요. 백그라운드 작업이 끝나면 Claude Code는 결과를 새 턴으로 Claude에 전달하므로 프롬프트할 필요가 없어요.

백그라운드 작업이 목표를 30분 동안 기다리게 하면 체크인이 도래해요. 체크인에서 Claude Code는 실행 중인 작업을 나열하고 Claude에게 그 출력을 읽고, 진행 중이면 계속 기다리고, 멈춘 것은 고치거나 중지하라고 요청해요. 첫 체크인 후 Claude Code는 각 후속 체크인 전에 두 배를 기다려, 최대 첫 간격의 네 배까지 간격을 두는데, 기본값으로 첫 체크인 후 1시간, 그다음엔 2시간마다예요. Claude Code는 도래한 체크인(첫 번째 포함)을 두 가지 방식 중 하나로 전달해요.

  • 턴이 끝날 때: Claude Code는 작업이 여전히 도는 채로 끝나는 다음 턴 끝에 체크인을 전달해요. -p로 시작한 것 같은 비대화형 세션에서는 이것이 체크인 전달의 유일한 방식이에요.
  • 세션이 유휴인 동안: 대화형 세션에서는 Claude Code가 다음 프롬프트를 기다리는 대신 체크인을 전달하기 위해 스스로 턴을 시작해요. 백그라운드 작업이 결과 보고 없이 멈췄다면 Claude Code는 Claude에게 목표를 향해 계속하라고 요청해요. Claude Code는 프롬프트 사이에 목표당 유휴 체크인을 최대 세 번 시작해요. 세 번째 유휴 체크인에서는 유휴 체크인이 다음 프롬프트까지 일시중지된다고 말해요. v2.1.246 이전에는 유휴 체크인에 상한이 없었어요. 유휴 체크인은 Claude Code v2.1.236 이상이 필요해요.

v2.1.239 이전에는 유휴 체크인만 이렇게 백오프했고, 턴 끝에 전달된 체크인은 첫 간격으로 반복됐어요.

첫 간격을 바꾸려면 CLAUDE_CODE_GOAL_CHECKIN_MINUTES를 설정하세요. Claude Code는 30분 간격 대신 그 값을 쓰고 이후 간격을 함께 조정해요. 체크인을 끄려면 0으로 설정하세요. 체크인은 Claude Code v2.1.234 이상이 필요해요.

평가 모델과 비용

다른 모델로 평가하려면 ANTHROPIC_DEFAULT_HAIKU_MODEL을 설정하세요.

경고: Claude Code는 작고 빠른 모델을 쓰는 모든 곳에서 ANTHROPIC_DEFAULT_HAIKU_MODEL을 읽는데, /goal 평가만이 아니에요. 설정하면 Claude Code가 haiku 별칭도 그 모델로 해석하고, 대화 요약 같은 백그라운드 기능도 그 모델로 돌려요.

평가자는 세션이 구성된 프로바이더에서 실행돼요. 도구를 호출하지 않으므로, Claude가 이미 대화에서 표면화한 내용만 판단할 수 있어요.

참고: 평가 토큰은 프로바이더에 구성된 작고 빠른 모델로 청구되며, 보통 주 턴 지출에 비해 무시할 수 있을 정도예요.

요구 사항

Claude Code는 평가자가 훅 시스템의 일부이므로, 설정 파일의 훅과 같은 워크스페이스 신뢰 규칙 아래에서 /goal을 제공해요. 설정 우선순위 적용 후 disableAllHooks가 true이거나, 관리 설정에서 allowManagedHooksOnly가 설정된 경우에도 /goal은 쓸 수 없어요. 각 경우 명령은 조용히 아무것도 안 하는 대신 이유를 알려줘요.

더 알아보기