[Claude] Claude Code /goal 명령어 활용 방법

 

이번 글에서는 새롭게 추가된 /goal 명령어가 어떻게 동작하는지, 그리고 어떤 상황에서 쓸 수 있을지 살펴보고자 합니다.

 

/goal은 사용자가 지정한 완료 조건이 충족될 때까지 Claude가 스스로 턴을 이어가는 명령어입니다. 기존에 /loop이 시간 간격으로 반복했다면, /goal은 "결과 상태"가 확인됐을 때 멈춥니다.

 

1. 기본 동작 원리

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

 

명령어를 입력하는 순간 조건 자체가 첫 지시로 전달되어 Claude가 바로 작업을 시작합니다. 매 턴이 끝날 때마다 별도의 평가자 모델이 조건 충족 여부를 yes/no로 판정합니다. 조건 미충족이라고 판단하면 그 사유를 짧게 반환하고, Claude는 다음 턴을 이어갑니다. 조건이 충족됐다고 판단되면 루프가 종료됩니다.

 

평가자와 작업자가 분리된 구조가 핵심입니다. 평가자가 자신의 작업을 스스로 검증하는 편향을 줄이기 위한 설계입니다. 평가자는 도구 호출 없이 트랜스크립트만 읽고 판단하기 때문에, 조건은 반드시 Claude의 출력으로 증명 가능한 형태여야 합니다. 테스트 실행 결과 stdout, `git status` 출력 같은 형식이 적합합니다.

 

2. 상태 확인과 종료

/goal

인자 없이 실행하면 현재 조건, 누적 실행 시간, 평가된 턴 수, 토큰 사용량, 평가자의 최근 사유를 보여줍니다.

 

/goal clear

 

`stop`, `off`, `reset`, `none`, `cancel`도 같은 동작을 합니다. `/clear`로 대화를 새로 시작해도 goal이 함께 해제됩니다.

 

세션을 `--resume`이나 `--continue`로 이어 열면 활성 상태였던 goal은 복원됩니다. 단 턴 카운트, 타이머, 토큰 사용 기준치는 재설정됩니다.

 

3. 조건 작성 팁

잘 작성된 조건에는 세 가지 요소가 들어갑니다.

 

• 측정 가능한 종료 상태 : 테스트 결과, 빌드 exit code, 파일 수처럼 확인 가능한 것이어야 합니다.
• 검증 방법 : "npm test exits 0", "git status is clean" 처럼 Claude가 무엇을 실행해서 어떤 결과를 트랜스크립트에 남겨야 하는지를 명시합니다.
• 유지해야 할 제약 : "no other test file is modified" 같이 건드리면 안 되는 범위를 함께 씁니다.

 

무한 루프 방지를 위해 `or stop after 20 turns`를 조건 끝에 붙이는 것도 실용적입니다. "improve the dashboard"처럼 모호한 조건은 검증은 통과하지만 결과물이 엉뚱한 방향으로 흐를 수 있습니다.

 

조건 예시:

/goal Migrate every call site of legacy_api.py to new_api.v2, npm test exits 0, and no files outside /src/auth are modified, or stop after 30 turns

 

/goal CHANGELOG.md has an entry for every PR merged this week

 

4. `/loop`과의 차이

	/goal	/loop
다음 턴 시작	직전 턴이 끝났을 때	시간 간격이 경과했을 때
종료 시점	평가 모델	사용자가 멈추거나 Claude 자체 판단
평가 주체	별도 평가자 모델	메인 모델 자체

 

"완료된 상태"가 명확하면 `/goal`, 배포 진행 상황을 10분마다 체크하는 식의 주기적 폴링이 필요하면 `/loop`가 맞습니다.

 

Auto mode와 조합하면 한 턴 안의 도구 호출 승인까지 자동화되어 사람 개입 없는 실행이 가능합니다.

 

5. Headless 모드

터미널에서 `-p` 플래그로 호출하면 한 번의 실행 안에서 조건 충족까지 루프가 돕니다.

 

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

 

CI 파이프라인에서 특정 상태가 확인될 때까지 Claude를 돌리는 용도로 활용할 수 있습니다. 비대화형 실행 중에도 Ctrl+C로 중단 가능합니다.

마무리

`/goal`의 실용적인 쓰임새는 "완료 상태가 명확한 반복 작업"에 있습니다. 테스트 통과, 마이그레이션 완료, 이슈 백로그 정리처럼 완료 기준을 출력으로 검증할 수 있는 작업이라면 조건 하나로 Claude가 끝까지 처리하게 할 수 있습니다. 조건을 구체적으로 쓸수록, 특히 제약 범위를 함께 명시할수록 원하는 방향으로 작업이 흘러갑니다.

 

 

<참고>

1. Keep Claude working toward a goal - Claude Code 공식 문서

2. Claude Code's '/goals' separates the agent that works from the one that decides it's done - VentureBeat

3. Claude Code /goal: A Field Guide with Games - Jason Croucher (Medium)

4. Claude Code /goal 출시: 목표만 주면 AI가 끝까지 처리한다 - 이랜서 블로그