Claude Code의 '기억'을 설계하기——CLAUDE.md와 Skills로 AI Agent가 완전히 달라진 이야기

며칠 전, 문득 깨달은 점이 있습니다.

Claude Code를 반년 정도 계속 사용해 왔는데, 어떤 프로젝트에서는 놀라울 정도로 매끄럽게 코드가 나오는 반면, 다른 프로젝트에서는 마치 매번 처음 만난 인턴에게 제로 베이스에서 설명하고 있는 듯한 느낌을 지울 수 없었습니다.

차이는 단 하나였습니다. CLAUDE.md를 작성하고 있는지 여부였습니다.

이 기사에서는 Claude Code의 '기억 관리 (Memory Management)' 메커니즘과, Skills 시스템을 어떻게 사용하면 실제로 개발 경험이 바뀌는지, 제가 시행착오를 겪은 과정을 그대로 적어보겠습니다.

애초에 CLAUDE.md는 무엇을 하고 있는가

CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽어들이는 Markdown 파일입니다. 프로젝트의 루트(Root)에 두기만 하면 기술 스택 (Tech Stack), 코딩 규약 (Coding Convention), 테스트 실행 방법, 디렉터리 구조——이러한 '코드만으로는 추측할 수 없는 문맥 (Context)'을 매번의 대화로 가져올 수 있게 됩니다.

대략 말하자면, 새로운 멤버가 들어왔을 때 건네주는 '프로젝트 온보딩 (Onboarding) 자료'에 가깝습니다. 다만 읽는 주체가 인간이 아니라 AI Agent라는 점이 다릅니다.

/init

명령어를 입력하면 Claude가 코드베이스를 분석하여 초기 초안을 생성해 줍니다. 이 부분에서 꽤 고생했습니다. 처음에는 자동 생성된 것을 그대로 사용했는데, 90행이나 되면 Agent가 오히려 길을 잃더라고요.

첫 번째 실패: 너무 많이 적은 CLAUDE.md

솔직하게 말씀드리겠습니다.

처음에 작성한 CLAUDE.md는 이것저것 다 집어넣어서 90행을 넘었습니다. 기술 스택 설명, Git 브랜치 전략, 이미지 포맷 지정, SEO 요구사항…… 전부 넣었습니다.

결과가 어땠을까요? CSS를 수정해 달라고만 했는데 Agent가 "이미지는 WebP로 출력할까요?"라고 물어봅니다. 글을 써달라고 하면 먼저 빌드 체크를 실행합니다. 매번 관계없는 지시에 끌려가며 멀리 돌아가게 되었습니다.

ETH Zurich의 연구에 따르면, CLAUDE.md는 60행을 넘어가면 Agent의 퍼포먼스가 떨어지기 시작한다고 합니다. 또한 Anthropic의 공식 문서에서도 "짧고 읽기 쉽게"가 원칙으로 명시되어 있습니다.

여기서 생각이 바뀌었습니다. CLAUDE.md에는 '항상 필요한 규칙'만 적고, 영역별 지식은 별도의 메커니즘으로 분리해야 한다고 말이죠.

Skills 시스템——'필요할 때만 기억을 불러오는' 설계

여기서부터가 본론입니다——

Claude Code의 Skills는 SKILL.md라는 파일을 넣은 폴더를 지정된 경로에 두기만 하면 사용할 수 있는 구조입니다. CLAUDE.md가 '매번 읽히는 전체 규칙'인 것에 반해, Skills는 '태스크에 부합할 때만 읽히는 전문 지식'입니다.

실제 구조는 다음과 같습니다.

~/.claude/skills/
├── tdd/
│ └── SKILL.md # 테스트 주도 개발 (TDD) 규칙
...

SKILL.md의 서두에 YAML 형식으로 name과 description을 적어두면, Claude가 기동 시 해당 설명문만 읽고 태스크와 관련이 있어 보일 때만 본문을 전개합니다. 스킬 하나당 약 100 토큰 정도만 소비하므로, 수십 개를 넣어두어도 관련 없는 태스크에는 영향을 주지 않습니다.

이것은 제가 내내 고민하던 문제였습니다. CLAUDE.md에 전부 적으면 문맥이 비대해져 정밀도가 떨어집니다. 그렇다고 아무것도 적지 않으면 매번 똑같은 설명을 해야 합니다. Skills는 그 중간 단계——'AI Agent의 기억을 계층화한다'는 발상이었습니다.

Karpathy 규칙——70행으로 11만 스타

2026년 1월, Andrej Karpathy (Tesla의 전 AI 디렉터, OpenAI 공동 창립자)가 X에 게시한 "LLM에게 코드를 작성하게 할 때의 전형적인 실패 패턴"이 화제가 되었습니다. 개발자 Forrest Chang이 이를 한 장의 CLAUDE.md로 구현한 것이 andrej-karpathy-skills입니다. 현재 GitHub 스타 수는 11만 개를 넘었습니다.

내용은 단 4가지 원칙입니다.

① Think Before Coding——가정을 명시한다. 모호하면 질문한다. 멋대로 실행하지 않는다.

② Simplicity First——요구된 것만 최소한으로 작성한다. 투기적인 기능 추가는 하지 않는다.

③ Surgical Changes (정밀한 변경)——변경은 요청된 부분만 수행한다. 작동 중인 코드를 휘말리게 하지 않는다.

④ Goal-Driven Execution (목표 중심 실행)——절차가 아닌 「성공 기준」을 부여한다. Agent는 목표를 향해 루프(Loop)를 도는 것에 능숙하다.

직접 사용해 본 느낌으로는 특히 ①과 ②의 효과가 컸다. 이전에는 Claude가 멋대로 추상화를 쌓아 올려 1,000행의 코드를 작성해 오는 경우가 있었지만, 이 규칙을 넣은 이후로는 "정말로 이 구현으로 충분합니까?"라고 확인을 거쳐 오기 시작했다.

실전: 나의 CLAUDE.md는 현재 이렇다

시행착오 끝에, 지금은 다음과 같은 구성으로 정착되었습니다.

CLAUDE.md (프로젝트 루트, 50행 이내):

기술 스택 선언 (프레임워크, 언어 버전)
명령어 목록 (빌드, 테스트, 배포)
반드시 지켜야 할 규칙 (.env를 커밋하지 말 것, strict mode 필수 등)

Skills ( ~/.claude/skills/ 또는 .claude/skills/ ):

TDD 스킬 (테스트를 먼저 작성하고, 구현은 나중에)
디버깅 스킬 (추측이 아닌 체계적으로 원인을 좁힘)
코드 리뷰 스킬 (PR 전의 체크포인트)

더 이상 하지 않는 것:

CLAUDE.md에 SEO 규칙이나 문장 스타일 가이드를 섞는 것
자동 생성된 CLAUDE.md를 그대로 사용하는 것
한 파일에 모든 것을 다 담는 것

Anthropic 공식 Skills 문서에도 나와 있듯이, CLAUDE.md는 "지시서이지, 문서가 아니다". 한 줄 한 줄이 Claude의 행동을 바꾼다는 마음으로 작성한다. 그것만으로도 Agent의 움직임이 완전히 달라진다.

좋았던 점과 아쉬운 점, 둘 다 적겠습니다

좋았던 점:

세션이 바뀌어도 Claude가 "이 프로젝트의 문맥"을 기억하고 있다는 느낌이 들었다
Skills의 on-demand (온디맨드) 로딩 덕분에, 무관한 규칙에 휘둘리는 일이 없어졌다
Karpathy 규칙을 도입한 이후, 과도한 추상화나 암묵적인 가정이 눈에 띄게 줄었다

아쉬운 점:

Skills의 description 작성 방식에 따라, 필요한 시점에 발화(Trigger)되지 않을 때가 있다. 트리거의 정밀도는 아직 수동 튜닝이 필요하다
프로젝트가 커지면 CLAUDE.md에 "무엇을 남기고 무엇을 Skills로 뺄 것인가"에 대한 판단이 어려워진다
Cursor 등 다른 에디터와의 호환성은 아직 완전하지 않다 (포맷은 수렴하고 있으나, 2026년 중반 시점에서는 수동 변환이 필요한 상황도 있다)

적합성이 다르기에 모두에게 권하는 것은 아니지만——Claude Code를 메인으로 사용하면서 "매번 똑같은 것을 다시 설명하는 것이 힘들다"라고 느끼는 사람에게는, CLAUDE.md의 정비와 Skills의 도입은 체감상 확실히 변화를 느낄 수 있는 포인트라고 생각한다.

AI Agent의 "기억 설계"——요약하자면

여기까지 읽으신 분들은 눈치채셨을지도 모르겠지만, 이 이야기의 본질은 "AI에게 무엇을 기억시키고, 언제 떠올리게 할 것인가"라는 설계의 문제이다.

CLAUDE.md에는 상시 필요한 규칙만 50행 이내로. 영역별 지식은 Skills로 분리하여 on-demand로 읽어 들인다. 그리고 Karpathy 규칙으로 "멋대로 실행하지 않고, 불필요하게 작성하지 않음"을 담보한다.

이 삼층 구조의 조합이 현재로서는 나에게 가장 잘 맞는다.

아직 검증 중이지만, 현시점에서의 기록으로서 남긴다.

또 변화가 생기면 추가하겠다.

이상, Claude Code의 기억 관리에 관한 기록이었다.