회고 스킬

현재 대화 세션을 돌아보며 유의미한 정보를 추출하고, 스킬 문서·상시 로드 지침·서브에이전트 정의에 반영한다. 다음 대화에서 LLM이 같은 실수를 반복하지 않거나, 더 나은 판단을 내릴 수 있도록 맥락을 축적하는 것이 핵심 목적이다.

돌아보는 대상은 두 갈래다 — 사용자와 주고받은 것(내가 뭘 틀렸고 뭘 고쳐 받았나)과 서브에이전트에 위임한 것(무엇을 시켜 무엇을 받았고 그게 쓰였나). 뒤쪽을 빼면 위임으로 돌아간 작업이 통째로 회고에서 사라진다.

범위: 이 스킬은 명시적으로 로드되는 규칙(스킬 SKILL.md, 전역·프로젝트·디렉토리 지침 파일), 서브에이전트 정의, 신규 스킬 추천만 다룬다. 자동 메모리, 날짜별 회고 로그(retrospective/YYYY-MM-DD.md) 같은 별도 기록물은 이 스킬의 대상이 아니다.

실행 절차

Step 1: 대화 세션 분석

현재 대화 전체를 읽으며 아래 항목을 추출한다. 여러 세션을 대상으로 하는 회고라면, 먼저 아래 "옵션: 범위 확장 → 다중 세션·주간 회고 워크플로우"로 세션을 분산 분석한 뒤 그 결과를 종합해 같은 항목을 추출한다.

추출 항목:

• 수정/재작업 발생 지점: 내가 처음 제안한 것을 사용자가 수정 요청한 경우 → 왜 틀렸는지
• 사용자 명시적 피드백: "그건 아니야", "그게 아니라", "다시 해봐", "원본 유지해" 등의 표현
• 사용자 암묵적 피드백: 수정 없이 바로 수락한 접근법 → 무엇이 잘 작동했는지
• 새로 확립한 규칙: 이번 세션에서 사용자가 알려준, 앞으로도 계속 적용될 작업 방식·판단 기준
• 스킬 개선 포인트: 스킬이 놓친 케이스, 잘못된 절차, 빠진 단계
• 반복 작업 패턴: 이번 세션(또는 여러 세션)에서 여러 번 반복한 다단계 절차 → 신규 스킬 후보
• 에이전트 작업: 서브에이전트에 무엇을 시켜 무엇을 받았고 그 결과가 어떻게 쓰였나

→ 아래 "에이전트 작업 진단" 절에서 원재료를 뽑는다

• 수행 지표: 이번 세션에서 셀 수 있는 것 — 재작업 횟수, 사용자 교정 건수, 스킬을 열어 놓고 어긴 조항, 확인 없이 단정했다가 뒤집힌 주장 (세는 규칙은 Step 3)

Step 1-b: 에이전트 작업 진단

이번 범위에서 서브에이전트를 띄웠다면, 그 위임이 값을 했는지 본다. 에이전트를 안 띄웠으면 이 단계를 건너뛴다.

원재료 뽑기 — 현재 SKILL.md가 들어 있는 디렉터리의 scripts/agent_trace.py를 실행한다. 셸에 넘기기 전 절대 경로로 바꾼다. 인자 없이 실행하면 하네스가 넘긴 세션 id(CLAUDE_CODE_SESSION_ID)로 현재 세션을 보고, 그 값이 없으면 현재 작업 디렉터리의 최신 세션 하나를 본다. 기간 회고면 --days N, 특정 세션이면 --session <경로>, 보고서 전문이 필요하면 --full을 붙인다.

스크립트는 에이전트별로 위임 프롬프트 · 보고서 · 직후 사용자 발화 · 소요·토큰·도구 호출 · 동시 실행 여부를 뽑아 마크다운으로 낸다. 좋았는지 나빴는지는 판정하지 않는다 — 그건 아래에서 읽고 판단한다.

직접 띄운 에이전트와 워크플로우 스크립트가 띄운 에이전트를 함께 낸다. 뒤쪽은 대화에 도구 호출로 남지 않아(부모가 부른 것은 워크플로우 하나뿐이다) 따로 읽지 않으면 작업 전체를 워크플로우로 돌린 회고에서 위임 내역이 통째로 "실행 없음"이 된다. 워크플로우 단계에는 직후 사용자 발화를 짝짓지 않는다 — 사용자는 회차 전체를 기다렸지 단계 하나하나에 반응하지 않았고, 짝지으면 같은 발화가 모든 단계의 "반응"으로 복제된다.

하네스가 세션 로그를 제공하지 않거나 형식이 달라 스크립트가 아무것도 못 찾으면, 다른 로그를 억지로 비슷하게 파싱하지 말고 현재 대화에 남아 있는 위임 내역만으로 같은 네 가지를 본다. 그렇게 했으면 "로그 미확보, 대화 기록만으로 판단"임을 결과에 밝힌다.

무엇을 보나 — 네 가지. 각 판정에는 스크립트 출력에서 근거를 인용한다. 인용 없는 판정은 적지 않는다.

1. 결과가 쓰였나 — 보고서의 권고가 이후 편집·결정에 반영됐나, 사용자가 뒤집었나.

결과를 받고 아무 일도 안 일어났으면 그 위임은 헛돈 것이다.

1. 비용이 값을 했나 — 소요·토큰·도구 호출 대비 산출. 크게 쓰고 한두 줄로 끝난 건이 반복되면

에이전트 품질이 아니라 위임 판단의 문제다.

1. 프롬프트가 오염되지 않았나 — 독립 검증으로 띄운 에이전트에 "내가 왜 그렇게 했는지"를 흘렸으면

그건 독립이 아니다. 그 옹호 논리를 그대로 흡수해 같은 사각지대를 공유한다. 범위·경로를 줬는지, 읽기 전용임을 명시했는지도 함께 본다.

1. 띄운 판단이 맞았나 — 독립적인 조사를 순차로 띄워 시간을 버렸는지(스크립트의 "동시 실행" 표시),

직접 하면 될 일을 띄웠는지, 반대로 띄웠어야 하는데 혼자 붙들고 있었는지.

값을 못 구한 칸은 없는 것으로 취급하지 않는다. 스크립트가 "계산 불가"·"완료 알림 없음"으로 낸 항목은 0이 아니라 미측정이다. 그대로 미측정으로 적는다.

Step 2: 인사이트 분류 및 업데이트 항목 결정

추출한 항목을 아래 3가지 카테고리로 분류하고, 각각 업데이트가 필요한지 판단한다. 업데이트 여부는 강제하지 않는다 — 유의미한 변경이 없으면 해당 항목은 건너뛴다.

개선 위치를 먼저 고른다

실패를 찾았다고 바로 금지 문장을 추가하지 않는다. 후보마다 원인과 가장 작은 수정 위치를 고른다.

기존 도구·검사가 해결할 수 있으면 그 경로를 우선한다. 회고 자체가 코드 수정 권한을 주지는 않는다. 승인된 범위의 지침 수정 외에 도구·구조 변경이 필요하면 구체적인 개선안으로 제안하고 승인을 받는다. 기계가 확인할 증거와 사람이 판단할 내용을 구분한다. AI가 설명을 생성한 것을 사용자 이해 완료로 세지 않는다.

업데이트 판단 기준

카테고리별로 아래 기준을 충족할 때만 처리한다.

스킬 개선 — 스킬이 다음에 같은 상황에서 다르게 행동해야 할 때

• 스킬이 커버하지 못한 케이스가 실제로 발생한 경우
• 절차상 순서가 잘못됐거나 빠진 단계가 있는 경우

신규 스킬 추천 — 같은 다단계 작업을 반복했을 때

• 한 세션에서 같은 절차를 여러 번 반복했거나, 기간 회고에서 여러 세션에 걸쳐 같은 순서로 도구를 엮는 패턴이 보일 때.
• 추천만 한다(자동 생성 금지). "이런 패턴이 반복되니 스킬로 만들면 좋겠다"고 제안하고, 사용자가 동의하면 skill-creator로 넘긴다.
• 왜: 반복은 스킬화의 가장 강한 신호고, 회고는 그 신호를 포착하기 가장 좋은 시점이다.

에이전트 정의 / 위임 지시 — 같은 위임 문제가 반복됐을 때

• 한 번 헛돈 것은 그날의 사고일 수 있다. 같은 종류의 에이전트가 같은 것을 반복해서 놓쳤거나,

같은 위임 습관이 반복해서 비용을 버렸을 때만 정의·지시를 고친다.

• 어디를 고칠지 가른다: 그 에이전트가 어떤 작업을 받든 똑같이 잘못하면 에이전트 정의,

특정 스킬 안에서 부를 때만 어긋나면 그 스킬의 위임 지시, 띄울지 말지의 판단 자체가 문제면 상시 로드 지침이다.

• 정의 파일은 짝으로 본다: 도구마다 정의 파일을 따로 두는 환경이면 한쪽만 고쳤을 때

반대쪽이 조용히 어긋난다. 고치기 전에 반대쪽이 있는지 확인한다.

상시 로드 지침 — 계층을 구분해서 반영한다 지침이 적용될 범위에 맞는 층을 고른다. 잘못된 층에 넣으면 너무 넓게(전역) 새거나 너무 좁게(디렉토리) 갇힌다.

• 판단 기준 = 공유 여부: 팀과 공유할 규칙이면 프로젝트/디렉터리 지침, 다른 팀원에게 강요하면 안 되는 개인 방식·로컬 환경이면 하네스가 공식 지원하는 비공유 위치를 쓴다. 지원 근거가 없으면 AGENTS.local.md 같은 파일을 지어내지 말고 사용자에게 저장 위치를 확인한다.
• 전역 변경은 파급이 가장 크니 가장 신중하게 — 정말 모든 프로젝트에 맞을 때만. 사용자가 명시적으로 "항상 이렇게"라고 한 경우.

Step 2-b: 후보 검증 (사용자에게 보이기 전에)

후보가 하나 이상이면 사용자에게 보이기 전에 거른다. 기본 태도는 덜 넣는 쪽이다.

1. 이미 있는지 먼저 직접 본다: 후보마다 대상 파일(지침·스킬·메모리 인덱스)을 grep해 같은 행동이

이미 적혀 있으면 폐기하거나 기존 문장 병합안으로 바꾼다. 이 단계는 서브에이전트 없이 한다.

1. 남은 후보를 검증자 하나에 묶어 넘긴다: 이 플러그인의 retro-verifier 에이전트를 한 번만

띄운다(후보마다 따로 띄우지 않는다). 모델은 지정하지 않아 세션 모델을 따르게 한다. 프롬프트에는 후보 목록(제안 문장·대상 파일·근거 한 줄), 대상 파일 절대경로, 과거 세션 검색 명령(있으면), 도구 호출 상한(기본 15회)만 넣는다. 이름으로 부를 수 없는 하네스는 이 스킬 폴더 기준 ../../agents/retro-verifier.md의 머리말을 뺀 본문을 서브에이전트 지시로 넘긴다.

1. 판정이 채택·병합·자리 이동인 것만 Step 3의 확인 목록에 올린다. 메모리로·폐기는 Step 3 끝

"걸러진 후보"에 한 줄씩 보인다(메모리 저장은 이 스킬 대상이 아니므로 세션이 따로 판단한다).

서브에이전트를 쓸 수 없으면 retro-verifier.md의 판정 기준으로 직접 거르되 "독립 검증 아님"을 밝힌다.

Step 3: 회고 출력 — "무엇을 업데이트할지"를 중심으로

회고 출력은 반영할 업데이트 목록을 중심에 둔다. "잘 된 것 / 개선이 필요했던 것" 같은 서술 섹션은 사용자가 잘 읽지 않으므로 별도로 만들지 않는다 — 업데이트를 낳지 않는 서술은 생략하고, 업데이트로 이어지는 경우에만 그 항목의 한 줄 근거에 녹인다.

수행 지표는 예외로 남긴다 — 서술이 아니라 개수라서 회차를 넘겨 비교되기 때문이다. "잘했다·아쉬웠다"로 쓰지 말고 몇 건인지만 센다.

확인이 필요한 항목(스킬·지침·신규 스킬)을 [ ]로 세워 사용자가 그것만 보고 판단하게 한다.

## 회고 — YYYY-MM-DD

### 수행 지표
- 재작업 N회 — 무엇을 다시 만들었나 한 줄
- 사용자 교정 N건 — 무엇이 틀려 바로잡혔나 한 줄
- 스킬 미준수 N건 — 어느 스킬의 어느 조항인지
- 근거 없는 단정 N건 — 무엇을 단정했다 뒤집혔나

### 에이전트 작업 (N건)
- Explore "세션 로그 구조 조사" — 11분·13.2만 토큰 → 결론 전량 채택, 사용자 이견 없음
- general-purpose "재사용 자산 조사" — 3분·11.6만 토큰 → 절반만 사용, 나머지는 범위 밖
- 둘은 구간이 겹쳐 동시에 돌았다 (병렬 활용 ○)
- 위임 프롬프트에 내 옹호 논리가 들어간 건 0건
- 읽기 전용 지시를 어긴 에이전트 1건 (임시 파일 생성)

### 확인이 필요한 업데이트 (스킬·지침·에이전트·신규 스킬)
- [ ] [스킬] daily-standup — "다듬기 모드" 분기 추가 (왜: …)
- [ ] [지침·전역] 문서 고칠 때 그림 안 글자도 함께 보기 (왜: …)
- [ ] [지침·프로젝트] `<repo>/CLAUDE.md`에 … 규칙 추가 (왜: …)
- [ ] [에이전트] Explore 정의에 … 추가 (왜: 같은 문제 N회 반복)
- [ ] [신규 스킬?] 같은 다단계 작업 N회 반복 → skill-creator 제안 (왜: …)

### 걸러진 후보 (N건)
- 폐기: 문서 고칠 때 그림도 보기 — 이미 있음 (`<파일>:<라인>`)
- 메모리로: ◯◯ 빌드 옵션 — 한 번뿐

• 확인이 필요한 항목이 하나도 없으면 그 섹션을 통째로 생략하고 "이번 세션엔 확인받을 업데이트 없음"만 남긴다(빈 서술로 부풀리지 않는다).
• 각 항목엔 왜를 한 줄로 붙인다.
• 항목 이름은 고칠 파일의 절 이름이 아니라 다음에 무엇이 달라지는지로 쓴다 (예: "◯◯ 원칙에 항목 추가" ✗ → "문서 고칠 때 그림 안 글자도 함께 보기" ○).
• 에이전트 작업 섹션은 에이전트를 띄웠을 때만 낸다. 0건이면 통째로 생략한다(수행 지표와 같은 규칙).

띄웠는데 지표를 못 구한 항목은 빼지 말고 "미측정"으로 남긴다.

수행 지표를 세는 규칙 — 넷 다 0이면 수행 지표: 해당 없음 한 줄로 접는다.

• 스킬 미준수는 어느 스킬의 어느 조항인지 함께 적는다 — 그 자체가 스킬 개선 후보다.
• "없다"는 부재 주장은 특히 세라. 일부만 보고 없다고 단정하는 것이 가장 흔한 유형이다.
• 지표는 그 자체로 끝나지 않는다. 0이 아닌 항목은 위 확인 목록의 근거로 이어져야 한다 — 이어지지 않으면 센 의미가 없다.

Step 4: 업데이트 실행 (전부 사용자 확인 후)

추천 목록을 보여주고 사용자 확인을 받은 뒤 실행한다.

"위 항목을 업데이트할까요? 빼거나 추가할 항목이 있으면 말씀해 주세요."

사용자가 전체 동의하거나 일부 선택하면 해당 항목만 실행한다. 확인이 필요한 항목이 하나도 없으면 이 확인 단계를 생략한다 — 억지로 만들지 않는다.

업데이트 원칙:

• 스킬 문서: 기존 문서를 최대한 유지하고, 변경 최소화. 새 규칙은 기존 구조에 자연스럽게 삽입.
• 상시 로드 지침: 위 계층 표대로 올바른 층을 고른다. 전역 변경은 사용자가 명시적으로 동의한 경우만.
• 에이전트 정의: 도구마다 정의 파일이 따로 있으면 양쪽을 함께 고친다. 한쪽만 고쳤으면

그 사실을 완료 보고에 밝힌다.

• 신규 스킬 추천: 제안만 하고 사용자 동의를 받는다. 동의 시 skill-creator로 연결한다.

Step 5: 완료 보고

업데이트한 파일 목록과 변경 내용을 간략히 보고한다.

옵션: 범위 확장

기본은 현재 대화 세션만 분석한다. 사용자가 원하면 아래 추가 소스도 포함할 수 있다.

다중 세션·주간 회고 워크플로우

"지난 주", "이번 주", "최근 N일", "여러 세션" 같은 요청은 세션이 수십~수백 개라 현재 컨텍스트로 한 번에 읽을 수 없다. 아래 순서로 분산 처리한다.

1. 세션 수집 — 현재 하네스가 세션 로그 위치와 형식을 실제로 제공할 때만 대상 기간의 실질 세션을 모은다. 알려진 예는 Claude Code의 ~/.claude/projects/<인코딩된-경로>/*.jsonl과 Codex 계열의 ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl이다. 다른 위치를 추측하지 않는다.

첫 몇 이벤트로 스키마를 확인한 뒤 timestamp와 사용자 발화를 추출한다. Claude Code 스키마가 확인된 경우에는 subagents/ 하위를 제외하고 20줄 이하의 즉시 종료 세션을 거르는 기존 기준을 유지한다. 다른 하네스에는 같은 줄 수나 필드명을 무조건 적용하지 않는다. 로그에 접근할 수 없으면 다중 세션 범위는 수행할 수 없다고 알리고, 현재 대화 회고로 좁힐지 사용자에게 확인한다.

2. 날짜별 분산 분석 — 날짜(또는 프로젝트) 단위로 묶는다. 서브에이전트 위임이 가능하면 독립 묶음을 병렬 분배하고, 불가능하면 같은 묶음을 순차 처리한다. 각 패스는 사용자 발화에 집중하고 tool result는 제외하며, assistant 출력은 결론만 일부 참고한다. Step 1의 추출 항목과 날짜별 마크다운 출력 형식을 모든 패스에 동일하게 적용한다.

3. 실제 산출물 대조 — 각 레포 git log --since=<시작일> 으로 커밋/PR을 모아 교차 검증한다. 세션은 "왜/어떻게"(과정·피드백), git log는 "무엇을"(성과)을 보여준다.

4. 종합 — 분산 분석 결과를 합쳐 반복되는 선호 패턴을 추린다. 주간 회고에서는 개별 사건보다 반복 패턴이 가장 큰 자산이다 — 반복 패턴은 상시 로드 지침 후보다.

주의사항

1. 강제 업데이트 금지: 유의미한 변경이 없으면 파일을 건드리지 않는다. "변경 없음"이 정직한 결과다.
2. 과잉 해석 금지: 사용자가 단순히 방향을 바꾼 것과 내가 틀린 것을 구별한다. 사용자 의도 변경은 피드백이 아니다.
3. 추천은 추천으로 끝낸다: 신규 스킬은 제안만 하고, 사용자 동의 없이 스킬을 만들지 않는다.
4. 지침 계층 신중하게: 층 선택을 틀리면 너무 넓게/좁게 퍼진다. 특히 전역 변경은 파급이 크니 사용자가 명시적으로 원하는 경우에만. 개인 비공유 지침은 현재 하네스의 공식 지원 위치가 확인될 때만 쓴다.
5. 에이전트 정의는 짝으로 고친다: 도구마다 정의 파일을 따로 갖고 있으면 한쪽만 고쳤을 때 반대쪽이 조용히 어긋난다. 고칠 때 양쪽을 함께 확인하고, 한쪽만 고쳤으면 보고에 밝힌다.
6. 에이전트 한 건으로 정의를 고치지 않는다: 한 번 헛돈 것은 그날의 사고일 수 있다. 같은 문제가 반복될 때만 정의를 건드리고, 1회성은 이번 회고의 서술로만 남긴다.