에이전트를 돌리는 것과 에이전트를 잘 돌리는 것 사이의 간격은, 생각보다 구조적이다. 토큰 청구서가 예상보다 두 배 나왔다면, 에이전트가 같은 파일을 세 번 읽었기 때문일 가능성이 높다. 답이 틀렸다면, 컨텍스트 없이 grep으로 추측했기 때문일 가능성이 높다. 이 두 문제는 모델의 문제가 아니다. 에이전트를 둘러싼 구조의 문제다.
구조 없는 에이전트는 매 세션마다 제로에서 시작한다
dev.to에 공개된 GraphPilot 사례는 이 문제를 숫자로 보여준다. Claude Sonnet으로 300개 파일 규모의 Node.js 프레임워크(fastify)에 40개 구조적 질문을 던졌을 때, 파일 직접 읽기 방식은 2,796,760 토큰과 $8.88을 소비했다. GraphPilot—tree-sitter로 레포를 파싱해 함수·클래스·호출 관계를 그래프로 색인한 로컬 MCP 서버—을 붙이자 1,088,276 토큰, $3.68로 줄었다. 61% 절감이고, 정답률은 33/40에서 37/40으로 오히려 올라갔다.
핵심은 간단하다. 에이전트는 구조적 질문—"이 함수를 누가 호출하는가?", "이걸 바꾸면 뭐가 깨지는가?"—에 매번 파일을 다시 읽어 답한다. 세션 간 기억이 없기 때문이다. GraphPilot은 이 구조적 메모리를 외부화한다. 그래프가 미리 색인되어 있으면 에이전트는 파일을 열 필요 없이 노드와 엣지를 조회한다. "who calls X?" 유형 질문에서 토큰이 82% 줄고, 변경 영향 분석에서 73% 줄었다는 수치는 이 구조 차이의 직접적인 결과다. 단, 미들웨어를 따라가는 플로우 트레이싱처럼 코드를 실제로 읽어야 하는 질문에서는 효과가 미미하다고 저자는 직접 밝힌다. 이 정직함이 오히려 신뢰할 만한 수치라는 증거다.
에이전트 하네스: 구조화의 다섯 계층
GraphPilot이 "레포 구조"를 외부화한 사례라면, dev.to의 하네스 엔지니어링 글은 에이전트를 둘러싼 설정 전체를 계층별로 정의한다. 하네스(harness)란 날 모델과 실제 작업 사이에 놓이는 모든 구성의 총합이다. "모델이 옳아 보이는 코드를 썼다"와 "에이전트가 우리가 신뢰할 수 있는 코드를 배포했다" 사이의 거리가 하네스 설계의 품질이다.
계층은 다섯 개다. 모델 하네스는 Claude Code, Cursor, Copilot 같은 도구 선택 자체다—설정 여지가 가장 적고 제품 의견이 가장 강하다. 에이전트 하네스는 ~/.claude/CLAUDE.md처럼 개인이 레포를 옮겨다닐 때 함께 따라오는 전역 설정이다. 테스트 철학, 파일 삭제 전 확인 요청 같은 개인 습관이 여기 들어간다. 프로젝트 하네스는 레포 루트의 CLAUDE.md, 서브디렉토리별 컨텍스트 파일, 프로젝트 레벨 MCP 서버다. 조직 하네스는 여러 레포에 걸친 보안 베이스라인, 공유 룰 라이브러리, 내부 서비스 MCP다. 대부분의 팀이 이 계층을 아직 만들지 않았다. 오케스트레이션 하네스는 여러 에이전트를 조합하는 플릿 레벨이다.
이 구조에서 실수가 가장 많이 나는 지점은 계층 혼동이다. 특정 레포에서만 유효한 규칙이 전역 에이전트 설정에 올라가거나, 모든 레포에서 반복해야 하는 규칙이 프로젝트 파일에 묻혀 있다. 더 큰 문제는 프로젝트 하네스의 부패다. 코드는 변하는데 이를 설명하는 CLAUDE.md가 갱신되지 않으면, 에이전트는 3개월 전 지도로 지금 도시를 안내한다. 하네스는 만드는 것보다 유지하는 것이 더 어렵다.
컨텍스트 파일: '왜'를 설계하는 일
세 번째 사례는 Claude 프로젝트 파일 설계 방법론이다. 핵심 통찰은 단순하다. 프로젝트 파일에 들어가야 하는 것은 코드 패턴이나 파일 구조가 아니다—에이전트는 코드를 직접 읽을 수 있다. 들어가야 하는 것은 코드 뒤에 있는 결정의 맥락이다: 왜 이 라이브러리를 선택했는가, 왜 이 방향으로 리팩터링하고 있는가, 지금 어떤 제약이 에르고노믹스보다 컴플라이언스를 우선시하게 만드는가.
"문을 열지 마시오"라는 표지판은 무시하기 쉽다. "문을 열지 마시오—지난번에 연 사람이 소화 시스템을 작동시켰다"는 무시하기 어렵다. Why 필드가 있어야 에이전트가 새로운 엣지 케이스에서 규칙을 맹목적으로 따르지 않고 원래 의도를 추론할 수 있다. 그리고 이 Why 필드는 나중에 해당 결정이 여전히 유효한지 판단하는 기준이 된다. 컨텍스트 파일은 작성이 아니라 갱신이 핵심이다.
세 사례가 공통으로 가리키는 것
그래프 색인, 하네스 계층, 컨텍스트 파일—세 가지는 서로 다른 수단이지만 같은 질문에 답하고 있다: 에이전트가 매 세션마다 다시 발견하지 않아도 되도록, 무엇을 어디에 저장할 것인가.
토큰 비용은 이 질문에 대한 답이 얼마나 좋은지를 직접적으로 나타낸다. 에이전트가 이미 알 수 있는 것을 다시 읽으면 비용이 나간다. 알아야 하는 것을 모르면 품질이 깨진다. 두 문제 모두 구조 설계로 해결된다—모델 교체로 해결되는 문제가 아니다.
팀에 적용할 수 있는 실행 순서
지금 당장 내일 써먹을 수 있는 순서로 정리하면 이렇다. 첫째, 프로젝트 CLAUDE.md가 없다면 만들어라—단, 코드 패턴이 아니라 결정의 이유를 쓰는 것으로 시작해라. 둘째, 에이전트가 같은 구조적 질문을 반복하고 있다면 GraphPilot 같은 로컬 색인 도구 도입을 검토해라—TypeScript/JavaScript 레포라면 오늘 바로 측정 가능하다. 셋째, 팀 레포가 두 개 이상이라면 조직 하네스 계층을 설계하라—보안 베이스라인과 공통 룰이 레포마다 중복되고 있다면, 그 비용은 지금도 조용히 쌓이고 있다.
모델은 계속 강해진다. 하지만 더 강한 모델이 구조 없는 루프 위에서 돌면, 더 빠르게 더 많은 비용을 낭비한다. 에이전트 ROI의 천장은 모델 성능이 아니라 에이전트를 둘러싼 구조의 품질이 결정한다.