fix: Phase 번호 일관성·Incremental QA 훅·사용자 핸드오프 3건

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 이 프로젝트는 [Semantic Versioning](https://semver.org/)을 따릅니다.
 
+## [Unreleased]
+
+### Fixed
+
+- **Phase 번호 일관성** — `SKILL.md` Phase 5-5와 산출물 체크리스트가 "오케스트레이터 Phase 1에 컨텍스트 확인"으로 기술했지만, `orchestrator-template.md` 템플릿 A/B는 `Phase 0: 컨텍스트 확인`, `Phase 1: 준비`로 구성되어 있어 문서 내부 모순이 존재. SKILL.md 측을 "Phase 0"으로 통일하고 "워크플로우 시작부"라는 의미 기반 설명을 덧붙여 번호 의존에 따른 재발을 완화
+- **Incremental QA 원칙의 템플릿 반영** — `SKILL.md` Phase 3은 "QA는 각 모듈 완성 직후 점진적으로 실행"을 강제하지만, `orchestrator-template.md` 템플릿 A/B는 Phase 4를 "전체 완성 후 통합 검증"으로만 기술하여 템플릿을 복사한 사용자가 자연스럽게 폭포수 QA로 회귀할 위험. "QA 에이전트 포함 시 공통 규칙 (Incremental QA)" 섹션을 신설하여 템플릿 A/B/C 모두에 "각 산출 Phase 끝에 검증 훅 삽입" 규칙을 공통 적용
+
+### Added
+
+- **Phase 6-7: 사용자 핸드오프** — 구축 직후 사용자가 하네스 호출법을 모르는 공백을 제거. 트리거 예문 2~3개 제시, 단순 질문 vs 하네스 호출 구분, 재실행·수정 키워드 공유, 산출물 위치 안내를 포함하는 보고 규칙을 Phase 6 말미에 추가
+
 ## [1.2.1] - 2026-04-18
 
 ### Fixed

skills/harness/SKILL.md

@@ -274,8 +274,8 @@ Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:
 - "{도메인}의 {부분작업}만 다시"
 - "이전 결과 기반으로", "결과 개선"
 
-**2. 오케스트레이터 Phase 1에 컨텍스트 확인 단계 추가:**
-워크플로우 시작 시 기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다:
+**2. 오케스트레이터 Phase 0에 컨텍스트 확인 단계 추가:**
+워크플로우 시작부(Phase 0)에서 기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다. Phase 1(준비)보다 먼저 실행되어야 `_workspace/` 보존·이동 판단이 선행된다:
 - `_workspace/` 존재 + 사용자가 부분 수정 요청 → **부분 재실행** (해당 에이전트만 재호출)
 - `_workspace/` 존재 + 사용자가 새 입력 제공 → **새 실행** (기존 _workspace를 `_workspace_prev/`로 이동)
 - `_workspace/` 미존재 → **초기 실행**
@@ -346,6 +346,22 @@ Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:
 - 오케스트레이터 스킬에 `## 테스트 시나리오` 섹션 추가
 - 정상 흐름 1개 + 에러 흐름 1개 이상 기술
 
+#### 6-7. 사용자 핸드오프
+
+검증까지 끝났다면 **사용자가 이 하네스를 실제로 깨우는 방법**을 알려준다. 구축 직후 사용자가 "이걸 어떻게 부르지?"하고 막히는 공백을 제거한다.
+
+핸드오프 보고서에 포함할 것:
+
+1. **트리거 예문 2~3개** — 실제 호출해보면 되는 자연어 문장
+   - 예: "AI 학습 진도 점검해줘", "Week 3 LoRA 공부 시작할게"
+2. **단순 질문 vs 하네스 호출 구분**
+   - 단순 질문("토크나이저가 뭐야?")은 오케스트레이터 없이 직접 응답
+   - 다단계 워크플로우가 필요한 요청만 하네스 호출
+3. **재실행·수정 요청 표현** — description에 넣은 후속 작업 키워드를 사용자에게도 공유 (예: "결과 수정", "보완", "부분 재실행")
+4. **산출물 위치** — `_workspace/` 경로와 최종 산출물 경로
+
+사용자에게 이 정보를 단일 메시지로 한 번만 보고하고, 스킬 실행은 종료한다. 사용자가 시도하고 막히면 그때 Phase 7(진화)로 돌아온다.
+
 ### Phase 7: 하네스 진화
 
 하네스는 한 번 만들고 끝나는 정적 산출물이 아니다. 사용자 피드백에 따라 계속 진화하는 시스템이다.
@@ -431,7 +447,7 @@ Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:
 - [ ] 트리거 검증 (should-trigger + should-NOT-trigger) 완료
 - [ ] **CLAUDE.md에 하네스 포인터 등록** (트리거 규칙 + 변경 이력)
 - [ ] **CLAUDE.md 변경 이력에 에이전트/스킬 추가/삭제/수정 기록**
-- [ ] **오케스트레이터 Phase 1에 컨텍스트 확인 단계** (초기/후속/부분 재실행 판별)
+- [ ] **오케스트레이터 Phase 0에 컨텍스트 확인 단계** (초기/후속/부분 재실행 판별)
 
 ## 참고
 

skills/harness/references/orchestrator-template.md

@@ -264,6 +264,24 @@ description: "{도메인} 오케스트레이터 (하이브리드). {키워드}.
 
 ---
 
+## QA 에이전트 포함 시 공통 규칙 (Incremental QA)
+
+템플릿 A/B/C 모두에 공통 적용되는 규칙. QA 에이전트가 팀에 포함된 경우, QA를 **마지막 통합 단계에만** 배치하지 말고 **각 산출 Phase 끝에 검증 훅(hook)을 삽입**한다.
+
+**왜 그래야 하는가**: QA를 마지막에만 두면 경계면 버그가 누적·전파되어 수정 비용이 급증한다. 각 모듈 완성 직후 즉시 교차 검증해야 초기 불일치를 잡는다 (`qa-agent-guide.md` 참조).
+
+**적용 방법**:
+
+- **템플릿 A (에이전트 팀)**: Phase 3의 각 팀원 산출물이 완성될 때마다 QA에게 SendMessage로 즉시 검증 요청. 팀원이 다음 작업으로 넘어가기 전에 QA 피드백 반영.
+- **템플릿 B (서브 에이전트)**: 병렬 실행 그룹이 끝날 때마다 QA 서브 에이전트를 호출. 다음 그룹 투입 전 경계면 검증.
+- **템플릿 C (하이브리드)**: 각 Phase 말미에 `**QA 훅:**` 단계를 명시하고, 해당 Phase의 산출물만을 대상으로 부분 검증.
+
+**공통 산출물**: `_workspace/{phase}_qa_report.md` (통과/실패/미검증 항목 분리). 실패 시 해당 생성 에이전트에게 즉시 피드백 → 수정 → 재검증.
+
+QA 에이전트가 팀에 없으면 이 규칙은 적용하지 않는다.
+
+---
+
 ## 작성 원칙
 
 1. **실행 모드를 먼저 명시** — 오케스트레이터 상단에 "에이전트 팀" / "서브 에이전트" / "하이브리드" 중 하나 명시. 하이브리드면 Phase별 모드 표 필수