문제는 모델이 아니라 '세션 경계'다
Claude Code를 며칠째 쓰다 보면 반드시 마주치는 순간이 있다. 어제 두 시간 짜 디버깅해서 찾아낸 auth 버그의 원인, 그 판단 과정, 고친 파일 경로까지 전부 새 세션에서는 처음 보는 얘기가 된다. 모델이 멍청해진 게 아니다. 그냥 기억이 없다. dev.to에 올라온 두 편의 실전 경험담이 이 문제를 정면으로 다룬다. 그리고 둘 다 같은 결론에 도달한다. 컨텍스트를 채팅 밖으로 꺼내야 한다.
패턴 1: GitHub Issue를 실행 계획서로 쓰기
dev.to 기고자 Gjoranv이 수개월 간 다듬은 첫 번째 패턴은 GitHub Issues를 세션 간 상태 저장소로 활용하는 방식이다. 구조는 단순하다. /gh-create-plan으로 작업을 체크박스 기반 이슈로 만들고, /gh-implement-plan으로 Claude가 이슈를 읽고 미완료 항목부터 이어받고, 단계마다 커밋 후 체크박스를 닫고, /gh-update-plan으로 결정 사항을 누적한다. 새 세션이 시작돼도 Claude는 이슈만 보면 '어디까지 했는지'를 즉시 파악한다. 재설명이 없다.
이 패턴의 진짜 가치는 체크박스가 아니다. 작업 상태가 코드베이스와 동일한 버전 관리 시스템 안에 있다는 것이다. Mermaid 다이어그램도 이슈 본문에 텍스트로 포함되어 플랜이 바뀔 때 함께 업데이트된다. 이슈가 단순한 티켓이 아니라 에이전트가 읽는 실행 명세서가 된다.
패턴 2: CLAUDE.local.md로 개인 컨텍스트 영구화하기
두 번째 문제는 더 조용하게 팀을 갉아먹는다. CLAUDE.md는 팀 공유 파일이다. 내가 자주 쓰는 테스트 커맨드, 내가 담당하는 모듈, 코드 리뷰에서 배운 컨벤션—이런 개인 레이어는 커밋할 수 없다. 오픈소스 기여자라면 CLAUDE.md 자체를 못 만든다.
Claude Code는 CLAUDE.local.md도 읽는다. gitignore 대상이라 커밋되지 않지만, 에이전트는 자동으로 참조한다. Gjoranv의 해법은 ai-memory라는 프라이빗 레포를 만들어 프로젝트별 CLAUDE.local.md를 관리하고, 각 프로젝트 디렉토리에 심링크로 연결하는 것이다. 파일 안에는 내 테스트 커맨드, 내 담당 모듈, 리뷰에서 배운 패턴이 쌓인다. 지식이 채팅 탭이 아니라 버전 관리되는 파일에 산다.
패턴 3: 디버깅 결론을 레포 상태로 저장하기
fcontext를 활용한 접근법은 문제를 조금 다른 각도에서 본다. 어제 디버깅으로 알아낸 결론—토큰이 잘못된 키에 저장되고, 동시 요청이 refresh를 중복 트리거하고, mutex와 debounce가 필요하다는 사실—이 오늘 새 세션에서 다시 필요하다면, 그건 .fcontext/_topics/ 아래 마크다운 파일로 남아있어야 한다. fcontext는 에이전트가 세션 시작 시 이 파일들을 읽도록 지시한다. 결과적으로 다음 세션은 '어제 배운 것'에서 시작하지, 'Day 1'에서 시작하지 않는다.
dev.to 기고자 Marvin Ma는 이 경험에서 핵심 통찰을 끌어낸다. 더 좋은 프롬프트도, 더 큰 컨텍스트 윈도우도 이 문제를 해결하지 못한다. 프롬프트는 지금 원하는 것을 기술하는 도구고, 컨텍스트 윈도우는 하나의 세션을 더 길게 만드는 도구다. 어제의 결론을 오늘로 가져오는 건 다른 설계가 필요하다.
시사점: 에이전트의 기억은 설계하는 것이다
세 패턴을 AI-First 워크플로우 설계 관점에서 묶으면 하나의 원칙이 나온다. 에이전트에게 기억을 기대하지 말고, 기억할 수 있는 구조를 설계하라. 이건 단순히 Claude Code 팁이 아니다. 어떤 AI 코딩 에이전트를 쓰든—Cursor, Copilot, Gemini CLI—세션 경계에서 컨텍스트가 증발하는 문제는 동일하다. 해결책도 동일하다. 상태를 레포 안으로 가져오는 것.
팀 리더 입장에서 추가로 짚을 부분이 있다. 이 패턴들은 개인 생산성 도구이기도 하지만, 팀 온보딩 설계에도 직접 연결된다. CLAUDE.md에 팀 컨벤션을 잘 정리해두면 신규 팀원이 Claude와 함께 컨텍스트를 쌓는 속도가 달라진다. GitHub Issue 기반 실행 계획은 코드 리뷰어가 에이전트의 작업 맥락을 추적할 수 있는 감사 트레일이 된다. 개인 패턴이 팀 인프라로 확장될 수 있는 지점이다.
한계와 전망: 판단은 여전히 사람의 몫
세 기사 모두 한 가지를 솔직하게 인정한다. 저장된 컨텍스트의 품질이 나쁘면 다음 세션도 나쁘게 시작한다. 무엇을 기록할지, 어떻게 구조화할지, 언제 에이전트를 멈추고 방향을 틀지—그 판단은 자동화되지 않는다. 컨텍스트 설계 능력이 AI-First 개발자의 핵심 역량이 되고 있다.
Claude Code hooks를 활용해 에이전트가 AFK 중에도 Slack으로 권한 요청을 보내고 작업을 이어가는 방식까지 등장하고 있다. 에이전트의 자율성이 높아질수록 컨텍스트 설계의 중요성은 더 커진다. 에이전트가 길을 잃지 않으려면, 에이전트가 읽을 지도를 사람이 먼저 그려야 한다. 그 지도를 얼마나 잘 그리느냐가 팀 생산성의 실질적 상한선을 결정하게 될 것이다.