---
name: project-gotchas
description: >
  오답노트 + 성공 패턴 자동 관리. CLI(Claude/Codex/Gemini)의 실패 패턴(gotchas)과
  성공 패턴(learned)을 2계층(글로벌 + 프로젝트별)으로 기록하고 참조.
  므네모(mnemo)가 생성하는 memory/ 폴더 안에서 크로스 CLI 참조 가능.
  트리거 1 (참조): 작업 시작 시 gotchas + learned를 확인.
  트리거 2 (기록): "실수였어", "이거 기록해", "gotcha 추가", "함정이었네",
  "오답노트", "이것도 주의사항", "이 패턴 좋다", "이거 기억해" 같은 표현 시.
  트리거 3 (자발적 제안): CLI가 실수를 수정당하거나 성공 패턴이 반복될 때 기록을 제안.
when_to_use: >
  1. 작업 시 기존 gotchas(글로벌 + 프로젝트)를 참조하여 같은 실수 방지.
  2. 사용자가 기록을 요청하면 적절한 계층에 파일 생성 + index.md 업데이트.
  3. CLI가 실수를 수정당한 후, 반복 가능한 패턴이면 "이거 gotchas에 기록할까요?" 제안.
avoid_if: >
  단순 오타, 일회성 실수, 이미 CLAUDE.md에 규칙으로 등록된 내용.
---

# Project Gotchas (오답노트 + 성공 패턴)

CLI의 실패 패턴과 성공 패턴을 자동으로 기록하고 학습합니다.
글로벌 설치 1회로 어떤 프로젝트에서든 자동 작동합니다.
므네모(mnemo)가 생성하는 `memory/` 폴더 안에 관리하여 Claude/Codex/Gemini 모두 참조 가능합니다.

## 2계층 저장 구조

```
어떤-프로젝트/memory/
├── gotchas/                        ← 실패 패턴 (오답노트)
│   ├── index.md
│   ├── observations.jsonl          ← 에러 관찰 로그 (자동 생성)
│   ├── 001-특정API-반올림주의.md
│   └── 002-빌드설정-함정.md
└── learned/                        ← 성공 패턴 (학습 노트)
    ├── index.md
    ├── observations.jsonl          ← 성공 관찰 로그 (자동 생성)
    ├── 001-grep-먼저-edit-나중에.md
    └── 002-테스트-먼저-구현-나중에.md
```

- `memory/` 폴더가 없으면 자동 생성
- 므네모가 이미 `memory/`를 관리하므로 별도 `.gitignore` 처리 불필요
- Claude, Codex, Gemini 어떤 CLI에서든 접근 가능

### 참조 순서

1. **글로벌** 글로벌 스킬 레포의 `memory/gotchas/` + `memory/learned/` 확인
2. **프로젝트** 현재 프로젝트의 `memory/gotchas/` + `memory/learned/` 확인
3. 현재 작업과 관련된 키워드 매칭 → 해당 파일만 읽기

### 저장 범위 판단

| 범위 | 기준 | 예시 |
|------|------|------|
| **글로벌** | CLI 버릇, OS/도구 함정, 프레임워크 공통 패턴 | YAML 파싱, PowerShell 성능, 서브에이전트 return 폭발 |
| **프로젝트** | 특정 API, 특정 라이브러리 설정, 프로젝트 고유 규칙 | 특정 DB 스키마, 사내 API 주의점, 빌드 설정 |

판단이 애매하면 사용자에게 "글로벌과 프로젝트 중 어디에 기록할까요?" 확인.

## 기록 유형

| 유형 | 설명 | 예시 |
|------|------|------|
| **CLI 오답** | Claude/Codex/Gemini가 반복 실수하는 패턴 | return text 폭발, YAML 형식 오류 |
| **환경 함정** | OS/도구/라이브러리의 예상치 못한 동작 | PowerShell tail 성능, .bat 인코딩 |
| **설치 함정** | dependency 누락, 설정 오류 | node_modules 누락 handshake 실패 |

## 워크플로우

### 1. 참조 (작업 시작 시)

1. 글로벌 `memory/gotchas/index.md` 존재 여부 확인
2. 프로젝트 `memory/gotchas/index.md` 존재 여부 확인
3. 양쪽 인덱스에서 현재 작업과 관련된 키워드 매칭
4. 매칭된 항목의 개별 파일만 읽기 (전체 읽기 금지)

### 2. 기록 (사용자 요청 또는 자발적 제안)

기록 트리거:
- 사용자가 "실수였어", "gotcha 추가", "오답노트" 등 요청
- CLI가 실수를 수정당한 후 반복 가능한 패턴이라 판단되면 자발적 제안

기록 절차:

1. 저장 범위 판단 (글로벌 vs 프로젝트)
2. `memory/gotchas/` 디렉토리가 없으면 자동 생성
3. `index.md`가 없으면 빈 인덱스 테이블로 초기화
4. 기존 파일명에서 마지막 번호 확인 → 다음 번호로 파일 생성
5. `index.md` 테이블에 행 추가

### 3. 자발적 제안 판단 기준

기록을 제안할 것:
- CLI가 **2회 이상 같은 유형의 실수**를 했을 때
- 사용자가 **"아까도 그랬잖아"** 류의 지적을 했을 때
- 환경/도구의 **문서화되지 않은 동작**을 발견했을 때

기록하지 않을 것:
- 단순 오타, 일회성 실수
- 이미 CLAUDE.md에 규칙으로 등록된 내용
- 프로젝트와 무관한 일반 지식

## 파일 형식

### index.md (인덱스)

```markdown
# Gotchas

| # | 함정 | 유형 | 키워드 | 파일 |
|---|------|------|--------|------|
| 1 | 서브에이전트 return 폭발 | CLI 오답 | agent, subagent | [001-서브에이전트-return-폭발.md](001-서브에이전트-return-폭발.md) |
```

### 개별 gotcha 파일

```markdown
# 제목

`tags: keyword1, keyword2`
`type: CLI 오답 | 환경 함정 | 설치 함정`
`date: YYYY-MM-DD`

**함정**: 무엇이 잘못되었는지 (구체적으로)
**해결**: 어떻게 고쳤는지 (재현 가능하게)
**교훈**: 다음에 이 상황에서 어떻게 해야 하는지
```

## 승격 규칙

- 프로젝트 gotcha가 **다른 프로젝트에서도 동일하게 발생**하면 글로벌로 승격
- 승격된 항목은 프로젝트 index.md에서 `PROMOTED → global` 표시
- 글로벌 gotcha가 **CLAUDE.md 규칙으로 등록**되면 `PROMOTED → CLAUDE.md` 표시

## 자동 관찰 시스템

### 구조

```
skills/project-gotchas/
├── SKILL.md              ← 이 파일 (규칙서)
├── config.json           ← 관찰 설정
└── agents/
    └── gotcha-analyzer.md ← cleanup-low 분석 에이전트 (패턴 감지 → gotcha 생성)

hooks/
├── save-tool-use.ps1|sh          ← Claude PostToolUse: 도구 단위 관찰
├── codex-mnemo/save-turn.ps1|sh  ← Codex notify: 턴 단위 관찰
└── gemini-mnemo/save-turn.ps1|sh ← Gemini AfterAgent: 턴 단위 관찰
```

### 동작 흐름

별도 훅 없이 각 CLI의 므네모 저장 훅에 통합되어 동작합니다.

```
Claude: 도구 호출 완료 (PostToolUse)
    ↓
hooks/save-tool-use.ps1|sh (기존 므네모 훅)
    ↓ 1. 도구 사용 로그 기록 (conversations/toollog.md) ← 기존 기능
    ↓ 2. 에러 패턴 감지 (error|fail|exception|denied 등)
    ↓ 에러가 있는 경우만:
    ↓   memory/gotchas/ 없으면 자동 생성
    ↓   시크릿 스크러빙
    ↓   observations.jsonl에 기록
    ↓
Codex/Gemini: 턴 종료/응답 완료 훅
    ↓
save-turn.ps1|sh
    ↓ 응답에 에러 패턴이 있으면 memory/gotchas/observations.jsonl
    ↓ 정상 응답이면 memory/learned/observations.jsonl

observations.jsonl 에 관찰 축적
    ↓ 관찰 20개 이상 축적 시
    ↓
agents/gotcha-analyzer.md (cleanup-low 모델 티어)
    ↓ 에러→수정 패턴, 반복 실패 감지
    ↓ 글로벌/프로젝트 범위 자동 판단
    ↓
memory/gotchas/에 gotcha 파일 자동 생성 + index.md 업데이트
```

### 분석 모델 매핑

`gotcha-analyzer`의 `model: haiku`는 Claude Code 네이티브 실행용 실제 모델명입니다.
Codex/Gemini에서는 같은 이름을 그대로 쓰지 않고 `cleanup-low` 티어로 해석합니다.

| CLI | cleanup-low 매핑 |
|-----|------------------|
| Claude | `haiku` |
| Codex | `gpt-5.2-mini` + `reasoning low` |
| Gemini | `gemini-2.5-flash-lite` |

### 훅 등록

별도 등록 불필요. 므네모 설치 시 각 CLI에 맞는 훅이 자동 등록됩니다.
Claude는 도구 단위 관찰, Codex/Gemini는 구조적 한계상 턴 단위 관찰입니다.

### 설정 (config.json)

```json
{
  "observer": {
    "enabled": true,
    "min_observations_to_analyze": 20
  }
}
```

| 키 | 기본값 | 설명 |
|----|--------|------|
| `observer.enabled` | `true` | 관찰 활성화 여부 |
| `observer.min_observations_to_analyze` | `20` | 분석 트리거 최소 관찰 수 |

### 관찰 데이터 관리

- **에러가 포함된 도구 호출만** 기록 (노이즈 최소화)
- `observations.jsonl`은 10MB 초과 시 자동 아카이브
- 아카이브: `memory/gotchas/archive/observations-YYYY-MM-DD.jsonl`
- 시크릿 패턴(api_key, token, password 등)은 `[REDACTED]`로 자동 스크러빙
- Glob/Grep/Read 등 빈번한 도구는 save-tool-use에서 이미 스킵

## 주의사항

- `index.md`는 **간결하게** 유지 (인덱스만, 상세 내용은 개별 파일에)
- 파일명은 `NNN-짧은-설명.md` 형식 (번호로 순서 보장)
- gotchas가 30개 이상 쌓이면 유형별로 하위 디렉토리 분리 고려
- 글로벌과 프로젝트 양쪽에 같은 내용이 중복되지 않도록 주의
- 분석 에이전트의 return은 **1줄 요약만** (컨텍스트 폭발 방지)