# Retrospective

> 현재 대화 세션, 또는 여러 세션(지난 주·이번 주 같은 주간/기간 단위, 여러 프로젝트 포함)을 회고하여 유의미한 인사이트·피드백을 추출하고, 관련 스킬·지침 문서에 반영하는 스킬. 사용자가 "회고해줘", "회고", "이번 작업 회고", "retrospective", "오늘 대화 정리", "이번 세션 돌아봐", "지난 주 회고", "주간 회고", "지난 N일 돌아봐", "여러 세션 정리해줘", "배운 것 정리해줘", "피드백 반영해줘" 같은 표현을 쓰면 반드시 이 스킬을 사용한다. 작업 완료 후 같은 실수를 반복하지 않고 LLM이 다음 대화에서 더 잘 도울 수 있도록 맥락을 남기는 것이 목적이다. 이 스킬은 스킬 문서와 상시 로드 지침(전역/프로젝트 CLAUDE.md 등)만 갱신 대상으로 삼는다 — 메모리·볼트 회고 로그는 다루지 않는다.

- Skill: `gagip/retrospective` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gagip/retrospective`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gagip/retrospective/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gagip (https://skillmd.com/u/gagip)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gagip/retrospective

---


# 회고 스킬

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

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

---

## 실행 절차

### Step 1: 대화 세션 분석

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

**추출 항목**:
- **수정/재작업 발생 지점**: 내가 처음 제안한 것을 사용자가 수정 요청한 경우 → 왜 틀렸는지
- **사용자 명시적 피드백**: "그건 아니야", "그게 아니라", "다시 해봐", "원본 유지해" 등의 표현
- **사용자 암묵적 피드백**: 수정 없이 바로 수락한 접근법 → 무엇이 잘 작동했는지
- **새로 확립한 규칙**: 이번 세션에서 사용자가 알려준, 앞으로도 계속 적용될 작업 방식·판단 기준
- **스킬 개선 포인트**: 스킬이 놓친 케이스, 잘못된 절차, 빠진 단계
- **반복 작업 패턴**: 이번 세션(또는 여러 세션)에서 여러 번 반복한 다단계 절차 → 신규 스킬 후보
- **수행 지표**: 이번 세션에서 **셀 수 있는 것** — 재작업 횟수, 사용자 교정 건수, 스킬을 열어 놓고 어긴 조항, 확인 없이 단정했다가 뒤집힌 주장 (세는 규칙은 Step 3)

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

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

| 카테고리 | 무엇을 추출하나 | 어디로 보내나 |
|---|---|---|
| 스킬 개선 | 스킬이 놓친 케이스, 잘못된 절차 | 해당 `SKILL.md` 직접 수정 |
| 신규 스킬 추천 | 여러 번 반복한 다단계 작업 패턴 | 사용자에게 스킬화 제안 (동의 시 `skill-creator`로 연결) |
| 상시 로드 지침 | 지속 적용할 규칙 | 현재 하네스가 실제로 읽는 전역/프로젝트/디렉토리 지침 (아래 계층 기준) |

### 업데이트 판단 기준

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

**스킬 개선** — 스킬이 다음에 같은 상황에서 다르게 행동해야 할 때
- 스킬이 커버하지 못한 케이스가 실제로 발생한 경우
- 절차상 순서가 잘못됐거나 빠진 단계가 있는 경우

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

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

| 층 | 대상 | 적용 범위 | 공유 | 언제 |
|---|---|---|---|---|
| 전역 | 현재 하네스가 실제로 로드한 전역 지침 | 모든 프로젝트·대화 | 개인 환경 | 보편 규칙. "항상 이렇게 해줘" |
| 프로젝트 | `<repo>/AGENTS.md`, `<repo>/CLAUDE.md` 등 현재 하네스가 읽는 파일 | 그 레포 전체 | 팀 공유(git) | 그 프로젝트의 팀 규칙·구조 |
| 디렉토리 | 하위 디렉터리에 있는 같은 종류의 지침 파일 | 그 하위 트리 | 팀 공유(git) | 모노레포 하위 패키지 등 국소 규칙 |
| 개인 | 현재 하네스가 공식 지원하고 실제 존재하는 비공유 지침 위치 | 그 레포, 나만 | git 미추적 | 비공유 작업 방식·로컬 경로·개인 선호 |

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

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

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

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

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

```
## 회고 — YYYY-MM-DD

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

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

- 확인이 필요한 항목이 **하나도 없으면** 그 섹션을 통째로 생략하고 "이번 세션엔 확인받을 업데이트 없음"만 남긴다(빈 서술로 부풀리지 않는다).
- 각 항목엔 **왜**를 한 줄로 붙인다.

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

| 지표 | 세는 것 | 세지 않는 것 |
|---|---|---|
| 재작업 | 내가 만든 산출물을 사용자 지적으로 다시 만든 횟수 | **사용자가 방향을 바꾼 것**(주의사항 2와 같은 기준) |
| 사용자 교정 | 내가 말한 사실·판단이 틀려 사용자가 바로잡은 건수 | 취향·선호 차이 |
| 스킬 미준수 | 스킬을 열어 놓고 그 안의 조항을 어긴 건수 | 스킬을 아예 안 연 경우(그건 스킬 개선 포인트) |
| 근거 없는 단정 | 확인하지 않고 단정했다가 뒤집힌 주장 | 명시적으로 "확인 필요"라 밝힌 추정 |

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

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

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

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

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

**업데이트 원칙**:
- **스킬 문서**: 기존 문서를 최대한 유지하고, 변경 최소화. 새 규칙은 기존 구조에 자연스럽게 삽입.
- **상시 로드 지침**: 위 계층 표대로 올바른 층을 고른다. 전역 변경은 사용자가 명시적으로 동의한 경우만.
- **신규 스킬 추천**: 제안만 하고 사용자 동의를 받는다. 동의 시 `skill-creator`로 연결한다.

### Step 5: 완료 보고

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

---

## 옵션: 범위 확장

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

| 옵션 | 활성화 방법 | 추가 작업 |
|---|---|---|
| 오늘 git log | "git 커밋도 포함해줘" | 워크스페이스 하위 레포의 오늘 커밋 수집 |
| 오늘 전체 세션 | "오늘 전체 세션 다 봐줘" | 오늘자 세션 JSONL 모아 분석 (아래 워크플로우) |
| 주간/기간 회고 | "지난 주 회고", "최근 N일" | 기간 내 여러 프로젝트 세션 전체를 분산 분석 (아래 워크플로우) |

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

"지난 주", "이번 주", "최근 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. **지침 계층 신중하게**: 층 선택을 틀리면 너무 넓게/좁게 퍼진다. 특히 전역 변경은 파급이 크니 사용자가 명시적으로 원하는 경우에만. 개인 비공유 지침은 현재 하네스의 공식 지원 위치가 확인될 때만 쓴다.