evolve

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은 전체 하네스를 깨뜨릴 수 있다.
• 사용자 무시: 진화 결과를 보고하지 않으면 사용자가 모르는 규칙이 쌓인다. 항상 보고하고, 커밋은 사용자에게 맡긴다.