세 개의 Markdown 파일로 Claude Code에 세션 간 메모리 부여하기

Claude Code는 세션 _내부_에서는 매우 뛰어나지만, 세션 _사이_에는 완전히 건망증에 걸린 상태가 됩니다. 터미널을 닫고 다음 날 돌아오면, Claude Code는 당신의 아키텍처(Architecture), 선호도, 이미 해결한 버그, 그리고 지난주에 내린 결정을 모두 잊어버립니다. 그래서 매 세션의 첫 10분은 프로젝트를 다시 설명하는 데 소비하게 되며, 심지어 어제 제외했던 방안을 여전히 밝게 웃으며 제안하기도 합니다.

이러한 콜드 스타트 비용(Cold-start tax)은 계속 쌓입니다. 이를 해결하기 위해 제가 사용하는 작은 시스템을 소개합니다. 플러그인도, 확장 프로그램도, 구독도 필요 없습니다. 그저 세 개의 평범한 Markdown 파일과 두 가지 습관만 있으면 됩니다.

핵심 통찰 (The key insight)

Claude Code는 매 세션이 시작될 때 CLAUDE.md라는 파일을 자동으로 읽습니다. 이것이 핵심 연결 고리입니다. 이 파일을 정적인 설정 파일(Static config file)로 취급하는 대신, 하나의 **관문(Doorway)**으로 취급하세요. Claude가 무엇인가를 수행하기 전에 스스로의 컨텍스트(Context)를 재구축하도록 지시하는 짧은 프로토콜(Protocol)을 담는 것입니다.

변경 빈도에 따라 컨텍스트를 세 개의 파일로 나눕니다:

• CLAUDE.md — 상시 규칙 + 세션 프로토콜. 매 세션 읽히므로 짧게 유지합니다.
• docs/JOURNAL.md — 발생한 일들에 대한 연대기적 로그(Log). 매 세션 변경됩니다.
• docs/KNOWLEDGE.md — 지속적인 사실, 결정 사항, 주의 사항(Gotchas). 거의 변경되지 않습니다.

프로토콜 (The protocol)

핵심은 CLAUDE.md에 들어 있습니다:

## 세션 시작 프로토콜 (필수 — 다른 무엇보다 먼저 수행할 것)
1. docs/JOURNAL.md를 읽으세요 — 가장 최근 항목이 현재 우리가 있는 위치입니다.
2. docs/KNOWLEDGE.md를 읽으세요 — 기본 원칙, 결정 사항, 주의 사항.
...

이 설정이 완료되면 세션은 다음과 같이 진행됩니다:

당신이 Claude Code를 엽니다. Claude Code는 프로토콜을 읽은 다음, 저널(Journal)과 지식 베이스(Knowledge base)를 읽고, _"현재 단계는 X이고, 마지막 작업은 Y였으며, 다음 단계는 Z입니다"_라고 인사하며 당신을 맞이합니다. 다시 설명할 필요가 없습니다.

당신이 작업합니다. Claude Code는 이미 당신의 스택(Stack), 스타일, 그리고 확정된 결정 사항들을 알고 있습니다. 따라서 지난주에 거절했던 데이터베이스를 다시 제안하는 일은 없을 것입니다.

마무리합니다. 앱은 당신이 무엇을 했는지, 무엇이 발목을 잡았는지, 그리고 정확히 다음에 해야 할 행동이 무엇인지를 담은 저널 엔트리 (journal entry)를 추가한 뒤 커밋 (commit)합니다. 내일의 세션은 아무런 사전 정보가 없는 상태(cold start)로 시작되지만, 1분 이내에 생산적인 작업을 시작할 수 있습니다.

왜 저널 (journal)과 지식 베이스 (knowledge base)가 모두 필요한가요?

두 가지가 서로 다른 질문에 답하기 때문입니다. 저널은 "무슨 일이 일어났는가" (연대기적, 추가 전용)에 답합니다. 지식 베이스는 "무엇이 사실인가" (참조용, 제자리 편집)에 답합니다. 저널에서 가장 가치 있는 줄은 최신 엔트리 하단에 있는 **다음 단계 블록 (next-steps block)**입니다. 이는 미래의 자신에게 전달하는 인수인계 노트이며, 콜드 스타트 (cold start)를 즉각적으로 만들어주는 핵심입니다. 지식 베이스에서 가장 가치 있는 섹션은 **결정 로그 (decision log)**로, 이는 이미 해결된 질문이 3주 후에 다시 논쟁되는 것을 방지합니다.

설정 (약 5분 소요)

1. claude를 실행하는 위치 옆, 프로젝트 루트 (project root)에 CLAUDE.md를 넣습니다.
2. docs/JOURNAL.md와 docs/KNOWLEDGE.md를 생성합니다 (처음에는 비어 있어도 괜찮습니다).
3. CLAUDE.md의 프로젝트별 빈칸(소유자, 목표, 스택, 리포 맵 (repo map))을 채웁니다.
4. 다음 세션을 시작합니다. 그러면 프로토콜 (protocol)을 읽고 무엇을 작업할지 물어볼 것입니다.

당신에게 필요한 유일한 습관은 각 세션의 끝에 "마무리하기 — 저널 엔트리를 추가하고 커밋하기"를 실천하는 것입니다. 이 단 하나의 습관이 모든 미래의 세션을 빠르게 시작할 수 있게 만듭니다.

이 방식을 오래 유지할수록 가치는 더욱 높아집니다. 저널은 깊어지고, 힘들게 얻은 시행착오(pitfalls)는 반복되지 않으며, 지식 베이스는 프로젝트의 조직적 기억 (institutional memory)이 됩니다.

파일 가져오기

핵심 프로토콜과 바로 사용할 수 있는 CLAUDE.md를 MIT 라이선스의 무료 리포지토리 (repo)로 공개했습니다:

👉 github.com/igal-in/claude-code-memory

해당 무료 파일은 엔진 역할을 하며 단독으로 작동합니다. 만약 저널(journal)과 지식 베이스(knowledge-base) 템플릿을 처음부터 직접 만들고 싶지 않다면, 검증된 형식이 적용된 두 가지 템플릿, 데이터가 모두 채워진 예시 프로젝트, 그리고 이를 적용하는 방법에 대한 짧은 가이드를 모두 포함한 완성된 시스템을 Claude Code Memory Kit(Gumroad에서 $12에 구매 가능)으로 패키징해 두었습니다.

여러분은 AI 코딩 도구의 콜드 스타트(cold-start) 문제를 어떻게 해결해 오셨나요? 다른 분들은 어떤 방식이 효과적인지 궁금합니다.