같은 이름이 셋을 가리킵니다
2026년 들어 AI 쪽에서 그래프가 붙은 말이 한꺼번에 늘었습니다. 그런데 이 셋은 서로 다른 것을 그립니다. 어느 쪽이 더 좋은지 고르는 문제가 아니라, 지금 내가 막힌 지점이 어느 층인지 가려내는 문제입니다.
| 실행 그래프 | 코드 그래프 | 지식 그래프 | |
|---|---|---|---|
| 그리는 것 | 일의 진행 순서 | 코드의 구조 | 자료의 관계 |
| 노드는 | 에이전트 · 함수 · 검증기 | 함수 · 클래스 · 파일 | 엔티티 — 사람 · 제품 · 문서 |
| 엣지는 | 다음에 무엇이 도는가 | 무엇이 무엇을 부르는가 | 무엇이 무엇과 엮여 있나 |
| 답하는 질문 | “이 다음엔 누가?” | “이걸 바꾸면 뭐가 깨지지?” | “이 둘은 무슨 관계지?” |
| 대표 도구 | LangGraph · Agent Framework | CodeGraph · Serena | GraphRAG · LazyGraphRAG |
| 이 과정의 연결 | B-4 에이전트 · B-10 하네스 | B-5 MCP | 1-2 콘텍스트 |
배선이 곧 설계입니다
2026년 문헌이 Graph Engineering이라고 부를 때는 대개 이것을 가리킵니다. 여러 에이전트·함수·검증기·사람이 어떻게 맞물려 도는지를 설계하는 일입니다.
| 층 | 다루는 것 |
|---|---|
| 프롬프트 | 모델 한 번의 호출 |
| 콘텍스트 | 모델이 무엇을 보는지 |
| 에이전트 루프 | 한 에이전트가 어떻게 생각하고 도구를 쓰는지 |
| 실행 그래프 | 여러 에이전트·루프·함수·검증기·사람이 어떻게 맞물리는지 |
루프로 될 일인가, 그래프가 필요한 일인가
이 구분이 이 절의 전부입니다. 루프에서는 목표와 기준만 정하고 경로는 에이전트가 고릅니다. 그래프에서는 허용된 경로와 그 위의 검사를 내가 선언합니다.
| 루프면 충분하다 | 그래프가 필요하다 |
|---|---|
| 끝나는 지점이 하나로 분명하다 | 일이 서로 다른 전문 분야로 갈린다 |
| 단계가 자연스럽게 이어진다 | 나눠서 동시에 돌리는 이득이 있다 |
| 같은 도구 · 같은 모델로 끝난다 | 단계마다 모델 · 도구가 다르다 |
| 검증자 하나면 된다 | 다른 노드의 결과를 따로 검토해야 한다 |
| 에이전트가 자유롭게 돌아다녀도 안전하다 | 어디를 지났는지 남아야 한다 |
구성요소 — 셋, 그리고 프로덕션에서 넷 더
| 이름 | 하는 일 |
|---|---|
| 노드 | 일을 하는 단위. LLM 호출 · 도구 에이전트 · 평범한 함수 · 정책 검사 · 사람의 승인 — 모든 노드가 AI일 필요는 없습니다 |
| 엣지 | 어디로 갈 수 있는지. 직행 · 조건 · 병렬 · 되돌아가기 · 오류 · 사람 대기 |
| 상태 | 그래프를 따라 흐르는 공유 기록. 노드마다 필요한 칸만 넘깁니다 |
| 프로덕션에서 더 | 없으면 생기는 일 |
|---|---|
| 리듀서 | 병렬 결과를 합치는 규칙(이어붙이기 · 덮어쓰기 · 충돌 해소). 없으면 마지막에 끝난 놈이 이깁니다 |
| 가드 | 넘으면 안 되는 선. 단단한 제약을 프롬프트 안에 숨기면 안 됩니다 |
| 체크포인트 | 중간 저장. 실패 지점부터 재개하고, 사람 답을 기다리는 동안 멈출 수 있습니다 |
| 인터럽트 | 승인 · 검토를 받으려 실행을 멈추는 지점 |
여섯 가지 배선 패턴
| 패턴 | 모양 | 쓰는 자리 |
|---|---|---|
| 프롬프트 체이닝 | 일렬 | 단계가 고정이고 각 단계를 검증할 수 있을 때 |
| 라우팅 | 갈래 | 입력 종류에 따라 다른 전문가로 보낼 때 |
| 병렬화 | 팬아웃 · 팬인 | 서로 독립인 일을 동시에 돌릴 때 |
| 오케스트레이터 · 워커 | 중앙 분배 | 일을 쪼개 나눠주고 결과를 모을 때 |
| 평가자 · 최적화기 | 되돌아가기 | 만들고 → 평가하고 → 고치기를 반복할 때 |
| 사람 개입 | 중간 정지 | 되돌리기 어려운 행동 앞 |
조직 그래프와 작업 그래프
규모가 커지면 그래프가 두 겹으로 나뉩니다. 하나는 오래 살고, 하나는 이번 실행에서만 존재합니다.
| 구분 | 조직 그래프 | 작업 그래프 |
|---|---|---|
| 수명 | 오래 산다 — 다시 배포할 때까지 | 이번 실행 동안만 |
| 노드 | 이름과 역할이 있는 담당자 | 지금 해야 할 작업 |
| 답하는 것 | 누가 무엇을 맡나 | 지금 무엇을 해야 하나 |
| 변하는 방식 | 바꾸려면 다시 배포 | 돌면서 갈라지고 합쳐지고 취소된다 |
담당자를 고정하면 각자 자기 구역의 문맥을 쌓습니다. 인증·권한을 맡은 담당자는 그 코드를 계속 보게 되고, 스키마를 맡은 담당자는 마이그레이션 이력을 계속 봅니다. 매번 새로 쪼개는 것보다 축적이 생깁니다.
에이전트가 grep을 덜 돌리게
“이 함수를 바꾸면 뭐가 깨지나”를 에이전트는 보통 찾고 → 열고 → 또 찾고로 풉니다. 파일을 열 때마다 토큰이 나가고, 놓친 호출처는 그냥 안 보입니다.
코드 그래프는 이 작업을 미리 해둡니다. tree-sitter로 소스를 파싱해 심볼(함수·클래스·타입)과 엣지(호출·임포트·상속)를 뽑아 로컬 SQLite에 쌓고, 에이전트는 MCP로 질의합니다. 파일을 여는 대신 질문 하나를 던지는 방식으로 바뀝니다.
실습 — 붙이고 인덱싱하기
# ① 설치 npm i -g @colbymchenry/codegraph # ② 에이전트에 MCP 서버로 등록 codegraph install # ③ 초기화 + 첫 인덱싱 codegraph init -i . # ④ 인덱스 상태 확인 codegraph status
Node가 없다면 저장소의 설치 스크립트(Windows는 PowerShell install.ps1, macOS · Linux는 install.sh)를 써도 됩니다. 어느 쪽이든 codegraph 명령이 생기면 그다음은 같습니다.
인덱싱이 끝나면 CLI로도 바로 물어볼 수 있습니다. 에이전트는 같은 것을 MCP 도구로 부릅니다.
codegraph query renderPage # 이름으로 심볼 찾기 codegraph callers renderPage # 이걸 부르는 곳 codegraph callees renderPage # 이게 부르는 것 codegraph impact renderPage # 바꾸면 영향받는 범위 codegraph context "결제 실패 처리" # 작업 하나에 필요한 문맥 묶음
언제 그래프고, 언제 grep인가
코드 그래프는 구조를 답합니다. 글자를 답하지는 않습니다.
| 이런 질문 | 그래프 | grep · 읽기 |
|---|---|---|
| “X를 바꾸면 뭐가 깨지나” | ✓ | |
| “X는 어디 정의돼 있나” | ✓ | |
| “X를 부르는 곳이 전부 어디인가” | ✓ | |
| “이 로그 문구가 어디서 나오나” | ✓ | |
| 주석 · 문자열 내용 찾기 | ✓ | |
| 이미 연 파일 안에서 찾기 | ✓ |
수치 — 누가 잰 것인지 구분해서
| 출처 | 주장 |
|---|---|
| 도구 저장소의 자체 벤치마크 | 7개 저장소에서 툴콜 89%↓ · 토큰 69%↓ · 비용 60%↓ |
| 제3자 도구 비교 | 툴콜 58~70%↓ (측정 조건이 다름) |
| 별도 연구(Codebase-Memory, 31개 저장소) | 토큰 약 10배↓ · 툴콜 2.1배↓ |
못 하는 것
| 한계 | 내용 |
|---|---|
| 인덱스 지연 | 파일 감시가 몇백 ms 뒤에 따라옵니다. 방금 고친 파일을 곧바로 질의하면 옛 결과가 나옵니다 |
| 정적 분석의 벽 | 런타임 동적 디스패치 · 리플렉션 · DI 컨테이너 · 프레임워크 관례 진입점은 못 따라갑니다 |
| 의미 검색이 아님 | “인증 비슷한 거 어디 있지” 같은 질문에는 답하지 못합니다. 이름과 구조로만 찾습니다 |
| 파일 크기 | 기본적으로 1MB를 넘는 파일은 건너뜁니다 |
한 번에 못 찾는 답
벡터 검색은 비슷한 문단을 찾아옵니다. 그래서 답이 문서 하나에 들어 있으면 잘합니다. 반대로 두세 다리를 건너야 나오는 질문에는 약합니다 — “이 부품을 납품하는 회사가 작년에 문제를 일으킨 적 있나” 같은 것입니다.
지식 그래프는 자료를 엔티티와 관계로 미리 정리해 둡니다. 관계가 명시된 엣지가 되기 때문에 여러 다리를 건너 따라갈 수 있고, 지나온 경로가 남습니다.
| 벡터 검색 (RAG) | 지식 그래프 | |
|---|---|---|
| 잘하는 질문 | 문서 하나에 답이 있는 것 | 여러 다리를 건너야 하는 것 |
| 만드는 시간 | 며칠 | 몇 주 |
| 설명 가능성 | 낮음 — 왜 그 문단이 나왔는지 불분명 | 높음 — 지나온 경로가 보임 |
| 유지 비용 | 문서 재색인 | 스키마 · 엔티티 관리 |
| 실제로는 | 둘 중 하나를 고르기보다 겹쳐서 씁니다 — 벡터로 넓게 긁고, 그래프로 이어 붙입니다(GraphRAG) | |
비용이 발목을 잡았다가, 풀렸습니다
2024년 Microsoft가 GraphRAG를 내놓으며 관심이 몰렸지만, 큰 데이터셋 인덱싱에 3만 3천 달러가 드는 비용 때문에 대부분의 팀에게는 그림의 떡이었습니다. 이후 이 비용 문제를 푸는 연구가 이어졌습니다.
| 지표 | 내용 |
|---|---|
| 인덱싱 비용 | LazyGraphRAG는 벡터 RAG와 같은 수준 — 풀 GraphRAG의 0.1% |
| 글로벌 질의 비용 | 비슷한 품질에서 풀 GraphRAG 대비 700배 저렴 |
| 정확도 | 그래프 구조를 얹어 벡터 단독 대비 정답 정밀도 최대 35% 개선 보고 |
| 환각 | 단순 벡터 검색 대비 40% 이상 감소 보고 |
| 전망 | Gartner — 2028년까지 기업 AI 에이전트 시스템의 50% 이상이 그래프 기반 컨텍스트를 쓸 것 |
세 가지만 묻습니다
위에서부터 물어보고 처음 “예”가 나오는 곳에서 멈춥니다. 셋 다 아니면 지금은 그래프가 필요한 상황이 아닙니다.
막힌 게 순서인가?
일이 전문 분야로 갈리고, 누가 무엇 다음에 도는지를 내가 정해야 한다면 → 실행 그래프. 아직 한 갈래로 끝난다면 루프로 두세요.
막힌 게 코드 구조인가?
에이전트가 파일을 여닫느라 토큰을 태우고 영향 범위를 놓친다면 → 코드 그래프. 문자열·주석을 찾는 일이라면 grep이 여전히 낫습니다.
막힌 게 자료의 관계인가?
답이 문서 하나에 없고 두세 다리를 건너야 나온다면 → 지식 그래프. 단일 문서 질문이라면 벡터 검색이 더 싸고 빠릅니다.
실습 — 내 일을 분류해 보기
지금 하는 일 중 AI에게 시켰다가 잘 안 됐던 것 세 가지를 떠올려 아래에 넣고 물어보세요.
아래 세 가지 일을 각각 분류해줘. 1) (일 하나) 2) (일 하나) 3) (일 하나) 분류 기준: - 실행 그래프 — 여러 전문 단계로 갈리고 순서·검사를 내가 정해야 한다 - 코드 그래프 — 코드의 호출·영향 범위를 찾느라 시간이 든다 - 지식 그래프 — 답이 여러 자료에 흩어져 있고 관계를 따라가야 한다 - 해당 없음 — 프롬프트나 단순 루프로 충분하다 각각에 대해 (1) 어디에 해당하는지 (2) 그렇게 본 이유 한 줄 (3) "해당 없음"이면 대신 무엇을 손봐야 하는지 알려줘. 과하게 그래프로 몰지 말고, 애매하면 "해당 없음"으로 판단해줘.
- 세 가지 그래프가 각각 무엇을 그리는지 한 문장으로 말할 수 있다
- 루프로 될 일과 그래프가 필요한 일을 구분할 수 있다
- 코드 그래프가 답하지 못하는 질문을 두 가지 말할 수 있다
- 벡터 검색이 지식 그래프보다 나은 경우를 말할 수 있다
- 내 일 세 가지를 분류했고, 그중 몇 개가 “해당 없음”인지 안다