AI 코딩 에이전트가 grep 대신 타입화된 그래프 쿼리를 사용해야 하는 이유

실용적 조언

agentmako와 같은 MCP 서버를 설치하여 Claude Code나 Cursor에 연결하라.
CLAUDE.md 파일에 'grep 사용 전 context_packet 또는 cross_search를 먼저 호출하라'는 지침을 추가하라.

섹션별 상세

기존의 grep 방식은 인간에게는 유용하지만 AI 에이전트에게는 막대한 토큰 낭비를 초래한다. 에이전트는 검색 결과에서 실제 소스 코드와 테스트 코드, 문서, 바이너리 파일을 구분하지 못해 모든 결과를 읽어야 하며, 이는 불필요한 턴 소모와 컨텍스트 윈도우 압박으로 이어진다. 실제 사례에서 verifySession 검색 시 6개의 결과 중 4개가 노이즈였으며, 이를 처리하기 위해 수천 개의 토큰이 낭비되는 현상이 확인됐다.

grep은 배럴 재내보내기(Barrel Re-exports)나 동적 임포트와 같은 복잡한 의존성 구조를 추적하지 못한다. 에이전트가 특정 함수의 영향 범위를 파악할 때 단순 문자열 매칭에 의존하면 재내보내기 뒤에 숨겨진 호출처를 놓치게 되어 불완전한 리팩터링을 수행할 위험이 크다. 이를 해결하기 위해 파일 의존성 그래프를 직접 탐색하는 imports_impact와 같은 도구가 필요함이 강조됐다.

bash

auth_path({ route: "/api/manager/onboarding", verb: "POST" })
→ {
  guards: ["lib/auth/dal.ts:resolveManagerScope:142"],
  routeFile: "app/api/manager/onboarding/route.ts",
  tablesTouched: ["manager_district", "onboarding_state"],
  rlsState: "enforced",
}

단순 텍스트 검색 대신 경로와 메서드를 통해 관련 가드, 파일, DB 테이블 정보를 한 번에 가져오는 타입화된 쿼리 예시

bash

imports_impact({ filePath: "lib/users/queries.ts" })
→ 47 dependents, including:
- 11 via barrel: lib/users/index.ts
- 3 via generated SDK: packages/sdk/users.ts
- 33 direct named imports

특정 파일의 의존성을 분석하여 배럴 재내보내기나 생성된 SDK를 포함한 모든 영향 범위를 파악하는 예시

프레임워크의 라우팅 규칙이나 데이터베이스 스키마와 같은 고차원적인 맥락 파악에 grep은 부적합하다. 특정 API 경로의 핸들러를 찾기 위해서는 프레임워크의 컨벤션을 이해해야 하며, DB 컬럼의 사용처를 찾을 때는 단순 문자열이 아닌 읽기/쓰기 작업을 구분해야 한다. agentmako는 route_trace나 schema_usage 도구를 통해 단 한 번의 쿼리로 핸들러 위치와 관련 DB 테이블 정보를 구조화된 형태로 제공한다.

에이전트에게 필요한 것은 더 빠른 grep이 아니라 타입화된 그래프 노드를 반환하는 검색 인터페이스이다. 모든 검색 결과는 함수 선언인지 호출인지 등의 타입 정보를 가져야 하며, 결과 간의 연결 관계(임포트 그래프 등)를 포함하여 에이전트가 추가 검색 없이도 탐색을 이어갈 수 있어야 한다. 이러한 방식은 에이전트가 결과를 추측하는 데 드는 토큰을 줄이고 캐시 효율성을 높이는 결과를 가져온다.

용어 해설

모델 컨텍스트 프로토콜(Model Context Protocol (MCP)): — AI 모델이 외부 도구, 데이터 소스 및 서비스와 표준화된 방식으로 상호작용할 수 있도록 Anthropic에서 공개한 개방형 프로토콜이다. 이를 통해 에이전트는 로컬 파일 시스템이나 데이터베이스 등에 직접 접근하여 필요한 정보를 효율적으로 가져올 수 있다.
추상 구문 트리 검색(ast-grep): — 단순 텍스트 매칭이 아닌 코드의 구조적 의미를 분석하는 추상 구문 트리(AST)를 기반으로 코드를 검색하는 도구이다. 변수명이나 함수 호출 패턴 등 코드의 문법적 역할을 이해하여 검색하므로 일반적인 grep보다 정확도가 높다.
컨텍스트 윈도우(Context Window): — AI 모델이 한 번에 처리할 수 있는 텍스트 데이터의 최대 범위를 의미한다. 불필요한 검색 결과가 이 윈도우를 채우면 비용이 증가하고 모델의 추론 성능이 저하되므로 효율적인 정보 주입이 중요하다.
배럴 재내보내기(Barrel Re-export): — 여러 모듈의 내보내기를 하나의 인덱스 파일로 모아서 다시 내보내는 소프트웨어 개발 패턴이다. 단순 텍스트 검색(grep)으로는 실제 소스 위치를 추적하기 어렵게 만들어 에이전트의 코드 분석을 방해하는 요인이 된다.

언급된 도구

agentmako추천링크

AI 에이전트를 위한 MCP 기반의 타입화된 코드 검색 및 컨텍스트 제공 도구

ripgrep중립

매우 빠른 텍스트 검색 도구로, 에이전트의 기본 검색 수단으로 쓰임

ast-grep추천

추상 구문 트리를 기반으로 코드 구조를 검색하는 도구

언급된 리소스

GitHubagentmako npm page