feat(harness): add interview-driven HRD workflow and HITL architecture review gates

skills/harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: harness
-description: "하네스를 구성합니다. 전문 에이전트를 정의하며, 해당 에이전트가 사용할 스킬을 생성하는 메타 스킬. (1) '하네스 구성해줘', '하네스 구축해줘' 요청 시, (2) '하네스 설계', '하네스 엔지니어링' 요청 시, (3) 새로운 도메인/프로젝트에 대한 하네스 기반 자동화 체계를 구축할 때, (4) 하네스 구성을 재구성하거나 확장할 때, (5) '하네스 점검', '하네스 감사', '하네스 현황', '에이전트/스킬 동기화' 등 기존 하네스 운영/유지보수 요청 시 사용."
+description: "하네스를 구성합니다. 사용자 인터뷰로 요구사항을 수집하고, HRD(Harness Requirements Document)를 작성하며, 전문 에이전트를 정의하고 스킬을 생성하는 메타 스킬. (1) '하네스 구성해줘', '하네스 구축해줘' 요청 시, (2) '하네스 설계', '하네스 엔지니어링' 요청 시, (3) 새로운 도메인/프로젝트에 대한 하네스 기반 자동화 체계를 구축할 때, (4) 하네스 구성을 재구성하거나 확장할 때, (5) '하네스 점검', '하네스 감사', '하네스 현황', '에이전트/스킬 동기화' 등 기존 하네스 운영/유지보수 요청 시, (6) '하네스 인터뷰', '요구사항 정의', 'HRD 작성' 요청 시 사용."
 ---
 
 # Harness — Agent Team & Skill Architect
@@ -20,7 +20,14 @@ description: "하네스를 구성합니다. 전문 에이전트를 정의하며,
 하네스 스킬이 트리거되면 가장 먼저 기존 하네스 현황을 확인한다.
 
 1. `프로젝트/.claude/agents/`, `프로젝트/.claude/skills/`, `프로젝트/CLAUDE.md`를 읽는다
-2. 현황에 따라 실행 모드를 분기한다:
+2. `_workspace/harness-design/` 디렉토리를 확인하여 HRD 상태를 감지한다 (상세: `references/hrd-template.md`의 6-상태 감지 테이블 참조):
+   - **신규** (디렉토리 없음) → Phase 1 인터뷰부터
+   - **요구사항 작성됨** → Phase 2부터
+   - **아키텍처 승인 대기** → HITL Gate 1 재표시
+   - **아키텍처 승인됨** → Phase 4부터
+   - **스킬 승인 대기** → HITL Gate 2 재표시
+   - **전체 승인 완료** → 파일 생성 Phase로 진행
+3. 현황에 따라 실행 모드를 분기한다:
    - **신규 구축**: 에이전트/스킬 디렉토리가 없거나 비어있음 → Phase 1부터 전체 실행
    - **기존 확장**: 기존 하네스가 있고 새 에이전트/스킬 추가 요청 → 아래 Phase 선택 매트릭스에 따라 필요한 Phase만 실행
    - **운영/유지보수**: 기존 하네스의 감사·수정·동기화 요청 → Phase 7-5 운영/유지보수 워크플로우로 이동
@@ -34,10 +41,22 @@ description: "하네스를 구성합니다. 전문 에이전트를 정의하며,
 3. 기존 에이전트/스킬 목록과 CLAUDE.md 기록을 대조하여 불일치(drift)를 감지한다
 4. 감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다
 
-### Phase 1: 도메인 분석
-1. 사용자 요청에서 도메인/프로젝트 파악
-2. 핵심 작업 유형 식별 (생성, 검증, 편집, 분석 등)
-3. Phase 0 감사 결과를 기반으로 기존 에이전트/스킬과의 충돌/중복 분석
+### Phase 1: 인터뷰 & 요구사항 정의
+
+Phase 0 분류 결과에 따라 인터뷰를 수행하고 HRD(Harness Requirements Document)를 생성한다. HRD는 `_workspace/harness-design/hrd-{YYYYMMDD-HHmmss}.md`에 저장하며, 불변 스냅샷 원칙을 따른다 (상세: `references/hrd-template.md` 참조).
+
+**Phase 0 분류별 동작:**
+- **신규 구축** → 5축 인터뷰 실행 → HRD §1(요구사항) 생성
+- **기존 확장** → 축소 인터뷰 (변경 관련 축만 확인) → HRD §1 생성
+- **운영/유지보수** → 인터뷰 건너뜀, Phase 7-5로 이동
+
+**5축 인터뷰 프레임** (상세: `references/interview-guide.md` 참조):
+- 5개 축(도메인, 작업 유형, 입출력, 품질 기준, 재사용성)을 기준으로 정보를 평가한다
+- 3축 이상 파악 → 나머지 추론 후 HRD 즉시 작성 (추론 내용에 "(추론)" 표기)
+- 2축 이하 파악 → 3~5개 질문 생성 (예시 답변 포함)
+- 5축 모두 포함된 요청 → Fast Path: 질문 없이 즉시 HRD 작성
+
+**인터뷰 완료 후:**
 4. 프로젝트 코드베이스 탐색 — 기술 스택, 데이터 모델, 주요 모듈 파악
 5. **사용자 숙련도 감지** — 대화의 맥락 단서(사용 용어, 질문 수준)로 기술 수준을 파악하고, 이후 커뮤니케이션 톤을 조절한다. 코딩 경험이 적은 사용자에게는 "assertion", "JSON schema" 같은 용어를 설명 없이 쓰지 않는다.
 
@@ -75,6 +94,20 @@ description: "하네스를 구성합니다. 전문 에이전트를 정의하며,
 
 전문성·병렬성·컨텍스트·재사용성 4축으로 판단한다. 상세 기준표는 `references/agent-design-patterns.md`의 "에이전트 분리 기준" 참조.
 
+#### 2-4. HRD 아키텍처 섹션 작성 & HITL Gate 1
+
+아키텍처 설계 완료 후, HRD에 §2(팀 아키텍처 설계) 섹션을 추가한 **새 스냅샷**을 생성한다. 사용자에게 다음을 표시한다:
+1. 에이전트 목록 테이블 (에이전트명, 타입, 역할, 스킬)
+2. 아키텍처 패턴 설명 (파이프라인/팬아웃팬인/팀 등)
+3. ASCII 아키텍처 다이어그램 (80자 폭, `references/hrd-template.md`의 패턴별 템플릿 준수)
+4. "이 하네스 구조가 맞나요? 수정이 필요하면 말씀해주세요."
+
+**승인 시** → 현재 HRD를 복사하여 `*-arch-approved.md` 생성 → Phase 3 진행
+**거절 시** → 사용자 피드백 캡처 → 새 HRD 스냅샷 생성 (원본 보존) → Phase 2 반복
+**모호 시** → "수정이 필요하시면 구체적으로 말씀해주세요. 이대로 진행하려면 '진행'이라고 해주세요." 재질문
+
+승인/거절/모호 판정 규칙: `references/hrd-template.md`의 HITL Gate 프로토콜 참조. **HITL Gate를 통과하기 전에는 `.claude/agents/`, `.claude/skills/` 파일을 생성하지 않는다.**
+
 ### Phase 3: 에이전트 정의 생성
 
 **모든 에이전트는 반드시 `프로젝트/.claude/agents/{name}.md` 파일로 정의한다.** 에이전트 정의 파일 없이 Agent 도구의 prompt에 역할을 직접 넣는 것은 금지한다. 이유:
@@ -166,6 +199,21 @@ cloud-deploy/
 
 > 상세 작성 패턴, 예시, 데이터 스키마 표준은 `references/skill-writing-guide.md` 참조.
 
+#### 4-6. HRD 스킬 섹션 작성 & HITL Gate 2
+
+스킬 설계 완료 후, HRD에 §3(스킬 설계) 섹션을 추가한 **새 스냅샷**을 생성한다. 사용자에게 다음을 표시한다:
+1. 스킬 목록 테이블 (스킬명, 설명, 사용 에이전트)
+2. 스킬 간 데이터 흐름 ASCII 다이어그램 (80자 폭)
+3. "스킬 설계가 맞나요? 수정이 필요하면 말씀해주세요."
+
+**승인 시** → HRD 전체(§1+§2+§3)를 복사하여 `*-full-approved.md` 생성 → Phase 5 파일 생성 진행
+**거절 시** → 피드백 캡처 → 새 HRD 스냅샷 → Phase 4 반복
+**모호 시** → 재질문 (Gate 1과 동일 문구)
+
+스킬 설계 변경은 스킬 레이어에 한정한다. 아키텍처 변경이 필요하면 Gate 1로 역행한다 — 기존 `*-arch-approved.md`는 이력으로 보존하고, 새 아키텍처 설계 후 새 `*-arch-approved.md`를 생성한다.
+
+**`*-full-approved.md`가 존재해야만 Phase 5 이후의 실제 파일 생성으로 진행한다.**
+
 ### Phase 5: 통합 및 오케스트레이션
 
 오케스트레이터는 스킬의 특수한 형태로, 개별 에이전트와 스킬을 하나의 워크플로우로 엮어 팀 전체를 조율한다. Phase 4에서 생성한 개별 스킬이 "각 에이전트가 무엇을 어떻게 하는가"를 정의한다면, 오케스트레이터는 "누가 언제 어떤 순서로 협업하는가"를 정의한다. 구체적 템플릿은 `references/orchestrator-template.md` 참조.
@@ -369,6 +417,7 @@ Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:
 | 워크플로우 순서 | 오케스트레이터 스킬 | "검증을 먼저 해야" → Phase 순서 변경 |
 | 팀 구성 | 오케스트레이터 + 에이전트 | "이 둘은 합쳐도 될 듯" → 에이전트 병합 |
 | 트리거 누락 | 스킬 description | "이 표현으로 하면 작동 안 함" → description 확장 |
+| 구조적 개선 | HRD 새 버전 생성 | 에이전트/스킬 구조 변경이 필요한 경우 → 새 HRD 스냅샷을 생성하고 Gate 1/2 재승인 |
 
 #### 7-3. 변경 이력
 
@@ -418,6 +467,8 @@ Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:
 
 생성 완료 후 확인:
 
+- [ ] `_workspace/harness-design/hrd-*-full-approved.md` — HRD 최종 승인본 존재 (HITL Gate 1+2 통과)
+- [ ] `_workspace/harness-design/` — HRD 이력 파일들 보존 (불변 스냅샷)
 - [ ] `프로젝트/.claude/agents/` — **에이전트 정의 파일 필수 생성** (빌트인 타입이라도 파일 생성 필수)
 - [ ] `프로젝트/.claude/skills/` — 스킬 파일들 (SKILL.md + references/)
 - [ ] 오케스트레이터 스킬 1개 (데이터 흐름 + 에러 핸들링 + 테스트 시나리오 포함)

skills/harness/references/hrd-template.md

@@ -0,0 +1,109 @@
+# HRD (Harness Requirements Document) 템플릿
+
+## 파일 경로 규칙
+
+- **경로**: `_workspace/harness-design/hrd-{YYYYMMDD-HHmmss}.md`
+- **예**: `hrd-20260409-153000.md`
+- **타임스탬프**: UTC 기준, 초 단위까지 포함 (충돌 방지)
+- **충돌 시**: 동일 타임스탬프 파일이 존재하면 +1초 재시도 (예: `153000` → `153001`)
+- **파일 시스템 호환 문자만 사용** (콜론·슬래시 금지)
+
+## 불변성 + 스냅샷 원칙
+
+- HRD 파일은 생성 후 **수정 금지** (immutable snapshot).
+- Phase가 진행되어 새 섹션(§2, §3)을 추가할 때도 **기존 파일을 편집하지 않고 새 타임스탬프의 새 HRD 파일을 생성**한다 (이전 내용 + 새 섹션 포함).
+- 사용자 피드백으로 변경이 필요할 때도 동일하게 새 파일을 생성한다.
+- 모든 HRD 파일은 특정 시점의 완전한 스냅샷이다. 시계열로 이력을 추적한다.
+
+### 스냅샷 진행 규칙
+
+- Phase 1 완료 → `hrd-{TS1}.md` 생성 (§1만 포함)
+- Phase 2 완료 → `hrd-{TS2}.md` 생성 (§1+§2 포함, TS1 파일 보존)
+- Phase 4 완료 → `hrd-{TS3}.md` 생성 (§1+§2+§3 포함, TS2 파일 보존)
+- 각 스냅샷의 `<!-- SOURCE: hrd-{이전TS}.md -->` 태그로 계보를 추적한다.
+- **SOURCE 부모 결정 규칙**: 직전에 생성된 HRD 파일(draft/arch-approved/full-approved 무관)을 SOURCE로 참조한다.
+
+## 승인 파일 체계 (2단계)
+
+| Gate | 승인 파일명 | 포함 내용 |
+|------|-----------|----------|
+| **Gate 1** (아키텍처) | `hrd-{timestamp}-arch-approved.md` | §1 요구사항 + §2 아키텍처 |
+| **Gate 2** (전체) | `hrd-{timestamp}-full-approved.md` | §1 + §2 + §3 스킬 설계 |
+
+- `*-full-approved.md`만이 파일 생성 Phase로 진행하는 최종 게이트.
+- 최신 `*-full-approved.md`가 현재 유효한 설계.
+
+## 6-상태 감지 테이블
+
+**파일 선택 규칙:**
+- **최신 draft 스냅샷**: `hrd-*.md`에서 `*-arch-approved.md`와 `*-full-approved.md`를 제외한 파일 중 타임스탬프가 가장 큰 것
+- **최신 아키텍처 승인**: `*-arch-approved.md` 중 타임스탬프가 가장 큰 것
+- **최종 승인**: `*-full-approved.md` 중 타임스탬프가 가장 큰 것
+- 상태 판별은 **최종 승인 → 최신 아키텍처 승인 → 최신 draft 스냅샷** 순서로 확인
+
+| 상태 | 조건 | 액션 |
+|------|------|------|
+| **1. 신규** | 디렉토리 없음 | 인터뷰부터 시작 |
+| **2. 요구사항 작성됨** | 최신 draft 스냅샷에 §1만 존재 | Phase 2 (아키텍처 설계)부터 |
+| **3. 아키텍처 승인 대기** | 최신 draft 스냅샷에 §2까지 존재, `*-arch-approved.md` 없음 | HITL Gate 1 재표시 |
+| **4. 아키텍처 승인됨** | `*-arch-approved.md` 존재, 최신 draft 스냅샷에 §3 없음 | Phase 4 (스킬 설계)부터 |
+| **5. 스킬 승인 대기** | 최신 draft 스냅샷에 §3까지 존재, `*-full-approved.md` 없음 | HITL Gate 2 재표시 |
+| **6. 전체 승인 완료** | `*-full-approved.md` 존재 | 파일 생성 Phase로 바로 진행 |
+
+## HITL Gate 프로토콜
+
+### 우선순위: 거절 > 승인 > 모호
+
+응답에 거절 키워드와 승인 키워드가 동시 포함 시 **거절로 처리**한다.
+
+**거절 키워드** (최우선 매칭):
+- 한국어: "수정", "변경", "바꿔", "다시", "추가", "삭제", "빼", "분리", "합쳐"
+- 영어: "change", "modify", "fix", "add", "remove", "split", "merge"
+
+**승인 키워드** (거절 키워드 미포함 시에만):
+- 한국어: "진행", "이대로", "맞아", "좋아", "승인", "만들어"
+- 영어: "approve", "proceed", "yes", "lgtm", "looks good"
+- **3자(글자) 미만 토큰은 전면 제외**: "네", "ok", "ㅇㅋ", "ㅇㅇ", "고" 등
+
+**모호한 응답** (어느 쪽에도 매칭 안 됨):
+"수정이 필요하시면 구체적으로 말씀해주세요. 이대로 진행하려면 '진행'이라고 해주세요." 로 재질문한다. 모호한 응답을 승인으로 처리하지 않는다.
+
+### Gate 역행 규칙
+
+- Gate 2에서 "아키텍처부터 다시" 요청 시 Gate 1로 돌아간다.
+- 기존 `*-arch-approved.md`는 **삭제하지 않고 보존**한다 (감사 추적/이력용).
+- 새 아키텍처 설계 → 새 draft 스냅샷 → Gate 1 재승인 시 새 `*-arch-approved.md`를 생성한다.
+- "최신 선택 규칙"에 의해 가장 최신 타임스탬프의 승인 파일이 유효본이 된다.
+
+## HRD 섹션 템플릿
+
+```markdown
+# HRD: {도메인명}
+<!-- CREATED: {YYYYMMDD-HHmmss} -->
+<!-- SOURCE: hrd-{이전타임스탬프}.md --> (개정 시에만)
+<!-- REVISION: "{사용자 피드백 요약}" --> (개정 시에만)
+
+## 1. 요구사항
+### 5축 인터뷰 결과
+- 도메인: {도메인명}
+- 작업 유형: {유형 목록}
+- 입출력: {입력} → {출력}
+- 품질 기준: {기준 목록}
+- 재사용성: {빈도/시나리오} (추론: {근거}) ← 추론 시에만
+
+## 2. 팀 아키텍처 설계
+### 에이전트 테이블
+| 에이전트 | 타입 | 역할 | 스킬 |
+|---------|------|------|------|
+
+### 아키텍처 다이어그램
+{ASCII 다이어그램 — 80자 폭, 패턴별 템플릿 준수}
+
+## 3. 스킬 설계
+### 스킬 테이블
+| 스킬 | 설명 | 사용 에이전트 |
+|-----|------|-------------|
+
+### 스킬 다이어그램
+{ASCII 다이어그램 — 스킬 간 데이터 흐름}
+```

skills/harness/references/interview-guide.md

@@ -0,0 +1,69 @@
+# 5축 인터뷰 가이드
+
+## 5축 요구사항 프레임
+
+| 축 | 파악할 내용 | 이미 충분한 신호 | 질문 우선순위 |
+|----|------------|----------------|-------------|
+| **1. 도메인** | 어떤 분야/프로젝트 | 명사로 도메인 명시 | 1 (최고) |
+| **2. 작업 유형** | 생성/분석/검증/변환/기타 | 동사가 구체적 | 2 |
+| **3. 입출력** | 무엇이 들어가고 나오는지 | 파일 형식, 데이터 유형 언급 | 3 |
+| **4. 품질 기준** | 좋은 결과의 정의 | 검증 조건, 기대 수준 언급 | 4 |
+| **5. 재사용성** | 사용 빈도와 시나리오 | 반복 언급, 자동화 목적 언급 | 5 (최저) |
+
+## 질문 우선순위
+
+1. **도메인** — 없으면 설계 불가
+2. **작업 유형** — 에이전트 수와 역할 결정
+3. **입출력** — 스킬 내용 결정
+4. **품질 기준** — QA 에이전트 필요 여부 결정
+5. **재사용성** — 기본값 "여러 번 반복 사용"
+
+## 종료 조건
+
+- 5축 중 **3개 이상** 충분히 파악 → 나머지는 합리적 기본값으로 추론하고 HRD를 **즉시 작성**한다. 추론한 내용에 "(추론)" 표기.
+- 5축 중 **2개 이하** 파악 → 부족한 축에 대해 **3~5개 질문**을 생성한다 (5개 초과 금지).
+- 각 질문에 반드시 예시 답변을 포함한다: "예) A 또는 B" 형식.
+- 이미 파악된 축은 재질문하지 않는다.
+- 기술 용어 대신 일상 언어를 사용한다.
+
+## 빠른 경로 (Fast Path)
+
+- 사용자 요청이 5축 모두를 이미 포함하면 질문 없이 즉시 HRD를 작성한다.
+- 미명시 축의 기본값: 품질 = "프로덕션급", 재사용성 = "여러 번 반복 사용".
+- 빈 섹션 금지 — 기본값이라도 명시적으로 기록한다.
+
+## 질문 형식
+
+질문 수는 3~5개로 제한한다. 5개를 초과하면 우선순위가 낮은 것을 제거한다.
+
+"어떤" 보다 "예를 들어 A인가요, B인가요?" 형태가 더 답하기 쉽다. 기술 용어(assertion, schema, orchestrator) 대신 사용자의 언어로 질문한다.
+
+```markdown
+1. 어떤 작업들을 자동화하고 싶으신가요?
+   예) "기획서 작성 → 대본 생성 → 검수" 또는 "데이터 수집 → 분석 → 보고서"
+
+2. 최종 결과물은 어떤 형태인가요?
+   예) "마크다운 문서 5개" 또는 "JSON 데이터 + 요약 보고서"
+
+3. 결과물의 품질을 어떻게 판단하시나요?
+   예) "팩트 체크 통과" 또는 "전문가가 보기에 자연스러운 문체"
+```
+
+## 축소 인터뷰 (기존 확장 시)
+
+Phase 0에서 "기존 확장"으로 분류된 경우:
+
+- 변경 관련 축만 빠르게 확인한다 (예: 에이전트 추가 → 축 2·3만 확인).
+- 기존 하네스에서 이미 정의된 축은 재질문하지 않고 기존 값을 유지한다.
+- 축소 인터뷰라도 HRD는 반드시 생성한다.
+
+## 특수 케이스
+
+**요청이 너무 단순한 경우** (단일 작업, 하네스 불필요):
+HRD에 "단일 스킬로 충분할 수 있음"을 기록하고, Phase 2에서 최종 판단하도록 한다.
+
+**요청이 이미 매우 상세한 경우**:
+질문 없이 바로 HRD를 작성한다 (Fast Path). 시간을 절약한다.
+
+**사용자가 5축 일부만 답변 후 진행 요청**:
+3축 이상이면 진행한다 (나머지 추론). 미만이면 재질문한다.

skills/harness/references/orchestrator-template.md

@@ -47,9 +47,7 @@ description: "{도메인} 에이전트 팀을 조율하는 오케스트레이터
 
 ### Phase 1: 준비
 1. 사용자 입력 분석 — {무엇을 파악하는지}
-2. 작업 디렉토리에 `_workspace/` 생성
-   - **초기 실행**: 새 `_workspace/` 생성
-   - **새 실행**: 기존 `_workspace/`를 `_workspace_{YYYYMMDD_HHMMSS}/`로 이동한 직후 새 `_workspace/` 재생성
+2. 작업 디렉토리에 `_workspace/` 생성 (초기 실행 시)
 3. 입력 데이터를 `_workspace/00_input/`에 저장
 
 ### Phase 2: 팀 구성
@@ -189,7 +187,7 @@ description: "{도메인} 에이전트를 조율하는 오케스트레이터. {
 
 ### Phase 1: 준비
 1. 입력 분석
-2. `_workspace/` 생성 (초기 실행 시, 또는 새 실행에서 기존 `_workspace/`를 보관 디렉토리로 이동한 직후)
+2. `_workspace/` 생성 (초기 실행 시)
 
 ### Phase 2: 병렬 실행
 단일 메시지에서 N개 Agent 도구를 동시 호출: