[기술검토] /goal 커맨드 — 헤드리스 자동화 파이프라인에서 사용 불가

📌 Claude Code 내장 커맨드 /goal을 자체 구축 멀티에이전트 하네스(이하 AI 개발 파이프라인)에서 쓸 수 있는지 실측 검증한 문서. 결론: 자동 모드(claude -p)에서는 사용 불가이며, 같은 효과는 스킬 markdown 본문에 재시도 규칙을 적는 것으로 충분히 낼 수 있다.

결론 (한 줄)

/goal은 헤드리스 자동화 파이프라인에서 사용할 수 없다. 비슷한 "조건 충족까지 반복" 효과가 필요하면, 스킬(.md) 본문에 재시도 규칙을 글로 적는 것만으로 충분히 흉내 낼 수 있다.

---

1. /goal이 뭔가?

Claude Code v2.1.139(2026-05-12 출시)에 추가된 공식 내장 슬래시 커맨드.

사용자가 자연어로 완료 조건을 정해주면, Claude가 그 조건이 만족될 때까지 자동으로 여러 턴 작업을 반복한다. 각 턴 끝에 별도의 평가용 모델(Haiku)이 "조건이 충족됐는지" 판정하고, 아직이면 또 작업하고, 충족되면 멈춘다.

핵심: 사람이 옆에서 채팅창 보고 있는 대화형 모드에서 쓰는 기능이다.

---

2. 파이프라인 하네스는 어떻게 돌아가나? (배경)

이 시스템은 사용자가 칸반 카드를 다음 단계로 옮기면, 백엔드가 자동으로 다음과 같은 명령 한 줄을 백그라운드에서 실행한다:

claude -p "/마켓정산자동화 {JIRA_KEY} models=claude,gemini,chatgpt" \
  --output-format stream-json

풀어보면:

• claude -p — 사람과 대화하지 않는 자동 모드 (한 번 실행 → 결과 받음 → 끝)
• "/마켓정산자동화 ..." — 직접 만든 사용자 정의 스킬 실행
• {JIRA_KEY} — 해당 카드의 Jira 이슈 번호
• models=claude,gemini,chatgpt — 여러 AI 모델을 함께 돌리는 옵션
• --output-format stream-json — 결과를 JSON 스트림으로 받기

흐름 그림:

이게 파이프라인의 기준선이다.

---

3. 왜 이 시스템에서 /goal을 못 쓰는가?

이유는 두 가지. 둘 다 단독으로도 사용 불가 사유가 된다.

이유 1 — 자동 모드(claude -p)에서 빌트인 슬래시 커맨드는 막혀 있다 (실측)

/goal을 파이프라인 호출 형식에 그대로 넣어 실행해봤다:

$ claude -p "/goal CLAUDE.md 파일이 현재 디렉토리에 존재한다"
/goal isn't available in this environment.

$ claude -p "/help"
/help isn't available in this environment.

/goal 뿐 아니라 /help 같은 빌트인 슬래시 커맨드 전부가 자동 모드에서 비활성화돼 있음을 확인. 매일 쓰는 /마켓정산자동화 같은 사용자 정의 스킬만 자동 모드에서 동작한다.

왜? 슬래시 커맨드는 사람이 채팅창에 입력하면 Claude Code가 그걸 가로채서 처리하는 구조다. 자동 모드는 그 "사람의 채팅창"이 존재하지 않으므로, 가로챌 곳이 없다. 버그가 아니라 모드 자체의 성격이다.

이유 2 — /goal의 "대화하며 반복" 모델은 fire-and-forget 구조와 안 맞는다

설사 자동 모드에서 /goal이 동작하도록 누군가 패치한다 해도, /goal은 살아있는 대화 세션을 유지하면서 여러 턴을 주고받는 모델이다. 메인 Claude와 평가자 Haiku가 계속 의견을 주고받아야 한다.

반면 이 하네스는:

이 두 모델은 구조적으로 호환되지 않는다. /goal을 그대로 끼우려면 헤드리스 실행 워커 자체를 "대화형 세션을 유지하는 형태"로 갈아엎어야 하는데, 이건 파이프라인의 근간(fire-and-forget WebSocket 콜백)을 뜯어내는 일이라 사실상 다른 시스템을 새로 만드는 것에 가깝다.

---

4. 그래도 비슷한 효과가 필요하다면? (권장 대안)

/goal이 주려 한 가치는 **"조건이 충족될 때까지 자동으로 반복"**이다. 이 시스템에서 이걸 흉내 내는 가장 간단한 방법은 스킬 markdown 파일 본문에 그 규칙을 글로 적어두는 것이다.

핵심 사실 한 가지

자동 모드(claude -p)는 싱글턴(한 턴만 돌고 끝남)이 아니다. "사람과 대화하지 않을 뿐", 한 번의 호출 안에서 Claude는 여러 번 추론하고, 여러 번 도구를 호출하고, 여러 번 코드를 고칠 수 있다. 종료 조건은 (a) 모델이 "다 됐다"고 판단할 때 또는 (b) --max-turns 한계에 도달할 때.

→ 그러므로 스킬 본문에 "실패하면 다시 해라" 규칙을 적기만 하면, 한 번의 claude -p 호출 안에서 자동 반복이 일어난다.

적용 예시 — 어떤 스킬이든 본문 끝에 이런 문단 추가

## 자체 재시도 루프

- 작업 후 검증(테스트/lint/문법 등)을 수행한다.
- 결과가 PASS가 아니면 원인을 진단하고 수정한 뒤 다시 검증한다.
- 최대 5회까지 반복한다. 5회 후에도 실패면 FAIL로 종료한다.
- 종료 시 `verification_result.json` 에 최종 상태(PASS/FAIL)와 시도 횟수를 기록한다.

그리고 스테이지 스킬 설정에서 max_turns를 30~50 정도로 넉넉히 잡아두면 끝. 백엔드 코드는 한 줄도 안 건드린다.

/goal과의 차이점

💡 자가 평가의 편향이 걱정된다면, 검증 기준을 숫자로 명확히 적는 게 좋다 (예: "테스트 N개 모두 exit 0", "lint 에러 0건"). 추상적 기준일수록 자가 평가가 편향되기 쉽다.

---

5. (참고) 본격적으로 외부 평가자를 두고 싶다면

자가 평가가 끝내 신뢰가 안 가서 "꼭 외부 평가자가 별도로 판정해야 한다"는 요구가 있다면, 백엔드 자체에 평가-재실행 루프를 직접 만드는 방법이 있다. 카드 콜백을 받을 때마다 결과를 평가해서, 조건 미충족이면 같은 스킬을 다시 디스패치하는 식.

이 방향은 구현 비용이 크고 데이터 스키마 변경도 필요하다 — 4번 대안이 부족할 때만 검토.

---

6. 요약

---

7. 참고

• 검증 일자: 2026-05-14
• 검증 환경: macOS, Claude Code CLI
• 검증 명령:
  • claude -p "/goal CLAUDE.md 파일이 현재 디렉토리에 존재한다" --max-turns 5 → /goal isn't available in this environment.
  • claude -p "/help ..." --max-turns 2 → /help isn't available in this environment.
• 기준선 호출 형식: claude -p "/<스킬> {JIRA_KEY} models=claude,gemini,chatgpt" --output-format stream-json
• 공식 문서 (/goal): https://code.claude.com/docs/en/goal