diff --git a/CHANGELOG.md b/CHANGELOG.md index fbcdeea..be8bf3d 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/skills/harness/SKILL.md b/skills/harness/SKILL.md index 01ccc63..9d18185 100644 --- a/skills/harness/SKILL.md +++ b/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에 컨텍스트 확인 단계** (초기/후속/부분 재실행 판별) ## 참고 diff --git a/skills/harness/references/orchestrator-template.md b/skills/harness/references/orchestrator-template.md index df5023b..8442028 100644 --- a/skills/harness/references/orchestrator-template.md +++ b/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별 모드 표 필수