에이전트를 켜는 것과 에이전트를 운영하는 것은 다른 문제다. 대부분의 팀이 Claude Code나 Cursor를 도입한 뒤 멈추는 지점이 여기다. 도구는 설치했고, 코드도 나온다. 그런데 세션마다 컨텍스트가 흔들리고, 에이전트가 건드리면 안 되는 파일을 건드리고, 토큰 카운터는 택시 미터처럼 올라간다. 이건 도구의 문제가 아니라 운영 레이어를 설계하지 않은 결과다.
레이어 1: 컨텍스트 설계 — CLAUDE.md
dev.to의 실전 가이드가 정확하게 짚는다. CLAUDE.md 없는 Claude Code 세션은 매번 '콜드 스타트'다. 에이전트는 코드를 읽을 수 있지만, 코드 밖에 있는 것들—Next.js 15인지 14인지, db/migrations/는 절대 손대면 안 된다는 규칙, 팀의 커밋 컨벤션—은 추론하지 못한다. 그래서 매 태스크마다 조금씩 다르게 설명하고, 출력은 조금씩 다르게 드리프트된다.
CLAUDE.md는 이 반복을 끊는다. 프로젝트 루트에 두는 마크다운 파일 하나가 매 세션의 출발점을 고정한다. /init 명령으로 초안을 생성할 수 있지만, 진짜 가치는 '에이전트가 뭘 틀리는지 확인하며 계속 다듬는 것'에서 나온다. 내용은 짧고 구체적이어야 한다. 스택과 버전, 디렉토리 구조, 빌드/테스트 명령, 절대 건드리면 안 되는 경로. 여기에 불필요한 설명을 채울수록 모든 상호작용에 세금이 붙는다.
실제로 CLAUDE.md의 품질은 수천 번의 세션에 걸쳐 복리로 작용한다. 이걸 가장 먼저 설계해야 하는 이유다.
레이어 2: 권한 제어 — AgentPerms
컨텍스트를 잘 설계했어도, 에이전트가 ~/.ssh/id_rsa를 읽거나 DROP TABLE users를 실행할 수 있는 권한을 그대로 갖고 있다면 운영 레이어는 절반만 완성된 것이다. dev.to에서 AgentPerms를 공개한 개발자는 MCP를 통해 에이전트에게 파일 접근, PR 생성, DB 쿼리 권한을 준 뒤 이 사실을 직시했다. 에이전트는 sudo를 가지고 있었고, 아무도 그걸 투표로 결정하지 않았다.
AgentPerms가 취하는 접근 방식은 단순하다. record → infer → lock → replay → enforce. 에이전트가 실제로 무엇을 하는지 먼저 기록하고, 그 행동에서 최소 권한 정책을 자동으로 도출한다. 정책을 손으로 쓰는 게 아니라 실제 동작에서 추론하는 것이다. 투명한 stdio 프록시로 에이전트와 MCP 서버 사이에 끼어들기 때문에 에이전트 측 수정이 필요 없다.
더 중요한 건 CI/CD 통합이다. mcp.policy.yaml과 mcp.lock을 커밋하면 에이전트의 권한이 버전 관리되는 보안 아티팩트가 된다. 툴 설명이나 스키마가 바뀌면 빌드가 실패한다. 프롬프트 인젝션이나 툴 포이즈닝 공격이 사용자에게 도달하기 전에 차단된다. 이건 '나중에 보안 리뷰하겠다'는 약속이 아니라, 지금 당장 파이프라인에 박아두는 구조다.
레이어 3: 토큰 효율 — CodeGraph
컨텍스트가 정확하고 권한이 제한되어도, 에이전트가 큰 코드베이스를 탐색할 때 grep과 파일 읽기를 반복하며 토큰을 소진하는 문제는 별개로 남는다. CodeGraph는 이 구조적 낭비를 겨냥한 MCP 서버다. 코드베이스 전체를 시맨틱 그래프로 사전 인덱싱해두고, 에이전트가 "auth 미들웨어가 어디 있지?"를 물으면 grep 47번 대신 한 번의 쿼리로 정확한 파일 경로와 라인 번호를 반환한다.
dev.to의 실측 리뷰에 따르면 잘 구조화된 프로젝트에서 탐색 호출 수가 74% 감소했다. 레거시 Flask 모놀리스처럼 동적 생성 경로가 많은 프로젝트에서는 47% 감소에 그쳤다—인덱싱 시점에 존재하지 않는 파일은 그래프에 없기 때문이다. 이게 CodeGraph의 실질적 한계다. 빠른 TDD 사이클에서 파일이 자주 생성·삭제된다면 20~30분마다 재인덱싱이 필요하다.
일일 AI 에이전트 사용자에게는 5분 설치 비용이 첫 세션에서 회수된다. 주 1회 사용자라면 오버헤드가 이점을 넘는다. 사용 빈도에 따라 도입 여부를 판단하면 된다.
세 레이어를 하나의 질문으로 묶으면
이 세 가지—CLAUDE.md, AgentPerms, CodeGraph—는 각각 다른 도구지만, 하나의 질문에 답한다. AI 에이전트를 프로덕션 워크플로우에 어떻게 안전하고 효율적으로 붙이는가.
컨텍스트 설계 없이는 에이전트의 출력이 세션마다 드리프트된다. 권한 제어 없이는 에이전트가 프로덕션 시스템에 대한 통제권을 조용히 갖게 된다. 토큰 효율 없이는 컨텍스트 윈도우가 탐색 비용으로 소진되며 정작 중요한 추론에 쓸 공간이 줄어든다. 세 레이어는 독립적으로 보이지만 실제 운영에서는 서로 보완한다.
에이전트를 켜는 것은 시작이다. 팀이 진짜 설계해야 하는 건 그 이후다. 컨텍스트 파일 하나, 권한 정책 하나, 인덱스 하나—이 세 가지를 코드베이스에 커밋하는 순간, 에이전트는 매번 새로 길들여야 하는 도구에서 운영 가능한 시스템으로 바뀐다.