왜 AI 에이전트는 구조화된 코드 지능이 필요한가 (파서 관리 방식을 어떻게 멈출 것인가)

코드를 다루는 AI 에이전트를 구축할 때, 파싱 레이어는 아키텍처 다이어그램에 거의 나타나지 않지만, 실제로는 나타날 필요가 있습니다. 에이전트가 만나는 모든 언어에는 파서가 필요합니다. 각 파서는 고유한 문법 형식, 컴파일 도구 체인, 그리고 오류 복구 주변의 고유한 특징을 가지고 있습니다. 파이썬, TypeScript, Go를 다루는 코딩 에이전트를 구축할 때, 단일 줄의 에이전트 로직을 작성하기 전에 이미 세 가지 별도의 파싱 의존성을 유지하고 있습니다. Rust, Java, Ruby를 추가하면, 인프라 문제 disguised as dependency management problem (의존성 관리 문제로 포장된) 의존성 관리 문제가 발생합니다. 이것이 코드 인식 AI 시스템에 대한 보이지 않는 세금입니다. 이 블로그는 이를 가시화하고 tree-sitter-language-pack이 인프라 레이어에서 이를 제거하는 방법을 보여줍니다.

파서 세금 nobody budgets for (누구나 예산을 책정하지 않는)
대부분의 코드 인식 에이전트는 파싱을 두 가지 방식으로 처리합니다: 소스 파일을 평문 텍스트로 처리하거나, 언어별 파싱 라이브러리를 하나씩 추가합니다. 평문 텍스트 chunking은 작동하지 않을 때까지 작동합니다. 파이썬 파일을 고정된 토큰 경계에서 분할하고, 함수를 절반으로 잘라내거나, import 를 사용하는 코드와 분리하며, 의미 있는 컨텍스트가 없는 chunk 를 모델에게 전달합니다. 모델이 회복할 수 있지만, 때로는 회복하지 못할 수도 있습니다. 규모가 커지면 "때로는"은 "자주 하지 않는"이 됩니다.

언어별 파서들은 문법적 문제를 해결하지만 운영적 문제를 만듭니다. Python 의 문법, JavaScript 의 다른 문법, Go 의 또 다른 문법, 그리고 그 외입니다. 각기 고유한 빌드 프로세스, 버전 관리, 실패 모드를 가지고 있습니다. 팀과 프로덕션 파이프라인에서 이를 관리할 때, 큰 headache 입니다.

결과적으로 대부분의 팀은 일관성 없는 파서 커버리지, 적절한 통합이 되지 않은 언어를 위한 workarounds, 그리고 문법 의존성이 동기화되지 않을 때 깨지는 코드를 얻습니다.

왜 AST-aware chunking 이 다른가
Abstract Syntax Tree 는 코드를 의미 있는 단위의 나무로 표현합니다: 함수, 클래스, import, 블록, 문장입니다. AST-aware chunking 은 그 구조를 사용하여 임의적인 경계가 아닌 실제 경계에서 코드를 분할합니다. 실용적 차이는 큽니다. 함수는 전체로 남습니다. import 는 연결됩니다. 클래스 메서드는 클래스 정의와 분리되지 않습니다. 모델은 코드 단위에 해당하는 chunk 를 받습니다.

Retrieval-augmented generation (RAG) 에 있어 이것이 더 중요할 수 있습니다. 개발자가 "이 코드베이스는 인증을 어떻게 처리하는가"라고 물을 때, AST-aware chunk 를 기반으로 작동하는 retriever 는 인증 함수 자체, 그리고 import 와 참조하는 타입을 함께 반환할 수 있습니다. 토큰 경계 chunk 를 기반으로 작동하는 retriever 는 창 안에 떨어진 Whatever 를 반환합니다. 첫 번째는 유용합니다. 두 번째는 모델이 받은 컨텍스트를 재구성해야 합니다.

동일한 논리는 코드 편집 에이전트, 코드 리뷰 에이전트, 그리고 코드가 무엇을 하는지 아닌 어떻게 보이는지에 대해 추론해야 하는 모든 것에 적용됩니다.

tree-sitter-language-pack 이 어떻게 도와주는가
Tree-sitter 는 Neovim, Helix, Zed, 그리고 많은 다른 에디터의 코드 지능 뒤에 있는 파싱 라이브러리입니다. 빠르고, 문법 오류에서 회복하며, AST-aware 작업에 깔끔하게 매핑되는 구체적인 syntax tree 를 생성합니다.

직접 사용하는 문제점은 각 언어마다 고유한 grammar repository 가 필요하고, 이는 별도로 컴파일되고 관리되어야 한다는 것입니다.
tree-sitter-language-pack 은 305 language grammars 를 뒤에서 감싸고 있습니다.

단일 의존성과 통합된 API 를 제공합니다. 파서 (Parsers) 는 필요 시에 로드되고 로컬에서 캐시되므로, 모든 것을 미리 컴파일하지 않습니다. process() API 는 구조화된 출력을 반환합니다: 함수, 클래스, 임포트, 주석, 그리고 인덱싱 또는 검색을 위한 AST(抽象语法树) 인지된 조각들 (chunks). 다음은 Python 에서의 모습입니다:

from tree_sitter_language_pack import process
result = process("path/to/file.py")
for chunk in result.chunks:
print(chunk.type) # "function", "class", "import_block" 등
print(chunk.content) # 실제 코드
print(chunk.metadata) # 언어, 줄 범위, 부모 스코프

코드 에이전트나 RAG 파이프라인 (Retrieval-Augmented Generation) 을 위한 경우, 처리하는 언어가 무엇이든 상관없이 파싱 단계는 동일하게 보입니다. Rust 파일에서 얻은 구조화된 출력 형식과 TypeScript 파일에서 얻은 형식은 같습니다. 다운스트림 리트리버 (retriever), 컨텍스트 어셈블리 로직, 조각 랭킹 — 어떤 것들도 처리하는 언어를 알 필요가 없습니다.

12 개의 생태계는 Rust, Python, Node.js, Go, Java, Ruby, Elixir, PHP, C#, WASM, CLI, 그리고 C FFI 를 포함합니다. 혼용된 코드베이스 (mixed-language codebase) 의 내부 툴링을 구축하는 팀이나 임의의 언어로 코드를 제출해야 하는 플랫폼을 위한 경우, 이는 취약한 다중 라이브러리 설정을 단일 임포트로 대체합니다.

단일 의존성의 운영적 수학 (operational math)
코드 인식을 가진 RAG 나 코드 에이전트를 프로덕션 환경에서 실행하는 팀의 경우, 언어별로 파서를 관리하는 것에서 하나의 의존성을 관리하는 것으로 전환할 때 운영적 수학이 바뀝니다.

단일 MIT 라이선스 패키지를 통해 305 개의 언어를 지원한다는 것은 법적 및 보안 검토가 한 번만 이루어집니다. 의존성 업데이트는 한 곳에서 추적됩니다. 문법 (grammar) 이 패치될 필요가 있을 때, 그것은 하나의 패키지 업데이트로 끝납니다. 보통은 6 개 문법 포크 (forks) 를 가로지르는 교차 저장소 추적을 하지 않습니다.

많은 언어의 코드를 수용하는 플랫폼 — 경쟁 프로그래밍 도구, 코드 리뷰 인프라 구조, 내부 개발자 포털 — 의 경우, 이전 접근 방식은 파서가 관리되어 작동했는지 기반으로 "지원되는" 언어를 결정했습니다. tree-sitter-language-pack 을 사용하면 지원되는 집합에는 305 개의 언어가 포함되며 계속 성장합니다.

지원해야 할 언어에 대한 결정이 아니라, 구조화된 출력으로 무엇을 구축할지에 대한 결정입니다.

요구성 캐싱 모델도 규모 (scale) 에서 중요합니다. 파서들은 필요할 때만 로드되므로, 주로 Python 을 처리하는 배포는 304 개의 다른 문법을 RAM 에 로드하는 메모리 비용을 부과하지 않습니다.

Kreuzberg 와 tree-sitter-language-pack 의 교점
Kreuzberg 는 이미 97 개의 파일 형식을 처리합니다: PDF, DOCX, HTML, OCR 처리된 이미지, 스프레드시트, 그리고 더 많은 것들입니다.

디자인 철학은 일관성 있고, 입력 형식에 관계없이 구조화된 출력 — Kreuzberg 를 사용하는 에이전트는 형식별 로직을 작성하지 않으며, 모든 문서 유형에 대해 동일한 출력 형식을 사용합니다.
tree-sitter-language-pack 은 소스 코드로 이를 확장합니다.

Kreuzberg 를 사용하여 코드베이스의 문서, 스펙 파일, README 를 처리하는 에이전트는 이제 동일한 구조화된 파이프라인을 통해 코드 자체를 처리할 수 있습니다.

출력 형식은 일관성 있고, 의존성 스토리 (dependency story) 는 일관성 있습니다.

에이전트는 "이것은 문서인가, 아니면 소스 코드인가?"라고 의문을 품지 않아도 됩니다.

문서와 코드의 지능을 함께 구축하는 팀 — API 스펙과 구현을 모두 이해하는 에이전트나 내부 문서를 구현하는 함수에 연결하는 도구를 생각해보세요 — 두 시스템이 단일 레이어로 작동하기 시작하는 곳입니다.

Kreuzberg Cloud 는 완전히 인프라 측면을 처리할 것입니다 (spin by spin).

문서 및 코드 처리 파이프라인을 팀이 자체적으로 실행하거나 유지보수할 필요 없이 확장하고 관리합니다. 규모를 구축하며 패서 인프라 (parser infrastructure) 를 전혀 생각하지 않으려는 경우, 이것이 그 길입니다. 패서 인프라 (parser infrastructure) 는 프로토타입에서는 작게 보이지만 프로덕션에서는 증폭되는 문제입니다. 그것은