git:20260508.a905dd0 to git:20260510.bca506a

---

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 ← 분석 에이전트 (패턴 감지 → 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 (메인 세션 모델 상속)

↓ 에러→수정 패턴, 반복 실패 감지

↓ 글로벌/프로젝트 범위 자동 판단

↓

memory/gotchas/에 gotcha 파일 자동 생성 + index.md 업데이트

```

### 분석 모델 정책

`gotcha-analyzer`는 frontmatter에 `model:`을 지정하지 않아 **호출자(메인 세션) 모델을 상속**합니다.

Anthropic Dreaming(`model: claude-opus-4-7`)과 동등한 분석 품질을 얻기 위한 의도된 설계입니다.

임계값 50으로 격하되어 빈도가 낮으므로 비용 부담은 제한적입니다.

| CLI | 상속 모델 |

|-----|----------|

| Claude | `claude-opus-4-7` |

| Codex | `gpt-5.5` |

| Gemini | `gemini-3.1-pro-preview` |

### 훅 등록

별도 등록 불필요. 므네모 설치 시 각 CLI에 맞는 훅이 자동 등록됩니다.

Claude는 도구 단위 관찰, Codex/Gemini는 구조적 한계상 턴 단위 관찰입니다.

### 설정 (config.json)

```json

{

"observer": {

"enabled": true,

}

}

```

| 키 | 기본값 | 설명 |

|----|--------|------|

| `observer.enabled` | `true` | 관찰 활성화 여부 |

### 관찰 데이터 관리

- **에러가 포함된 도구 호출만** 기록 (노이즈 최소화)

- `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줄 요약만** (컨텍스트 폭발 방지)