Trail-Code
무엇인가
Trail-Code는 코딩 에이전트가 저장소를 매번 다시 탐색하지 않도록 코드베이스 구조를 파일 그래프로 만들어 두는 CLI다. 에이전트 자체가 아니라 에이전트와 저장소 사이에 놓이는 컨텍스트 계층이며, Graft(코드 그래프)와 Trail(세션 학습 기록) 두 부분으로 나뉜다.
어떻게 동작하나
`graft init`은 코드를 분석해 `graft/` 디렉터리에 시스템·API·개념 단위의 마크다운 노드를 만들고 노드끼리 링크로 연결한다. 각 노드는 함수 이름 목록이 아니라 그 부분이 무엇을 하고 어떻게 연결되는지를 평문으로 설명한다. 임베딩, 유사도 검색, 벡터 DB를 쓰지 않으며 에이전트는 다른 저장소 파일을 읽듯 노드를 열고 grep하고 링크를 따라간다. 구조 그래프는 결정적 tree-sitter 파싱으로 만들어져 모델을 호출하지 않고, 노드 요약문만 사용자가 지정한 제공자(OpenAI, Anthropic, OpenRouter, Fireworks, Groq, OrcaRouter, LiteLLM 프록시, 로컬 모델)의 키로 생성한다.
무엇과 다른가
질의할 때마다 그래프를 워킹 트리 기준으로 먼저 다시 만들기 때문에 커밋하지 않은 편집까지 반영된 현재 상태를 설명한다. 변경이 없으면 약 3ms에 끝나고 비용이 들지 않는다. `graft/`는 `.gitignore`에 자동 추가되는 로컬 재생성 캐시로 node_modules와 같은 성격이고, 저장소에 커밋하는 것은 `graft init`이 `.claude/`, `AGENTS.md`, MCP 설정에 심는 배선뿐이다. 팀원은 각자 `graft build`로 자기 그래프를 만든다.
어떻게 쓰나
Trail 쪽은 세션에서 알아낸 결정과 배제한 선택, 주의점을 `.trail/learnings/`에 기록하고 변경과 함께 커밋한다. 다음 세션은 해당 코드를 파기 전에 그 기록을 먼저 받는다. 반복해서 어기는 규칙은 무시되는 노트가 아니라 차단 훅으로 바뀐다. PR 전에 `trail check`가 변경과 팀 학습 기록을 비교해 어긋나는 부분을 표시하며, 로컬에서 실행되고 로그인이 필요 없다.
전제와 한계
설치 후 첫 명령은 `graft init`이다. 어떤 코딩 에이전트를 연결할지 묻고 `graft/`를 만든 뒤 `.claude/`에 상태라인과 훅을 심는다. `--dry-run`으로 건드릴 파일을 먼저 확인하고 `--agents claude`로 프롬프트를 건너뛸 수 있으며, 전역 설치를 피하려면 `npx @nanonets/graft init`을 쓴다. Claude Code에서는 매 턴 뒤 백그라운드로 그래프가 갱신되고 다른 에이전트는 MCP 서버로 연결한다. 조회 명령은 `graft grep`, `graft map`, `graft callers`, `graft skeleton`, `graft check`, `graft viz`다. 구조 그래프 생성과 `graft check`는 모델이나 API 키 없이 동작하지만 노드 요약문 생성에는 선택한 제공자의 키가 필요하고, Node.js 실행 환경이 전제다. 데몬이나 서버, 데이터베이스를 두지 않고 그래프는 파일로만 존재하며, 모노레포와 여러 저장소를 담은 폴더를 다룬다. 지원 언어 목록은 README의 Supported languages 절에 있고, README는 SWE-bench Verified 기준 최대 4배 저렴하고 3배 빠르다고 밝힌다.