Claude Code의 /goal을 사용해 보기 전에 조사한 내용 메모

2026년 6월 시점의 개인용 메모. Claude Code는 거의 매일 업데이트가 이루어지므로, 실제로 사용할 때는

claude --version

과

/release-notes

로 최신 버전을 확인할 것.

/goal

은 공식 Claude Code에 실제로 존재하는 내장 명령어였다. 2026년 5월 11일 v2.1.139에서 추가된 것. 하는 일은 심플하며,

"
완료 조건을 한 줄로 선언하면, 그 조건이 충족될 때까지 Claude가 턴을 넘기며 알아서 작업을 계속해 준다"

이것뿐이다. 평소라면 매 턴마다 "계속해"라고 말해야 하는 부분을, 종료 조건을 미리 정해두면 방치할 수 있다는 이야기다.

메커니즘이 흥미로운데, 작업하는 모델과 "끝났는지 판정하는 모델"이 분리되어 있다. 각 턴이 끝날 때마다 별도의 작고 빠른 모델(기본값은 Haiku)이 대화 로그를 읽고 "조건을 충족했는가? yes / no"를 반환한다. no라면 이유가 다음 턴의 지시사항으로 주입되어 한 바퀴 더 돌고, yes가 되면 goal이 자동으로 클리어된다.

VentureBeat의 기사에서 Sprinklr의 직원이 했던 말이 핵심을 찔렀다(의역). "자신의 숙제를 스스로 채점하게 해서는 안 된다. 작업 중인 모델이야말로 끝났는지 여부를 판단하는 판정자로서는 최악이다". 그래서 builder와 judge를 나누고 있다는 것이다.

/goal <조건> # 골을 설정. 즉시 실행됨 ("해줘"라고 할 필요 없음)
/goal # 인자 없음. 현재 상태(조건·경과 시간·턴 수·토큰·최근 판정 이유)를 표시
/goal clear # 해제. stop / off / reset / none / cancel로도 동일

• 1세션당 골은 하나만 가능. 새로운 /goal은 기존 것을 덮어쓴다.
• 조건은 최대 4,000자.
• /clear로 대화를 리셋하면 goal도 함께 사라진다.
• 인터랙티브 / -p (headless) / 데스크톱 앱 / 원격 제어에서 사용할 수 있다.

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

이것만으로 완주할 때까지 실행된다. 멈추고 싶다면 Ctrl+C. cron이나 CI에서 호출한다면 이 형태를 사용한다.

이 부분이 가장 중요해 보인다. "검증 가능한 종료 상태가 있는 태스크"에만 사용한다.

• 좋은 예:
  all tests in test/auth pass (npm test exits 0), the module compiles and every call site is migrated

• 나쁜 예:
  make it production-ready, make the UI better
  ← 주관적인 조건은 토큰을 계속 소모하며 영원히 끝나지 않는다.

개인용 템플릿으로서, 다음과 같은 4요소로 작성하는 것이 좋아 보인다 (공식에서 명시한 것은 처음 3가지. 4번째는 "무인 실행이라면 넣어두라" 정도의 뉘앙스):

/goal implement dark mode matching the Figma spec, # 1. 측정 가능한 종료 상태
all tests pass (npm test exits 0), # 2. 검증 방법
do not modify existing API contracts, # 3. 지켜야 할 제약
...

• 토큰 예산은 내장되어 있지 않다. 모호한 조건으로 밤새 방치했다가 토큰을 다 써버리는 사고 보고가 있음. 조건에 or stop after N turns를 반드시 포함할 것.
• 판정 모델은 로그만 읽는다. 툴을 직접 실행하거나 파일을 읽지는 않는다. 따라서 Claude가 "테스트를 통과한 것 같다"라고만 쓰고 실제로는 실행하지 않았더라도, judge는 잘못하여 yes를 반환할 수 있다. → 조건에 "npm test를 실행하여 exit 0을 확인"이라고 적어 증거를 강제할 것.
• pause / resume은 없다. OpenAI의 Codex CLI 버전 /goal

에는 create/pause/resume/clear가 있지만, Claude Code 버전은 「active → 달성 시 자동 clear 또는 수동 clear」뿐이다. 혼동하지 말 것. -
복합 목표에 취약함. 「인증 로직 재작성 + OAuth 추가 + 테스트 + 문서 업데이트」와 같이 한꺼번에 몰아넣은 작업은 judge가 처리하지 못한다. 검증 가능한 end state (종료 상태) 단위로 분할할 것. -
trust dialog (신뢰 대화) 승인이 완료된 워크스페이스가 필요함. disableAllHooks가 설정되어 있으면 사용할 수 없다 (judge가 hooks 메커니즘을 사용하기 때문).

기능	역할	/goal과의 관계
/plan (plan mode)	읽기 전용으로 계획만 수립. 구현은 하지 않음	/goal은 계획 이후의 「실행 루프 (execution loop)」. 대체재가 아닌 상보적 관계
/loop	일정 시간 간격으로 동일한 프롬프트를 재실행 (배포 모니터링 등)	/goal은 조건 기반. 종료 후 멈추는 용도는 이쪽
auto mode	턴 내의 도구 승인을 자동으로 허용함	auto mode + /goal이 완전 자율 주행의 정석 조합
Stop hook	설정 파일에서 영구적으로 정의하는 메커니즘	/goal은 해당 세션 한정 버전 (내용은 prompt-based Stop hook)
Agent View (claude agents)	여러 백그라운드 세션을 관리하는 대시보드	v2.1.139에서 동시 구현. /bg와 조합하면 병렬 모니터링 가능

공식(Boris Cherny) 권장 워크플로우는 「Plan mode로 계획을 구체화 → auto-accept로 전환하여 실행」하는 2단계 방식이다. /goal은 이 실행 단계에 끼워 넣는 이미지다.

환경 확인: claude --version으로 v2.1.139 이상인지 확인. 낮다면 claude update. 대상 디렉토리에서 한 번 실행하여 trust를 승인할 것. -
작게 시작하기: 30분 이내에 끝나는 검증 태스크로 진행. 먼저 git status를 통해 클린 상태를 만들고 현재 테스트 실패 횟수를 기록해둘 것. /goal all tests in test/auth pass (npm test exits 0), do not modify files outside test/auth or src/auth, do not delete or skip tests, or stop after 15 turns -
auto mode와 조합: Shift+Tab으로 permission mode를 auto까지 돌린다. 이렇게 하면 승인 클릭이나 「계속(continue)」 입력이 필요 없어진다. -
모니터링 운영: /bg로 백그라운드화 → claude agents로 목록 모니터링. 진행 상황은 인자 없이 /goal을 입력하여 judge의 최근 이유를 읽는다. 폭주하면 /goal clear, 안 되면 Ctrl+C. -
야간 배치: claude -p "/goal <턴 상한이 포함된 조건>"를 cron 또는 GitHub Actions에서 실행.

중단 시점의 기준:

• judge의 이유가 3턴 연속으로 동일함 → 루프(loop)에 빠짐. 수동 개입 필요.
• 토큰 사용량이 예상의 2배를 초과함 → 조건이 모호함. clear 후 다시 작성.
• 조건에 「production-ready」, 「looks good」 같은 주관적인 단어가 포함됨 → 애초에 /goal에 적합하지 않음.

사실 OpenAI의 Codex CLI가 11일 더 빠르다. Codex CLI v0.128.0(2026년 4월 30일)에 /goal이 포함되었고, Claude Code의 v2.1.139는 5월 11일이다. 양사 모두 「코딩 에이전트의 장시간 자율 주행」을 표준 기능으로 가져가려는 흐름 속에 있다. Anthropic의 차별점은 기능의 선점 여부가 아니라, builder/judge 분리 구현의 정교함이라는 평가였다.

공식 커맨드 해설:
https://code.claude.com/docs/en/goal ("Keep Claude working toward a goal") -
커맨드 목록:
https://code.claude.com/docs/en/commands

• CHANGELOG:
  https://code.claude.com/docs/en/changelog

(v2.1.139 항목)

• VentureBeat "Claude Code의 '/goals'는 작업하는 에이전트와 완료를 결정하는 에이전트를 분리한다"
• Codex CLI 측:
  https://github.com/openai/codex/releases/tag/rust-v0.128.0

⚠️ 메모 주의사항: 4요소 템플릿, "3턴 연속 동일 이유" 임계값, 토큰 소진 (Token burn) 사례 등은 커뮤니티 블로그/Medium에서 유래한 2차 정보임. 공식적으로 명시된 것은 "측정 가능한 종료 상태 / 검증 방법 / 준수해야 할 제약"의 3요소까지임.