# /diary & /reflect 사용 가이드

## /diary 사용법

### 실행 방법

Claude Code에서 `/diary` 입력

### 언제 사용하는가

- 세션 종료 전 (작업 내용 기록)
- 중요한 피드백을 받은 후 (즉시 기록)
- 복잡한 설계 결정을 한 후

### 결과

`/home/jay/.claude/memory/diary/YYYY-MM-DD-session-NN.md` 파일 생성

### 예시 diary 엔트리

```markdown
---
date: "2026-04-05"
session: 1
team_id: "dev3-team"
task_id: "task-1477.1"
tags: [backend, hooks, shell, phase1]
auto_generated: false
---

## 수행한 작업

- claude-diary 패턴 Phase 1 구현
- /diary, /reflect 커맨드 생성
- PreCompact 훅 등록
- 문서 2개 작성

## 피드백 및 수정 지시

- 디자인 작업은 개발팀이 직접 하지 않도록 지시

## 설계 결정 및 이유

- PreCompact 훅에서 최소 메타데이터만 저장 (full diary는 CLI 호출 제약으로 불가)
- frontmatter에 team_id/task_id 포함 (Phase 2 SQLite 인덱싱 대비)

## 실수 및 원인

- 없음

## 반복 패턴

- 없음
```

### 자동 생성 diary (PreCompact 훅)

- Compact 도구 실행 시 자동 생성
- `auto_generated: true` 태그로 수동 diary와 구분
- 수동 diary보다 내용이 최소화됨 (CLI 호출 제약)
- 세션 연속성 확보가 주목적

---

## /reflect 사용법

### 실행 방법

Claude Code에서 `/reflect` 입력

### 언제 사용하는가

- diary 엔트리가 5개 이상 누적되었을 때
- 주 1회 정기 회고
- 반복 실수가 느껴질 때

### 결과

- 6개 카테고리별 패턴 분석 결과 출력
- 강력 패턴(3회+)은 CLAUDE.md 추가 제안
- 사용자 승인 후에만 CLAUDE.md 수정

### 예시 reflect 결과

```
## Reflect 분석 결과 (2026-04-05)

분석 대상: 8개 diary 엔트리 (미처리 6개)

### 1. 반복 실수 패턴
- [3회] 디자인 작업 경계 위반 → 강력 패턴, 규칙화 권고
- [2회] task_id 미기재 → 패턴 후보, 모니터링

### 2. 설계 결정 경향
- [4회] Shell 스크립트 선호 (외부 의존성 회피) → 팀 원칙으로 확립됨

### 3. 피드백 수신 패턴
- [3회] 범위 초과 작업 후 수정 지시 → 강력 패턴, 규칙화 권고

### 4. 작업 완료 패턴
- [5회] 문서 먼저, 구현 나중 순서 유지 → 일관성 확인

### 5. 협업 패턴
- [2회] 아누(실장)와 설계 결정 전 확인 누락 → 패턴 후보

### 6. 기술 선택 패턴
- [3회] frontmatter 구조 사전 정의 후 구현 → 강력 패턴, 유지 권고

---
강력 패턴 2개를 CLAUDE.md에 추가하시겠습니까? (y/n)
→ 추가 대상:
  1. "디자인 작업은 개발팀이 직접 수행하지 않는다"
  2. "작업 범위 불명확 시 실행 전 아누(실장) 확인"
```

### 패턴 인식 기준

| 반복 횟수 | 분류 | 처리 방식 |
|-----------|------|-----------|
| 2회 | 패턴 후보 | 보고만 함 (규칙화 미제안) |
| 3회+ | 강력 패턴 | CLAUDE.md 규칙화 권고 |

### processed.log

- 이미 분석한 diary 엔트리는 재분석하지 않음 (중복 방지)
- 경로: `/home/jay/.claude/memory/diary/processed.log`
- 형식: 분석 완료된 diary 파일명을 한 줄씩 기록

---

## FAQ

**Q: diary를 수동으로 편집해도 되나요?**
A: 네. frontmatter 구조(date, session, team_id, task_id, tags, auto_generated)만 유지하면 본문은 자유롭게 편집 가능합니다.

**Q: reflect가 CLAUDE.md를 자동으로 수정하나요?**
A: 아닙니다. 반드시 사용자 승인 후에만 반영합니다. 분석 결과와 제안만 출력하며, 실제 수정은 명시적 확인을 거칩니다.

**Q: Phase 2에서 무엇이 바뀌나요?**
A: diary 파일이 SQLite FTS5로 인덱싱되어 시맨틱 검색이 가능해집니다. 현재 frontmatter + 본문 구조가 그대로 유지되므로 기존 diary 파일의 재작성은 불필요합니다.

**Q: PreCompact 자동 diary와 수동 diary의 차이는 무엇인가요?**
A: `auto_generated: true` 여부로 구분됩니다. 자동 diary는 최소 메타데이터만 포함하며, 수동 diary는 5개 섹션을 모두 채웁니다. reflect 분석 시 두 유형 모두 포함됩니다.

**Q: 멀티봇 환경에서 팀별로 따로 관리되나요?**
A: diary 저장은 team_id로 구분되지만 저장 위치는 동일합니다(`/home/jay/.claude/memory/diary/`). reflect 실행 시 team_id 필터링으로 팀별 패턴 분리 분석이 가능합니다.

---

## 검색 CLI Layer 사용법 (Phase 3)

Phase 3에서 도입된 Progressive Disclosure 패턴으로 토큰을 절감하며 메모리를 검색할 수 있습니다.

### Layer 1: Index (빠른 탐색, ~50-100 토큰)

```bash
python3 memory_search.py query "디자인 위임" --layer index
```

출력 예시:
```
[1] 위임 규칙 종합 (feedback) score=-1.23
[2] 2026-04-05 session 1 (diary) score=-0.56
```

### Layer 2: Summary (관련성 확인, ~200-300 토큰)

```bash
python3 memory_search.py query "디자인 위임" --layer summary
```

출력 예시:
```
[1] 위임 규칙 종합 (feedback) score=-1.23
    미리보기: 파일 기반 위임 규칙, 논리적 팀 라우팅 규칙 준수...
```

### Layer 3: Full (선택 항목 전체 조회)

```bash
# Layer 1/2에서 확인한 ID로 전체 내용 조회
python3 memory_search.py get 1 3
```

### 권장 워크플로우

1. `--layer index`로 관련 메모리 빠르게 스캔
2. `--layer summary`로 실제 필요한 항목 선별
3. `get <id1> <id2>`로 선택 항목만 전체 로드

기존 명령어(layer 미지정)는 그대로 동작합니다 (하위 호환).