에이전트가 틀리는 건 모델 탓이 아니다
Claude Code, Cursor, Codex를 매일 쓰다 보면 반드시 한 번은 벽에 부딪힌다. 에이전트가 존재하지 않는 함수를 자신 있게 호출하고, 거의 동작하는 코드를 제안하고, 코드베이스 안에 분명히 있는 패턴을 놓친다. 많은 개발자가 이걸 모델의 한계로 돌리지만, dev.to에 공개된 cocoindex-code 사례 분석은 다른 진단을 내린다. 문제는 컨텍스트다.
대부분의 코딩 에이전트는 코드베이스를 이해하기 위해 기본적으로 파일을 읽는다. 때로는 파일 전체를, 때로는 임의의 청크를. 문제는 실제 프로덕션 코드베이스는 컨텍스트 윈도우에 절대 다 들어가지 않는다는 것이다. 에이전트는 결국 잘리고, 불완전하고, 종종 오해를 유발하는 코드 조각을 받아 든다. 2인치짜리 구멍으로 내시경 수술을 집도하는 것과 다르지 않다.
AST 기반 시맨틱 인덱싱: 에이전트에게 눈을 달아주는 법
해법의 핵심은 코드의 의미 단위를 보존한 채 컨텍스트를 전달하는 것이다. cocoindex-code가 채택한 방식이 바로 AST(Abstract Syntax Tree) 기반 청킹이다. 일반 텍스트 분할과 달리 AST는 코드의 구조를 이해한다. 함수의 시작과 끝을 안다. 클래스를 절반으로 잘라내지 않는다. import와 그 컨텍스트를 함께 묶는다.
이 방식으로 인덱스를 구성하면 에이전트는 "user authentication과 session management에 관련된 코드를 찾아줘" 같은 자연어 쿼리로 정확히 필요한 코드 단위를 가져올 수 있다. 결과는 수치로 드러난다. 10K+ 파일 규모의 코드베이스에서 토큰 소비량 70% 감소, 그리고 코드베이스 특화 할루시네이션의 극적인 감소. 28개 이상 언어를 지원하고, 로컬 임베딩 모델로 동작해 API 키도 필요 없다. LSP가 getUserById가 어디 정의됐는지 알려주는 도구라면, cocoindex-code는 에이전트에게 코드베이스 전체의 의미 지도를 쥐여주는 도구다. 둘은 경쟁이 아니라 상호 보완이다.
CLAUDE.md와 AGENTS.md: 컨텍스트를 코드로 고정하는 패턴
컨텍스트 품질 문제는 단순히 검색 정확도의 문제가 아니다. 에이전트가 세션과 세션 사이에 코드베이스를 '기억'하는 방식도 설계가 필요하다.
macOS 데스크톱 에이전트 Fazm를 Claude로 구축한 사례(dev.to)는 이 지점에서 중요한 실천을 보여준다. 개발팀이 가장 가치 있었다고 꼽은 것은 CLAUDE.md 파일의 유지였다. 각 모듈이 무엇을 하는지, 코드베이스가 어떤 컨벤션을 따르는지, 어떤 Swift 패턴을 쓰고 어떤 걸 피해야 하는지, 빌드와 테스트를 어떻게 실행하는지. 이건 인간 독자를 위한 문서가 아니라 AI 리더를 위해 최적화된 문서다.
이 패턴 덕분에 새로운 Claude 세션이 열릴 때마다 코드베이스를 처음부터 다시 파악하는 오버헤드가 사라졌다. Open SWE 프레임워크(GeekNews)도 동일한 접근을 AGENTS.md로 공식화했다. 레포지토리 루트에 파일을 두면 에이전트가 샌드박스 시작 시 자동으로 읽어 시스템 프롬프트에 주입한다. 레포지토리 전체 지식과 작업별 정보(Linear 이슈, Slack 스레드)를 이중 레이어로 결합하는 구조다.
프로덕션이 수렴한 아키텍처: Open SWE가 말하는 공통 패턴
Stripe의 Minions, Ramp의 Inspect, Coinbase의 Cloudbot. 서로 독립적으로 구축된 사내 코딩 에이전트들이 놀랍도록 유사한 아키텍처로 수렴했다는 사실이 GeekNews를 통해 소개된 Open SWE 분석의 핵심이다.
공통 패턴을 요약하면 네 가지다.
- 격리된 실행 환경: 각 작업은 전용 클라우드 샌드박스에서 돌아간다. 프로덕션 시스템 영향을 차단하면서도, 액션마다 승인 프롬프트 없이 에이전트가 자유롭게 실행할 수 있는 구조다.
- 큐레이션된 툴셋: Stripe는 에이전트가 약 500개 도구에 접근하지만, 그게 시간이 지나며 쌓인 것이 아니라 신중하게 선별·유지된 것이라고 밝혔다. 도구의 양이 아니라 큐레이션이 핵심이다.
- 시작 시 풍부한 컨텍스트 주입: Linear 이슈, Slack 스레드, GitHub PR의 전체 컨텍스트를 작업 시작 전에 에이전트에 제공한다. 도구 호출로 요구사항을 '발견'하는 오버헤드를 줄이는 설계다.
- 서브에이전트 오케스트레이션: 복잡한 작업을 분해해 각자 격리된 컨텍스트와 책임을 가진 전문 자식 에이전트에 위임한다. Fazm 개발 사례에서도 UI 레이어와 데이터 파이프라인을 각각 별도 Claude 세션이 담당하는 병렬 에이전트 전략이 같은 맥락이다.
프론트엔드·풀스택 개발자에게 주는 실용적 시사점
이 흐름을 종합하면 프로덕션 AI 코딩 워크플로우의 실제 병목이 어디인지 선명하게 보인다. 모델의 추론 능력이 아니라, 에이전트가 코드를 보는 방식의 품질이다.
지금 당장 적용할 수 있는 레이어는 세 가지다.
- 인덱싱 레이어:
cocoindex-code같은 AST 기반 시맨틱 인덱싱을 도입해 에이전트가 의미 단위로 코드를 탐색하게 한다.pipx install cocoindex-code한 줄로 시작할 수 있다. - 컨텍스트 문서 레이어:
CLAUDE.md또는AGENTS.md를 프로젝트에 추가한다. 컨벤션, 모듈 경계, 금지 패턴을 인간이 아닌 AI를 위해 명시적으로 기술한다. 이건 문서화 비용이 아니라 에이전트 품질 투자다. - 격리와 오케스트레이션 레이어: 대규모 작업은 스코프를 나눠 병렬 에이전트로 분배한다. 같은 파일을 두 에이전트가 건드리지 않는 단순한 규칙 하나가 충돌을 막는다.
전망: 에이전트 시대의 진짜 개발자 역할
우리는 AI가 단순 자동완성을 넘어 계획하고, 리팩터링하고, 기능을 완성하는 시대에 진입하고 있다. 그 전환이 신뢰할 수 있으려면 에이전트가 코드베이스를 추측하는 것이 아니라 이해해야 한다.
Open SWE의 아키텍처가 시사하는 것은 명확하다. 에이전틱(모델 구동)과 결정론적(미들웨어 구동) 오케스트레이션의 분리, 컨텍스트를 파일로 오프로딩하는 메모리 전략, 큐레이션된 툴셋. 이 모든 것이 결국 컨텍스트 엔지니어링이라는 하나의 축으로 수렴한다.
앞으로 개발자의 핵심 역량 중 하나는 코드를 직접 짜는 것이 아니라, 에이전트가 코드를 올바르게 이해하고 작동할 수 있는 컨텍스트 구조를 설계하는 능력이 될 것이다. CLI의 부활도, AGENTS.md 패턴의 확산도 같은 방향을 가리킨다. 작고 조합 가능하고, 에이전트 친화적인 도구들이 프로덕션 워크플로우의 중심으로 이동하는 흐름은 이미 시작됐다.