Harness retro
과거 세션에서 잘못된 부분을 찾아내고, 동일한 문제가 재발하지 않도록 설정을 변경합니다. 모든 발견 사항은 특정 세션 기록의 증거를 제시해야 합니다. 사용자가 승인하기 전에 변경 사항을 절대 적용하지 마십시오.
1. 세션 기록 수집
수집기는 이 파일과 같은 디렉토리에 있는 표준 라이브러리 전용 스크립트입니다. -I 플래그와 함께 실행하세요. 출력 결과를 세션 스크래치패드에 쓰거나, 스크래치패드가 없는 경우 임시 디렉토리에 쓰세요:
python3 -I <이 스킬의 기본 디렉토리>/scripts/mine.py [경로] [--since 30d] --out <스크래치패드>/retro.json
- PATH 없이 실행하면 현재 작업 디렉토리의 프로젝트 기록을 수집합니다. 다른 프로젝트를 수집하려면 해당 작업 디렉토리 경로를 지정하거나,
--project=<키>를 사용하여~/.claude/projects아래의 폴더 이름을 지정하세요. 키가-로 시작할 수 있으므로=형식을 사용하세요. - 사용자가 특정 기간을 지정했다면
--since를 사용하세요. 출력이 잘렸고 더 많은 데이터가 필요한 경우에만--max-bytes(기본값 40000)를 늘리세요. - 사용자가 모든 프로젝트를 요청한 경우
~/.claude/projects의 각 폴더에 대해 한 번씩 실행하고, 마찰이 가장 많은 프로젝트를 확인하세요.
스크립트는 한 줄 요약을 출력합니다. 수집된 세션이 거의 없거나 전혀 없으면 사용자에게 알리세요. Claude Code는 cleanupPeriodDays(기본값 30) 후에 트랜스크립트를 삭제하므로, 오래된 기록은 사라졌을 수 있습니다. 나중에 더 깊은 회고를 원한다면 해당 설정을 높이는 것을 제안하세요.
2. 신호 읽기
JSON에는 마찰 점수 순으로 정렬된 세션 목록이 포함됩니다. 각 항목에는 signal, score, ts, prior_prompt(사용자의 요청), recent_actions(신호 발생 직전 Claude의 마지막 도구 호출), 그리고 user_reaction 또는 detail이 포함됩니다.
신호(중요도 순):
user_correction: 사용자가 반박했습니다. 5점 이상의 점수는 강한 불만 또는 반복("still", "again", "I said", 욕설)을 의미합니다.edit_revert및edit_churn: Claude가 동일한 파일을 반복해서 수정했습니다.tool_error_streak: Claude가 동일한 실패를 계속 경험했습니다.interrupted: 사용자가 Claude의 작업을 중간에 중단했습니다. 이는 일반적으로 잘못된 방향으로 진행 중이었음을 의미합니다.permission_denied: Claude가 사용자 또는 분류기가 차단한 작업을 시도했습니다.self_retraction: Claude가 오류를 인정했습니다. 이 신호는 노이즈가 많으므로 보조 증거로만 사용하세요.
정규식은 단순합니다. 일반적인 명령어의 "don't"나 네트워크 오류 후의 "try again"과 같은 잘못된 긍정은 폐기하세요. 항목이 모호한 경우 해당 트랜스크립트를 확인하세요. 파일은 ~/.claude/projects/<키>/<세션>.jsonl에 있으며, 타임스탬프로 grep하여 주변 몇 줄을 읽으세요. 전체 트랜스크립트를 읽지 마세요.
3. 패턴 그룹화
실제 신호를 반복되는 패턴으로 그룹화하세요. 패턴은 하나의 근본 원인으로, Claude가 잘못 수행하는 동작으로 설명됩니다. 예: "승인된 에셋 라이브러리 대신 새 이미지를 생성함", "새 버전을 만들지 않고 현재 버전을 편집함", "빌드 출력을 확인하지 않고 변경 사항이 표시된다고 주장함". 각 패턴에 대해 다음을 기록하세요:
- 발생 빈도 및 세션 수.
- 사용자의 짧은 인용문 2-3개(세션 제목 및 날짜 포함).
- 근본 원인. 다음 중 하나를 선택하세요: 누락된 지식, 존재했지만 무시된 규칙, 잘못된 기본 워크플로우, 누락된 검증, 또는 도구/권한 부족.
단일 사건은 사용자가 명백히 화가 났거나 비용이 높은 경우(예: 파괴적이거나 작업 손실)에만 집계하세요.
4. 현재 Harness 확인
변경 사항을 제안하기 전에 현재 설정을 읽으세요:
~/.claude/CLAUDE.md, 프로젝트CLAUDE.md및 중첩된 모든 파일.~/.claude/settings.json, 프로젝트의.claude/settings.json및.claude/settings.local.json(후크, 권한).- 프로젝트 메모리 디렉토리
~/.claude/projects/<키>/memory/및MEMORY.md. ~/.claude/skills/및 프로젝트의.claude/skills/에 있는 스킬.
이미 Claude가 무시한 규칙으로 패턴이 커버되는 경우, 동일한 규칙을 다시 추가하는 것은 도움이 되지 않습니다. 규칙을 더 구체적으로 만들고 표시될 위치에 배치하거나, 더 강력한 메커니즘으로 전환하세요.
5. 해결책 선택
각 패턴에 대해 실제로 작동할 가장 가벼운 메커니즘을 사용하세요:
| 근본 원인 | 해결책 |
|---|---|
| Claude가 몰랐던 프로젝트 사실 | 프로젝트 메모리 디렉토리에 name, description, metadata.type frontmatter와 Why: 및 How to apply: 본문을 포함한 메모리 파일, 그리고 MEMORY.md에 한 줄 포인터를 추가하세요. 중복을 피하기 위해 기존 메모리를 업데이트하세요. |
| 이 저장소에 대한 지속적인 규칙 | 프로젝트 CLAUDE.md |
| 모든 프로젝트에 대한 규칙 | ~/.claude/CLAUDE.md |
| 계속 위반되며 스크립트로 확인 가능한 규칙(포맷팅, 금지 문자열, 커밋 전 필수 명령어 등) | settings.json의 후크. update-config 스킬이 있으면 사용하세요. |
| 안전한 명령어에 대한 반복적인 권한 프롬프트 또는 거부 | 허용 목록 항목을 제안하거나, fewer-permission-prompts 스킬이 있으면 제안하세요. 파괴적인 명령어에 대한 권한은 확장하지 마세요. |
| 계속 잘못되는 다단계 워크플로우 | 새 스킬 또는 편집된 스킬(skill-creator가 있으면 사용하세요). |
| Claude Code 제품 버그 | 보고서에 기록하세요. Harness 수정 방법은 없습니다. |
규칙은 파일, 에셋 경로, 명령어 또는 버전 이름과 같은 특정 항목을 명명하는 구체적이고 확인 가능한 지침으로 작성하세요. "이미지에 주의하세요"는 너무 모호하여 실행할 수 없습니다.
6. 보고 및 승인 얻기
가장 비용이 많이 드는 패턴부터 순서대로 각 패턴에 대한 섹션을 하나씩 제시하세요. 각 섹션:
- 패턴 요약 (한 줄).
- 증거: 횟수, 세션, 그리고 2-3개의 짧은 인용문 (날짜 포함).
- 근본 원인.
- 제안된 변경 사항: 대상 파일 및 정확한 텍스트 또는 diff.
그런 다음 어떤 변경 사항을 적용할지 물어보세요. 패턴당 하나의 옵션이 있는 다중 선택 AskUserQuestion이 효과적입니다. 승인된 변경 사항만 적용하고, 변경된 내용과 위치를 나열하세요.
규칙 작성
CLAUDE.md, 메모리 또는 스킬에 작성되는 모든 내용은 사용자의 CLAUDE.md 파일에 있는 어조, 금지 단어 또는 귀속 규칙과 같은 작성 규칙을 따라야 합니다. 짧고 구체적으로 유지하세요. 트랜스크립트의 인용문에는 사용자가 붙여넣은 비밀이 포함될 수 있습니다. 수집기는 일반적인 키 형식을 수정(redact)하지만, 텍스트를 파일에 복사하기 전에 확인하세요.