# 문서화 패턴

> Buffer Pattern은 AI 지원 세션에서 중요한 발견을 보존해요. 세션이 끝나거나 연결이 끊겨도 소중한 인사이트를 잃지 않도록 해주죠.

- Published: 2025-01-15
- Updated: 2026-08-02
- Category: general
- Tags: general, documentation, 3b, patterns
- Page: https://brandonwie.dev/ko/posts/documentation-patterns

이 패턴은 근본적인 문제를 해결해요: 세션이 끝나거나 연결이 끊기면 소중한 인사이트가 사라진다는 것이죠.

단일 buffer 파일(`.claude/buffer.md`)에 중요한 순간을 즉시 기록해요. 세션 끝에 `/wrap`을 실행하면 항목들이 journal과 knowledge 파일로 처리돼요.

---

## 왜 존재할까?

### 문제

```text
시나리오: Claude와 작업 세션

- 중요한 결정을 내림 (Y 대신 X를 선택)
- 까다로운 문제를 해결 (근본 원인이 Z였음)
- 유용한 패턴을 발견 (이 접근법이 잘 동작함)

그리고:
- 세션 종료 / 연결 끊김 / 새 세션 시작

결과: 모든 컨텍스트 유실
```

제 환경만의 문제가 아니라 도구가 원래 그렇게 동작해요. [Claude Code memory 문서](https://code.claude.com/docs/en/memory)에도 세션은 매번 새로운 context window로 시작하고, 세션을 넘어 지식을 옮겨주는 건 디스크에 있는 파일이라고 적혀 있어요. 대화 안에만 있던 건 대화가 끝나면 같이 사라지죠.

그리고 잃어버리는 건 "무슨 일이 있었는지"가 아니라 "왜 그렇게 했는지"예요. Michael Nygard도 2011년 ADR 글에서 [프로젝트를 진행하는 동안 추적하기 가장 어려운 것 중 하나가 결정의 동기](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)라고 썼고, 해법도 같았어요 — 결정을 내리는 그 순간에 근거를 적어두는 것. Buffer는 같은 아이디어를 훨씬 짧은 시간 단위에 적용한 거예요. ADR이 몇 년 단위라면 buffer는 몇 시간 단위죠.

### 해결책

```text
세션 중 (중요한 일이 생길 때마다):
┌────────────────────────────────────────────────────────────────┐
│ 중요한 순간 발생 (결정, 해결, 발견)                              │
│         │                                                      │
│         ▼                                                      │
│ 즉시 .claude/buffer.md에 기록                                   │
│ (5W1H 컨텍스트와 함께 간단한 항목)                               │
│         │                                                      │
│         ▼                                                      │
│ Buffer는 세션이 끝나도 유지됨                                    │
└────────────────────────────────────────────────────────────────┘

/wrap 실행 시:
┌────────────────────────────────────────────────────────────────┐
│ buffer 항목 읽기                                                │
│         │                                                      │
│         ▼                                                      │
│ journal/knowledge로 처리                                        │
│         │                                                      │
│         ▼                                                      │
│ 다음 세션을 위해 buffer 비우기                                   │
└────────────────────────────────────────────────────────────────┘

결과: 중요한 순간 보존됨
```

---

## 어떻게 동작할까?

### 언제 기록할까

| 트리거                  | 즉시 기록하는 경우             |
| ----------------------- | ------------------------------ |
| 결정을 내렸을 때        | 명확한 근거로 Y 대신 X를 선택  |
| 문제를 해결했을 때      | 근본 원인이 명확하지 않았음    |
| 패턴을 발견했을 때      | 어떤 기법/접근법이 잘 동작함   |
| 유용한 참고를 찾았을 때 | 공식 문서나 검증된 소스를 발견 |

### 항목 형식

```markdown
## YYYY-MM-DD HH:MM - {프로젝트}

**What:** {한 줄 요약}
**Why it matters:** {왜 기억할 가치가 있는지}
**Details:**
{코드, 설명, 참고 - 5W1H 컨텍스트 포함}
```

### Buffer 위치

단일 파일: `~/dev/personal/3b/.claude/buffer.md`

---

## 핵심 포인트

1. **즉시 기록** - 세션 끝까지 기다리지 말 것
2. **간결하게** - 중요한 순간 하나당 항목 하나
3. **5W1H 포함** - 나중에 떠올리려면 컨텍스트가 핵심
4. **단일 파일** - 프로젝트별 복잡성 없음

---

## 변천사

| 날짜       | 변경                                  |
| ---------- | ------------------------------------- |
| 2025-01-15 | `learning-queue.md`로 초기 설계       |
| 2026-01-23 | 프로젝트별 `session-buffer.md`로 발전 |
| 2026-01-26 | 단일 `buffer.md`로 단순화(현재)       |

이 패턴은 세 번의 반복을 거쳤어요:

1. **learning-queue.md** - 복잡한 항목 형식, 실제로 사용되지 않음
2. **session-buffer.md** - 프로젝트별 파일, 5가지 항목 유형, 실제로 사용되지 않음
3. **buffer.md** - 단일 파일, 간단한 형식(현재)

---

## 참고

- [How Claude remembers your project](https://code.claude.com/docs/en/memory) - Claude Code memory 문서: 세션은 fresh context window로 시작하고, 디스크의 파일만 세션을 넘어감
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - Michael Nygard, 결정의 근거가 사라지기 전에 기록하기
- 제 개인 tooling 저장소에서는 `.claude/buffer.md`가 buffer 파일이고, `wrap` skill이 세션 끝에 이를 처리해요
