| name | compound-engineering |
| description | 이 프로젝트에서 실수·교정·발견을 docs/LESSONS.md에 기록하고, 그 교훈을 하네스(에이전트·스킬·CLAUDE.md)·규약·코드에 되먹여 같은 실수가 재발하지 않게 하는 실천. 버그를 고쳤거나, 사용자에게 교정받았거나, "이렇게 했어야 했다"는 깨달음이 생겼거나, 구조의 모순·개선점을 발견했을 때 반드시 사용. "교훈 기록", "lesson", "compound", "하네스 개선/업데이트" 상황에 사용. |
Compound Engineering — 실수를 자산으로
매 실수를 한 번 고치고 끝내지 않는다. 기록 → 되먹임으로 시스템이 시간이 갈수록 똑똑해지게 한다(compound). 비용은 한 줄, 이득은 영구적이다.
언제 기록하나 (트리거)
- 버그를 고쳤다 (특히 일찍 잡았으면 좋았을 것).
- 사용자에게 교정받았다 / 가정이 틀렸다.
- "측정했더니 통념과 달랐다" 같은 발견.
- 하네스/구조의 모순·중복·개선점을 발견했다.
어떻게 (2단계)
1. 기록 — docs/LESSONS.md에 한 항목 추가 (terse)
### YYYY-MM-DD — <한 줄 제목>
- 무엇: 무슨 일이 있었나 (증상)
- 근본 원인: 왜 생겼나
- 고친 방법: 무엇을 바꿨나 (file/commit)
- 재발 방지(되먹임): 어떤 규약/하네스/테스트를 바꿔 같은 실수를 막았나
근본 원인까지 적는다(증상만 적으면 되먹임이 안 나온다).
2. 되먹임 — 교훈을 시스템에 반영
교훈 유형 → 반영 대상:
| 유형 | 되먹임 대상 |
|---|
| 코드 규약/패턴 실수 | health-trainer-conventions 또는 해당 스킬 |
| 도메인 계약 오해 | pose-rule-authoring 등 도메인 스킬 |
| 에이전트가 반복 실패 | 해당 .claude/agents/*.md |
| 검증 누락(예: 빌드 안 해봄) | 검증 스킬/오케스트레이터/CI |
| 환경 가정 오류 | CLAUDE.md 환경 현실 |
되먹임이 하네스를 바꾸면 CLAUDE.md 변경 이력에 한 줄 남긴다. 반영 커밋은 작게, 그때그때.
원칙
- 측정 > 추측. 통념·가정은 가능하면 데이터로 확인하고, 결과를 교훈으로 남긴다.
- 일찍 검증. "디바이스 필요(미검증)"가 "검증 불가"는 아니다 — 컴파일·계약·테스트로 가능한 검증은 미루지 않는다.
- terse. 항목은 짧게. 길어지면 가치가 묻힌다.
- harness 진화 원칙(harness 스킬 Phase 7)과 한 쌍이다 — 이 스킬은 "왜 바꾸는지"의 근거를 모은다.
