Dannykkh 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 ← 관찰 설정
└── agents/
└── gotcha-analyzer.md ← source-only 호환 프롬프트 (기본 등록 안 함)
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줄 요약만 (컨텍스트 폭발 방지)