AI 코딩 에이전트를 오래 써본 개발자라면 한 번쯤 이런 경험을 했을 것이다. 어제 결정한 아키텍처를 오늘 다시 설명하고, 지난주에 Vue를 왜 버렸는지 또 이야기하고, 새 세션을 열 때마다 프로젝트 구조를 처음부터 읊어준다. 에이전트가 멍청한 게 아니다. 기억할 장소가 없을 뿐이다.
이 문제를 정면으로 파고든 사례가 있다. dev.to에 소개된 ContextMixer 프로젝트는 "AI 에이전트가 프로젝트 컨텍스트를 잊지 않도록" 직접 지식베이스를 만든 결과물이다. 개발자는 20개 넘는 개인 프로젝트를 오가면서 Claude Code, Codex 등 여러 도구를 병행하다 보니 컨텍스트가 도구 사이에서 증발하는 문제를 겪었다. Notion은 MCP 지원이 있지만 페이지 패칭이 느리고 토큰 소비가 크다. Obsidian은 로컬 우선이라 채팅 기반 도구에서 접근이 안 된다. 결국 직접 만들었다.
핵심 설계 아이디어는 '점진적 조회(Progressive Retrieval)'다. 에이전트가 문서 전체를 한 번에 읽는 대신, meta(제목+요약, 수십 토큰) → outline(헤딩 구조, 수백 토큰) → section(필요한 섹션만, 수백~수천 토큰) → full(전체) 순으로 필요한 만큼만 가져간다. "Auth 설계 확인"이라는 하나의 쿼리가 API 호출 세 번으로 해결되고, 전체 문서를 읽을 때보다 토큰을 수십 배 아낄 수 있다. 에이전트는 모든 걸 기억할 필요가 없다. 필요할 때 꺼낼 수 있는 좋은 장소가 있으면 된다.
프로젝트 메모리의 구조도 흥미롭다. 개발자가 'AI Cortex'라 부르는 이 패턴은 프로젝트당 네 문서를 유지한다. context는 현재 페이즈, 최근 작업, 미해결 이슈, 다음 세션을 위한 인수인계 노트다. spec은 확정된 목표와 기술 스택만 담는다. decisions는 결정과 그 근거, 기각된 대안까지 기록한다. notes는 라이브러리 함정, 버그 우회법, 구현 팁이다. 에이전트는 세션 시작 시 context를 읽고, 세션 종료 시 업데이트한다. 다음 세션은 이어서 시작된다. "왜 Vue를 버렸어요?"는 이제 개발자가 반복해서 설명할 필요가 없다. 문서가 대신 답한다. 단, AI가 지식베이스에 쓰기 권한을 가지면 규칙 없이는 혼돈이 온다. 미확인 아이디어가 spec에 들어가거나, 합의 없는 결정이 decisions에 등록되는 식이다. 쓰기 권한만으로는 부족하고, 쓰기 규칙이 필요하다는 것이 이 프로젝트가 얻은 실전 교훈이다.
지식베이스가 '프로젝트 맥락'을 저장한다면, 코드 구조 자체를 그래프로 만드는 도구 카테고리도 빠르게 성장하고 있다. dev.to에서 비교 분석된 세 가지 MCP 도구—code-review-graph, Graphify, codebase-memory-mcp—는 모두 같은 문제를 겨냥한다. 에이전트가 "ProcessOrder를 호출하는 곳이 어디야?"라는 질문에 답하려고 저장소 전체를 grep하며 수십 번 파일을 읽는 대신, 미리 파싱된 코드 그래프에서 한 번의 쿼리로 끝내는 것이다.
세 도구는 각자 다른 방향으로 특화되어 있다. code-review-graph는 PR 리뷰에 집중한다. Tree-sitter로 함수·클래스·임포트·호출 체인을 파싱해 로컬 SQLite에 저장하고, 파일이 변경될 때 영향을 받는 모든 호출자·의존 파일·테스트를 추적하는 '블래스트 래디어스 분석'이 강점이다. 27,700개 파일 규모의 Next.js 모노레포에서 리뷰 대상을 15개 파일로 좁혔다는 수치가 인상적이다. Graphify는 스케일이 다르다. 코드뿐 아니라 SQL 스키마, Terraform, PDF, 심지어 회의 영상까지 하나의 그래프로 통합한다. Y Combinator S26 배치 기업이고 GitHub 스타가 7만 5천을 넘는다. /graphify . 슬래시 커맨드 하나로 20개 이상의 AI 코딩 어시스턴트에서 즉시 사용할 수 있다는 접근성이 차별점이다. codebase-memory-mcp는 아키텍처 자체가 이질적이다. 순수 C로 작성된 단일 정적 바이너리로, 런타임 의존성이 없다. 리눅스 커널 2800만 라인을 3분에 인덱싱하고 이후 쿼리를 1밀리초 미만으로 처리한다. 158개 언어 지원에 LSP 수준의 타입 분석까지 결합해, arXiv 논문으로 발표된 벤치마크에서 토큰 10배 절감, 도구 호출 2.1배 감소를 기록했다.
그런데 이 모든 도구가 잘 작동하려면 전제 조건이 있다. 에이전트에게 맥락을 공급하기 전에, 무엇을 먼저 만들고 무엇을 나중에 만들지가 명확해야 한다. dev.to에서 소개된 페이즈 기획 방법론은 이 질문에 정면으로 답한다. 핵심 명제는 단순하다. "한 번에 전체를 요청하는 것이 AI를 과잉 빌드하게 만드는 가장 빠른 방법이다."
'소셜 앱을 만들어줘'라고 요청하면 AI는 인증, 대시보드, 프로필, 피드, 결제, 알림, 관리자 도구, 검색, 업로드 플로우를 한꺼번에 쏟아낸다. 기술적으로는 인상적이지만 실제로는 폴더 가득한 안개 덩어리다. 더 나은 첫 번째 프롬프트는 "이 아이디어를 페이즈별 빌드 계획으로 만들어줘"다. 이 방법론은 다섯 단계를 제안한다. 먼저 추상적인 '사용자' 대신 구체적인 한 사람을 정의한다. 그 사람이 처음으로 해낼 수 있어야 하는 한 가지 워크플로우를 MVP로 확정한다. 전체 기능을 에픽 단위로 분류하되 Phase 1/2/이후로 엄격하게 구분한다. 데이터 모델을 화면보다 먼저 설계한다. 그리고 AI에게 "나를 과잉 빌드로부터 보호해"라고 명시적으로 요청한다. 마지막 지시가 가장 인상 깊다. AI는 기본적으로 확장하려는 성향이 있기 때문에, 보호적으로 행동하라는 명령을 컨텍스트에 심어둬야 한다.
세 가지 소스를 함께 읽으면 하나의 설계 레이어 구조가 보인다. 가장 아래에는 코드 그래프 도구가 있다. 저장소의 구조적 사실—누가 누구를 호출하는지, 변경의 파급 범위가 어디까지인지—을 에이전트가 매번 다시 읽지 않아도 되게 한다. 그 위에는 프로젝트 지식베이스가 있다. 무엇을 결정했고, 왜 결정했고, 지금 어느 단계인지를 세션을 넘어 보존한다. 가장 위에는 페이즈 설계가 있다. 에이전트에게 어떤 순서로 무엇을 만들어야 하는지를 명확히 전달한다. 이 세 레이어 중 하나라도 빠지면 나머지 두 개가 아무리 정교해도 에이전트는 맥락을 잃거나 방향을 잃는다.
결국 AI 코딩 에이전트를 잘 활용한다는 건, 더 좋은 프롬프트를 쓰는 문제가 아니다. 에이전트가 읽고 쓸 수 있는 구조를 먼저 설계하는 문제다. 코드 그래프로 구조적 사실을 제공하고, 지식베이스로 결정의 역사를 보존하고, 페이즈 계획으로 다음 행동의 경계를 그어주는 것—이 세 가지가 갖춰질 때 에이전트는 비로소 매 세션을 처음부터 시작하지 않아도 된다. 컨텍스트를 설계하는 개발자가 에이전트를 이기는 게 아니다. 컨텍스트를 설계한 개발자만이 에이전트와 함께 실제로 전진할 수 있다.