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

CLI의 실패 패턴과 성공 패턴을 자동 수집하고 명시적으로 정제합니다. 글로벌 설치 1회로 어떤 프로젝트에서든 자동 작동합니다. 므네모(mnemo)가 생성하는 memory/ 폴더 안에 관리하여 Claude/Codex/Antigravity/Grok 모두 참조 가능합니다.

단순 오타·일회성 실수·이미 전역 지침에 등록된 규칙은 새 항목으로 만들지 않습니다.

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, Antigravity 어떤 CLI에서든 접근 가능

참조 순서

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

저장 범위 판단

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

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

기록 유형

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

워크플로우

1. 참조 (작업 시작 시)

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

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

기록 트리거:

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

기록 절차:

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

3. 자발적 제안 판단 기준

기록을 제안할 것:

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

기록하지 않을 것:

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

파일 형식

index.md (인덱스)

# Gotchas

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

개별 gotcha 파일

# 제목

`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           ← 관찰 설정

hooks/
├── save-tool-use.ps1|sh          ← Claude PostToolUse: 도구 단위 관찰
├── codex-mnemo/save-turn.ps1|sh  ← Codex notify: 턴 단위 관찰
├── antigravity-mnemo/save-turn.js ← Antigravity Stop: 턴 단위 관찰
└── grok-mnemo/save-turn.ps1|sh   ← Grok Stop: 턴 단위 관찰

동작 흐름

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

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

observations.jsonl 에 관찰 축적
    ↓ 새 관찰 delta 또는 핸드오프 경과 기준 도달 시 텍스트 알림만 생성
    ↓ 사용자 /memory-distill 또는 핸드오프 정제
skills/memory-distill/SKILL.md (현재 CLI가 직접 실행)
    ↓ 클러스터링·중복/모순·범위·승격 후보 판단
memory/gotchas/·memory/learned/ 정제 파일 + index 갱신

정제 실행 경계

정제는 현재 CLI가 memory-distill 계약을 직접 수행하므로 별도 named agent나 고정 모델이 필요하지 않습니다. 대용량 입력의 읽기 전용 클러스터 추출만 네이티브 일반 작업자에게 격리할 수 있고, archive·쓰기·인덱스 갱신은 메인 스킬 실행이 담당합니다.

훅 등록

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

설정 (config.json)

{
  "observer": {
    "enabled": true,
    "notify_threshold_new_observations": 200,
    "notify_threshold_handoff_days": 14
  }
}

키	기본값	설명
`observer.enabled`	`true`	관찰 활성화 여부
`observer.notify_threshold_new_observations`	`200`	마지막 정제 offset 이후 새 raw 합계가 이 이상이면 안내 출력
`observer.notify_threshold_handoff_days`	`14`	마지막 핸드오프가 이 일수보다 오래되면 안내 출력

정제 트리거 (의도된 설계)

자동 분석기는 두지 않습니다 — LLM 호출 비용을 한 번에 하나의 명시적 트리거에만 묶기 위함입니다. 같은 세션 내 학습은 컨텍스트가 처리하므로, 정제는 세션 경계(핸드오프) 또는 사용자 의지(/memory-distill)에서만 일어납니다.

트리거	빈도	깊이	LLM 비용	역할
Stop 훅 (jsonl append)	매 응답	0	0	관찰 수집
Stop 훅 (mnemo-status notify)	임계값 도달 시	0 (텍스트 출력만)	0	사용자 인지
`/memory-distill`	사용자 의지	풀 정제 + rebuild	1회	주 정제
핸드오프 자동 추출	컨텍스트 위기	풀 정제 + 통합	1회	세션 경계 정제

/memory-distill과 핸드오프 자동 추출은 동일한 memory-distill rebuild 계약을 공유합니다. Stop 훅의 안내 출력은 LLM 호출이 아니라 단순 텍스트 — memory/.mnemo-status.md 파일 작성 + stderr 한 줄.

관찰 데이터 관리

에러가 포함된 도구 호출만 기록 (노이즈 최소화)
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줄 요약만 (컨텍스트 폭발 방지)

project-gotchas

SKILL.mdskills/project-gotchas/SKILL.md