| name | evolve |
| description | 하네스 자체를 진화시킬 때 사용하세요. "이거 규칙으로 만들어", "이 작업 스킬로 만들어", "이거 차단해", 같은 실수가 반복될 때, 같은 패턴의 코드를 여러 번 작성할 때, 프로젝트 구조가 변경되었을 때 트리거합니다. 규칙·스킬·hook·메모리를 프로젝트에 맞게 진화시킵니다. |
진화 스킬 — Venom의 자기 성장 엔진
이 스킬은 Venom을 살아있게 만드는 핵심이다.
프로젝트에서 일하면서 발견한 것을 규칙·스킬·hook·메모리로 응결시킨다.
트리거
- 같은 태그의 실수가
mistakes.md에 2회 이상 기록됨
- 같은 패턴의 코드를 3회 이상 작성함
- 사용자가 관례를 교정해 줌 ("항상 이렇게 해", "그렇게 하면 안 돼")
- 프로젝트 구조가 변경됨 (새 모듈, 새 의존성, 빌드 명령 변경)
- 사용자가 명시적으로 진화를 요청함
진화 유형 판단
무엇을 진화시킬지 판단하는 기준:
| 상황 | 진화 대상 | 이유 |
|---|
| 같은 실수 반복 | 규칙 강화 또는 hook 신규 | 조언으로 안 되면 강제로 |
| 같은 작업 반복 | 스킬 추출 | 절차를 한 번에 따를 수 있도록 |
| 비자명한 사실 발견 | 메모리 기록 | 다음 세션에 전달 |
| 관례 교정 | 규칙 추가 | 영구적 행동 변경 |
| 아키텍처 결정 | 메모리 ADR | 왜 그렇게 했는지 기록 |
| 위험 행동 감지 | hook 추가 | 결정적으로 차단 |
| 빌드/테스트 변경 | 규칙 + 스킬 갱신 | 도구 명령 최신화 |
절차
1. 분석 — 무엇이 진화를 요구하는가
a) 트리거 원인을 한 줄로 적는다
b) 기존 규칙/스킬/hook 중 관련된 것이 있는지 확인한다
c) 새로 만들지, 기존을 보강할지 결정한다
- 원칙: 기존 파일 보강 > 새 파일 생성
2. 기존 파일 보강 (기존 것이 있을 때)
a) 대상 파일을 읽는다
b) 추가할 내용을 정한다
c) Edit으로 추가한다
d) 변경 이유를 lessons.md 또는 decisions.md에 기록한다
3. 새 규칙 생성
a) 배치 위치 결정:
- 기존 규칙 파일 보강 가능 → 기존 파일에 추가 (최우선)
- 새 파일이 필요 → .claude/rules/evolved/<이름>.md
(기존 00-55 번호 prefix 파일은 flat 유지, 진화 생성분은 evolved/)
b) 규칙 파일 작성:
- 제목: # <규칙 영역>
- 섹션별로 *무엇을* *왜* 해야 하는지 명시
- 예제 포함 (좋은 예 vs 나쁜 예)
c) CLAUDE.md의 부록 테이블에 등재한다
d) decisions.md에 ADR로 남긴다
4. 새 스킬 생성
a) .claude/skills/evolved/<이름>/SKILL.md 생성
(기존 기반 스킬은 skills/<name>/ 유지, 진화 생성분은 evolved/ 아래)
b) 형식:
---
name: <kebab-case-이름>
description: <트리거 조건, 한 줄>
---
# <제목>
<왜 필요한가>
## 절차
1. ...
## 안티 패턴
- ...
c) 실제 상황에 적용해본다 (머릿속 시뮬레이션이라도)
5. 새 hook 생성
a) .claude/hooks/evolved/<이름>.sh 작성
- #!/usr/bin/env bash
- set -euo pipefail
- stdin에서 JSON 읽기
- 차단 시 JSON 출력, 통과 시 exit 0
(기존 기반 훅 flat 파일은 그대로 유지, 진화 생성분은 evolved/ 아래)
b) bash -n 문법 검증
c) chmod +x 부여
d) settings.json의 적절한 이벤트에 등록
예: "$CLAUDE_PROJECT_DIR"/.claude/hooks/evolved/<이름>.sh
e) JSON 유효성 검증:
python3 -c "import json; json.load(open('.claude/settings.json'))"
f) 대표 입력으로 스모크 테스트:
echo '{"tool_name":"Bash","tool_input":{"command":"<테스트명령>"}}' \
| bash .claude/hooks/evolved/<이름>.sh
g) decisions.md에 ADR로 남김
6. 메모리 기록
a) 카테고리 판단:
- 실수 → mistakes.md
- 항구적 사실 → lessons.md
- 아키텍처 결정 → decisions.md
b) 해당 파일 형식에 맞춰 추가
c) 태그 포함
6.5 승급 후 원본 삭제 (진화가 규칙/스킬/hook 생성을 포함할 때 필수)
a) decisions.md에 ADR 추가
형식:
## ADR-NNNN: <제목>
- 날짜: YYYY-MM-DD
- 상태: 채택
- 기원: mistakes.md #태그 (N회) 또는 lessons.md #태그
- 맥락: <어떤 문제에서 비롯됐나>
- 결정: <어떤 규칙/스킬/hook을 만들었나>
- 결과: <이 진화가 막는 것>
b) mistakes.md 또는 lessons.md에서 승급된 항목 삭제
- 동일 태그 항목 전체를 승급했으면 해당 항목 모두 삭제
- 일부만 승급했으면 승급된 항목만 삭제
c) 삭제 확인: 파일에 해당 태그 항목이 남아있지 않은지 확인
왜: mistakes.md/lessons.md는 "진화 대기열"이다. 승급된 항목이 남아있으면
세션마다 "이미 해결된 문제"에 컨텍스트를 낭비한다.
7. 보고
진화를 수행했으면 사용자에게 보고한다:
📝 진화: <무엇을> <어떻게> 했습니다.
- 이유: <왜>
- 파일: <경로>
- 검증: <어떻게 확인했는지>
안티 패턴
- 과잉 진화: 1회성 관찰을 바로 규칙화. 2회 이상 반복될 때만 규칙화한다.
- 이유 없는 규칙: "왜"가 없는 규칙은 의문의 쓰레기. 반드시 출처를 남긴다.
- 거대한 진화: 한 번에 5개 규칙 + 3개 스킬 + 2개 hook → 추적 불가.
한 번에 1~2개씩 진화한다.
- 검증 없는 hook:
bash -n도 안 돌린 hook은 전체 하네스를 깨뜨릴 수 있다.
- 사용자 무시: 진화 결과를 보고하지 않으면 사용자가 모르는 규칙이 쌓인다.
항상 보고하고, 커밋은 사용자에게 맡긴다.
