같은 Claude Code를 써도 어떤 프로젝트는 세션을 열 때마다 맥락을 처음부터 설명하고, 어떤 프로젝트는 에이전트가 이미 상황을 파악한 채로 시작한다. 이 차이가 누적되면 하루 이틀이 아니라 프로젝트 전체의 속도 격차로 벌어진다. 최근 dev.to에 올라온 두 편의 글이 그 격차의 정체를 꽤 명확하게 짚어낸다.
기억 상실 에이전트를 구조로 고치는 법
첫 번째 글 "Claude Code, Beyond the Prompt — Part 1"은 자동화 트레이딩 시스템을 Claude Code로 운영한 경험을 바탕으로 쓰인 글이다. 핵심 관찰은 단순하다. Claude Code는 이미 메모리 시스템을 갖추고 있다. 프로젝트 루트의 CLAUDE.md를 세션 시작 시 자동으로 로드한다. 문제는 메커니즘의 부재가 아니라, 그 파일에 무엇을 어떻게 담느냐다.
흔한 실수는 하나의 파일에 모든 것을 욱여넣는 것이다. "우리는 Postgres를 쓴다"는 1년짜리 사실과 "payments 모듈 리팩터링 진행 중"이라는 3일짜리 상황, "스테이징 DB가 내려가 있다"는 오늘만 유효한 상태가 같은 파일에 섞이면, 파일 전체의 신뢰도가 무너진다. 절반이 낡았다는 걸 알면 나머지도 믿기 어려워진다. 신뢰할 수 없는 메모리는 메모리가 없는 것보다 나쁘다.
해법은 파일을 주제가 아니라 변화 주기로 나누는 것이다.
CLAUDE.md— 스택, 아키텍처, 컨벤션, 절대 건드리지 말아야 할 것들. 한 달에 한 번 바뀔까 말까 한 프로젝트의 '헌법'.MEMORY.md— 지금 진행 중인 작업, 이번 주의 주의사항, 최근 변경 사항. 매 세션마다 업데이트되는 '현재 상태 대시보드'.
두 파일의 신뢰 수준이 다르다는 것을 에이전트도, 개발자 자신도 알게 된다. CLAUDE.md는 안정된 사실이고, MEMORY.md는 지금 이 순간의 스냅샷이다. 충돌이 생기면 최신인 MEMORY.md가 이긴다는 규칙을 명시해두면 된다.
이 구조의 진짜 힘은 CLAUDE.md 하단에 한 줄을 추가하는 데서 나온다. "세션 시작 시 MEMORY.md를 읽고, 변경 사항이 있는 세션 종료 시 MEMORY.md를 업데이트하라." 두 정적 파일이 이 한 줄로 살아있는 시스템이 된다. 여기에 한 가지 원칙을 덧붙이면 완성된다: 메모리 파일의 사실을 행동의 근거로 삼기 전에 반드시 실제 코드에서 검증하라. 기억이 맞더라도 코드는 이미 움직여 있을 수 있다.
'잘 구조화된 저장소'가 없으면 에이전트는 부채다
두 번째 글 "Why 'Just Use Claude Code' Isn't a Mobile Strategy"는 다른 각도에서 같은 결론에 도달한다. 많은 개발자들이 "Claude Code가 있는데 왜 템플릿이 필요하냐"고 묻는다. 이 질문은 도구와 전략을 혼동한 데서 나온다.
Claude Code는 도구다. 모바일 앱 전략은 그 도구가 올라서는 기반이다. 기반 없이 도구만 있으면, 에이전트가 생성한 코드가 오히려 위험해지는 지점들이 있다. 글이 열거하는 실제 실패 모드들은 프론트엔드 개발자라면 한 번쯤 마주쳤을 법한 것들이다.
- EAS Build는 계정 상태다. 에이전트는 그럴싸한
eas.json을 생성할 수 있지만, 인증서를 만들거나 프로비저닝 프로파일을 Apple에 올릴 수 없다. - Supabase RLS는 계약이다.
for all using (true)는 정책이 아니라 데이터 유출이다. 에이전트는 계약을 구현할 수 있지만, 계약을 설계하는 건 사람의 몫이다. - Stripe 웹훅은 환각을 용납하지 않는다. 서명 검증, 원시 바디, 멱등성 키 없이 생성된 핸들러는 실전에서 조용히 무너진다.
EXPO_PUBLIC_*환경변수는 번들에 그대로 포함된다. 에이전트가 클라이언트에서 직접 AI API 키를 호출하도록 코드를 생성하면, 그 키는 앱 번들을 받은 모든 사용자에게 노출된다.
핵심은 Claude Code가 이것들을 올바르게 구현하지 못해서가 아니라는 점이다. 올바른 패턴이 저장소 안에 이미 있어야 한다는 것을 모르기 때문이다. 에이전트는 존재하는 패턴을 증폭시키지, 없는 패턴을 발명하지 않는다. 발명하면 그게 위험하다.
구조가 에이전트의 속도를 결정한다
두 글이 서로 다른 문제를 다루는 것처럼 보이지만, 가리키는 방향은 같다. 잘 구조화된 저장소가 있을 때 Claude Code는 10배 빠르고, 빈 폴더에서 시작하면 자동완성이 달린 부채다.
잘 구조화된 저장소가 갖춰야 할 것들을 정리하면 이렇다.
| 레이어 | 없을 때 | 있을 때 |
|---|---|---||
| CLAUDE.md | 매 세션마다 컨텍스트 재설명 | 세션 시작부터 프로젝트 인식 |
| MEMORY.md | 3일 전 작업 기억 못 함 | 중단 지점 정확히 복원 |
| RLS 패턴 | 에이전트가 임의 설계 | 기존 계약 따라 구현 |
| 웹훅 패턴 | 환각 코드 생성 | 검증된 구조 복제 |
| API 키 패턴 | 클라이언트 노출 위험 | 서버사이드 프록시 자동 적용 |
이것은 AI 도구를 잘 쓰는 기술이 아니라, 프로젝트 구조를 에이전트가 읽을 수 있도록 설계하는 일이다. 디자인 시스템이 디자이너와 개발자 사이의 공통 언어이듯, 잘 만들어진 CLAUDE.md와 MEMORY.md, 그리고 검증된 코드 패턴들은 에이전트와 개발자 사이의 공통 언어다.
지금 당장 할 수 있는 것
현재 진행 중인 프로젝트에 이 구조가 없다면, 10분이면 시작할 수 있다. CLAUDE.md에 스택, 컨벤션, 절대 금기 사항을 담고, MEMORY.md에 지금 진행 중인 작업과 최근 변경 이력을 적는다. CLAUDE.md 하단에 MEMORY.md 읽기/쓰기 지시를 추가한다.
더 중요한 건 다음 단계다. RLS 정책, 웹훅 핸들러, AI API 프록시 패턴처럼 에이전트가 발명하면 위험한 영역을 먼저 파악하고, 그 패턴을 저장소 안에 명시적으로 심어두는 것이다. 에이전트가 증폭시킬 패턴을 개발자가 먼저 설계하는 것, 그게 AI 워크플로우에서 '전략'이 의미하는 바다.
AI 코딩 도구의 생산성 격차는 모델 성능에서 오지 않는다. 에이전트가 올라서는 저장소의 구조에서 온다. 같은 Claude Code를 써도 어떤 팀은 컨텍스트를 매번 다시 쌓고, 어떤 팀은 에이전트가 어제 멈춘 지점부터 오늘 이어간다. 그 차이를 만드는 건 프롬프트 실력이 아니라 프로젝트 구조 설계다.