LLM은 새 세션마다 당신을 처음 만난다 — 그래서 문서화가 전략이다
배경 설명이 세금처럼 쌓였을 때, 나는 CLAUDE.md를 쓰기 시작했다
LLM에 대해 처음 배울 때 “기억이 없다”는 말을 들었습니다. 그때는 그냥 “아, 그렇구나” 하고 흘렸어요. 그런데 실제로 코딩 프로젝트에서 Claude Code를 쓰기 시작하고 나서야 그 말이 무엇을 의미하는지 몸으로 느끼게 됐습니다.
주식 앱을 만들던 어느 날이었습니다. 새 세션을 열고 첫 메시지를 보냈더니 “이 프로젝트가 무엇인지 설명해줄래요?”라는 답이 돌아왔어요. 어제 두 시간 동안 아키텍처를 같이 정했는데, DB 스키마 선택 이유, 포기한 방향들, 삽질 기록 — 다 사라진 거였죠. 처음에는 그냥 붙여넣기 식으로 대응했습니다. “이 프로젝트는 이러저러하고, 지금까지 이렇게 해왔고, 어제 이런 결정을 했어요.” 그런데 이게 반복되기 시작하면서 슬슬 짜증이 쌓였습니다. 배경 설명이 세금처럼 쌓이기 시작했거든요.
예상: 그냥 불편한 거겠지. 실제: 이게 LLM의 근본 설계였다
저는 처음에 이걸 단순한 불편 정도로 생각했습니다. 그런데 알고 보니 이건 LLM의 근본적인 작동 방식이에요. LLM은 세션이 끝나면 기억을 갖지 않습니다. 다음 세션의 Claude는 이전 Claude가 아니에요. 완전히 다른 맥락에서 시작하는 거죠.
이 사실을 “어쩔 수 없는 제약”으로 받아들이면 거기서 멈추게 됩니다. 그런데 달리 보면 이게 하나의 질문이 됩니다. “그렇다면 LLM이 매번 나를 새로 만나도 괜찮도록 만들 수 있지 않을까?”
그 답이 CLAUDE.md였습니다.
문서가 LLM의 기억이 된다
Claude Code에는 프로젝트 루트에 CLAUDE.md를 두면 세션이 시작할 때 자동으로 읽히는 기능이 있어요. 4레버 방법론에서 이 CLAUDE.md가 에이전트를 제어하는 첫 번째 레버로 다뤄집니다. 처음에는 코딩 컨벤션 같은 규칙만 넣었습니다. 그런데 어느 순간부터 다른 것들도 넣기 시작했어요. “지금 이 프로젝트는 이런 상태다”, “이 결정을 이런 이유로 했다”, “이걸 시도했다가 이래서 포기했다.”
그랬더니 LLM이 갑자기 “아는 사람”이 됐습니다. 새 세션을 열어도 배경 설명 없이 바로 이어갈 수 있었어요. 그 체감이 꽤 강렬했습니다.
그런데 삽질도 있었습니다. 넣을수록 좋겠다는 생각에 점점 길어졌는데, 어느 순간부터 LLM이 앞부분만 잘 따르고 뒷부분은 흘리는 게 느껴졌어요. 과적재가 된 거죠. 결국 다시 줄였습니다. 이때 깨달은 게 있어요. 문서는 분량이 아니라 밀도다. LLM이 지금 읽을 수 있는 것만 가치가 있다.
살아남은 최소 패턴
다양하게 시도해보고 살아남은 구조는 단순했습니다. index.md(지금 어떤 상태인가), log.md(뭘 했나), todo.md(뭘 할 건가) — 딱 세 파일. 이 최소 패턴을 Claude Code 스킬로 만들어 자동화한 방법은 /docs-init 스킬에서 다뤘습니다.
그 중에서도 index.md가 핵심이에요. 새 세션의 LLM에게 주는 인수인계서거든요. “이 프로젝트는 현재 이 단계이고, 최근에 이런 결정이 있었고, 지금 이 부분을 작업 중이다.” 1분 안에 파악할 수 있게.
그리고 흥미로운 건, 이게 LLM한테만 쓸모 있는 게 아니라는 거예요. 6개월 만에 프로젝트를 다시 열었을 때 “내가 뭘 하던 거지”를 파악하는 데도 똑같이 작동했습니다. 결국 다음 세션의 LLM에게 컨텍스트를 건네는 것이 문서화의 재정의였어요. 나중을 위해 쓰는 게 아니라, 지금 일이 이어지게 하는 인프라로.
코딩 밖에서도 같은 문제를 만났다
마이위키를 기획하면서 나눈 대화에서 이런 말이 나왔습니다. “새 채팅마다 배경을 다시 깔아야 하는 게 진짜 고통이다.” 이게 코딩 프로젝트 요구사항 목록 4번이었어요. 해결해야 할 문제로 명시된 거죠.
그 순간 코딩 프로젝트에서 해결했던 문제가 사실 더 넓은 문제였다는 게 보였습니다. 관심사, 아이디어, 기획 대화들 — 이것도 마찬가지로 파편화되고, 새 세션마다 배경 설명을 또 해야 했던 거예요. GPT 프로젝트를 써봤는데 프로젝트 분리에 세션 분리까지 해도 다른 프로젝트 내용을 가져와서 생각하는 일이 있었습니다. “컨텍스트 오염”이라는 말을 그때 처음 쓰게 됐어요.
나만의-세컨드브레인-설계-결정을 거쳐 에이전트-컨텍스트-끊김-second-브레인-통합으로 이어진 여정은 사실 코딩에서 먼저 부딪혔던 이 문제를 지식 전반으로 확장하는 과정이었습니다.
LLM 시대의 문서화는 독자가 다르다
기존의 문서화 개념은 “나중에 참고”하거나 “팀원에게 전달”하기 위한 거였죠. 그래서 귀찮은 부가 작업처럼 느껴졌습니다.
LLM 시대의 문서화는 독자가 다릅니다. 지금 AI가 맥락 없이 실수하지 않도록 컨텍스트를 공급하는 것. 이 인식이 바뀌면 동기가 달라져요. “나중에 언젠가”가 아니라 “안 쓰면 지금 AI가 헛돈다”는 걸 알면 쓰게 됩니다.
Atlas 구상에서 나온 표현이 이걸 잘 설명해줬어요. “통증은 이음매에서 컨텍스트가 증발하는 것.” 세션과 세션 사이, 도구와 도구 사이에서 컨텍스트가 사라지는 게 진짜 문제였고, 문서화는 그 이음매를 메우는 거예요.
가장 단순한 시작점은 index.md 하나입니다. “지금 이 프로젝트는 어떤 상태인가”를 딱 한 단락, 3~5줄. 다음에 이 프로젝트를 열 때 LLM에게 주는 첫 브리핑이 됩니다.
배경: 세컨드브레인 설계 결정들 · 방법: /docs-init 스킬 · CLAUDE.md 4레버 · 심화: 에이전트 컨텍스트 끊김 문제 · 컨텍스트 척추 아이디어 · 함께 보기: 마이위키 탄생 스토리 · 세컨드브레인 콘텐츠엔진 활용기