Claude Code의 /goal로 '완료까지 자율 실행' 구현하기

서론: 매 턴마다 「계속해」라고 입력하는 것이 번거롭다

Claude Code로 테스트 수정이나 모듈 이관과 같은 긴 작업을 하고 있을 때, 이런 경험을 하지 않으십니까?

Claude가 테스트를 하나 고치고 멈춤 → 「계속해」 → 또 하나 고치고 멈춤 → 「계속해」 → 아직 3개 남음 → 「계속해」…

auto mode는 도구 호출(tool calling) 승인을 생략해 주지만, 턴이 끝날 때마다 멈추는 것은 변하지 않습니다. 10개의 테스트를 고치는 작업에 10번이나 「계속해」라고 입력하는 것은 인간 쪽이 병목(bottleneck)입니다.

이 장벽을 허무는 것이 바로 ** /goal**입니다. 「모든 테스트가 통과할 때까지」라고 완료 조건을 한 줄 적는 것만으로, Claude가 조건 달성까지 자율적으로 턴을 반복합니다. 본 기사에서는 /goal의 구조, 사용법, 효과적인 조건 작성법, 유사 기능과의 구분 방법까지 해설합니다.

/goal이란 무엇인가

/goal은 완료 조건을 설정하여 Claude를 목표를 향해 계속 달리게 하는 명령어입니다 (v2.1.139에서 추가).

/goal test/auth의 테스트가 모두 통과하고, lint도 깨끗해질 것

이것만으로 Claude는 「테스트 실행 → 실패 수정 → 재실행」을 인간의 입력 없이 반복하며, 모든 테스트가 통과하면 자동으로 멈춥니다.

이미지로 비유하자면, 일반적인 Claude Code가 「한 걸음 나아갈 때마다 지시를 기다리는 강아지 산책」이라면, /goal은 「골라인을 긋고 도그런(dog run)에서 자유롭게 달리게 하는」 감각입니다. 조건이 충족되는 순간 리드줄이 당겨져 돌아옵니다.

구조

내부적으로는 Claude가 턴을 종료할 때마다, 조건과 대화 내용이 사용자가 설정한 작고 빠른 모델로 전송됩니다 (기본값은 Haiku). 이 모델이 조건의 성패를 판정합니다.

평가기(evaluator)는 도구를 호출하지 않고, Claude가 대화 중에 표시한 내용(테스트 결과, 빌드 출력 등)만을 보고 판정합니다. 즉, 조건은 「Claude의 출력으로 증명할 수 있는 것」이어야 기능합니다.

유사 기능과의 구분

Claude Code에는 「세션을 계속 실행하는」 방법이 여러 가지 있습니다. 선택 방법은 「다음 턴이 시작되는 트리거」와 「멈추는 조건」이라는 두 축으로 결정됩니다.

접근 방식	다음 턴 시작 트리거	멈추는 조건	적합한 용도
`/goal`	이전 턴이 종료됨	평가기가 조건 달성을 확인	테스트 수정, 이관, 백로그 소화
`/loop`	시간 간격 (예: 5분마다)	사용자가 정지 또는 Claude가 판단	정기 모니터링, CI 워치
Stop hook	이전 턴이 종료됨	자체 제작 스크립트/프롬프트가 판단	커스텀 평가 로직
auto mode	― (턴 내의 도구 승인을 생략)	Claude의 판단	도구 승인 생략

구분 포인트:

검증 가능한 목표가 있다 → /goal (「모든 테스트 통과」, 「빌드 성공」)
정기적으로 반복한다 → /loop (「5분마다 CI 체크」)
독자적인 판정 로직이 필요하다 → Stop hook (스크립트로 exit code를 반환)
도구 승인만 생략하고 싶다 → auto mode

/goal과 auto mode는 병용이 가능하며 상호 보완적입니다. auto mode가 도구별 승인을 생략하고, /goal이 턴별 승인을 생략하므로, 조합하면 완전히 자율적인 실행을 실현할 수 있습니다.

사용법

Step 1: 목표를 설정하기

Claude Code의 프롬프트에서 /goal 뒤에 완료 조건을 작성합니다.

/goal test/auth의 테스트가 모두 통과하고, lint도 깨끗해질 것

설정하는 즉시 턴이 시작됩니다. 별도로 프롬프트를 보낼 필요는 없습니다. 목표가 활성화되어 있는 동안에는 ◎ /goal active 인디케이터가 표시됩니다.

세션마다 단 하나의 목표만 활성화됩니다. 새로운 목표를 설정하면 이전 목표는 교체됩니다.

Step 2: 진행 상황 확인하기

인자 없이 /goal을 실행하면 현재 상태를 확인할 수 있습니다.

/goal

다음 정보가 표시됩니다.

항목	내용
조건	설정된 목표 문구
...

"최신 이유 (Latest Reason)"는 Claude가 무엇 때문에 막혀 있는지에 대한 단서가 됩니다. 방침을 변경하고 싶을 때는 다음 단계에서 클리어하여 다시 시작할 수 있습니다.

Step 3: 필요에 따라 클리어하기

조건 달성 전에 중단하고 싶거나 방침을 바꾸고 싶을 때는 클리어합니다.

/goal clear

다음 서브 커맨드(Subcommand) 및 에일리어스(Alias)를 사용할 수 있습니다.

커맨드	동작
`/goal <조건>`	목표 설정 (기존 목표가 있으면 교체)
`/goal`	현재 상태 표시
`/goal clear`	활성화된 목표 삭제
`/goal stop`	`clear`의 에일리어스
`/goal off`	`clear`의 에일리어스
`/goal reset`	`clear`의 에일리어스
`/goal none`	`clear`의 에일리어스
`/goal cancel`	`clear`의 에일리어스

/clear로 새로운 대화를 시작한 경우에도 목표는 삭제됩니다. 조건이 달성된 경우에는 자동으로 클리어되므로 수동 클리어는 필요하지 않습니다.

Step 4 (선택 사항): 세션 재개로 계속하기

세션 종료 시 활성화되어 있던 목표는 --resume 또는 --continue로 재개하면 복원됩니다.

claude --resume

단, 턴(Turn) 수, 타이머, 토큰 지출은 리셋됩니다. 이미 달성되었거나 클리어된 목표는 복원되지 않습니다.

Step 5 (선택 사항): 비대화형으로 실행하기

-p 플래그와 조합하면, 한 번의 커맨드로 목표를 설정하고 완료까지 실행할 수 있습니다.

claude -p "/goal 이번 주에 머지된 모든 PR의 CHANGELOG 엔트리가 추가되어 있을 것"

CI/CD 파이프라인이나 스크립트에서 사용할 때 유용합니다. Ctrl+C로 중단할 수 있습니다.

효과적인 조건 작성법

평가기(Evaluator)는 Claude가 대화에서 표시한 내용만을 보고 판단합니다. 평가기 스스로가 커맨드를 실행하거나 파일을 읽지는 않습니다. 이 제약 사항을 이해하면 효과적인 조건을 작성할 수 있습니다.

좋은 조건의 3요소

요소	설명	예시
측정 가능한 종료 상태	테스트 결과, 빌드 종료 코드, 파일 수 등	`npm test가 종료 코드 0으로 완료될 것`
명시된 체크 사항	Claude가 어떻게 증명해야 하는지 명시	`git status에서 커밋되지 않은 변경 사항이 없을 것`
중요한 제약 사항	과정 중에 망가뜨려서는 안 되는 것	`다른 테스트 파일은 변경하지 말 것`

좋은 예와 나쁜 예

# 좋은 예: 측정 가능하며 Claude가 입증할 수 있음
/goal test/auth의 테스트가 모두 통과하고, lint도 깨끗할 것
# 좋은 예: 제약 사항 포함
...

폭주 방지: 턴/시간 제한

조건에 턴이나 시간의 상한을 포함하면, 달성하지 못할 경우의 폭주를 방지할 수 있습니다.

/goal 인증 테스트가 모두 통과할 것. 20턴 내에 달성하지 못하면 정지

Claude는 각 턴마다 진행 상황을 보고하며, 평가기가 대화 내용을 통해 상한 도달 여부를 판단합니다.

실측: 가위바위보 모듈을 /goal로 자율 구현시켜 보았다

실제로 /goal을 사용하여, 테스트 주도(TDD) 방식으로 가위바위보 로직을 구현하게 했습니다.

준비

테스트를 먼저 8개 작성하고, 구현부는 throw new Error("not implemented")만 있는 빈 스텁(Stub)을 준비했습니다.

describe("judge", () => {
  it("가위는 보를 이긴다", () => {
    expect(judge("가위", "보")).toBe("win");
    ...

이 상태에서 총 8개의 테스트가 실패하는 것을 확인한 후, /goal을 실행합니다.

/goal janken/ 하위의 가위바위보 모듈을 구현하고, npm test가 모두 통과할 것

결과

항목	값
소요 시간	38초
...

/usage로 확인한 토큰 내역은 다음과 같습니다.

모델	input	output	cache 읽기	cache 쓰기	비용
Opus 4.6 (작업 본체)	230	1.5k	541.6k	176.9k	$1.42
Haiku 4.5 (목표 평가)	3	169	0	8.2k	$0.01

1턴, 38초 만에 총 8개의 테스트를 통과했습니다. Claude는 빈 스텁(stub)을 읽고, 테스트 케이스로부터 사양을 이해하며, 승패 판정 테이블과 난수 생성을 한 번에 구현했습니다. 평가기 (Haiku)가 npm test의 출력을 보고 "모든 테스트 통과"를 확인하여, 목표를 달성한 것으로 판단하고 종료했습니다.

실측: 비용의 대부분은 시스템 프롬프트나 대상 파일의 캐시 읽기/쓰기 (약 718k 토큰)입니다. Haiku를 통한 조건 판정 비용은 $0.01로, /goal 메커니즘 자체에 발생하는 오버헤드는 무시할 수 있는 수준입니다.

실전 Tips

auto mode와 병용하기: /goal만 사용하면 도구 승인(tool approval) 단계에서 멈출 수 있습니다. auto mode를 활성화하면 각 턴도 무인으로 실행되어 완전 자율 상태가 됩니다.
에이전트 뷰(agent view)와 조합하기: claude agents로 여러 세션을 관리하면서 각 세션에 /goal을 설정하면 병렬 자율 실행이 가능합니다.
-p로 스크립트에 포함하기: claude -p "/goal ..." 방식은 CI/CD나 정기 배치 작업과 궁합이 좋습니다.
조건의 중간 과정을 활용하기: /goal에서 표시되는 "평가기의 최신 이유(latest reason from evaluator)"를 보면 Claude가 무엇 때문에 막혀 있는지 알 수 있습니다. 막히는 부분이 보이면 /goal clear를 한 뒤 프롬프트로 방침을 수정하고, 다시 /goal을 설정하세요.

전제 조건 및 제약 사항

버전: v2.1.139 이상이 필요합니다.
hooks 활성화: /goal은 내부적으로 Stop hook으로 동작하기 때문에, disableAllHooks가 설정되어 있으면 사용할 수 없습니다 (이유가 메시지로 표시됩니다).
관리 설정: 관리 설정에서 allowManagedHooksOnly가 활성화되어 있으면 /goal을 이용할 수 없습니다.
조건의 최대 길이: 4,000자
평가기 모델: 기본값은 Haiku이며, 설정에서 변경 가능합니다.
세션 범위: 목표(goal)는 현재 세션에서만 유효하며, 설정 파일에는 저장되지 않습니다.

요약

/goal은 "검증 가능한 종료 상태가 있는 작업"에서 진가를 발휘합니다.

테스트 수정 → "모든 테스트가 통과할 때까지"
모듈 마이그레이션 → "모든 콜 사이트(call site)가 컴파일될 때까지"
백로그 처리 → "큐(queue)가 빌 때까지"

판단 기준은 간단합니다. "무엇을 완료로 간주할 것인가?"를 한 문장으로 쓸 수 있는가? —— 쓸 수 있다면 /goal, 쓸 수 없다면 인터랙티브 방식, 정기 실행이라면 /loop를 사용하세요. auto mode와 조합하면 도구 승인이나 턴 지속이 필요 없는 완전 자율 실행을 얻을 수 있습니다. 우선 테스트 수정과 같은 작은 작업부터 시도해 보세요.