Claude Code /goal 기능 사용법과 목표 조건 체크리스트

2026년 5월 13일 KST 기준, Claude Code 문서는 /goal을 목표 조건이 충족될 때까지 여러 턴을 이어가는 자동화 기능으로 설명한다. 사용자가 매 단계마다 다음 프롬프트를 넣지 않아도, 턴이 끝날 때마다 별도 평가 모델이 조건 충족 여부를 확인하고 미완료라면 다음 턴을 시작하는 구조다.

처음 보면 이건 그냥 “오래 걸리는 일을 알아서 끝내는 버튼”처럼 보인다. 그런데 운영 관점에서 보면 더 중요한 건 반복 실행 자체가 아니라, 어떤 조건을 완료로 인정할지 먼저 쓰게 만든다는 점이다. 자동화는 팔 힘이 세지는 기능이지만, 목표 조건이 흐리면 힘센 자동화가 엉뚱한 벽을 열심히 밀 수도 있다.

내가 이 기능을 TECHTAEK 글감으로 보는 이유도 여기에 있다. Claude Code에 새 명령어가 생겼다는 뉴스보다, AI 코딩 에이전트가 채팅형 보조자에서 목표 기반 작업자로 이동하고 있다는 신호가 더 크다. 이 변화는 개발자가 프롬프트를 잘 쓰는 문제를 넘어, 작업의 종료 조건과 검증 로그를 어떻게 설계할지 묻는다.

지금 판단

/goal은 긴 작업을 맡길 때 유용하지만, 모든 작업을 밤새 돌리는 스위치로 보면 위험하다. 공식 문서 기준으로 /goal의 평가자는 파일이나 명령을 직접 읽지 않고, Claude가 대화에 남긴 실행 결과와 설명을 바탕으로 조건 충족 여부를 판단한다. 그래서 조건은 “알아서 잘 끝내줘”가 아니라 “무엇을 실행했고 어떤 결과가 transcript에 남아야 하는지”까지 들어가야 한다.

내가 운영한다면 /goal은 새 기능 전체 구현보다, 완료 조건이 선명한 작업부터 붙인다. 예를 들면 특정 테스트 디렉터리가 통과할 때까지 고치기, 린트와 빌드가 모두 0으로 끝날 때까지 정리하기, 큰 파일을 여러 모듈로 나누되 각 파일 크기 제한을 지키기 같은 작업이다. 반대로 제품 방향을 정하거나, UX 판단을 하거나, 보안 예외를 승인하는 일은 사람이 중간 결정을 해야 하므로 /goal만으로 밀면 안 된다.

작업 유형	/goal 적합도	이유
테스트 실패를 고쳐 `npm test` 통과시키기	높음	종료 조건과 증거가 명확함
마이그레이션 후 모든 call site 컴파일 확인	높음	반복 수정과 검증 루프가 잘 맞음
“사용자 경험을 더 좋게 만들기”	낮음	완료 조건이 주관적이고 평가 증거가 약함
보안 권한을 넓히는 자동 수정	낮음	승인과 리스크 판단이 필요함
문서 TODO 큐를 전부 닫기	중간	큐 정의와 검수 기준이 있으면 가능

/goal은 /loop나 auto mode와 어디가 다른가

공식 문서에서 /goal은 /loop, Stop hook, auto mode와 비교된다. /loop는 시간 간격으로 다음 실행을 시작하는 쪽에 가깝고, Stop hook은 설정 파일에 들어가는 더 넓은 범위의 자동 평가 장치다. auto mode는 도구 승인 부담을 줄여 한 턴 안의 실행을 덜 끊기게 만드는 기능이고, /goal은 턴이 끝난 뒤 다음 턴을 시작할지를 결정한다.

이 차이를 실무 언어로 바꾸면 간단하다. auto mode는 “이 명령 실행해도 돼?”라는 마찰을 줄이는 기능이고, /goal은 “아직 끝나지 않았으니 다음 행동으로 넘어가”를 자동화하는 기능이다. 둘은 겹치는 듯 보이지만 승인 자동화와 턴 반복 자동화는 다른 층이다.

여기서 운영자가 봐야 할 포인트는 비용과 검수다. /goal이 여러 턴을 이어가면 주 모델 사용량은 자연스럽게 늘 수 있고, 각 턴 뒤 평가 모델도 사용된다. 문서상 평가 토큰은 보통 주 작업 대비 작다고 설명되지만, 긴 작업을 여러 세션에 걸쳐 자주 돌리면 “왜 한도가 빨리 닳지?”라는 질문이 바로 나온다.

그래서 /goal을 켜기 전에 작업 예산을 같이 적는 게 좋다. 예를 들면 “모든 테스트가 통과하거나 20턴이 지나면 멈춘다”, “2시간 이상 걸리면 현재 상태와 남은 blocker를 요약하고 정지한다”처럼 조건에 시간이나 턴 제한을 넣을 수 있다. 이 한 줄이 없으면 자동화가 성실하게 오래 일하고, 사람은 나중에 청구서와 diff를 보며 눈이 얇아진다.

Agent View와 같이 쓸 때 더 조심할 점

2026년 5월 14일 기준 Claude Code의 Agent View는 claude agents로 여러 백그라운드 세션을 한 화면에서 보고, 각 세션에 attach하거나 peek할 수 있게 해준다. /goal이 한 세션 안에서 목표 조건까지 계속 달리는 장치라면, Agent View는 그런 세션 여러 개를 한 화면에서 관리하는 관제판에 가깝다.

둘을 같이 쓰면 편해진다. 예를 들어 테스트 실패 수정, 문서 TODO 처리, 작은 마이그레이션을 각각 다른 백그라운드 세션으로 보내고, 각 세션마다 /goal 조건을 좁게 걸어둘 수 있다. 하지만 이 조합은 생산성만 늘리는 게 아니라 사용량과 리뷰 부담도 같이 늘린다. 세션이 3개면 일도 3개가 아니라, 검토해야 할 diff와 로그도 3개가 된다.

그래서 Agent View에서 /goal을 여러 개 굴릴 때는 세션 이름보다 완료 증거를 먼저 봐야 한다. 각 goal에는 테스트 명령, 최대 턴 수, 변경 금지 범위, 실패 시 요약 조건이 들어가야 하고, 완료 뒤에는 사람이 diff와 권한 변경을 다시 봐야 한다. Agent View가 여러 세션을 보기 좋게 정리해줘도, 리뷰 책임까지 정리해주는 건 아니다.

내 기준으로는 처음부터 “병렬 goal 10개”로 가면 안 된다. 첫 주에는 독립성이 높은 2개 정도만 돌리고, 각 세션이 남긴 로그와 변경 범위가 리뷰 가능한지 확인하는 편이 낫다. 자동화는 확장 전에 계측이 먼저다. 안 그러면 멋진 관제판 위에서 멋지게 비용과 diff가 같이 불어난다.

목표 조건을 잘 쓰는 법

좋은 /goal 조건은 멋진 문장이 아니라 검증 가능한 문장이다. 공식 문서는 한 가지 측정 가능한 종료 상태, 그것을 증명할 체크, 작업 중 지켜야 할 제약을 조건에 넣으라고 설명한다. 이 기준은 AI 코딩 에이전트용 Definition of Done이라고 봐도 된다.

나쁜 예시는 이렇다. “auth 모듈을 깔끔하게 리팩터링해줘.” 이 문장은 방향은 있지만 종료 조건이 없다. Claude가 파일을 나누고 이름을 바꾸고 테스트를 조금 고친 뒤 “깔끔해졌습니다”라고 말해도, 평가자는 대화 기록만 보고 진짜 깔끔한지 알기 어렵다.

좋은 예시는 더 좁고 딱딱하다. “test/auth의 모든 테스트가 통과하고, npm run lint가 0으로 종료되며, 인증 public API의 함수명은 바꾸지 않는다. 통과하지 못하면 실패한 테스트명과 남은 blocker를 요약하고 12턴 뒤 멈춘다.” 이런 조건은 에이전트에게도 사람에게도 덜 낭만적이지만 훨씬 안전하다.

내 볼트 운영 문서에서 하네스의 완료 기준을 “실행 명령 1개, 실패 복구 루프, 상태 파일 복원 가능”으로 잡아둔 것도 비슷한 이유다. 장기 작업은 역할 설명만으로 굴러가지 않는다. 실행 명령, 복구 기준, 상태 확인 방법이 같이 있어야 자동화가 일을 했는지, 일을 하는 척했는지 구분된다.

바로 써볼 만한 /goal 패턴

처음 쓸 때는 코드베이스 전체를 던지기보다 작은 폐쇄 구간을 잡는 게 낫다. 한 디렉터리, 한 테스트 스위트, 한 문서 큐처럼 작업 경계가 보이는 곳이 좋다. /goal은 세션당 하나만 활성화되므로, 여러 주제를 한 세션에 섞는 순간 목표가 서로 밀고 당긴다.

예를 들어 테스트 수정 작업이면 이렇게 시작할 수 있다.

/goal test/auth의 모든 테스트가 통과하고 npm run lint가 exit 0으로 끝난다. public API 이름은 바꾸지 말고, 10턴 안에 끝나지 않으면 실패 테스트와 남은 blocker를 요약하고 멈춘다.

문서 정리 작업이면 조건을 파일 상태로 잡는 편이 좋다.

/goal docs/migration 안의 TODO 항목이 모두 처리되고, 변경된 문서마다 검증 명령 또는 수동 확인 메모가 남아 있다. 불확실한 항목은 삭제하지 말고 "needs-owner-review"로 표시한다.

리팩터링 작업에서는 “무엇을 바꾸지 않을지”가 특히 중요하다. 자동화가 열심히 움직일수록 범위 밖 개선을 하고 싶어질 수 있기 때문이다. “새 dependency 추가 금지”, “테스트 파일 외 스냅샷 갱신 금지”, “마이그레이션 대상 모듈 밖 변경 금지” 같은 제약은 귀찮아 보여도 나중에 리뷰 시간을 줄인다.

PRD에서 작은 Goal까지 끊는 최소 템플릿

/goal을 바로 던지기 전에 더 좋은 순서가 있다.

아이디어를 PRD 한 장으로 좁히고, 구현 범위를 기능 단위로 나눈 뒤, 각 기능을 작은 Goal로 바꾸는 흐름이다.

이렇게 하면 에이전트가 “대충 멋진 앱”을 만들려고 뛰는 대신, 지금 끝내야 할 증거를 보고 움직인다.

내가 쓴다면 PRD는 길게 쓰지 않는다.

처음 5줄이면 충분하다.

PRD 5줄	적을 내용
사용자	이 기능을 누가 쓰는가
문제	지금 무엇 때문에 막히는가
성공 장면	사용자가 어떤 상태가 되면 성공인가
제외 범위	이번 Goal에서 하지 않을 것은 무엇인가
검증 증거	테스트, 화면, 로그, 문서 중 무엇을 남길 것인가

그다음 SDD는 거창한 설계 문서가 아니라 “수정할 경계”를 정하는 메모로 둔다.

예를 들어 auth 기능이면 public API, DB migration 여부, 변경 가능한 파일, 테스트 명령만 적어도 충분하다.

이 상태에서 Goal은 아래처럼 좁아진다.

/goal auth 로그인 실패 메시지를 사용자에게 보이게 한다. 변경 범위는 src/auth와 test/auth로 제한한다. public API 이름은 바꾸지 않는다. npm test -- auth와 npm run lint가 exit 0이면 완료다. 8턴 안에 끝나지 않으면 남은 blocker를 요약하고 멈춘다.

이 템플릿의 장점은 개발자가 똑똑한 척을 덜 해도 된다는 점이다.

아이디어, PRD, SDD, Goal을 전부 길게 쓰려 하면 금방 지친다.

대신 5줄 PRD와 4줄 SDD, 1개의 검증 가능한 Goal로 줄이면 에이전트도 사람도 무엇을 끝냈는지 확인하기 쉬워진다.

바이브코딩이 위험해지는 순간은 감으로 시작해서 감으로 완료 선언할 때다.

작은 Goal은 그 감에 줄자를 대는 장치에 가깝다.

언제 쓰지 않는 게 나은가

/goal은 목표가 분명한 반복 작업에 강하다. 하지만 제품 판단, 보안 승인, 데이터 삭제, 결제/배포 권한이 걸린 작업은 자동 반복에 올리기 전에 사람의 승인 지점을 따로 둬야 한다. 특히 auto mode와 같이 쓰면 도구 승인 마찰과 턴 반복 마찰이 동시에 줄어들 수 있으므로, 팀 정책이 먼저 있어야 한다.

보안 쪽에서는 “Claude가 알아서 필요한 권한을 쓰게 한다”가 아니라 “Claude가 쓸 수 있는 권한을 먼저 줄이고, 목표 조건으로 반복 범위를 묶는다”가 맞다. 프로덕션 DB, 결제 키, 배포 토큰, 고객 데이터가 걸린 저장소에서는 /goal 조건보다 sandbox, allowlist, branch/worktree 격리가 먼저다. 편해지는 순서와 안전해지는 순서는 종종 다르다.

비용도 같은 방식으로 봐야 한다. /goal은 사람이 다음 프롬프트를 안 넣어도 된다는 장점이 있지만, 그만큼 멈춤 지점을 사람이 덜 느낀다. 팀에서 쓴다면 “goal당 최대 턴 수”, “큰 diff 발생 시 중간 요약”, “테스트 실패 3회 반복 시 정지” 같은 운영 규칙을 같이 두는 편이 좋다.

팀에 붙일 때의 최소 운영표

팀에서 바로 도입한다면 기능 소개보다 운영표가 먼저다. 특히 AI 코딩 에이전트를 여러 명이 쓰는 팀은 누가 goal을 설정했고, 어떤 조건으로 완료됐고, 어떤 검증 로그가 남았는지를 나중에 볼 수 있어야 한다. /goal이 성공했다고 해서 PR 리뷰가 사라지는 건 아니다.

운영 항목	추천 기준
goal 이름	이슈 번호나 작업 범위를 포함
종료 조건	테스트, 빌드, 파일 수, 큐 상태처럼 측정 가능하게 작성
중단 조건	최대 턴 수, 최대 시간, 반복 실패 횟수 명시
변경 금지 범위	public API, 보안 설정, unrelated 파일 등
검증 로그	실행한 명령과 결과가 대화 기록에 남도록 요구
사람 리뷰	goal 완료 뒤 diff, 테스트, 권한 변경을 별도 확인

이 표를 보면 /goal은 개발자를 빼는 기능이 아니라, 개발자가 적어야 할 작업 계약을 더 또렷하게 만드는 기능에 가깝다. 에이전트가 오래 달릴수록 사람의 역할은 “다음 명령 입력”에서 “좋은 종료 조건 설계와 리뷰”로 이동한다. 손은 덜 바쁘지만 머리는 더 또렷해야 한다는 얘기다.

내가 운영한다면 이렇게 시작한다

첫 주에는 /goal을 세 가지 작업에만 붙이겠다. 첫째, 실패 테스트 복구. 둘째, 작은 마이그레이션. 셋째, 문서 TODO 큐 처리다. 이 셋은 모두 완료 조건을 transcript에 남기기 쉽고, 실패했을 때도 원인 요약이 비교적 명확하다.

반대로 첫 주에는 새 기능 전체 구현, 프로덕션 배포, 보안 정책 변경에는 쓰지 않겠다. 기능이 약해서가 아니라, 좋은 자동화일수록 처음에는 울타리가 필요해서다. 작업 울타리를 잘 치면 /goal은 “AI가 혼자 달린다”가 아니라 “사람이 정한 완료 조건까지 지치지 않고 반복한다”에 가까워진다.

그래서 이 기능을 볼 때 검색어는 “Claude Code /goal 사용법”이지만, 실제 질문은 조금 다르다. 우리 팀의 goal 조건은 평가 가능한가. Claude가 무엇을 증거로 남겨야 하는가. 그리고 끝났다고 말했을 때, 사람이 무엇을 다시 확인할 것인가.

FAQ

Claude Code /goal은 무엇인가?

Claude Code에서 /goal은 사용자가 완료 조건을 설정하면 Claude가 여러 턴을 이어가며 그 조건을 달성하려고 작업하는 기능이다. 각 턴 뒤에는 별도 평가 모델이 대화 기록을 보고 조건 충족 여부를 판단한다.

/goal과 /loop는 어떻게 다른가?

/loop는 시간 간격을 기준으로 반복 실행하는 흐름에 가깝고, /goal은 조건 충족 여부를 기준으로 다음 턴을 이어간다. 시간표가 중요하면 /loop, 완료 조건이 중요하면 /goal이 더 자연스럽다.

auto mode와 같이 쓰면 좋은가?

상황에 따라 좋을 수 있지만 먼저 권한 범위를 좁혀야 한다. auto mode는 도구 승인 마찰을 줄이고 /goal은 턴 반복을 줄이므로, 둘을 함께 쓰면 작업이 더 잘 이어지는 대신 실수도 더 멀리 갈 수 있다.

/goal 조건은 얼마나 구체적으로 써야 하나?

테스트 결과, 빌드 exit code, 파일 수, TODO 큐 상태처럼 확인 가능한 종료 조건을 넣는 게 좋다. 여기에 최대 턴 수나 시간 제한, 변경 금지 범위를 함께 쓰면 리뷰 부담이 줄어든다.

평가 모델이 직접 테스트를 실행하나?

공식 문서 기준으로 평가자는 파일이나 명령을 직접 확인하지 않는다. Claude가 실행 결과를 대화에 남겨야 평가자가 그 기록을 보고 판단할 수 있다.

어떤 작업에는 쓰지 않는 게 좋나?

보안 승인, 결제/배포 권한, 프로덕션 데이터 수정, 제품 방향 결정처럼 사람 판단이 필요한 작업은 /goal 단독으로 맡기지 않는 편이 안전하다. 이런 작업은 승인 게이트와 sandbox를 먼저 설계해야 한다.

Claude Code /goal 기능 사용법 2026 – 자동 반복 실행보다 먼저 볼 목표 조건 체크리스트