trailhq/Trail-Code

Trail(이전 명칭 Graft) – 코드베이스를 인식하는 어시스턴트 헬퍼

그것이 무엇인가 – Trail은 리포지토리의 가볍고 로컬한 "그래프"를 구축하는 TypeScript/Node.js CLI입니다. 그래프는 짧고 평이한 영어 요약, 핵심 코드 발췌(핵심), 개념 간의 유형화된 링크를 포함하는 마크다운 파일로 구성됩니다. 이 그래프를 Claude Code, Cursor, Codex, Gemini 또는 LLM 기반 "코딩 어시스턴트"와 같은 코딩 에이전트에 연결함으로써 Trail은 에이전트가 프로젝트 구조를 이미 인식한 상태로 세션을 시작할 수 있게 하여 일반적으로 토큰, 도구 호출 및 대기 시간을 소모하는 비용이 많이 드는 "재탐색" 단계를 피합니다.

왜 중요한가 – 일반적인 AI 코딩 어시스턴트는 모든 새 작업을 코드베이스를 본 적이 없는 것처럼 취급합니다. 반복적으로 grep하고, 파일을 열고, 가져오기를 추적하여 토큰 사용량을 늘리고 응답 속도를 늦춥니다. Trail은 그 이해를 한 번 캡처하여 로컬에 저장하고 에이전트의 프롬프트에 주입합니다. README는 정확성 손실 없이 최대 4배 저렴하고 3배 빠른 실행을 주장하며, SWE-bench 벤치마크에서 정확도가 측정 가능할 정도로 향상된다고 합니다.

주요 기능

• 일회성 그래프 구축(graft init / trail init)은 tree-sitter로 소스 파일을 구문 분석하고(모델 없음, API 키 없음), 선택적으로 파일당 한 번 언어 모델을 실행하여 사람이 읽을 수 있는 요약을 생성합니다.
• 마크다운 노드: 각 노드에는 요약, 가장 관련성 높은 코드 줄, 소스 파일 해시, wikilink 스타일의 유형화된 엣지(depends_on, uses 등)가 포함됩니다.
• 로컬 캐시: graft/ 폴더는 .gitignore에 추가됩니다. 작은 배선 파일(.claude/, AGENTS.md)만 커밋됩니다.
• 자동 최신성: 답변하기 전에 도구가 파일 해시를 확인하고 변경된 부분만 다시 구축하므로 에이전트는 커밋되지 않은 편집이 있어도 항상 현재 작업 트리 상태를 볼 수 있습니다.
• 에이전트 통합: Claude Code(심층 통합)에 대한 내장 지원 및 다른 에이전트를 위한 일반 MCP 서버 훅.
• CLI 유틸리티 – graft ask, graft grep, graft map, graft viz, graft check로 그래프를 검색, 시각화, 검증할 수 있습니다.
• 다중 리포지토리 / 모노레포 지원 및 광범위한 언어 커버리지(TS/JS, Python, Go, Java, Rust, C/C++ 등 23개 언어).
• 공급자에 구애받지 않는 LLM 사용 – 요약 단계에 OpenAI, Anthropic, OpenRouter, Groq, LiteLLM 또는 로컬 모델을 자체 API 키로 연결할 수 있습니다.

일반적인 워크플로우

1. CLI를 설치합니다(npm i -g @trailhq/trail 또는 npm i -g @nanonets/graft).
2. trail init(또는 graft init)을 실행합니다 – 사용하는 에이전트를 선택하면 도구가 graft/ 디렉토리와 배선 파일을 생성합니다.
3. 다음에 Claude Code 세션을 시작하면 Trail이 관련 노드 요약을 프롬프트에 주입하므로 모델은 훨씬 적은 도구 호출로 답변할 수 있습니다.
4. 각 코딩 세션 후에 수정한 내용은 .trail/learnings/ 아래에 "학습 내용"으로 저장됩니다. 이는 향후 세션에서 에이전트가 자동으로 적용하는 규칙이 됩니다.
5. PR 전에 trail check가 기존 학습 내용과 충돌하는 변경 사항을 표시합니다.

벤치마크(보고된 대로)

• 콜드 vs. Graft(Claude Code): 도구 호출 46% 감소, 토큰 42% 감소, 대기 시간 60% 감소, SWE-bench에서 정확도 12포인트 향상(54% → 66%).
• 비용: 작업당 $0.029 vs. $0.042(약 32% 저렴).

누가 사용할까 – LLM 기반 코딩 어시스턴트에 크게 의존하고 API 비용을 줄이고 응답 속도를 높이며 기관 지식(팀별 결정, 패턴, 수정 사항)을 리포지토리에 직접 캡처하려는 개발 팀.

---

TL;DR: Trail(이전 명칭 Graft)은 코드베이스의 사람이 읽을 수 있는 마크다운 기반 지식 그래프를 구축하고 이를 AI 코딩 에이전트에 연결하여 반복적인 코드 탐색을 줄이고 토큰과 시간을 절약하며 팀 학습 내용을 향후 세션을 위해 유지하는 CLI입니다.