Graft란? AI 코딩 에이전트의 코드 탐색 시간을 줄여주는 오픈소스 도구

AI 코딩 에이전트로 기능을 개발하거나 오류를 수정할 때는 관련 파일을 찾고, 함수 호출 관계를 따라가며 프로젝트 구조를 파악하는 과정이 반복됩니다. 

프로젝트 규모가 커질수록 탐색에 드는 시간도 늘어납니다. 같은 저장소라도 새 작업을 시작할 때마다 비슷한 파일을 다시 읽어야 해, 불필요한 토큰 사용으로 이어질 수 있습니다.

이 문제를 줄이기 위해 코드베이스의 구조와 관계를 그래프로 정리하는 오픈소스 도구 ‘Graft’가 개발됐습니다. 

이 글에서는 Graft의 주요 특징과,사용 방법, 사용시 주의사항 등에 대해 살펴보겠습니다.

Graft 핵심 요약

• 코드베이스를 연결된 문서 그래프로 정리합니다. 기능, API, 주요 모듈의 역할과 연결 관계를 Markdown 노드로 만들어 에이전트가 필요한 정보를 빠르게 찾도록 돕습니다.
• 기본 구조 분석은 로컬에서 실행됩니다. Tree-sitter 기반으로 함수, 클래스, 호출 관계를 분석하는 기본 그래프는 API 키나 LLM 호출 없이 만들 수 있습니다.
• 원하는 AI 에이전트에 연동해 작업할 수 있습니다. 코드의 역할을 자연어로 요약하고 핵심 로직을 추출하는 심화 분석은 사용자가 선택한 AI 모델을 사용해 진행합니다.
• 코드 변경 범위를 먼저 파악할 수 있습니다. 특정 함수나 파일을 수정하기 전에 연결된 호출부와 의존 관계를 확인해, 수정 영향 범위를 검토하는 데 활용할 수 있습니다.

Graft란?

* 이미지 출처: Graft 공식 Github 저장소

Graft는 AI 코딩 에이전트가 새 작업을 시작할 때마다 프로젝트를 처음부터 다시 탐색하는 과정을 줄이기 위해 개발된 오픈소스 도구입니다. 

파일과 함수가 어떤 역할을 하는지, 어떤 코드에 의존하는지, 변경 시 어느 기능까지 영향을 받을 수 있는지를 연결 관계로 정리합니다.

Graft는 코드를 벡터 데이터베이스에 저장하는 대신, 에이전트가 읽을 수 있는 연결형 Markdown 문서와 함수·호출 관계 정보로 코드베이스 그래프를 만듭니다. 

이를 통해 Graft를 사용하는 AI 코딩 에이전트는 관련 파일을 무작정 검색하기보다, 기능과 연결된 코드부터 확인하며 프로젝트 문맥을 파악할 수 있습니다.

Graft가 주목받는 이유

1. 매 작업마다 반복되는 코드 탐색을 줄일 수 있습니다

Graft는 AI 에이전트가 매번 파일을 처음부터 찾는 대신, 미리 만든 코드 지도를 참고하도록 돕습니다.

AI 코딩 에이전트는 기능을 수정하기 전 파일을 검색하고, import 관계를 따라가며, 관련 테스트를 다시 찾는 과정을 거칩니다. 작은 프로젝트에서는 큰 문제가 아니지만, 여러 서비스와 모듈이 연결된 저장소에서는 탐색 자체가 작업의 상당 부분을 차지할 수 있습니다.

Graft는 주요 시스템과 API, 개념을 노드로 정리하고 노드 사이의 관계를 연결합니다. 에이전트가 “로그인 후 토큰은 어디에서 생성되는가”처럼 질문을 받았을 때, 관련 파일을 무작정 열기보다 인증 흐름과 연결된 코드를 먼저 파악할 수 있게 하는 방식입니다.

2. 별도의 벡터 데이터베이스 없이 코드 문맥을 관리할 수 있습니다

Graft는 코드 구조를 프로젝트 내부의 연결된 Markdown 파일로 저장해, 별도 서버나 검색 인덱스를 관리하지 않아도 됩니다.

코드 문맥을 AI 에이전트에 제공하려면 일반적으로 외부 검색 시스템이나 벡터 데이터베이스를 구축해야 하는 경우가 많습니다. Graft는 함수·클래스·호출 관계를 로컬 그래프로 만들고, 에이전트가 일반 파일을 읽듯 필요한 정보를 찾게 합니다. 또한 작업 중인 코드가 바뀌면 현재 작업 폴더를 기준으로 구조를 다시 확인합니다. 

커밋하지 않은 변경 사항도 그래프 갱신 대상에 포함되므로, 오래된 문서를 참고해 잘못된 파일을 수정하는 문제를 줄이는 데 도움이 됩니다.

3. 수정 전에 영향 범위를 확인할 수 있습니다

Graft는 특정 함수나 파일을 수정했을 때 함께 점검해야 할 코드 범위를 찾는 데 활용할 수 있습니다.

예를 들어 인증 토큰 생성 함수를 바꾸면 로그인 API뿐 아니라 미들웨어, 오류 처리, 관련 테스트에도 영향이 갈 수 있습니다. Graft는 호출 관계와 의존성을 바탕으로 연결된 코드 위치를 보여줘, 수정 대상과 검증 범위를 함께 판단하도록 돕습니다.

덕분에 여러 서비스와 모듈이 연결된 프로젝트에서 변경과 연결된 기능을 먼저 살펴볼 때 유용하게 활용할 수 있습니다.

Graft 사용법

Graft는 설치 과정에서 일부 코드 분석 모듈을 빌드하기 위해 C++ 개발 환경이 필요할 수 있습니다. C++ 빌드 도구가 설치되지 않은 경우, 사용하는 운영체제에 맞춰 먼저 설치해야 합니다.

• macOS: Xcode Command Line Tools를 설치합니다.
  xcode-select --install

• Linux: Ubuntu·Debian 계열에서는 build-essential 패키지를 설치합니다.

  sudo apt update

  sudo apt install -y build-essential

• Windows: Visual Studio Build Tools를 설치한 뒤, 설치 항목에서 C++를 사용한 데스크톱 개발을 선택합니다.

2. Graft를 설치합니다

터미널에 위 명령어를 입력해 Graft를 설치합니다. 설치가 완료되면 added 41 packages라는 문구가 표시되며, Graft 실행에 필요한 패키지가 함께 설치됩니다.

제대로 설치됐는지 확인하기 위해 위의 명령어를 입력해 Graft를 실행합니다. 사용 가능한 옵션과 명령어 목록이 표시됐으므로 실행 환경까지 준비된 상태를 볼 수 있습니다.

AI 코딩 에이전트로 Graft 사용하는 방법

AI 코딩 에이전트에서 Graft를 사용하려면 먼저 연동할 AI 코딩 에이전트를 설정해야 합니다. 위 명령어를 입력한 뒤 목록에서 사용할 AI 코딩 에이전트를 선택합니다. 

Claude Code부터 Windsurf까지 Graft가 지원하는 AI 코딩 에이전트와 연동할 수 있습니다. 방향키로 원하는 에이전트 항목으로 이동한 뒤 스페이스바를 눌러 선택합니다.

Codex를 연결하려면 목록에서 agents 항목을 선택하면 됩니다.

연동을 완료하면 설치 목록에 이어 위의 이미지와 같은 화면이 나옵니다. 그러면 이제 

Graft 활용 테스트

Graft가 코드 관계를 바탕으로 필요한 문맥을 좁혀 주는지 확인하기 위해, 동일한 주문 취소 프로젝트에서 오류 원인 탐색과 수정 영향 범위 확인 테스트를 진행했습니다. 두 테스트는 Graft 미적용 환경과 적용 환경에서 같은 질문으로 실행했습니다.

1. 환불 완료 이메일 오류 원인 탐색 테스트

결제 대행사 타임아웃으로 환불이 보류됐는데도 환불 완료 이메일이 발송되는 원인을 찾는 테스트입니다.

주문 취소 처리, 환불 상태 저장, 이메일 제목 선택 로직이 여러 파일에 나뉘어 있어 관련 코드를 찾아 연결 관계를 확인해야 합니다.

테스트 상황

결제 대행사 타임아웃이 발생하면 환불 상태는 refund_pending으로 저장됩니다. 그러나 고객에게는 ‘주문 취소와 환불이 완료되었습니다’라는 제목의 이메일이 발송됩니다. 이메일이 잘못 선택되는 직접 원인을 찾아야 합니다.

테스트 프롬프트

결제 대행사 타임아웃이 발생한 주문에서 환불은 보류됐는데, 고객에게 환불 완료 이메일이 발송됐습니다. 이 이메일이 잘못 발송되는 직접 원인은 무엇인가?

Graft 미적용 결과

Graft 적용 결과

두 환경 모두 같은 원인을 찾았지만, Graft를 적용한 환경에서는 관련 함수의 연결 관계를 먼저 좁힌 뒤 필요한 코드 문맥을 확인했습니다. 

이 과정에서 Graft는 7회 호출 기준 약 6,276토큰의 코드 문맥을 절감한 것으로 표시됐습니다. 여러 파일에 나뉜 오류 원인을 분석할 때 Graft를 사용하면 코드베이스 전체를 다시 읽기보다, 관련 코드부터 탐색할 수 있습니다. 

2. 수정 영향 범위 확인 테스트

이메일 제목 선택 조건을 수정하기 전에, 함께 확인해야 할 운영 코드와 테스트 범위를 찾는 테스트입니다.

오류가 발생한 함수만 수정하면 다른 처리 흐름이나 기존 테스트와 충돌할 수 있습니다. 변경 대상 함수와 연결된 이메일 발송 흐름, 주문 취소 흐름, 회귀 테스트 범위를 함께 확인해야 합니다.

테스트 상황

환불 상태가 refund_completed일 때만 환불 완료 이메일 제목을 선택하도록 수정하려고 합니다. 이 변경이 영향을 주는 운영 코드와 테스트 파일을 확인해야 합니다.

테스트 프롬프트

환불 상태를 기준으로 취소 이메일 제목을 고치려면 selectCancellationTemplate 변경의 영향을 받는 운영 코드와 테스트는 무엇인가?

Graft 미적용 결과

Graft 적용 결과

두 환경 모두 같은 수정 대상과 테스트 범위를 찾았습니다. 다만 Graft를 적용한 환경에서는 이메일 템플릿 함수부터 이메일 발송, 주문 취소 흐름, API 진입점, 단위·통합 테스트까지의 관계를 연결된 범위로 정리했습니다. 

이 과정에서 Graft는 2회 호출 기준 약 815토큰의 코드 문맥을 절감한 것으로 표시됐습니다. 

수정 전 영향 범위를 확인할 때 Graft를 사용하면 특정 함수와 연결된 호출 흐름과 테스트를 함께 살펴볼 수 있어, 변경 대상과 회귀 검증 범위를 더 구체적으로 판단하는 데 도움이 됩니다. 

3. 코드 관계 그래프 확인

Graft는 옵시디언처럼 코드 요소 사이의 관계를 그래프로 보여줍니다. Graft가 파일과 함수의 연결 관계를 어떻게 정리하는지 살펴보겠습니다. 

그래프 확인 방법

프로젝트 폴더에서 위의 명령어를 실행합니다.

그래프 확인 결과

Graft를 사용하면 코드 검색 결과만 나열하는 데 그치지 않고, 파일·함수·테스트 사이의 포함 관계와 참조 관계를 그래프로 확인할 수 있습니다. 여러 모듈이 연결된 프로젝트에서 수정 전 영향 범위를 빠르게 파악할 때 유용합니다.

Graft 주요 명령어

Graft 사용 시 주의사항

1. 초기 설정 전에는 변경되는 파일을 먼저 확인하세요

Graft를 초기화하면 프로젝트 규칙 파일뿐 아니라 Codex의 사용자 설정과 훅 파일이 함께 변경될 수 있습니다.

Codex 연동을 선택하면 AGENTS.md에 Graft 지침이 추가되고, 경우에 따라 사용자 폴더의 ~/.codex/config.toml과 hooks.json에도 MCP 서버와 훅 설정이 등록됩니다. 이 설정은 현재 프로젝트뿐 아니라 이후 사용하는 다른 프로젝트에도 영향을 줄 수 있으므로, 설치 전 변경 목록을 확인하는 것이 좋습니다.

2. 생성된 그래프가 팀원에게 자동으로 공유되지 않습니다

Graft가 만든 graft/ 폴더는 기본적으로 Git에 포함하지 않는 로컬 캐시입니다. 그래프를 만들었다고 해서 다른 팀원의 저장소에 같은 그래프가 자동으로 생기지 않습니다. 팀원이 프로젝트를 새로 내려받거나 그래프가 없어진 경우에는 각자 graft build를 실행해야 합니다.

따라서 팀 도입 시에는 Graft 연동 설정을 공유할지, 각 개발자가 그래프를 생성하는 절차를 문서화할지 함께 정해두는 것이 좋습니다. 

3. 그래프 결과만 믿고 코드를 수정하면 안 됩니다

Graft는 코드 구조를 파악하는 도구이지, 변경 결과의 정확성을 보장하는 도구는 아닙니다.

지원 언어와 분석 방식에 따라 호출 관계를 추적하는 수준이 달라질 수 있습니다. 동적 호출, 리플렉션, 프레임워크 내부 동작처럼 정적 분석만으로 확인하기 어려운 구조도 존재합니다.

Graft가 제시한 관련 파일과 영향 범위는 작업의 출발점으로 활용하고, 실제 수정 전에는 원본 코드와 테스트, 실행 결과를 함께 확인해야 합니다.

AI 에이전트 코딩 노하우가 궁금하다면

Ponytail 사용법: AI 코딩 에이전트의 과잉 구현을 줄이는 스킬 실행하기

ECC란, Anthropic 해커톤 우승자가 만든 AI 에이전트 하네스 활용법

OpenWiki 사용법: 코드베이스를 AI 에이전트의 지식 저장소로 만들기

AI 에이전트 기반 개발 환경 구축,

검증된 IT 프리랜서와 시작하세요.

대한민국 최대 IT 프리랜서 매칭 플랫폼 이랜서

이랜서는 27년간 삼성 · 현대 · SK · 카카오 등 주요 기업에 매칭하며 축적한 8만 건 이상의 IT 프리랜서 매칭 데이터를 바탕으로, AI 에이전트 시스템 구축 경험과 클라우드 실무 역량을 갖춘 검증된 전문가를 매칭합니다.

단순 이력서 연결이 아닌, 프로젝트 성격과 기술 스택, 활용 모델, 협업 방식까지 고려한 정밀 매칭으 98%의 재의뢰율을 달성하고 있습니다.

AI 에이전트 기반 개발 환경을 기획부터 구축, 운영 자동화까지 안정적으로 추진하세요. 프로젝트에 적합한 AI 전문 프리랜서를 24시간 내, 매칭해 드립니다.