Commands

---
description: 학습 스킬을 실패 트레이스 기반으로 진화시킨다 — GEPA식 반영·변이·평가·선별 후 diff로 제안 (Hermes self-evolution 이식)
---

한 학습 스킬(`~/.claude/skills/<name>/SKILL.md`)을 **측정 기반으로 진화**시킵니다. 이것은 self-improving-skills 플러그인이 갖지 못한 축입니다 — 그 플러그인은 스킬을 *획득·유지*하지만, 실제 성능을 측정해 *다듬지는* 않습니다. 이 커맨드가 Hermes의 GEPA(반영적 텍스트 진화) 루프를 이식합니다.

## 0. 대상 선정

- `$ARGUMENTS` 에 스킬 이름이 있으면 그 스킬을 대상으로 합니다.
- 없으면 랭킹에서 1순위 후보를 고릅니다:
  ```
  python3 "${CLAUDE_PLUGIN_ROOT}/scripts/evolution_report.py" candidate
  ```
  빈 문자열이면 "아직 최적화할 데이터(outcome)가 없다"고 사용자에게 알리고 중단하세요. `/evolution-status` 로 현재 상태를 보여주세요.

대상 스킬의 현재 통계도 함께 확인하세요:
```
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/evolution_report.py" json
```

## 1. 근거 수집 (traces → "왜 실패했나")

GEPA의 핵심은 실패 여부가 아니라 **왜**입니다. 대상 스킬이 실제로 쓰인 세션을 찾아 실패의 원인을 모으세요:

1. 대상 `SKILL.md` 전문을 읽습니다.
2. 이 스킬이 사용된 트레이스를 프로젝트 기록에서 찾습니다 (Grep 도구 사용):
   - `~/.claude/projects/**/*.jsonl` 에서 `"skill":"<name>"` 또는 `"<name>"` 이 등장하는 세션.
   - 그 사용 지점 이후의 `is_error` tool_result, 사용자 정정 발언, 재시도를 읽어 **무엇이 어긋났는지** 3~6개 구체적 실패 양상으로 정리하세요.
3. 트레이스가 빈약하면(신규 스킬 등) 스킬 설명·본문 자체의 약점(모호한 트리거 조건, 빠진 엣지케이스, 과한 "MUST ALWAYS" 방어문구, 낡은 명령/경로)을 근거로 삼으세요.

이 실패 목록이 GEPA가 말하는 **Actionable Side Information** — 변이의 방향을 주는 신호입니다.

## 2. 변이 생성 (candidates)

실패 목록을 겨냥해 SKILL.md의 **후보 변형 2~3개**를 만드세요. 서로 다른 전략을 쓰세요 (한 방향으로만 바꾸지 말 것):
- A: 트리거 조건(description의 "이런 상황에 사용")을 실패 사례에 맞게 더 정확히.
- B: 본문 절차에 빠진 단계·엣지케이스·검증을 보강.
- C: 군더더기를 덜어내 더 짧고 선명하게(같은 커버리지, 적은 토큰).

각 후보는 반드시:
- 유효한 frontmatter(`name`, `description`) 유지, 의미(원래 목적) 보존.
- 크기 상한 존중: 본문 15KB 이하 권장, description 500자 이하 권장(초과 시 매 세션 컨텍스트 비용).

## 3. 평가 (evaluate) — LLM-judge

원본 + 각 후보를, 1단계 실패 목록을 **루브릭**으로 삼아 채점하세요. 각 실패 양상마다 "이 버전이라면 막았을까?"를 판정하고, 다음을 0~5로 스코어링:
- **failure coverage** — 정리한 실패들을 실제로 예방하는가 (가장 중요).
- **trigger precision** — 써야 할 때 켜지고, 아닐 때 안 켜지는가.
- **clarity/actionability** — 상황매칭 서술인가, 방어적 명령 나열인가.
- **cost** — 크기/토큰 (작을수록 가점).

정직하게 채점하세요. 원본이 이미 최선이면 "개선 없음"이 정답입니다.

## 4. 선별 (Pareto)

품질(coverage+precision+clarity)을 1차 기준, cost를 동점 시 2차 기준으로 **파레토 최적** 후보를 고르세요. 원본이 파레토 프론트를 지배하면 변경하지 않습니다.

## 5. 적용 (human-gated)

- 선택한 후보와 원본의 **diff, 그리고 각 변경이 어떤 실패를 겨냥하는지**를 사용자에게 먼저 보여주세요.
- 사용자가 승인하면 `Edit` 도구로 `~/.claude/skills/<name>/SKILL.md` 를 그 내용으로 교체하세요.
  - 이 Edit은 self-improving-skills 플러그인의 PreToolUse(백업)·PostToolUse(검증·롤백) 훅을 자동으로 통과합니다 — frontmatter가 깨지면 자동 롤백됩니다. 별도 백업 불필요.
- 적용 후 최적화 시점을 기록하세요(다음 outcome이 실제로 나아졌는지 나중에 비교할 수 있게):
  ```
  python3 "${CLAUDE_PLUGIN_ROOT}/scripts/outcome_store.py" optimized "<name>"
  ```
- 마지막으로 무엇을·왜 바꿨는지 2~3줄로 요약하세요.

## 설계 원칙

- **자동 커밋·자동 적용 없음.** 변이·평가·선별은 자동이되, 실제 파일 교체는 사람이 승인(Hermes의 "never direct commit, always PR review" 이식).
- **의미 보존.** 진화는 같은 목적을 더 잘하게 만드는 것이지, 스킬의 정체성을 바꾸는 게 아닙니다.
- **데이터 없으면 진화 없음.** outcome 트레이스가 없으면 추측으로 바꾸지 말고 중단하세요.

### 선택: DSPy + GEPA 엔진 (opt-in, 고급)
위 루프는 외부 의존성 없는 "Claude-as-optimizer" 반영 루프입니다. 정량적 최적화가 필요하면 `intertwine/dspy-agent-skills`(DSPy 3.2 + GEPA)를 별도로 설치해 eval 데이터셋 기반 최적화로 대체할 수 있습니다. 단 API 키·평가셋 구성이 필요하며 실행당 비용이 듭니다. 기본은 위 반영 루프입니다.