evolve

Harness Evolve — 하네스 진화 메커니즘

하네스는 고정물이 아니라 진화하는 시스템이다. 이 스킬은 "무엇이 먹혔고 무엇이 안 먹혔는가"의 델타를 포착해 하네스에 되먹여, 다음 실행이 측정 가능하게 더 나아지도록 한다.

초기 하네스 ──▶ 실 프로젝트 사용 ──▶ 현재 하네스
                                        │
                                        ▼ (evolve로 델타 포착)
                                  피드백 일반화 → 에이전트·스킬·오케스트레이터 반영
                                        │
                                        ▼
                                  변경 이력 갱신 → 다음 실행은 더 나은 초안에서 시작

워크플로우

Phase 1: 델타 수집

1. .claude/agents/, .claude/skills/, CLAUDE.md(변경 이력 테이블)를 읽는다
2. git 저장소라면 하네스 파일들의 변경 이력을 조회한다 (git log --oneline -- .claude/ CLAUDE.md) — 초기 구성 대비 무엇이 언제 왜 바뀌었는지 파악
3. _workspace/가 있으면 최근 실행의 중간 산출물을 훑어 실제 실행 흔적을 확인한다:
   • 오케스트레이터가 정의한 경로에 산출물이 실제로 있는가 (없으면 워크플로우가 우회되었거나 죽은 코드)
   • 산출물 품질이 스킬이 명시한 형식/기준을 따르는가
4. 사용자에게 피드백을 요청한다 (이미 피드백을 제공했다면 생략):
   • "결과에서 개선할 부분이 있나요?"
   • "에이전트 구성이나 워크플로우에 바꾸고 싶은 점이 있나요?"
   • 피드백이 없으면 강요하지 않는다. 단, 아래 관찰 신호가 있으면 선제적으로 개선을 제안한다

관찰 기반 진화 신호 (피드백이 없어도 제안):

• 같은 유형의 수정 요청이 2회 이상 반복된 흔적
• 에이전트가 반복적으로 실패/재시도한 패턴
• 사용자가 오케스트레이터를 우회해 수동으로 작업한 흔적 (오케스트레이터 트리거 실패 의심 → description 확장 후보)
• 오케스트레이터에 v1 유물(TeamCreate/TeamDelete/실험 플래그)이 남아 있음 → harness 스킬의 마이그레이션 절차 안내

Phase 2: 피드백 유형 분류 및 수정 대상 매핑

피드백 유형	수정 대상	예시
결과물 품질	해당 에이전트의 스킬	"분석이 너무 피상적" → 스킬에 깊이 기준 추가
에이전트 역할	에이전트 정의 .md	"보안 검토도 필요" → harness 스킬로 에이전트 추가 안내
워크플로우 순서	오케스트레이터 스킬	"검증을 먼저 해야" → Phase 순서 변경
팀 구성	오케스트레이터 + 에이전트	"이 둘은 합쳐도 될 듯" → 에이전트 병합
트리거 누락	스킬 description	"이 표현으로 하면 작동 안 함" → description 확장
실행 모드 부적합	오케스트레이터	"매번 같은 팬아웃인데 느려" → 워크플로우 모드 전환
규모/비용	오케스트레이터	"토큰을 너무 써" → 기본 규모 축소, 버짓 연동 추가

범위 판단: 에이전트 신규 추가/삭제나 아키텍처 재설계가 필요하면 이 스킬에서 직접 하지 않고 harness 스킬(0단계의 기존 구성 확장 절차)로 안내한다. evolve는 기존 구성의 조정에 집중한다.

Phase 3: 일반화 및 반영

1. 피드백을 일반화한다 — 특정 사례에만 맞는 좁은 수정은 오버피팅이다. "이번 보고서에 서론이 길었다" → "서론은 전체의 10% 이내로"가 아니라, 왜 길어졌는지(스킬에 분량 배분 기준 부재)를 찾아 원리 수준으로 수정한다
2. Why를 함께 기록한다 — 수정된 지시에는 이유를 병기한다. 이유를 알면 에이전트가 엣지 케이스에서도 올바르게 판단한다
3. 변경은 한 번에 하나씩 적용하고, 각 변경 직후 Phase 4를 실행한다
4. 퇴행 방지: 수정이 기존 변경 이력의 이전 수정을 되돌리는 방향이면, 사용자에게 상충을 알리고 확인받는다 (과거에 "너무 길다"로 줄였는데 이번에 "너무 짧다"면 — 둘 다 만족하는 기준을 찾는 것이 정답이다)
5. 기존 파일의 언어를 유지한다 — 에이전트·스킬·오케스트레이터·CLAUDE.md에 반영하는 문장은 수정 대상 파일에 이미 쓰인 언어로 쓴다. 이 스킬 문서가 한국어라는 이유로 다른 언어로 된 하네스에 한국어 문장을 섞지 않는다

Phase 4: 변경 이력 갱신 및 검증

1. CLAUDE.md의 변경 이력 테이블에 기록한다:

**변경 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| 2026-07-19 | 톤 가이드 추가 | skills/content-creator | "너무 딱딱하다" 피드백 |

2. 수정된 파일의 구조를 검증한다 (frontmatter, 참조 일관성)
3. description을 수정했다면 트리거 검증 (should-trigger + near-miss 각 3개 이상)
4. CLAUDE.md와 실제 파일의 일치 여부 최종 확인

Phase 5: 진화 보고

사용자에게 보고한다:

• 포착된 델타 요약 (초기 구성 → 현재)
• 이번에 반영한 변경과 그 일반화 근거
• 반영하지 않기로 한 피드백과 이유 (있다면)
• 다음 실행에서 기대되는 개선점

원칙

• 델타는 자산이다 — 변경 이력이 쌓일수록 같은 도메인의 다음 하네스 구축이 "출시 상태에 더 가까운 초안"에서 시작된다. 이력을 지우지 않는다
• 일반화 없는 반영 금지 — 사례 하나에 규칙 하나를 1:1로 추가하면 스킬이 규칙 더미가 된다. 원리로 압축한다
• 한 번에 하나씩 — 여러 변경을 몰아서 적용하면 어떤 변경이 효과였는지 알 수 없게 된다