Keep Claude working toward a `goal`

https://code.claude.com/docs/en/goal

‎⁠/goal⁠에 완료 조건만 정해 두면, Claude가 그 조건을 만족할 때까지 여러 턴에 걸쳐 알아서 계속 작업을 이어갑니다.

/goal⁠ 명령은 완료 조건을 설정해 두면, 매번 당신이 프롬프트를 보내지 않아도 Claude가 그 조건이 충족될 때까지 계속 작업을 이어가도록 만들어 줍니다. 각 턴이 끝날 때마다 작은 빠른 모델이 조건이 충족되었는지를 검사합니다. 조건이 충족되지 않았다면, Claude는 다시 한 턴을 시작하고, 당신에게 제어권을 돌려주지 않습니다.

목표는 검증 가능한 완료 상태가 있는 충분히 큰 작업에 사용하세요.

모든 호출 지점이 컴파일되고 테스트가 통과할 때까지 모듈을 새 API로 마이그레이션하기
모든 승인 기준이 충족될 때까지 디자인 문서를 구현하기
각 파일이 크기 기준을 만족할 때까지 큰 파일을 여러 개의 집중된 모듈로 분리하기
큐가 빌 때까지 라벨이 붙은 이슈 백로그를 처리하기

이 페이지에서는 다음 내용을 다룹니다:

/loop⁠, Stop hook, 자동 모드와 같은 자율 워크플로 접근 방식을 비교하는 방법
목표를 설정하고 효과적인 조건을 작성하는 방법
상태를 확인하고, 조기에 해제하며, 비대화형으로 실행하는 방법
평가가 어떻게 동작하는지와 요구 사항을 확인하는 방법

다른 자율 워크플로와 비교하기

프롬프트 사이에서도 현재 세션을 계속 실행시키는 방법은 세 가지가 있습니다. 다음 턴을 무엇이 시작해야 하는지에 따라 선택하세요:

접근 방식	다음 턴이 시작되는 시점	중지되는 시점
`/goal`	직전 턴이 끝났을 때	모델이 조건이 충족되었다고 확인할 때
`/loop`	설정한 시간 간격이 지났을 때	사용자가 중지하거나 Claude가 작업이 끝났다고 판단할 때
Stop hook	직전 턴이 끝났을 때	사용자가 작성한 스크립트나 프롬프트가 중지 여부를 결정할 때

/goal⁠과 Stop hook은 모두 매 턴마다 실행됩니다. /goal⁠은 세션 범위에만 적용되는 단축 기능으로, 당신이 조건을 입력하면 그 세션에서만 활성화됩니다. Stop hook은 설정 파일에 정의되며, 해당 범위에 있는 모든 세션에 적용되고, 결정론적인 검사를 위한 스크립트나, 모델 기반 평가를 위한 프롬프트를 실행할 수 있습니다.

자동 모드만 켜두면, 하나의 턴 안에서 도구 호출을 승인해 주기만 하고 새 턴을 시작하지는 않습니다. Claude는 작업이 끝났다고 판단하면 멈춥니다. /goal⁠은 매 턴마다 조건을 검사하는 별도의 평가자를 추가하므로, 완료 여부는 작업을 수행하는 메인 모델이 아니라 매번 새로 호출되는 모델이 판단합니다. 이 둘은 상호 보완적입니다. 자동 모드는 도구 호출마다 프롬프트를 보낼 필요를 없애고, /goal⁠은 턴마다 프롬프트를 보낼 필요를 없앱니다.

위의 접근 방식들은 모두 현재 세션을 계속 유지합니다. 이와는 별개로, nightly 테스트나 morning 티어링처럼, 열린 세션과 무관하게 실행되는 작업을 예약할 수도 있습니다. 클라우드 루틴과 데스크톱 예약 작업에 대해서는 스케줄링 옵션을 참고하세요.

`/goal⁠` 사용하기

한 세션에는 한 번에 하나의 목표만 활성화될 수 있습니다. 같은 명령으로, 인자에 따라 목표를 설정·조회·해제할 수 있습니다.

목표 설정하기

만족시키고 싶은 조건을 /goal⁠ 뒤에 붙여 실행하세요. 이미 활성화된 목표가 있다면, 새 목표로 교체됩니다.

/goal all tests in test/auth pass and the lint step is clean

목표를 설정하면, 그 조건 자체가 지시문이 되어 즉시 한 턴이 시작됩니다. 별도의 프롬프트를 보낼 필요는 없습니다. 목표가 활성화되어 있는 동안에는 ◎ /goal active⁠ 표시가 나타나고, 목표가 얼마나 오랫동안 실행 중인지 보여줍니다.

각 턴이 끝날 때마다 평가자는 조건이 충족되는지 여부와 그 이유를 짧게 돌려줍니다. 가장 최근 이유는 상태 보기와 대화 기록(transcript)에 표시되므로, Claude가 다음 턴에서 무엇을 향해 작업하고 있는지 확인할 수 있습니다.

목표는 조건이 충족되거나 당신이 /goal clear⁠를 실행할 때까지 계속됩니다. 인자 없이 /goal⁠을 실행하면, 지금까지 사용된 턴 수와 토큰 사용량을 확인할 수 있습니다.

효과적인 조건 작성하기

평가자는 Claude가 지금까지 대화에서 표면으로 끌어올린 정보에 비추어 조건을 판단합니다. 직접 명령을 실행하거나 파일을 읽지는 않으므로, Claude의 출력만으로 조건이 증명될 수 있도록 작성해야 합니다. 예를 들어 “test/auth⁠의 모든 테스트가 통과한다”는 조건은 Claude가 테스트를 실행하고, 그 결과가 대화 기록에 남기 때문에 유효합니다.

여러 턴에 걸쳐서도 잘 유지되는 조건에는 보통 다음 요소가 있습니다:

하나의 측정 가능한 종료 상태: 테스트 결과, 빌드 종료 코드, 파일 개수, 비어 있는 큐 등
명시된 검사 방법: “npm test⁠가 0 코드로 종료된다” 또는 “git status⁠가 깨끗하다”처럼 Claude가 어떻게 입증해야 하는지 적어두기
중간에 지켜야 하는 제약: “다른 테스트 파일은 수정하지 않는다”처럼, 그 과정에서 절대 바뀌면 안 되는 것들

조건은 최대 4,000자까지 쓸 수 있습니다.

목표가 얼마나 오래 실행될지 한계를 두고 싶다면, 조건 안에 턴 수나 시간에 대한 절을 포함시키세요. 예를 들어 or stop after 20 turns⁠처럼 적을 수 있습니다. Claude는 매 턴마다 이 절에 대한 진행 상황을 보고하고, 평가자는 대화를 바탕으로 해당 절을 함께 판단합니다.

상태 확인하기

인자 없이 /goal⁠을 실행해 현재 상태를 확인합니다.

/goal

활성화된 목표가 있다면 상태에는 다음이 표시됩니다:

설정된 조건
실행된 시간
지금까지 평가된 턴 수
현재 토큰 사용량
평가자의 가장 최근 이유

활성 목표는 없지만, 이 세션에서 이전에 달성된 목표가 있었다면, 그 달성된 조건과 함께 소요 시간, 턴 수, 토큰 사용량이 함께 표시됩니다.

목표 해제하기

조건이 충족되기 전에 활성 목표를 제거하려면 /goal clear⁠를 실행하세요.

/goal clear

stop⁠, off⁠, reset⁠, none⁠, cancel⁠도 clear⁠의 별칭으로 사용할 수 있습니다. 새 대화를 시작하는 /clear⁠를 실행해도, 활성화된 모든 목표가 함께 제거됩니다.

활성 목표와 함께 세션 재개하기

세션이 끝났을 때 아직 목표가 활성 상태였다면, --resume⁠ 또는 --continue⁠로 그 세션을 다시 열 때 목표도 복원됩니다. 조건 자체는 그대로 이어지지만, 턴 수, 타이머, 토큰 사용량 기준선은 재개 시점부터 다시 시작됩니다. 이미 달성되었거나 해제된 목표는 복원되지 않습니다.

비대화형으로 실행하기

/goal⁠은 비대화형 모드와 Remote Control을 통해서도 동작합니다. -p⁠ 옵션으로 목표를 설정하면, 한 번의 호출로 조건이 충족될 때까지 루프를 돌립니다.

claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

조건이 충족되기 전에 비대화형 목표를 멈추려면, Ctrl+C로 프로세스를 중단하세요.

평가 방식

/goal⁠은 세션 범위에만 적용되는 프롬프트 기반 Stop hook을 감싼 래퍼입니다. Claude가 턴을 끝낼 때마다, 설정한 조건과 지금까지의 대화 내용이 설정된 작고 빠른 모델로 보내집니다. 기본값은 Haiku입니다. 이 모델은 예/아니오 결정과 짧은 이유를 반환합니다. “아니오”인 경우 Claude에게 계속 작업하라고 알려주며, 다음 턴을 위한 가이드로 이유를 함께 제공합니다. “예”인 경우 목표를 해제하고, 달성된 목표를 대화 기록에 남깁니다.

평가자는 세션에서 설정한 동일한 제공자(provider) 위에서 실행됩니다. 도구를 호출하지 않기 때문에, Claude가 이미 대화에서 드러낸 내용만을 기준으로 판단합니다.

평가에 사용되는 토큰은 설정된 작은 빠른 모델에 대해 과금되며, 일반적으로 메인 턴에서 쓰이는 토큰에 비하면 무시할 수 있는 수준입니다.

요구 사항

/goal⁠은 평가자가 hook 시스템의 일부이기 때문에, 신뢰 대화 상자(trust dialog)에 동의한 워크스페이스에서만 실행됩니다. 관리형 정책 설정에서 disableAllHooks⁠가 켜져 있다면, /goal⁠은 사용할 수 없습니다. 두 경우 모두, 명령은 아무 일도 일어나지 않는 것처럼 조용히 넘어가지 않고, 왜 사용할 수 없는지 이유를 알려줍니다.

함께 보기

반복해서 프롬프트 실행하기: /loop⁠ — 조건이 만족될 때까지가 아니라, 일정한 시간 간격으로 다시 실행합니다.
프롬프트 기반 hook: 맞춤형 평가 로직이 필요할 때 직접 Stop hook을 작성합니다.
자동 모드: 도구 호출을 자동 승인해, 각 목표 턴이 사용자 개입 없이 실행되도록 합니다.
스케줄링 비교: 열린 세션과 무관하게 일정에 따라 작업을 실행하는 방법을 정리한 문서입니다.