끝나는 조건만 선언하면, 세션이 그 조건이 성립할 때까지 턴을 이어가는 조건 선언형 자율 루프입니다. 매 턴 끝에 평가기가 조건을 검사해, 조건이 채워지면 루프가 스스로 멈춥니다. 사용자가 매 단계마다 “계속"을 누르지 않아도 됩니다.

정보

v3.1 신규: 무한 지속 가능한 목표(–max-turns 0), 반자율 모드의 흐름, 그리고 블록 상한 자동 조정이 이번 릴리스에 추가됐습니다.

/moai goal은 세션에 완료 조건 하나를 등록하고 무장(arm)합니다. 조건 문장은 두 종류 술어로 파싱됩니다.

• 기계 조건 (mechanical) — 셸 명령의 종료 코드로 참거짓을 판정합니다. 예: “go test ./... exits 0”.
• 모델 조건 (model) — 대화 기록에 특정 줄이 드러났는지로 판정합니다. 예: “모든 AC 행이 PASS로 기록됐다”.

등록한 조건은 moai hook stop-goal Stop-훅 평가기가 매 턴 끝에 읽어들입니다. 조건이 성립하지 않으면 평가기가 턴을 막아(block) 다음 턴으로 이어 붙이고, 조건이 성립하면 루프가 끝납니다. 따라서 사용자가 한 번이라도 덜 입력해도 긴 호라이즌 작업이 멈추지 않고 굴러갑니다.

긴 호라이즌 작업 — 다중 마일스톤 run, 대규모 리팩터, TDD 사이클 — 에서 가장 비싼 비용은 매 턴마다 사용자가 “계속"을 누르는 왕복입니다. 한 번의 /moai run SPEC-X는 구현 에이전트를 부르지만, 그 에이전트가 돌아왔을 때 다음 턴을 누가 이어 붙일까요? 보통은 사용자가 다시 프롬프트를 입력해야 합니다.

/moai goal은 이 왕복을 없앱니다. 조건을 한 번 선언하면, 평가기가 매 턴 끝에 “아직 조건이 안 채워졌다"를 판정해 자동으로 다음 턴을 열어 줍니다. 작업이 끝나는 조건이 기계적으로 검증 가능하다면, 사용자는 한 번의 명령으로 전체 사이클을 몰아갈 수 있습니다. 그래서 하네스 설계의 “사용자 개입 최소화” 원칙이 이 명령 하나로 현실이 됩니다.

다만 무조건 혼자 돌아가는 것은 아닙니다. /moai goal은 arm-only, 즉 “조건을 등록하고 턴을 이어 붙이는 역할만” 합니다. 조건이 등록됐을 때 진짜 일을 시작하는 명령(/moai run SPEC-X 등)이 짝으로 와야 합니다. 조건만 덩그러니 무장하고 일을 시작하지 않으면, 매 턴 끝에 조건이 안 채워졌으니 턴만 빙빙 도는 idle loop가 됩니다.

# 조건 등록 + 무장
> /moai goal "go test ./... exits 0 && lint is clean, or stop after 20 turns"

# 상태 확인
> /moai goal status

# 모든 세션의 골 상태 확인
> /moai goal status --all

# 루프 중단
> /moai goal clear

조건 문장은 큰따옴표로 감쌉니다. 기계 조건은 평가기가 매 턴 끝에 실제로 실행하므로, 빠르고 결정적인 명령(go test -run <pattern>)이 느린 전체 스위트(go test ./...)보다 턴마다 부담이 적습니다.

1. 하나의 측정 가능한 끝 상태 — 테스트 결과, 빌드 종료 코드, 파일 개수, 큐가 비었는지. 추상적 목표(“코드가 좋아진다”)는 기계나 모델 어느 쪽에서도 판정할 수 없습니다.
2. 측정 방식 명시 — “go test ./... exits 0”, “git status is clean”. “테스트가 통과한다"만으로는 평가기가 무엇을 실행할지 알 수 없습니다.
3. 제약 조건 포함 — “이때 다른 테스트 파일은 건드리지 않는다”. 끝 상태만 보면 중간 과정에서 의도치 않은 것을 바꿀 수 있습니다.

/moai goal은 다음 네 가지 상황에서 진가를 발휘합니다.

• T1 — 긴 run-phase / 다중 마일스톤 SPEC (Tier M/L): run-phase 자율성 배선(run.md의 ac_converge 블록)이 이 경우를 소유합니다. SPEC의 모든 수용 기준(AC)이 PASS로 뜰 때까지 run 페이즈를 이어 붙입니다.
• T2 — 대규모 마이그레이션 / 여러 호출 지점을 건드는 리팩터: 모든 호출 지점이 컴파일되고 테스트가 통과할 때까지 루프를 돕니다. 호출 지점 목록이 대화에 드러난 뒤에 무장하는 것이 전제입니다.
• T3 — TDD 사이클 / AC 수렴: RED-GREEN-REFACTOR 루프를 돌며 목표 테스트 스위트가 green이고 린트가 깨끗할 때까지 이어 붙입니다.
• T4 — /moai loop 대안: “도구 진단이 지적하는 것을 고친다”(/moai loop)와 “선언한 끝 상태가 참이 될 때까지 굴러간다”(/moai goal) 사이의 선택입니다. 끝이 명확하면 /moai goal이 더 적합합니다.

--max-turns 0으로 턴 상한을 끄면 벽시계 / 정체 가드가 걸기 전까지 루프가 멈추지 않습니다. 긴 unattended run에 적합한 형태입니다.

# 4시간 벽시계 상한, 턴 무제한
> /moai goal "<condition>" --max-turns 0 --max-duration 14400

다만 Claude Code 런타임의 연속 블록 상한(CLAUDE_CODE_STOP_HOOK_BLOCK_CAP, 기본 8)이 턴 상한보다 먼저 루프를 끊어 버립니다. 무한 골을 무장할 때는 이 상한도 함께 올려야 합니다.

# 블록 상한을 200으로 올려 무한 루프가 진짜로 지속되게 만든다
$ CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=200
> /moai goal "<condition>" --max-turns 0 --max-duration 14400

v3.1부터 moai goal arm --max-turns 0으로 무장하거나 칸반 모드 진입 시 런처가 이 상한을 자동으로 200으로 주입합니다. 그래서 사용자가 직접 환경변수를 건드리지 않아도 4시간짜리 체인이 중간에 끊기지 않습니다.

/moai goal은 arm-only입니다. 조건을 등록하고 턴을 이어 붙일 뿐, 스스로 일을 시작하지 않습니다. 따라서 항상 일을 시작하는 명령과 짝으로 씁니다.

# 잘못된 형태 — 골만 무장하고 일을 시작하지 않는다 (idle loop)
> /moai goal "<condition>"

# 올바른 형태 — run 명령과 같은 턴에 무장
> /moai run SPEC-X     # 일을 시작
> /moai goal "<condition>"   # run이 끝날 때까지 턴을 이어 붙임

무장된 골은 안전 경계를 늦추지 않습니다:

• 구현 착수 승인 (plan→run 휴먼 게이트)은 여전히 필수입니다. 골을 무장했다고 해서 run-phase 진입이 사전 승인되지 않습니다.
• 되돌리기 어려운 / 공유 시스템 액션 (PR 생성, 파괴적 연산)의 확인 경계도 그대로입니다. 평가기는 “턴을 이을지"만 결정하며, 파괴적 연산을 사전 승인하지 않습니다.

매 턴 끝에 평가기가 기계 조건 명령을 실행합니다. 따라서 턴마다 드는 비용은 곧 조건에 들어간 명령의 비용입니다. 빠르고 결정적인 명령을 쓰면 턴 루프가 촘촘해집니다. Stop-훅 타임아웃은 120초이지만, 더 빠른 명령이 루프를 더 민첩하게 만듭니다. 모델 조건은 이미 존재하는 대화 기록을 판정하므로 별도의 추가 비용이 없습니다.

/moai goal과 /moai loop는 보완 관계입니다. /moai loop는 “도구가 지적하는 것을 전부 고친다"에 적합하고, /moai goal은 “선언한 끝 상태가 참이라고 입증될 때까지 굴러간다"에 적합합니다. 같은 골 엔진 위에서 돌지만, 무엇이 “끝"인지를 결정하는 주체가 다릅니다.

• /moai loop — 진단 주도의 결정적 루프. 무엇을 고칠지 도구가 판정한다는 점이 다릅니다. /moai loop는 유틸리티 명령어 섹션에 있습니다.
• /moai run — 일을 시작하는 명령. goal과 짝으로 씁니다. /moai run.
• 칸반 모드 — /moai goal의 무한 지속 골을 plan → run → verify → sync 체인으로 묶은 진입 스위치. 칸반 모드에서 다룹니다.

• 일을 시작하지 않습니다 — arm-only입니다. 조건만 무장하고 일을 시작하지 않으면 idle loop가 됩니다.
• 휴먼 게이트를 넘지 않습니다 — 구현 착수 승인, PR 생성 등 되돌리기 어려운 결정은 여전히 사용자 고유 권한입니다.
• hooks 비활성화 상태에서는 동작하지 않습니다 — disableAllHooks나 allowManagedHooksOnly가 켜져 있으면 Stop-훅 평가기 자체가 안 돌아, 표준 매 턴 수동 흐름으로 내려갑니다 (graceful degradation).
• 네이티브 /goal과 충돌하지 않습니다 — 런타임이 네이티브 /goal 활성 신호를 보내면 MoAI 평가기는 양보합니다 (이중 블록 방지).

• 자율 연속 루프 — goal 엔진의 정체 가드와 상한 의미론
• 칸반 모드 — kanban_chain 골 프리셋으로 엮인 4-단계 체인
• /moai loop — 진단 주도의 결정적 루프 (형제 명령)
• 하네스 엔지니어링 — 루프와 관찰이 하네스 학습으로 흐르는 경로