이 글 목차
문서화 패턴
Buffer Pattern은 AI 지원 세션에서 중요한 발견을 보존해요. 세션이 끝나거나 연결이 끊겨도 소중한 인사이트를 잃지 않도록 해주죠.
이 패턴은 근본적인 문제를 해결해요: 세션이 끝나거나 연결이 끊기면 소중한 인사이트가 사라진다는 것이죠.
단일 buffer 파일(.claude/buffer.md)에 중요한 순간을 즉시 기록해요. 세션 끝에 /wrap을 실행하면 항목들이 journal과 knowledge 파일로 처리돼요.
왜 존재할까?
문제
시나리오: Claude와 작업 세션
- 중요한 결정을 내림 (Y 대신 X를 선택)
- 까다로운 문제를 해결 (근본 원인이 Z였음)
- 유용한 패턴을 발견 (이 접근법이 잘 동작함)
그리고:
- 세션 종료 / 연결 끊김 / 새 세션 시작
결과: 모든 컨텍스트 유실제 환경만의 문제가 아니라 도구가 원래 그렇게 동작해요. Claude Code memory 문서에도 세션은 매번 새로운 context window로 시작하고, 세션을 넘어 지식을 옮겨주는 건 디스크에 있는 파일이라고 적혀 있어요. 대화 안에만 있던 건 대화가 끝나면 같이 사라지죠.
그리고 잃어버리는 건 “무슨 일이 있었는지”가 아니라 “왜 그렇게 했는지”예요. Michael Nygard도 2011년 ADR 글에서 프로젝트를 진행하는 동안 추적하기 가장 어려운 것 중 하나가 결정의 동기라고 썼고, 해법도 같았어요 — 결정을 내리는 그 순간에 근거를 적어두는 것. Buffer는 같은 아이디어를 훨씬 짧은 시간 단위에 적용한 거예요. ADR이 몇 년 단위라면 buffer는 몇 시간 단위죠.
해결책
세션 중 (중요한 일이 생길 때마다):
┌────────────────────────────────────────────────────────────────┐
│ 중요한 순간 발생 (결정, 해결, 발견) │
│ │ │
│ ▼ │
│ 즉시 .claude/buffer.md에 기록 │
│ (5W1H 컨텍스트와 함께 간단한 항목) │
│ │ │
│ ▼ │
│ Buffer는 세션이 끝나도 유지됨 │
└────────────────────────────────────────────────────────────────┘
/wrap 실행 시:
┌────────────────────────────────────────────────────────────────┐
│ buffer 항목 읽기 │
│ │ │
│ ▼ │
│ journal/knowledge로 처리 │
│ │ │
│ ▼ │
│ 다음 세션을 위해 buffer 비우기 │
└────────────────────────────────────────────────────────────────┘
결과: 중요한 순간 보존됨어떻게 동작할까?
언제 기록할까
| 트리거 | 즉시 기록하는 경우 |
|---|---|
| 결정을 내렸을 때 | 명확한 근거로 Y 대신 X를 선택 |
| 문제를 해결했을 때 | 근본 원인이 명확하지 않았음 |
| 패턴을 발견했을 때 | 어떤 기법/접근법이 잘 동작함 |
| 유용한 참고를 찾았을 때 | 공식 문서나 검증된 소스를 발견 |
항목 형식
## YYYY-MM-DD HH:MM - {프로젝트}
**What:** {한 줄 요약}
**Why it matters:** {왜 기억할 가치가 있는지}
**Details:**
{코드, 설명, 참고 - 5W1H 컨텍스트 포함}Buffer 위치
단일 파일: ~/dev/personal/3b/.claude/buffer.md
핵심 포인트
- 즉시 기록 - 세션 끝까지 기다리지 말 것
- 간결하게 - 중요한 순간 하나당 항목 하나
- 5W1H 포함 - 나중에 떠올리려면 컨텍스트가 핵심
- 단일 파일 - 프로젝트별 복잡성 없음
변천사
| 날짜 | 변경 |
|---|---|
| 2025-01-15 | learning-queue.md로 초기 설계 |
| 2026-01-23 | 프로젝트별 session-buffer.md로 발전 |
| 2026-01-26 | 단일 buffer.md로 단순화(현재) |
이 패턴은 세 번의 반복을 거쳤어요:
- learning-queue.md - 복잡한 항목 형식, 실제로 사용되지 않음
- session-buffer.md - 프로젝트별 파일, 5가지 항목 유형, 실제로 사용되지 않음
- buffer.md - 단일 파일, 간단한 형식(현재)
참고
- How Claude remembers your project - Claude Code memory 문서: 세션은 fresh context window로 시작하고, 디스크의 파일만 세션을 넘어감
- Documenting Architecture Decisions - Michael Nygard, 결정의 근거가 사라지기 전에 기록하기
- 제 개인 tooling 저장소에서는
.claude/buffer.md가 buffer 파일이고,wrapskill이 세션 끝에 이를 처리해요