retro-compound

Retro Compound — 교훈 컴파운딩 방법론

세션마다 발생하는 교정·실수·발견을 일회성으로 흘려보내지 않고, 검증된 규칙으로 축적해 다음 세션의 실수율을 낮추는 방법론이다. Compound Engineering 패턴을 차용한다: 교훈은 복리로 쌓일 때만 가치가 있고, 저품질 규칙은 복리로 쌓이면 부채가 된다.

/retro 커맨드가 실행 절차(Phase)를 담당하고, 이 스킬은 판정 기준·기록 형식·방지 원칙을 담당한다.

When to Apply

• /retro 커맨드 실행 시 (품질 필터·라우팅·기록 형식의 기준으로 항상 로드)
• 사용자가 같은 지적을 반복하거나 "왜 또 이러냐"는 신호를 보낼 때
• 작업·코드 리뷰·루프 하네스 종료 시점에 교훈 회수가 필요할 때
• tasks/lessons.md의 항목을 정리·통합·승격하려 할 때

Core Principles

1. 하네스가 판정한다: 교훈의 채택 여부는 모델의 자기평가가 아니라 명문화된 품질 기준과 사용자 승인으로 결정한다
2. 적을수록 강하다: 판정 불가능한 훈계 10개보다 판정 가능한 규칙 1개가 낫다. 기록 보류를 두려워하지 않는다
3. 승격 사다리: 교훈은 기록 보류 → lessons.md → CLAUDE.md 컨벤션 or 가드 훅으로 검증을 거치며 승격된다. 단계를 건너뛰지 않는다
4. 자동 수정 금지 경계: 이 스킬이 직접 쓸 수 있는 파일은 tasks/lessons.md 하나뿐이다. CLAUDE.md는 sync-claude-md에, 훅 생성은 create-flow에, 스킬 본문은 사용자에게 맡긴다

1. 교훈 원료의 3분류

원료	정의	추출 신호
교정(correction)	사용자가 결과물·접근을 고쳐준 지점	지시 번복, 재작업 요청, "그게 아니라", "다시", 명시적 반려
실수(mistake)	스스로 실패했거나 되돌린 시도	실패한 명령, revert된 편집, 검증 게이트 불통과, 잘못된 파일 수정
발견(discovery)	세션 중 새로 알게 된 사실	문서에 없던 컨벤션, 도구 제약, 도메인 규칙, 숨은 의존성

전역 CLAUDE.md의 Self-Improvement Loop 규약과 정합: "사용자의 교정이 있을 때마다 tasks/lessons.md에 패턴을 기록하고, 같은 실수를 막는 규칙을 작성하며, 실수율이 떨어질 때까지 반복 개선한다. 세션 시작 시 lessons를 리뷰한다."

2. 교훈 품질 기준 (채택 게이트)

세 기준을 모두 통과해야 라우팅 대상이 된다. 하나라도 미달이면 기록 보류.

2.1 재현 가능성 (구체 사례)

제3자가 이 기록만 읽고 상황을 재구성할 수 있어야 한다.

[미달] "파일 경로를 잘못 다뤘다"
[통과] "plugins/workflow/commands/retro.md 생성 시 frontmatter의 category에
       존재하지 않는 값 'misc'를 사용해 verify-flow CMD-003 검증에 실패했다"

• 필수 요소: 관련 파일/명령/입력 중 최소 1개 + 무엇이 잘못됐는지 + 어떻게 드러났는지

2.2 일반화 가능성 (원리 수준)

특정 파일 1회에만 유효한 사후 설명이 아니라, 미래 작업에 적용되는 원리여야 한다.

[미달] "retro.md의 category는 workflow로 한다" (그 파일 한정)
[통과] "커맨드 frontmatter의 category/complexity는 신조어 금지 — 저장소에서
       grep으로 기존 값 분포를 확인하고 그중에서 고른다" (모든 커맨드에 적용)

• 자가 점검: "이 규칙이 다음 달 다른 작업에서도 발동하는가?"

2.3 판정 가능성 (actionable)

준수/위반을 객관적으로 판정할 수 있는 명령형 서술이어야 한다.

[미달] "컨벤션에 더 주의한다" (판정 불가한 훈계)
[통과] "신규 커맨드 작성 전 같은 플러그인의 기존 커맨드 1개를 Read해 섹션 구조를 대조한다"

3. 라우팅 표

harness:evolve 피드백 라우팅(품질→스킬 / 역할→에이전트 / 트리거→description)의 골격을 세션 교훈에 맞게 확장한 것이다.

유형	판정 신호	라우팅 대상	적용 방식	경계
(a) 컨벤션 변화	프로젝트 규칙·구조·도구 사용법이 바뀜, 또는 문서화 안 된 규칙 발견	workflow:sync-claude-md 위임	승인 후 스킬 발동	CLAUDE.md 직접 편집 금지
(b) 반복 실수 패턴	동일 패턴 교정·실수가 세션 내 2회+ 또는 기존 lessons 항목과 동일	tasks/lessons.md 기록	승인 후 직접 기록	유일하게 직접 쓰는 파일
(b′) 가드 훅 후보	(b) 중 결정론적 검사 가능 + 누적 2회+ 재발	lessons 항목에 #가드-훅-후보 태그	태그 표기까지만	훅 생성은 harness:create-flow 담당 (lessons 입력 모드는 별도 작업 예정)
(c) 도메인 지식 갱신	플러그인 스킬 내용이 낡음, 예시가 틀림, 레퍼런스 누락	해당 스킬 수정 제안서	제안 출력만	자동 수정 금지
(c′) 트리거 미스	스킬이 발동해야 할 상황에서 발동 안 함(또는 오발동)	해당 스킬 description 수정 제안서	제안 출력만	harness:evolve와 동일 원칙

• 복수 유형에 해당하면 복수 라우팅한다. 예: "커맨드 complexity 값 신조어 사용"은 (b) 반복 실수 기록이면서, 검증 규칙이 있다면 (b′) 가드 훅 후보다.
• 하네스(에이전트 팀) 자체의 역할·워크플로우 문제는 이 스킬의 범위 밖 — harness:evolve(기존 구성 조정) 또는 harness:team-harness(에이전트 추가·구조 재설계)로 안내한다.

가드 훅 후보 판정 기준 (b′)

아래를 모두 만족할 때만 태그를 단다.

1. 결정론적 검사 가능: 파일 패턴·명령어 매칭·정규식 등으로 기계 판정 가능 (예: "marketplace.json 수정 시도 차단" — 가능 / "설계가 우아한지" — 불가능)
2. 누적 2회 이상 재발: 이번 세션 포함 발생 횟수 2회 이상
3. 차단·경고 시점이 명확: PreToolUse/PostToolUse/Stop 등 훅 이벤트에 대응 가능

태그 형식: 항목의 태그: 필드에 #가드-훅-후보 (이벤트: PreToolUse, 검사: {한 줄 요약})

4. tasks/lessons.md 기록 형식

파일이 없으면 아래 헤더로 생성한다. 항목은 최신이 위로 오게 추가한다.

# Lessons — 재발 방지 규칙

> /retro가 관리한다. 세션 시작 시 이 파일을 리뷰하고, 규칙 위반 전에 스스로 점검한다.

## [YYYY-MM-DD] {교훈 제목 — 규칙을 한 줄로 요약}
- 유형: 반복 실수 | 컨벤션 | 도메인 지식
- 증상: {구체 사례 — 무엇이 어떻게 잘못됐나 (파일/명령/입력 포함)}
- 원인: {근본 원인 — 표면 증상이 아니라 왜 발생했나}
- 규칙: {명령형 서술 — 다음부터 무엇을 어떻게 한다}
- 검증: {이 규칙이 지켜졌는지 확인하는 방법}
- 발생: {N}회 (최초 YYYY-MM-DD / 최근 YYYY-MM-DD)
- 태그: {#가드-훅-후보 (이벤트: ..., 검사: ...) | #승격-후보 | 없음}

갱신 규칙

• 재발 시: 신규 항목을 만들지 않고 기존 항목의 발생 횟수를 +1, 최근 날짜 갱신, 필요 시 증상에 새 사례 1줄 추가
• 승격 시: CLAUDE.md 컨벤션으로 승격되거나 가드 훅이 생성되면 항목을 삭제하지 말고 → YYYY-MM-DD {대상}으로 승격 한 줄을 남긴다 (이력 보존)
• 날짜: 시스템 날짜를 사용하고 추측하지 않는다

5. 저품질 규칙 축적 방지 원칙

lessons.md는 늘어날수록 좋은 파일이 아니다. 세션 시작마다 리뷰되는 파일이므로 항목 하나하나가 컨텍스트 비용이다.

1. 1회성 기록 보류: 첫 발생 실수는 원칙적으로 기록하지 않는다(승인 게이트 보고에 "기록 보류"로만 표시). 재발하면 그때 기록한다.
   • 예외: 데이터 유실·보안·금지 파일 수정 등 피해가 큰 실수는 1회여도 즉시 기록
2. 훈계 금지: "더 조심한다", "꼼꼼히 확인한다" 류의 판정 불가 서술은 품질 기준 2.3에서 차단한다. 통과 못 하면 규칙이 아니다
3. 상한과 프루닝: 항목이 20개를 초과하면 /retro 실행 시 프루닝을 제안한다 — 6개월 이상 재발 없는 항목의 정리, 유사 항목 통합, 승격 후보 선별
4. 승격 사다리 운영: 발생 3회+ 또는 팀 전체에 적용되는 규칙은 #승격-후보 태그를 달고 (a) 라우팅(sync-claude-md 경유 CLAUDE.md 반영) 또는 (b′) 가드 훅 후보로 전환을 제안한다. lessons.md는 검증 대기소이지 종착지가 아니다
5. 중복은 횟수로: 같은 교훈의 재기록은 금지 — 발생 횟수 증가가 곧 그 규칙의 중요도 신호이며, 승격 판단의 근거가 된다
6. 환경·부정·일시 캡처 금지 (hermes-agent do-NOT-capture 이식): 다음 4종은 품질 기준을 통과해도 기록하지 않는다 — ⓐ 환경 의존 실패(미설치 바이너리·자격증명 부재·경로 불일치): 사용자가 고치면 끝나는 상태이지 규칙이 아니다. ⓑ 도구·기능에 대한 부정 주장("X는 안 됨/고장"): 실제 문제가 고쳐진 뒤에도 스스로에게 인용하는 거부(refusal)로 굳는 부채다. ⓒ 세션 안에서 해소된 일시 오류: 재시도가 통했다면 기록할 것은 재시도 패턴이지 원 실패가 아니다. ⓓ 설정 상태가 원인인 도구 실패는 "안 된다"가 아니라 고치는 방법(설치 명령·env·설정 단계)으로만 기록한다.

6. 중복·상충 검사 절차

라우팅 결과를 승인 게이트에 올리기 전에 수행한다.

단계	대조 대상	중복 시	상충 시
1	tasks/lessons.md 기존 항목	신규 기록 → 기존 항목 발생 +1로 전환	양쪽 병기, 사용자 판단 요청
2	프로젝트 CLAUDE.md (+ claude/CLAUDE.md)	이미 명문화됨 → 기록 생략, "기존 규칙 재확인"으로 보고	양쪽 병기, 사용자 판단 요청 — 자동 해소 금지
3	(c)/(c′) 제안 대상 스킬 현재 본문	이미 반영됨 → 제안 철회	스킬 서술과 실제 동작의 괴리를 제안서에 명시

• 중복 판정: 문구가 아니라 의미로 판정한다. 같은 상황에서 같은 행동을 요구하면 중복이다
• 상충 판정: 같은 상황에서 다른 행동을 요구하면 상충이다. 어느 쪽이 맞는지는 사용자만 결정할 수 있다 — 상충 항목은 승인 대상이 아니라 판단 요청 항목으로 승격한다

7. 사용자 승인 게이트

• 모든 라우팅 결과(lessons.md 기록, sync-claude-md 위임, 수정 제안)는 적용 전 요약 표로 제시하고 항목별 승인을 받는다. 예외 없음
• 승인 없이 실행 가능한 것은 읽기 작업뿐이다 (Read/Glob/Grep/git 조회)
• 제안서((c)/(c′))는 승인을 받아도 파일을 수정하지 않는다 — 승인은 "제안서를 전달받았다"는 확인이며, 실제 수정은 사용자 또는 해당 플러그인 담당 작업의 몫이다

8. Related Components

컴포넌트	관계
/retro 커맨드	이 스킬의 기준을 사용하는 실행 절차 (Phase 1~6)
workflow:sync-claude-md	(a) 컨벤션 변화의 CLAUDE.md 반영 위임 대상
harness:create-flow	(b′) 가드 훅 후보의 스캐폴딩 담당 — lessons 입력 모드는 별도 작업 예정
harness:evolve	피드백 라우팅 골격의 출처. 하네스 컴포넌트 개선(여러 실행에 걸친 피드백 반영)은 그쪽으로 안내
workflow:handoff	세션 컨텍스트 이관 담당 — /retro는 교훈만, /handoff는 작업 상태만 다룬다