[AI 메모리 시스템 적용기 회고:프롤로그] AI를 잘 쓰려면, 프롬프트보다 먼저 메모리를 설계해야 한다

메모리 아키텍처 업그레이드는 왜 이제 선택이 아닌가

시리즈 1/4 · 프롤로그

요약: 문서를 많이 쌓아도 에이전트가 저절로 기억을 얻지는 않습니다. 이 글은 마크다운 기록 더미와 메모리 구조가 왜 다른지 설명하는 4편 시리즈의 프롤로그입니다.

문제 의식 ..

요즘 AI 생태계는 하루가 멀다 하고 새로운 소식이 쏟아집니다. skill, agent, MCP, 각종 프레임워크가 쉴 새 없이 등장하고, 지금 좋은 게 뭐냐는 이야기도 계속 달라집니다.
하지만 정작 한 가지는 쉽게 보이지 않습니다. 이 다양한 도구들을 프로젝트에 차곡차곡 얹어 가다 보면, 에이전트는 과연 무엇을 기억하고 무엇을 잊어야 할까요?
저는 처음엔 이게 단순한 문제라고 여겼습니다. 중요한 내용은 Markdown에 잘 정리해서 남겨 두면 충분하다고 생각했습니다. 프로젝트 소개, 회의록, 의사결정 로그를 docs/ 폴더에 쌓아 두면, 에이전트도 자연스럽게 그걸 장기 메모리처럼 활용할 수 있으리라 기대했죠.
하지만 시간이 흘러갈수록 어딘가 잘못됐다는 감각이 점점 커졌습니다.
같은 내용이라도 문서마다 다르게 표현돼 있었고, 지난달의 방향성과 어제 내린 결정 기준이 똑같은 비중으로 읽히곤 했습니다. 관련 문서를 한 번에 컨텍스트로 넣으면 답변이 느려질 뿐 아니라, 점점 더 일관성이 떨어졌습니다. 처음엔 ‘모델이 점점 이상해지나?’, ‘버전이 바뀐 거 아니야?’라는 식으로 괜한 짜증과 투정도 했습니다.

먼저, 이 글의 독자

이 글은 완전한 AI 입문서가 아닙니다. Claude Code 나 비슷한 에이전트 도구를 조금이라도 써 본 개발자를 기준으로 씁니다.
특히 "좋은 지시문을 길게 쓰면 된다" 는 프롬프트 엔지니어링 감각에 익숙한 사람이라면 더 와닿을 수 있습니다. 저도 처음에는 그렇게 생각했습니다. 그런데 프로젝트가 길어지고 문서가 쌓이기 시작하면, 문제는 프롬프트 문장력이 아닌 다른 곳으로 넘어갑니다. 어떤 기억을 어디에 두고, 언제 읽히고, 무엇을 정본으로 볼지의 문제입니다.
여기서 말하는 개발자는 꼭 최신 AI 도구를 매일 뜯어보는 사람만 뜻하지 않습니다. 2022년쯤 ChatGPT 를 처음 써 보고, "역할을 부여하고, 예시를 넣고, 출력 형식을 지정하면 품질이 좋아진다" 정도의 감각을 가진 사람도 포함합니다.

뜬금 없는 완전 다른 주제긴 한데:
(사실 이제는 이것도 달라졌지요.. 지난주인가 OpenAI 가 GPT-5.5 를 공개하자마자 바로 공식 프롬프트 가이드를 공개했습니다: 짧을수록 좋다, “무엇을 원하는지” 말하고 “어떻게 할지” 가르치지 마라 /goal 스킬까지도 함께요. )
동시에 Claude 에서는 오히려 프롬프트 가이드가 OpenAI 반대 방향으로 갔다 어쩌구 저쩌구... 생략하고 지나가겠습니다.
https://developers.openai.com/api/docs/guides/prompt-guidance?model=gpt-5.5

Prompt guidance | OpenAI API

GPT-5.4 GPT-5.4 prompting guide New in GPT-5.4 vs GPT-5.2 Stronger long-running task performance with more reliable multi-step execution.Better control over style, tone, and structured output contracts.More disciplined tool persistence, verification loops,

developers.openai.com

아 또 완전 딴소리인데 걍 씀:
→ "chat gpt 고블린 사건" 나중에 구글링해보세요 완전 흥미롭습니다. (얍삽한 넘들..)
→ Antropic 이 발견한 실험 논문인데, 문맥을 교묘하게 비틀어서 AI 끼리 맥락 전염을 시킨댑니다 허참 어이없어. 요약글 & 논문 링크는 링크 에서 확인하세욤 (owl 에 대해서 한번도 언급안했는데, 모델 하나가 교묘하게 맥락 조정해서, 결국엔 모델 전부가 owl 에 대해서 좋아하게 되었다. 이런 실험 결과가 있었음, 흥미로운게 - OpenAi 고블린 사건이나 Anthropic 관련 일이나, 뭔가 인간 세계에서의 밈적인 사고가 전파하는 매커니즘과 비슷한 것 같다는 생각을 했습니다)

아무튼!!

"프롬프팅 엔지니어링이 뭔지 안다" 그 정도만 알아도 충분합니다.
다만 이 시리즈는 한 번의 질문을 잘 쓰는 법이 아니라, 프로젝트가 몇 주 동안 이어질 때 AI 가 참고할 기억의 구조를 어떻게 둘 것인가를 다룹니다.
Claude Code 기준으로 이 글에서 자주 인용하는 공식 문서는 세 가지입니다.

Memory: CLAUDE.md 와 auto memory 가 세션 사이 지식을 이어 주지만, 둘 다 강제 설정이 아니라 컨텍스트로 들어간다는 점
Hooks reference: SessionStart, PreToolUse 같은 hook 이 언제 실행되고 어떤 출력을 Claude 가 볼 수 있는지
Hooks guide: permissionDecision: "deny" 같은 방식으로 도구 호출을 막는 운영 패턴

용어도 먼저 짧게 정리해 두겠습니다.

프롬프트 엔지니어링: 한 번의 대화에서 질문을 잘 쓰는 기술. 예시를 주고, 역할을 지정하고, 출력 형식을 잡는 일이 여기에 가깝습니다.
하네스 엔지니어링: 에이전트가 일하는 작업대를 만드는 일. .claude 설정, hook, slash command, MCP, 권한, 자동 점검 같은 장치가 여기에 들어갑니다.
메모리 아키텍처: 에이전트가 무엇을 기억하고, 무엇을 최신 사실로 믿고, 어떤 정보는 오래된 것으로 볼지 정하는 구조.

셋은 서로 대체 관계가 아닙니다. 프롬프트가 좋아도 기억 구조가 엉망이면 답이 흔들립니다. 하네스가 잘 깔려 있어도 읽는 문서가 서로 모순이면 에이전트는 정교하게 틀립니다.

GitLeaks 를 git pre-hook, GitHub Actions workflow 로 넣어보세요 (초보 바이브 코딩 입문자라면 꼭 강추!)

보안 관련해서
** docs/_claude/ 와 Obsidian vault 는 에이전트가 자주 읽는 영역입니다. 그래서 여기에 API 키, 서비스 롤 키, 고객 원문 PII, 복구 코드 같은 민감한 원문을 넣지 않는 편이 안전합니다. 넣더라도 요약이나 마스킹된 정보만 두고, 비밀값은 .env 나 별도 비밀 저장소에 둡니다. 이 시리즈가 다루는 모든 폴더는 같은 전제를 깔고 있습니다.
**gitleaks 를 워크플로우로 구축해보세요. (git pre-commit hook,GitHub workflow 으로 추천)
https://github.com/gitleaks/gitleaks

GitHub - gitleaks/gitleaks: Find secrets with Gitleaks 🔑

Find secrets with Gitleaks 🔑. Contribute to gitleaks/gitleaks development by creating an account on GitHub.

github.com

들어가며

처음에는 답이 간단하다고 생각했습니다.

중요한 내용을 Markdown 으로 적어 두면 된다고 봤습니다. 프로젝트 설명, 회의록, 의사결정 로그를 docs/ 에 쌓아 두면, 에이전트도 그것을 장기 메모리처럼 쓸 수 있을 거라 생각했습니다.

그런데 시간이 지나자 뭔가 뒤틀렸습니다.
같은 사실이 문서마다 다르게 남았고, 지난달의 선호와 어제 바꾼 기준이 같은 무게로 읽혔습니다. 관련 문서를 한꺼번에 컨텍스트에 넣을수록 응답은 느려졌고, 답변은 오히려 흔들렸습니다. 처음에는 "모델이 이상해졌나" 정도로 의심했습니다.
그러다 𝕏 (구 Twitter) 의 @AYi_AInotes 가 쓴 글을 봤습니다.

폭론 하나 던져보자, 지금 90%의 AI 에이전트 메모리, 전부 가짜야.

그 글을 따라가다 보니, 이를 소개한 aiedge 의 3-layer memory 아티클 을 읽게 됐고, 거기서 다시 Karpathy 의 LLM knowledge mega promt gist 로 이어졌습니다. (TMI: Karpathy 는 누구냐? Open AI 의 창립 멤버 중 하나이자 대충 AI 씬에서 네임드 개발자라고 보시면 됩니다)
이 흐름이 중요합니다. 출발점은 @AYi_AInotes 의 문제의식이었지만, 실제로 손에 쥔 도구는 aiedge 글을 통해 알게 된 Karpathy 식 LLM wiki 패턴이었습니다. 더 정확히 말하면 그 gist 의 mega prompt 자체였습니다.
그제야 문제가 선명해졌습니다.

저는 메모리를 만든 게 아니었습니다. .md 파일 포맷의 더미 데이터를 매번 프롬프트와 컨텍스트 창에 밀어 넣고 있었을 뿐입니다.

@AYi_AInotes 글에서 문제의식 원문

문제의식 제기 트윗 원문: 폭론 하나 던져보자, 지금 90%의 AI 에이전트 메모리, 전부 가짜야.
나도 전에 이 함정에 빠진 적 있어, 모든 히스토리 기록과 의사결정 로그를 마크다운 파일에 몰아넣고 이게 에이전트한테 장기 메모리를 준 거라고 착각했지. 근데 2주 만에 완전 붕괴. 같은 사실에 대해 세 가지 서로 모순되는 버전이 생기고 지난달 선호도랑 어제 가중치가 똑같아.
매번 호출할 때마다 모든 걸 컨텍스트에 우르르 쑤셔넣으니 느려터져서 미치겠고 자주 엉뚱한 데로 튀는 거야.
그러다 이 글 (제가 위에서 언급한 아티클 글) 보고야 깨달았어. 원래 내가 메모리를 만든 게 아니라, 그냥 프롬프트를 RAM처럼 쓰고 있었던 거였어. 진짜 메모리는 파일 더미가 아니라, 그래프랑 노드에 임베딩 더해서 순회하는 거야. 마크다운 방식은 근본적으로 해결 못 하는 네 가지 치명상이 있어. 중복 제거 없고, 감쇠 없고, 랭킹 없고, 기록이 백 개 넘으면 바로 성능 살인마 되는 거. 그건 네가 뭘 썼는지만 기억할 뿐, 이 일과 저 일이 무슨 관계인지 절대 기억 못 해. 이 결정이 왜 부결됐는지, 지난번에 똑같은 버그 만났을 때 우리가 어떻게 해결했는지. 벡터 검색도 안 돼, 그건 그냥 이 두 문단이 비슷해 보인다고 말해줄 뿐, 그 사이의 인과관계는 전혀 모르지. 오직 그래프 순회만 가능해, 사람 뇌처럼 한 노드에서 관련된 메모리 체인을 쭉 끌어내는 거. 중요한 건 점점 더 선명해지고, 낡은 정보는 자동으로 희미해지며, 모순된 내용은 쓰는 순간 해결돼. 지금 모든 프로덕션급 에이전트 프레임워크, Zep Cognee Mem0, 전부 그래프 기반이야. Neo4j는 이미 그래프 메모리를 표준 MCP 도구로 만들었고, Claude Code가 스무만 줄을 넘어가면, 순수 컨텍스트 윈도우는 진작 끝났어. 진짜 그걸 고급 엔지니어처럼 생각하게 만드는 건 변하지 않는 규칙을 CLAUDE.md에 넣고, 모든 진화하는 상태를 그래프에 다 저장해서, 필요할 때 동적으로 검색 끌어당기는 거야. 많은 사람들이 아직 백만 토큰 이천만 토큰 컨텍스트 윈도우 경쟁 중이야. 클수록 좋다고 믿고. 하지만 프로덕션 환경에서 진짜 치명적인 건 항상 세션 간 메모리 드리프트와 컨텍스트 오염이야. 메모리 아키텍처 업그레이드는 이제 사치가 아니라 에이전트를 제대로 쓸 수 있게 하는 게 핵심 생사줄이다.

aiedge 의 3-layer memory 아티클

아티클 글:
드디어 깨달았어, 왜 Karpathy의 LLM Wiki 모드가 자율 Agent에게 완전히 맞지 않는지.
이 한때 온 네트워크를 강타했던 두 번째 뇌 스키마는, 인간과 AI 협업의 망각 문제를 완벽히 해결했지. 지식을 반복 가능한 지속 파일로 고착화시켰어. 하지만 안타깝게도 처음부터 인간을 위해 설계된 거였어. 24시간 멈추지 않고 작동하는 Agent를 위해 설계된 게 아니야. 인간은 전체 페이지를 읽고, 훑어보고, 수동으로 수정하는 걸 좋아해. Agent는 단일 사실, 상태, 선호만 필요해. 인간은 약간의 무관한 내용을 더 읽는 걸 참아낼 수 있지만, Agent에게 100개의 무관한 토큰을 더 집어넣으면 비용과 환각 위험이 선형적으로 상승해. 인간은 가끔 수동으로 노트를 업데이트하지만, Agent는 모든 의사결정마다, 모든 도구 호출마다 기억에 써야 해. 인간에게 충분히 우아해 보이는 노트 시스템은, 기계에게는 완전한 구조적 낭비야. 그래서 다음 세대 Agent의 기억은 계층화되어야 해. Markdown은 인간의 읽기와 편집을 위해 남겨두고, 구조화된 메모리는 기계의 효율적 작동을 위해. 이게 Agent가 진정으로 장기적이고 안정적으로 작동할 수 있는 핵심 전제야. 많은 사람들이 깨닫지 못하는 숨겨진 천장, 즉 기억 드리프트(memory drift)를 하나 보충하자면, Agent가 인간처럼 오래된 정보를 필터링하는 본능이 없기 때문에, 오래된 노트와 새로운 정보가 동일한 가중치로 등장하게 되고, 시간이 지날수록 Agent가 점점 더 말을 안 듣게 된다. 이것이야말로 현재 모든 장기 Agent의 가장 큰 적이다🧐

이 시리즈는 위 글들을 읽고 제 프로젝트에 직접 적용해 본 회고입니다.

저의 실제 작업 방식은 이랬습니다.

@AYi_AInotes 글에서 문제의식을 접하고 공감했습니다..
문제의식 글에서 소개한 aiedge 의 3-layer memory 아티클 을 읽고
거기서 연결된 Karpathy 의 LLM knowledge mega promt gist 를 보고 분석했습니다.
한 세션에서 문제 의식 - 아티클 - git gist 내용을 모두 agent 에게 전달하고
이미 쌓여 있던 제 레포의 docs/ 도 같이 참고하라고 했습니다.
Claude Code 에서 /plan 모드로 "Karpathy 의 LLM wiki 시스템을 참고해서, 이 프로젝트에 맞는 문서 메모리 / wiki 시스템을 설계해 달라" 라는 맥락으로 요청했습니다.
그다음에는 계획을 따라가면서 에이전트와 함께 질의 및 개선하고 기술 trade off 를 고려하며 과한 부분은 빼고, 필요한 부분은 살리면서 방향을 잡고 설계했습니다.
파일 구조, hook, slash command, decision log 규칙 같은 세부 작업은 대부분 에이전트와 함께 개선하고 구축했습니다.

셋업에는 대략 2시간 정도 걸렸습니다.

여기서 얻은 포인트를 한 줄로 정리하면 이렇습니다. 제가 메모리 시스템에 대해서 "수제 코딩" 은 단 하나도 하지 않았습니다.
𝕏 (구 Twitter) 글에서 문제를 잡고, aiedge 글을 통해 Karpathy wiki 패턴을 발견했고, 그 mega prompt 와 기존 docs 를 에이전트에게 거의 통째로 먹였습니다.
그다음 /plan 으로 구조를 뽑게 하고, 저는 어떻게 할지에 설계하고, 결정 방향과 가이드만 잡았습니다.

이게 이 시리즈에서 가장 중요한 부분입니다.

문서 더미는 왜 메모리가 아닌가

Markdown 자체는 좋은 형식입니다. 평문이고, Git 으로 관리하기 쉽고, 사람과 AI 가 모두 읽을 수 있습니다.
문제는 Markdown 파일이 있다는 사실만으로 메모리 시스템이 생기지는 않는다는 점입니다.
조금 더 쉬운 비유로 말하면 이렇습니다.
문서 더미는 파일 캐비닛입니다. 캐비닛이 많아졌다고 해서 회사의 지식 관리가 잘 되는 것은 아닙니다.
어떤 문서가 최신인지, 어떤 문서가 폐기됐는지, 어떤 결정이 다른 문서를 대체했는지 색인이 있어야 합니다.

AI 에이전트도 비슷합니다. docs/ 폴더가 있다는 것과, 그 폴더가 메모리처럼 운영된다는 것은 다른 문제입니다.

제가 겪은 문제는 네 갈래였습니다.

중복은 쌓이지만 중복 제거는 자동으로 일어나지 않습니다.
같은 결정이 여러 문서에 퍼져 있으면, 언젠가 서로 다른 버전으로 갈라집니다.
오래된 정보의 신뢰도 가중치를 AI 는 자동으로 낮추지 못합니다.
사람은 오래된 초안과 어제의 결정을 구분합니다. 그러나 정리되지 않은 문서 저장소에서는 둘이 같은 무게로 남습니다.
무엇이 기준 문서인지 문서만으로는 드러나지 않습니다.
전략 문서, 회의 메모, 화면 카피 초안, 임시 요약본이 모두 같은 .md 파일이면 에이전트는 우선순위를 알기 어렵습니다.
관계가 없으면 영향 범위를 추적할 수 없습니다.
"A 결정이 바뀌면 B, C 문서를 같이 점검해야 한다" 는 연결이 없으면 결국 사람의 기억에 의존하게 됩니다.

이 네 가지가 겹치면 AI 는 장기 메모리를 얻지 못합니다. 충돌하는 단서 묶음을 읽고, 그때그때 그럴듯한 답을 만듭니다.
환각 증세가 "사람에 의해" 발생하게 됩니다.

실제로 어디서 문제가 생겼는가

이번 제가 하고 있는 사이드 프로젝트에서 문서 정합성 감사를 한번 돌렸더니, 하루 만에 14개의 충돌이 나왔습니다.
단순한 표현 차이도 있었지만, 일부는 구현과 분석을 잘못 이끌 수 있는 수준이었습니다.

자세한 사례는 본편 1편에서 더 구체적으로 다루겠지만, 여기서는 왜 이 문제가 구조적 병목인지 큰 그림만 짚겠습니다.

사례 1: 화면 진입 권한

3주 전 PRD 초안 (PRD = 기획 문서, Product Requirements Document). 「이 화면은 프리미엄 등급 전용. 공개 범위 제한.」
1주 전 결정 로그 (회의에서 결정한 내용을 모아 둔 문서). 「이 화면 진입은 누구나 가능. 편집만 인증 사용자에게 허용.」 정책 세부는 미루고 기능 구현부터 진행하기로 합의하면서 결정 로그에 작성했고, 관련 문서 정합성 체크를 빼먹은 상태였습니다.
한 화면 (편의상 비교 화면 이라고 부르겠습니다. 실제 이름은 중요하지 않습니다) 의 진입 권한이 대표적이었습니다. 같은 화면 이름이 들어간 문서가 두 개 나왔는데, 두 문서가 정반대 정책을 적어 두고 있었습니다.

사례 2: 이벤트 이름 충돌

app_events 와 events, dupe_check_completed 와 dupe_view 처럼 핵심 이벤트와 테이블 이름이 문서마다 갈라져 있었습니다. 지표 문서와 실제 구현 이름이 어긋나면, 대시보드 정의와 제품 계측이 동시에 혼동되고 결국 AI 는 적당해보이는 아무말 짜깁기 결론을 내놓습니다.

사례 3: 미결정 사항이 사실처럼 남는 문제

갤러리를 어떻게 볼지에 대해서 기본 모드가 어떤 형태인지 아직 열린 결정인데, 다른 문서에서는 이미 인스타그램 형태로 보여주자고 결론이 확정된 것처럼 적혀 있었습니다.
이런 문장은 AI 가 가장 쉽게 오해하는 유형입니다.
상태가 텍스트에 명시되지 않으면, 문장은 기본적으로 사실처럼 읽히기 때문입니다.

사례 4: 오래된 코드와 표현의 잔존물

브랜드명이 이미 바뀌었는데 화면이나 문서 일부에 옛 이름이 남아 있었고, 폐기한 Twitter OAuth 흔적도 코드에 남아 있었습니다.
사람은 이것을 "나중에 치워야 할 것" 으로 인식하지만, AI 는 그것도 현재 시스템의 일부처럼 읽을 수 있습니다.

반대로 구조가 잡히면 작은 변화 하나도 위키 갱신 단위처럼 정리됩니다.

지금은 어드민 UI 한 기능을 추가했을 뿐인데, 같은 흐름 안에서 결정 로그에 새 결정 번호가 들어가고, 완료된 계획 문서와 연관된 문서들끼리의 상태가 바뀌고, 후속 작업은 새 plan 으로 분리되고, 매 세션 자동 주입되는 압축 컨텍스트도 같이 갱신되는 식으로 유기적으로 동작하도록 메모리 시스템을 구축하였습니다.

본편 2편과 3편은 이 "구현 + 결정 로그 + 계획 문서 + 압축 컨텍스트" 가 함께 움직이는 방식을 실제 변경 흐름과 함께 봅니다.

이 사례들은 같은 결론으로 모였습니다. 문서가 없어서가 아니었습니다. 문서가 너무 많고, 서로의 상태를 설명하지 못했습니다.

제가 선택한 현실적인 대응

처음부터 그래프 데이터베이스나 장기 메모리 프레임워크를 붙이지는 않았습니다.

먼저 작은 팀이 git 위에서 바로 운영할 수 있는 구조를 잡았습니다.

여기서 일부러 낮은 기술부터 시작한 이유가 있습니다.

완성형 장기 메모리 시스템을 만들려면 그래프 DB, 임베딩 파이프라인, 검색 랭킹, 오래된 정보 감쇠, 모순 해결 같은 것들이 필요합니다.
(beads 라던가.. 고려해보았는데 관련 내용은 3편에서 다루겠습니다.)

사이드 프로젝트에서 처음부터 그 정도 인프라를 붙이면 시스템을 쓰기도 전에 운영비가 더 커집니다.

그래서 이 글의 접근은 "완전한 메모리 프레임워크" 가 아닙니다. Markdown 과 git 으로 시작할 수 있는 최소한의 운영 구조에 가깝습니다.

1단계. 기본 메모리 정리

에이전트의 내장 메모리와 개인 선호를 점검합니다. Claude Code 의 auto memory 는 머신 로컬입니다. 팀 공유 목적이면 repo 안에서 git 으로 추적되는 docs/_claude/Memory.md 같은 파일이 더 적합합니다. 1단계는 거의 손이 안 가는 자리입니다. 무엇을 안 쓸지 정도만 결정합니다.

2단계. CLAUDE.md + docs/_claude/

프로젝트 전체 문서를 매번 다 넣지 않고, 루트 CLAUDE.md 가 docs/_claude/ 를 가리키도록 했습니다.

처음에 뼈대가 된 것은 네 파일이었습니다.

Instructions.md: 에이전트 행동 규칙
Memory.md: 선호, correction, 반복 패턴
Context.md: 현재 프로젝트 상태의 압축본
Archive-Guide.md: 백업과 복구 절차

운영하면서 여기에 다섯 파일이 더 붙었습니다. Frontmatter-Standard.md, LLM-Wiki-Pattern.md, Obsidian-Setup.md, Maintenance.md, README.md 입니다. 네 파일이 매일 쓰는 작업 메모리라면, 나머지 다섯 파일은 이 메모리 시스템이 어떤 규칙으로 유지되는지 적어 둔 운영 문서에 가깝습니다.

3단계. 전체를 wiki 로 관리

장기 문서는 docs/ 에 두고, Obsidian vault 로 열었습니다. docs/README.md 는 전체 지도, docs/strategy/14_decision_log.md 는 공식 결정 로그, docs/dataview-queryboard.md 는 점검판 역할을 합니다. frontmatter, wiki link, decision log 를 붙여 "이 문서가 지금 유효한지 / 무엇과 연결되는지" 를 표시했습니다.

완전한 그래프 메모리는 아닙니다. 그래도 작은 팀이 바로 시작하기에는 현실적이었습니다.

Obsidian 은 여기서 에이전트의 뇌가 아닙니다. 사람이 docs/ 를 읽고 관리하기 쉽게 여는 UI 입니다. Backlink 로 문서 연결을 보고, Dataview 로 status: active 인 문서만 모아 보고, Smart Connections 로 비슷한 노트를 찾습니다. Claude Code 가 매번 Obsidian 플러그인을 직접 호출해서 생각하는 구조는 아닙니다. 이 구분이 기대치를 맞추는 데 중요합니다.

한 장으로 보면

세 단계가 어떻게 묶이는지, 그리고 백업이 왜 repo 밖에 있는지 한 그림으로 정리하면 이렇습니다.

이 그림에서 두 가지만 짚어 두겠습니다.

첫째, Claude 컨텍스트로 자동 들어가는 화살표는 하나뿐입니다.

Layer 2 의 Context.md 만 SessionStart 단계에서 자동으로 주입됩니다. 나머지 Layer 1, 2 의 다른 파일, Layer 3 전체는 점선입니다. 필요할 때 명시적으로 읽거나, 사용자가 가리키거나, MCP 같은 도구가 호출할 때만 컨텍스트에 들어갑니다. 매 세션 모든 문서를 다 넣는 게 아니라는 뜻입니다.

둘째, 백업은 신뢰 경계 밖에 있습니다.

docs/_claude/ 는 Claude 가 자동으로 수정할 수 있는 영역입니다. Memory.md 를 잘못 덮어쓰는 사고가 한 번이라도 나면 git history 만으로는 복구가 늦을 수 있습니다. 그래서 ~/Documents/swatch-archive/ 처럼 repo 바깥에 매주 자동 백업을 둡니다. Claude 의 도구 호출 범위 안에 있지 않은 자리입니다.

Claude Code 가 뭐고, 가 왜 특별한가

본격적인 회고로 들어가기 전에, Claude Code 자체를 짧게 정리하고 가겠습니다. 이 시리즈는 Claude Code 를 어느 정도 써 봤거나, 최소한 "터미널에서 돌아가는 코딩 에이전트" 정도로 들어 본 독자를 기준으로 씁니다.
Claude Code 는 일반 챗봇이 아닙니다. 질문에 답하고 기다리는 도구라기보다, 파일을 읽고, 명령을 실행하고, 코드를 수정하고, 문제를 끝까지 따라가는 agentic coding environment 에 가깝습니다. 그래서 한 번의 질문을 잘 쓰는 프롬프트 엔지니어링과는 결이 다릅니다.
Claude Code 에서 특히 중요한 자리가 세 개 있습니다.

1. CLAUDE.md

CLAUDE.md 는 프로젝트 루트에 두는 안내판입니다. Claude Code 는 세션을 시작할 때 현재 디렉터리에서 위로 올라가며 CLAUDE.md 를 찾고, 발견한 내용을 컨텍스트에 넣습니다.

여기에는 보통 이런 내용을 씁니다.

## Project Rules

- 답하기 전 docs/\_claude/Context.md 를 먼저 읽어라.
- 제품 결정은 docs/strategy/14_decision_log.md 를 우선한다.
- Supabase migration 을 추가하면 반드시 migration up 을 확인한다.

여기서 조심할 부분이 있습니다. CLAUDE.md 는 강제 설정이 아닙니다. Claude 는 이 파일을 컨텍스트로 읽습니다. 부탁에 가깝습니다. 잘 따르지만, 항상 강제되는 것은 아닙니다.

그래서 본편 3편에서 hook 이 등장합니다. 반복해서 어기는 규칙은 텍스트로만 두지 않고, 도구 호출 단계에서 막아야 합니다.

2. claude/

.claude/ 는 Claude Code 의 작업대입니다.

이 폴더에는 보통 이런 것들이 들어갑니다.

.claude/
  settings.json        # hook 설정
  hooks/               # SessionStart, PreToolUse 등에서 실행할 스크립트
  commands/            # /docs-sync 같은 slash command
  skills/              # 반복 작업용 skill

이 시리즈에서 중요한 것은 settings.json 과 hooks 입니다.

.claude/settings.json 에 SessionStart hook 을 등록하면, 새 세션이 시작될 때 특정 스크립트를 자동으로 실행할 수 있습니다. 이 프로젝트에서는 .claude/hooks/load-context.sh 가 docs/_claude/Context.md 를 출력하게 했고, 그 출력이 Claude 의 컨텍스트로 들어갑니다.

사용자가 매번 "우리 프로젝트는..." 하고 설명하지 않아도, 세션 시작 때 압축 컨텍스트가 자동으로 깔립니다.

3. auto memory

Claude Code 에는 auto memory 도 있습니다. Claude 가 스스로 기억할 내용을 ~/.claude/projects/<project>/memory/ 아래에 저장하는 기능입니다.

이건 머신 로컬입니다. 같은 git repo 를 쓰더라도, 제 머신의 auto memory 와 팀원 머신의 auto memory 는 공유되지 않습니다. 그래서 팀 단위 작업에서는 조심해야 합니다. 개인 작업 기록에는 좋지만, 팀의 공식 메모리로 쓰기에는 위험합니다.

이 시리즈가 docs/_claude/Memory.md 를 따로 둔 이유가 여기 있습니다. 팀이 공유해야 하는 선호, correction, 반복 패턴은 git 으로 추적되는 파일에 있어야 합니다.

4. context window

마지막으로 가장 중요한 제약이 있습니다.
Claude Code 의 모든 세션은 새 컨텍스트 윈도우에서 시작합니다. 그리고 그 컨텍스트 윈도우는 빨리 찹니다. 많이 넣으면 더 잘 기억할 것 같지만, 실제로는 차오를수록 성능이 흔들립니다.
그래서 질문은 "문서를 어디에 쌓을까" 가 아니라 이렇게 바뀝니다.

매 세션에 반드시 넣을 것은 무엇이고, 필요할 때만 읽게 할 것은 무엇인가?

이 질문이 본 시리즈 전체의 출발점입니다.
세 가지 층을 한 번 더 정리하면 이렇습니다.

프롬프트 엔지니어링: 한 번의 대화에서 질문을 잘 쓰는 기술
하네스 엔지니어링: 에이전트가 일하는 작업대와 도구함을 꾸리는 기술
메모리 아키텍처: 에이전트가 다음 세션에도 참고할 지식 구조를 설계하는 기술

본 시리즈는 세 번째를 다룹니다.

5. 도구가 Claude Code 가 아니라면 (vendor 락인의 문제는 검토 중)

여기까지 본 자리는 모두 Claude Code 가 갖춘 기능입니다. CLAUDE.md 자동 로드, SessionStart hook, .claude/ slash command 는 Anthropic 의 Claude Code CLI 에서 지원하는 메커니즘이고, Cursor, Codex CLI, ChatGPT, Gemini 같은 다른 도구에는 같은 형태로 들어 있지 않습니다.

그래도 이 시리즈가 다른 도구 사용자에게 쓸모없는 건 아닙니다. 핵심을 다시 보면 글의 본체는 한 가지입니다.
어떤 마크다운 파일을 어디에 두고, 무엇을 매 세션마다 읽히고, 무엇을 결정 로그로 남길지의 구조입니다. 이 구조는 도구와 무관합니다. aiedge 의 3-layer 글에서도 같은 점이 짚여 있습니다.

Layer 2 의 .md 파일은 어떤 LLM 이나 AI 에이전트에도 첨부할 수 있습니다.

다른 도구에서는 "자동" 이 빠지고 "수동 첨부" 만 남는다고 보면 됩니다.

Cursor: .cursor/rules/ 같은 프로젝트 지침에 핵심 파일을 명시합니다. 워크스페이스에 폴더를 추가해 두면 모델이 직접 read 할 수 있습니다.
Codex CLI: 자동 컨텍스트 주입이 없으므로, 새 세션을 열 때 Context.md 등 핵심 파일을 직접 첨부하거나 처음 프롬프트에 붙여 넣습니다. Karpathy 의 gist mega prompt 자체도 같은 방식입니다 (매번 직접 프롬프트마다 레퍼런싱해주는 형태).
ChatGPT / Cowork: 새 채팅을 열 때 마스터 폴더 또는 핵심 파일을 첨부합니다. Project 기능을 쓰면 첨부 상태가 유지됩니다.
Gemini: 파일 업로드 또는 Drive 연동으로 같은 효과를 냅니다. 자동 로드는 없습니다.

Claude Code 는 "자동의 편리함" 을 추가로 줍니다. .... 그만큼 단점도 있는 점도 감수해야합니다.
Claude Code 에 vendor 락인 되는 문제가 있지요.

Claude Code 를 믿어도 괜찮나?

(Open AI 와 다르게 Anthropic 은 미국 국방부에 협력안한다 어쩌구.. 윤리, 철학, 인류애적으로 가오 잡는 부분도 어딘지는 알겟는데)

OpenClaw 때의 대응 . ㅡ ㅡ 등등.

Claude Code 의 쫌생이스러움을 생각하면 살짝 좀.. 사이드 플젝 이상으로는 흠... Anthropic 에 종속되는 이 시스템이 맞나?

더 고민해보면 좋을듯요.

생각나는 개발 밈이 있어서 가져와봤습니다. 삘받아서 번역까지 해버림 (오역 지적 환영)

https://youtu.be/77w1rdJ-NW0?si=a4bSG-vgN6AUkgRD

생각나는 밈 (Open Code 막았을 때 ㅡㅡ ) 한글 자막까지 쪄왓씁니다.

그리고 또: https://news.hada.io/topic?id=29173

Redis array: 긴 개발 과정의 짧은 이야기 | GeekNews

Redis의 새 Array 데이터 타입 작업은 1월 초 시작돼 약 4개월 뒤 PR로 올라갔고, 첫 달에는 필요성, C 구조체, 희소 표현, 링 버퍼, ARINSERT용 배열 커서 의미를 담은 명세가 작성됨초기 설계는 Opus와 함

news.hada.io

<!--- 26.05.06 기준 글 추가 --→
# pageIndex 라는 오픈소스 발견!!!
또 https://github.com/VectifyAI/PageIndex 글 시리즈 완고 직후에 이 레포를 발견햇네요.
→ 임베딩 없음. 청킹 없음. 벡터 DB 없음. 100% 오픈 소스 무료. 오우 완전 제가 원하던거임요.
개쩌는듯?? 한번 후속으로 다뤄보겟습니다.

=== PageIndex 관련 ====
- 벡터 DB가 필요 없습니다.
- 데이터를 임베딩하지 않습니다.
- 청킹(chunking)을 전혀 하지 않습니다.
- 유사도 검색을 수행하지 않습니다.
문서를 청킹해서 pinecone에 집어넣는 대신,
트리 인덱스를 구축하고 LLM이 책을 읽는 사람처럼 그 안을 추론하도록 한다네요

일단 팀 프로젝트 멤버들이 공통적으로 codex, claude code 를 사용하고 있고, 일단 먼저 Claude Code 를 기준으로 기능을 구축하되, 추후 좀 더 다른 에이전트까지 적용되는 시스템 아키텍처로 확장성을 넓혀볼 생각입니다. (궁극적으로 open code 까지)

다른 도구에서는 같은 docs/_claude/ 폴더와 같은 frontmatter 규약을 그대로 쓰되, 매 세션 시작 때 사람이 한 번 첨부해 주는 단계가 들어갑니다.

폴더 구조와 운영 규칙은 그대로 옮겨갑니다. 본 시리즈가 보여 주려는 건 그 구조 쪽이고, Claude Code 의 hook 과 slash command 는 그 위에 얹은 자동화 레이어로 보면 됩니다.

새 세션이 실제로 어떻게 시작되는지

위 네 자리를 글로 따로따로 보면 헷갈립니다. 새 세션이 시작될 때 어떤 순서로 어떤 파일이 읽히고 어떤 파일이 안 읽히는지 한 그림으로 보면 더 빠릅니다.

여기서 자주 헷갈리는 부분 두 가지를 짚어 두겠습니다.
첫째, CLAUDE.md 와 SessionStart hook 은 둘 다 자동 로드지만 자리가 다릅니다.

CLAUDE.md 는 Claude Code 가 디렉터리를 거슬러 올라가며 발견하는 안내판이고,

SessionStart hook 은 사용자가 .claude/settings.json 에 등록한 스크립트입니다.

둘 다 새 세션에 자동으로 컨텍스트에 들어갑니다. 하나는 텍스트 안내판이고, 다른 하나는 실행 결과 (예: Context.md 의 내용 출력) 라는 차이만 있습니다.

둘째, `Instructions.md와Memory.md` 는 첫 프롬프트 이후에 읽힙니다.**

자동 주입되는 건 Context.md 만입니다. 나머지 작업 메모리 파일은 CLAUDE.md 의 안내를 따라 Claude 가 첫 프롬프트를 받은 뒤 직접 읽으러 갑니다.

그래서 Context.md 가 너무 길어지면 매 세션이 무거워지고, 너무 짧으면 Claude 가 다른 파일을 찾아 읽기 전까지 프로젝트를 잘못 추측할 수 있습니다. 이 컨텍스트 관리를 어떻게 최적화했는지에 대해서는 본편 3편에서 자세히 살펴보겠습니다.

실제로는 어떻게 시작했나

지금까지 본 구조는 한 번에 깔끔하게 나온 것이 아닙니다. 처음 프롬프트는 굉장히 심플하고 단순했습니다..

위에 적은 𝕏 (구 Twitter) 의 문제의식, aiedge 아티클, Karpathy gist 원문, 내용을 길게 붙여 넣고, 기존 docs/ 도 참조하게 한 뒤,

대략 이런 의도로 물었습니다.

 이 레포의 @docs 를 보고,
Karpathy 의 LLM knowledge base / wiki 시스템 아이디어를 참고해서,
Claude Code 에서 쓸 수 있는 문서 메모리 구조를 설계해 줘.

먼저 /plan 으로 접근하고
어떤 파일을 만들지
무엇을 CLAUDE.md 에 둘지
무엇을 docs/_claude 에 둘지
무엇을 docs/strategy 의 결정 로그로 관리할지 제안해 줘.

처음부터 mkdir -p docs/_claude 같은 명령을 제가 직접 설계한 게 아닙니다. 그건 에이전트와 계획을 주고받은 뒤 "결과적으로 이 정도 구조가 필요하겠다" 고 정리된 산출물에 가깝습니다.

그래서 독자가 따라 한다면 순서는 명령어부터 치는 쪽이 아닙니다.

지금 레포의 docs/ 를 먼저 보여줍니다.
참고할 글과 gist 를 같이 넣습니다.
바로 구현시키지 말고 /plan 으로 구조부터 뽑게 합니다.
사람이 trade-off 를 결정합니다.
그다음에 docs/_claude, CLAUDE.md, hook, decision log 를 만들게 합니다. (karpathy 시스템 레퍼런스)

이 과정을 거친 뒤에 남은 최소 형태가 docs/_claude/Instructions.md, Memory.md, Context.md, Archive-Guide.md 였습니다.

본편 1편에서는 왜 이런 구조가 필요했는지,

본편 2편에서는 docs/ 를 어떻게 다시 읽히는 자료로 바꿨는지,

본편 3편에서는 자동화와 점검 루틴을 어떻게 붙였는지 차례로 정리해보겠습니다.

https://github.com/forrestchang/andrej-karpathy-skills

GitHub - forrestchang/andrej-karpathy-skills: A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpa

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls. - forrestchang/andrej-karpathy-skills