| name | harness-workflow |
| description | Jira 이슈 풀사이클 유일 진입점 — start(브랜치+In Progress)→grill(요구 명확화)→plan(dev-guide)→contract→[compile]→execute(dynamic Workflow 레인 / unattended 러너)→review(fan-out+Codex)→gate(테스트+DoD+커밋)→complete(QA 전이+closure ingest)를 자동 시퀀싱. '/harness-workflow', 'harness workflow', '전체 워크플로우', '이슈 전체 진행', '풀사이클', '이슈 시작해줘', '작업 시작', '브랜치 만들어줘', '티켓 잡아줘', '테스트 돌려줘', '커밋해줘', 'DoD 체크', '이어서 작업', '이전 작업 복원' 요청 시 사용 (구 /jira-start·/jira-clarify·/jira-test·/jira-commit·/harness-resume 는 2026-07-20 폐기 — 전부 이 워크플로의 내부 단계). |
/harness-workflow — 통합 오케스트레이터 (유일 진입점)
직교 원칙: 유지되는 Jira/Harness 스킬은 수정하지 않고 Skill() 로 호출. 상세 절차는 단계 진입 시에만 references/<단계>.md 를 Read (lazy-load 를 단계 레벨까지 연장).
폐기된 단독 명령 (2026-07-20, harness v2 설계 §3·ADR-106): /jira-start /jira-clarify /jira-test /jira-commit /harness-resume — 사용자가 이 이름으로 요청하면 해당 단계만 이 워크플로 절차로 수행하면 된다 (풀사이클 강제 아님).
Usage
/harness-workflow <KEY> # 단일 이슈 (BE+FE 걸치면 자동 2레인)
/harness-workflow <KEY1> <KEY2> ... # 다중부모 fan-out (worktree 격리 — references/parallel-modes.md)
⛔ Guard — HARNESS_MODE (최우선)
HARNESS_MODE 확인: suggest/auto 면 진행, 미설정/빈값/off 면 안내 후 중단. 정책 SSoT: ~/.claude/skills/_harness-guard.md (Skill() 호출 금지 — Read 또는 env 직접 확인).
단계 결정표
| # | 단계 | 하는 일 | 상세/호출 | 산출물 | 게이트 |
|---|
| ① | start | 이슈 조회·브랜치·assignee·In Progress | references/start.md | feat/<KEY> 브랜치 | — |
| ② | grill | 요구·결정사항 확정 (모호할 때만, 한 번에 한 질문) | Skill('grilling') + references/clarify.md (사전 크롤링) | 확정 결정 목록 | 이슈가 이미 구체적이면 skip |
| ③ | plan | recon → dev-guide 생성 (+ ingest forecast 자동 chain) | Skill('jira-plan', <KEY>) 필수 — 우회 금지 (§6 forecast 발화) | docs/<KEY>-dev-guide.md | INDEX.md cross-ref 선조회 (ALWAYS) |
| ④ | contract | DoD·Verify Targets·인간게이트 명시 | Skill('harness-plan', <KEY>) | .claude/runtime/sprint-contract/<KEY>.md | — |
| — | 승인 | dev-guide+contract 요약 제시 | — | — | 사용자 승인 필수 (수정 요청 시 ③ 복귀) |
| ⑤ | compile | (opt-in) dev-guide → step 컴파일 | Skill('jira-compile', <KEY>) — 대형 이슈·무인 실행 시에만 | phases/<KEY>/index.json + step*.md | 소형 이슈는 skip (러너는 opt-in) |
| ⑥ | execute | 구현 | attended: dynamic Workflow 레인 (references/parallel-modes.md — 모든 agent() 에 opts.model, 스모크 프로브) / unattended: harness-execute.py 러너 | 코드 + step summary | blocked/error 시 인간 개입 |
| ⑦ | review | fan-out 전문 리뷰 + Codex adversarial (scripts/codex-review.sh 래퍼) | Skill('harness-review') | .claude/runtime/aggregate-verdict.md | PASS→⑧ / ITERATE(≤3)→수정 후 재리뷰 / ESCALATE→재계획 |
| ⑧ | gate | 테스트+빌드 GREEN → DoD → 커밋 → Jira 댓글 | references/gate.md + Skill('harness-gate') | commit SHA | review-gate hook 이 verdict≠PASS commit 물리 차단 (JSON deny) |
| ⑨ | complete | QA 전이 + push + closure ingest + wiki-lint | Skill('jira-complete', <KEY>) 필수 — 우회 금지 (§4.4/4.6/4.7 chain 발화) | INDEX row closed·LOG append | — |
Phase 반복: contract 의 Phase 수만큼 ⑥→⑦ 을 Phase 단위로 반복 (Inner Loop 는 같은 Phase 안에서만 — Phase 간 blocker 는 ESCALATE).
병렬 모드 (fan-out 표준 = dynamic Workflow)
- 모드 결정: 부모 키 2개 이상 → 다중부모 fan-out / 단일 이슈 BE+FE → 2레인. 두 모드 모두
references/parallel-modes.md 가 SSoT.
- Agent Teams 신규 사용 금지 (실측 결함 4건 — LOG 228·632, CHANGELOG 116·235). 구
--subtasks 정식 모드(ADR-070)는 표면 제거 — Jira 하위이슈가 있으면 댓글/전이만 부모와 함께 처리하고, 병렬 실행 단위는 위 2모드로 판단.
- 모델 티어링(메인=fable): fable=orchestration·verify·크로스레인 seam / opus=난이도 상 / sonnet=중·하. 규칙 3개(전
agent() model 명시·스모크 프로브·fable 레인 사유 필수)는 references/parallel-modes.md.
재개 (구 /harness-resume 폐기)
중단된 작업 재개 = 상태 파일 읽고 이어가기 한 줄:
phases/<KEY>/index.json 있으면 첫 pending step 부터 (러너/컴파일 이슈).- 없으면
.claude/runtime/workflow-state.json(이슈별 임시 산출물) + sprint-contract/<KEY>.md + 최신 aggregate-verdict.md 를 Read 후 결정표의 해당 단계부터 재개.
- Jira 상태는 건드리지 않는다 (이미 ① 이 처리).
에러 핸들링
| 에러 | 처리 |
|---|
| 브랜치 충돌 | 사용자 알림, 수동 해결 후 재시도 |
| 빌드 실패 | 프로젝트 build-resolver 에이전트 제안 |
| 리뷰 에이전트 미존재 | 해당 축 스킵 + 경고 |
| Codex 래퍼 exit 42 | opus skeptic workflow 자동 폴백, verdict 에 codex=fallback(<사유>) |
| 3회 ITERATE 동일 blocker | ESCALATE → 재계획 제안 |
HARNESS_MODE 동작
| 모드 | 동작 |
|---|
auto | 전체 자동 진행, 승인 게이트만 수동. review-gate 가 commit 물리 차단 |
suggest | plan/review/gate 단계마다 사용자 확인. review-gate 는 경고만 |
off | 워크플로 호출은 동작하나 hook 비활성 |
자기 점검 (종료 직전)
docs/INDEX-SCHEMA.md 존재 시 — ③ ingest forecast + ⑨ closure ingest + wiki-lint summary 호출 흔적이 대화에 모두 있어야 함. 누락 감지 → 즉시 일괄 호출 + 사용자 보고.
