아프니까 개발자다

이 이름이 가리키는 진짜 그곳 — 코드 심볼을 구문에서 의미로 풀어내기

타이젠 개발자, 윤진 — Mon, 6 Jul 2026 23:00:07 +0900

배경: "이름"은 생각보다 모호하다

코드를 읽다가 process라는 함수를 만났다고 하자. 나는 자연스럽게 묻게 된다. "이 process는 도대체 어디에 정의돼 있지? 그리고 누가 이걸 호출하지?"

IDE에서는 함수 이름을 Ctrl 누르고 클릭하면 정의로 점프(go-to-definition)하고, 오른쪽 클릭으로 "모든 참조 찾기(find-references)"를 누른다. 너무 당연해서 마법처럼 느껴지지도 않는다. 그런데 이 마법을 여러 저장소(repo)에 걸쳐, 수많은 파일에서, 사람 없이 자동으로 해내려고 하면 갑자기 매우 어려운 문제가 된다.

핵심은 이렇다. 소스 코드에서 process라는 글자(텍스트)는 그냥 일곱 글자일 뿐이다. 이 글자가 가리키는 진짜 대상(심볼, symbol — 코드 안에서 이름이 붙은 정의 단위)이 무엇인지는 글자만 봐서는 알 수 없다. 같은 이름이 프로젝트 안에 수십 개 있을 수 있고, 그중 단 하나만이 "지금 이 자리의 process"가 가리키는 진짜 정의다. 이 글은 그 "글자 → 진짜 대상" 연결을, 그리고 몇 번째 줄에 있는지 라인 단위로 찾아내는 길을 따라가 본 학습 정리다.

문제: 글자만 봐서는 진짜를 못 짚는다

가장 소박한 방법 — grep

"process가 어디 있나 찾아줘"라고 하면 가장 먼저 떠오르는 건 grep이다. 파일 전체에서 process라는 글자를 모조리 찾아 나열한다. 빠르고 단순하다.

문제는 grep이 글자만 본다는 것이다. 의미를 모른다. 비유하자면, 전화번호부에서 "김민수"를 검색했더니 동명이인이 40명 나오는 상황이다. 내가 찾는 김민수가 누구인지 전화번호부는 모른다. 코드에서도 똑같은 일이 벌어진다.

동명 함수(같은 이름, 다른 정의): 결제(payments) 모듈의 process()와 이미지(imaging) 모듈의 process()는 완전히 다른 함수인데 grep은 둘 다 토해낸다.
재export(re-export — A 파일이 B의 함수를 가져와 다시 내보내는 것): 진짜 정의는 한쪽에 있는데 import 줄에도 같은 이름이 등장한다. grep은 어느 게 "진짜 집"인지 모른다.
주석·문자열 안의 단어: 주석에 적힌 process나 로그 메시지 "process failed" 속 글자까지 잡아온다.

다이어그램 설명. 같은 질문에 두 방법이 어떻게 다르게 답하는지를 보여준다. 글자 매칭 방식은 이름만 같으면 결제·이미지 모듈, 재export, 주석 속 단어까지 전부 후보로 올려놓고 "이 중 하나일 거예요"라며 손을 든다. 반면 의미 해석 방식은 "지금 이 자리에서 보이는 범위"가 어디까지인지, 즉 스코프(scope — 이름이 유효한 영역)를 추적하고 import 경로를 끝까지 따라가서 딱 하나의 진짜 정의와 그 정확한 줄 번호를 짚어준다. 함정은, 글자 매칭은 빠른 대신 "이 중 진짜가 무엇인지"라는 가장 중요한 질문에 끝내 답하지 못한다는 점이다.

조금 똑똑한 휴리스틱도 한계

"같은 폴더 우선", "import 줄을 대충 파싱" 같은 휴리스틱(heuristic — 경험적 어림짐작)을 얹으면 grep보다는 낫다. 하지만 이건 결국 추측이다. 언어의 진짜 규칙(스코프 규칙, 모듈 해석 규칙)을 흉내 낼 뿐이라 까다로운 경우에서 틀린다. 그리고 무엇보다 "틀릴 수 있다"는 사실 자체가 문제다. "이 함수가 호출되는 모든 곳"을 안다고 주장하려면 단 하나도 놓치거나 더하면 안 되기 때문이다.

정리하면, 자동화된 코드 이해 시스템에 필요한 건 두 가지다. 첫째 정확성 — 글자가 아니라 의미로 "이 이름 = 저 정의"를 안다. 둘째 라인 앵커(line anchor) — 단순히 "그 파일에 있어요"가 아니라 "그 파일 142번째 줄, process 심볼"이라고 검증 가능한 위치를 준다. 이 두 가지가 지금부터 풀어갈 목표다.

해결: 글자 → 구문 → 의미로 한 층씩 내려간다

핵심 직관 — 깊이가 곧 정확도다

코드를 이해하는 데에는 깊이의 층위가 있다. 가장 얕은 곳이 글자다 — grep이 머무는 자리, 의미를 모른다. 그 위 한 층이 구문(syntax)이다 — "이건 함수 정의이고, 이름은 process, 여기서 import가 일어난다"까지는 안다. 가장 깊은 곳이 의미(semantics)다 — "지금 이 자리의 process가 가리키는 정의는 저기, 그리고 그것을 호출하는 곳은 여기들"이라고 안다.

내가 만들고 있는 코드 위키 자동생성 시스템은 이 깊이를 단계적으로 내려가도록 짜여 있다. 먼저 구문을 다언어 구문 파서로 뽑고, 그다음 파이썬에 한해 의미까지 풀어낸 뒤, 그 결과를 검증 가능한 그래프로 굳힌다. 핵심 발상은 질문할 때마다 즉석에서 분석하지 말고, 한 번 결정적으로 분석해 그래프 DB로 구워두자는 것이다.

다이어그램 설명. 이 글 전체이자 내 시스템의 파이프라인을 한 줄로 요약한다. 글자 매칭은 의미를 모르고 동명 심볼을 혼동한다. 구문 파싱 단계가 함수·모듈·import를 구조로 뽑아내고, 다시 의미 해석 단계가 "이 함수를 누가 부르는가"라는 호출 관계를 풀어낸다. 마지막으로 그 결과를 라인 앵커가 달린 그래프 DB로 굳혀, 누가 언제 물어도 검증 가능한 답을 즉시 내준다. "글자"에서 "검증된 의미"로 나아가며, 함정은 구문을 안다고 해서 의미까지 아는 것은 아니라는 점이다 — 구조를 아는 것과 이름이 무엇을 가리키는지 아는 것은 다른 층위다.

Stage A — 구문 파서로 함수·모듈·import를 뽑는다 (tree-sitter)

첫 단계는 코드의 구문 구조를 뽑는 것이다. 여기서 쓰는 도구가 tree-sitter다. tree-sitter는 소스 코드를 빠르게 파싱해 문법 구조(구문 트리)를 만들어주는 다언어 파서다. 내 시스템은 이걸로 각 소스 파일을 훑어 함수 정의, 모듈, 그리고 모듈 사이의 import 의존(DEPENDS_ON) 관계를 추출한다.

tree-sitter를 고른 이유는 여러 언어를 같은 방식으로 다룰 수 있어서다. 내 시스템은 파이썬뿐 아니라 타입스크립트(TypeScript), 자바스크립트(JavaScript), C#, PHP, C용 문법까지 같은 추출기로 처리한다. 언어마다 "무엇을 함수로 볼 것인가"만 따로 지정해주면(예: 파이썬은 함수 정의, 타입스크립트는 함수 선언과 메서드 정의), 나머지 골격은 공유된다. 단, tree-sitter는 여기까지만 한다 — "이 process 호출이 어느 정의를 가리키는지"라는 의미 해석은 tree-sitter의 일이 아니다. 그건 다음 단계의 몫이다.

Stage B — 파이썬 의미를 풀어 호출 관계를 만든다 (jedi)

두 번째 단계는 파이썬 코드에 한해 의미까지 내려간다. 여기서 쓰는 도구가 jedi다. jedi는 파이썬 전용 정적 분석 라이브러리로, IDE 자동완성·정의 점프의 엔진으로 널리 쓰인다. 내 시스템은 Stage A가 찾아둔 함수 하나하나에 대해, jedi에게 "이 함수의 정의가 여기 있다, 그리고 이 이름이 쓰이는 모든 곳을 찾아줘"라고 물어본다.

구체적으로는 jedi의 정의 점프(goto)로 함수 정의 위치를 확정한 뒤, 참조 찾기(get_references)로 그 함수가 호출·사용되는 모든 지점을 받아온다. 그리고 각 참조 지점이 어느 함수 안에 들어 있는지를 역으로 찾아, "부른 쪽(caller) → 불린 쪽(callee)"이라는 호출 관계(CALLS)를 그래프에 엣지로 추가한다. 글자 매칭이 결코 줄 수 없던, 의미에 근거한 호출 그래프가 이렇게 만들어진다.

다만 정직하게 짚어둘 한계가 있다. 이 의미 해석은 파이썬에 한정되고, 호출 관계는 같은 저장소 안에서만 잇는다. 저장소 경계를 넘나드는 연결은 다른 방식(서브프로세스 호출, 알려진 포트로의 HTTP 호출 같은 신호를 구문 단계에서 잡는 식)으로 따로 다룬다. jedi는 컴파일러가 아니므로 동적 파이썬의 까다로운 부분에서는 놓치는 경우도 있고, 그래서 분석에 시간 제한을 두고 부분 실패를 허용하도록 설계했다.

그래프 DB로 결정적으로 굽는다 — 라인 앵커가 핵심

Stage A·B가 만든 노드(함수·모듈·심볼)와 엣지(호출·의존 관계)는 그래프 자료구조로 모인 뒤 디스크에 영속화된다. 내 시스템은 그래프 라이브러리(networkx)로 메모리에서 그래프를 다루고, 그걸 SQLite 파일로 저장한다. 무거운 외부 그래프 데이터베이스를 도입하는 대신, 저장소 규모(노드 수만 개)에 충분하고 다루기 쉬운 이 조합을 선택했다.

여기서 가장 중요한 두 가지 설계가 노드 ID와 라인 앵커다.

모든 노드는 저장소@커밋해시::언어::심볼경로 형태의 ID를 갖는다. 저장소가 다르거나, 같은 저장소라도 커밋이 다르거나, 심볼 경로가 다르면 ID가 달라진다. 이 ID는 그래프 DB와 벡터 검색, 그리고 위키 출력 경로를 한데 묶는 공통 정합 키 역할을 한다 — 같은 함수면 어디서든 같은 ID로 가리킬 수 있다.

그리고 위키의 모든 사실 주장에는 경로/파일.py:줄번호, 더 나아가 경로/파일.py:줄번호:심볼이름 형태의 라인 앵커가 달린다. "이 함수가 저 모듈을 호출한다"라고 문서가 주장하면, 그 주장 옆에는 "그 근거는 이 파일 이 줄, 이 심볼"이라는 검증 가능한 좌표가 따라붙는다. 검증기는 이 앵커가 실제로 그 줄에 진짜 코드(심볼)를 가리키는지 기계적으로 확인하고, 코드가 움직여 줄 번호가 어긋나면(앵커가 빈 줄이나 주석을 가리키면) 드리프트로 잡아낸다. 이 게이트가 없으면, 한때 맞았던 줄 번호가 코드 이동 뒤 거짓이 되어 미래의 분석을 오염시킨다.

효과와 한계

무엇이 가능해지나

이 파이프라인의 결과물은 한마디로 의미에 근거하고 라인 단위로 검증되는 코드 지도다. 같은 코드에서 항상 같은 그래프가 나오므로(결정적), 추출 단계에서는 추측도 환각도 끼어들 여지가 없다. 동명 함수를 ID로 구별하고, 호출 관계를 의미로 잇고, 모든 주장에 검증 가능한 좌표를 단다.

한계

의미 해석은 파이썬 전용: 구문 추출은 여러 언어를 다루지만, 호출 관계까지 푸는 의미 해석은 현재 파이썬에 한정된다. 다른 언어는 함수·모듈 골격까지만 잡힌다.
같은 저장소 안의 호출만: 저장소 경계를 넘는 정밀한 호출 관계는 의미 단계가 아니라 구문 단계의 신호로 근사한다.
정적 분석의 본질적 한계: 실행해야만 정해지는 동적 코드는 정적 분석이 일부 놓칠 수 있다. 그래서 시간 제한과 부분 실패 허용을 전제로 운영한다.
인덱스 신선도: 그래프는 "한 시점의 사진"이라, 코드가 바뀌면 언제 다시 구울지가 운영상 과제다. 변경된 저장소만 골라 다시 처리하는 방식으로 비용을 줄인다.

내 코드 위키 자동생성 시스템과의 연결

코드를 읽어 설명 문서를 자동으로 써내는 이 시스템에서, 모든 서술은 "실제로 그 코드 어디에 있는가"로 검증 가능해야 한다. "이 함수가 저 모듈을 호출한다"라고 문서가 주장하려면, 글자 매칭의 어림짐작이 아니라 의미에 근거한 정의·참조 관계가 뒷받침되어야 한다.

그래서 내 시스템은 즉석 질의 방식을 택하지 않고, 결정적으로 그래프 DB를 구워두는 길을 택했다. 구문 파서로 함수·모듈·import를 뽑고(tree-sitter), 파이썬 의미 분석으로 호출 관계를 풀고(jedi), 공통 정합 키가 달린 노드와 라인 앵커가 달린 그래프로 굳힌다. 이렇게 굳혀두면 같은 코드에서 같은 지도가 나오고, 위키의 모든 주장이 라인 앵커로 검증되며, 사실과 다른 설명을 기계적으로 걸러내는 게이트를 세울 수 있다. 이 토대가 없으면 자동 생성 문서는 "그럴듯하지만 검증 불가능한 글"에 그치고, 있으면 "코드에 단단히 묶인 신뢰할 수 있는 지도"가 된다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

이 함수를 누가 부르는가 — jedi로 호출 관계를 의미 수준에서 풀기

타이젠 개발자, 윤진 — Mon, 6 Jul 2026 21:00:55 +0900

배경: 함수 목록만으로는 "관계"를 말할 수 없다

나는 여러 코드 저장소(repo)를 읽어 설명 문서(코드 위키)를 자동 생성하는 개인 프로젝트를 만들고 있다. 첫 단계로 구문 파서를 써서 "이 저장소에 어떤 함수와 모듈이 어디에 있는가"라는 목록을 결정적으로 만들어 두었다. 함수 하나하나가 노드(node — 그래프의 마디)가 되고, "저장소가 모듈을, 모듈이 함수를 소유한다"는 포함 관계까지 그래프에 들어왔다.

그런데 위키가 정말로 유용해지려면 한 걸음 더 나아가야 한다. "이 주문 처리 핸들러가 GPU를 확보하는 함수를 호출한다" 같은 관계를 말할 수 있어야 한다. 함수가 어디 있는지 아는 것과, 그 함수가 무엇을 부르고 누구에게 불리는지를 아는 것은 다른 차원이다. 그리고 이 호출 관계가 있어야 "이 함수를 바꾸면 어디가 영향받지?" 같은 질문에 답할 수 있다.

다이어그램 설명. 구문 추출이 끝난 시점의 상태를 보여준다. 함수와 모듈의 목록은 손에 있지만, 그것들이 서로 어떻게 호출하는지를 잇는 선이 아직 없다. 그래서 "이 핸들러가 호출하는 함수들" 같은 가장 실용적인 질문에 답하지 못한다. 함정은 목록만 있어도 위키가 그럴듯해 보인다는 점인데, 정작 코드를 이해하는 데 가장 중요한 "무엇이 무엇을 부르는가"가 비어 있으면 그 위키는 절반짜리다.

문제: 같은 이름의 함수, 어느 정의를 가리키나

호출 관계를 만들려면 "이 자리의 함수 호출이 가리키는 진짜 정의"를 정확히 찾아야 한다. 이게 생각보다 어렵다. 코드에는 같은 이름의 함수가 수두룩하기 때문이다.

예를 들어 결제(payments) 모듈에도 process()가 있고 이미지(imaging) 모듈에도 process()가 있다고 하자. 어느 코드에서 process()를 호출하면, 그게 둘 중 어느 정의를 부르는 것인지는 이름만 봐서는 알 수 없다. 지금 이 자리에서 어떤 import가 일어났는지, 어떤 범위(스코프)가 보이는지를 따져야 비로소 정해진다. 이 판단을 컴파일러는 정확히 해내지만, 글자 매칭(grep)이나 구문 파싱만으로는 못 한다.

다이어그램 설명. 이름의 모호함이 어떻게 해소되는지 보여준다. 같은 process()라는 호출이 두 정의 후보를 두고 있지만, 지금 이 파일에서 무엇을 import했고 어떤 이름이 보이는지를 따지면 둘 중 하나로 확정된다. 핵심은 이 확정이 "글자가 같은가"가 아니라 "의미상 무엇을 가리키는가"의 문제라는 점이다. 함정은, 추측성 휴리스틱(예: 같은 폴더 우선)으로 대충 고르면 까다로운 경우에서 틀리는데, 호출 관계는 하나만 어긋나도 "이 함수가 영향 주는 모든 곳"이라는 주장이 깨진다.

해결: in-process 의미 분석으로 호출을 잇는다 (jedi)

왜 jedi인가 — 무거운 서버 대신 라이브러리

이 의미 해석을 위해 택한 도구가 jedi다. jedi는 순수 파이썬(pure Python)으로 된 정적 분석 라이브러리로, 많은 코드 에디터의 자동완성·정의 점프 기능을 떠받치는 엔진이기도 하다. 후보가 여럿이었지만 내 작업의 성격에 jedi가 가장 맞았다.

도구	특징	채택
jedi	순수 파이썬 라이브러리(~15MB). 별도 프로세스 없이 코드 안에서 직접 호출. 정확도 중상.	채택
풀 타입 검사기	정확도는 최상이지만 다른 런타임(Node.js) 의존 + 100MB대. 배치 추출엔 과함.	거절
언어 서버 데몬	별도 프로세스를 띄우고 통신해야 함. 관리 부담과 왕복 지연.	거절
구문 질의(tree-sitter)	가장 빠르지만 이름 해석이 없어 "어느 정의를 부르는지"를 못 짚는다.	거절

표 설명. 같은 일(호출 관계 추출)을 두고 네 가지 길을 비교한 것이다. 정확도만 보면 무거운 타입 검사기가 앞서지만, 사람 없이 밤마다 여러 저장소를 통째로 훑는 배치 작업에는 "다른 런타임을 깔고 100MB대 도구를 띄우는" 비용이 과했다. 별도 프로세스로 떠야 하는 언어 서버도 같은 이유로 부담이었다. 핵심은 "내 코드 안에서 함수처럼 바로 부를 수 있고(in-process), 의존성이 가볍고, 정확도가 충분한" 지점을 고른 것 — 그게 jedi였다. 함정은 가벼움을 택한 대가로 동적인 코드에서 일부 호출을 놓친다는 점인데, 이는 뒤에서 다룬다.

어떻게 호출 관계를 만드나

방법은 직관적이다. 구문 추출 단계가 찾아둔 함수 하나하나에 대해 jedi를 두 번 부른다. 첫째, 그 함수의 def 위치를 가리켜 "이게 바로 이 함수의 정의다"라고 jedi 기준으로 확정받는다(정의 확정, goto). 이건 정의를 어딘가에서 새로 찾는 게 아니라, 우리가 이미 아는 그 자리를 jedi가 인정하는 정확한 기준점(줄·칸)으로 못 박는 단계다. 둘째, 그 기준점에서 "이 함수가 쓰이는 모든 곳을 찾아 달라"고 요청한다(참조 찾기, get_references). 그런 다음 각 참조가 어느 함수 안에서 일어났는지를 역으로 찾아, "부른 쪽(caller) → 불린 쪽(callee)"이라는 호출 관계(CALLS)를 그래프에 엣지로 추가한다.

다이어그램 설명. 함수 하나로부터 호출 관계가 만들어지는 흐름이다. 정의를 확정하고, 그 이름이 쓰인 자리를 모두 모은 뒤, 각 자리가 어느 함수 안에 들어 있는지를 거슬러 올라가 "누가 이 함수를 불렀는지"를 알아낸다. 핵심은 "사용처 → 그 사용처를 감싼 함수"라는 역추적이다 — 이게 있어야 단순한 "여기서 쓰임"이 "이 함수가 저 함수를 호출함"이라는 방향 있는 관계로 승격된다. 함정은 참조 중에 정의 그 자체나 자기 자신 호출이 섞여 들 수 있다는 점인데, 그런 경우는 걸러내고 진짜 호출만 남긴다.

다이어그램 설명. 완성된 호출 관계가 그래프에서 어떤 모양인지 보여주는 작은 예시다. 주문 처리 핸들러가 GPU를 확보하는 함수와 응답을 직렬화하는 함수를 호출한다는 사실이, 방향 있는 두 개의 선으로 표현된다. 이런 선이 수천 개 모이면 "이 함수를 바꾸면 어디가 흔들리는가"를 따라갈 수 있는 지도가 된다. 핵심은 이 선들이 글자 매칭의 추측이 아니라 의미 해석으로 확정된 사실이라는 점이다.

일부러 보수적으로 — false positive 금지

중요한 원칙이 하나 있다. 파이썬은 매우 동적인 언어라, 실행 중에야 정해지는 호출(이름을 문자열로 조립해 부르거나, 데코레이터로 감싸거나 하는 경우)은 정적 분석이 다 잡지 못한다. 그래서 명시적으로 "놓치는 건 허용하되, 틀리게 잇는 건 금지"라는 정책을 택했다. jedi가 확신하지 못하면 차라리 엣지를 안 박는다.

다이어그램 설명. 정보의 신뢰도에 층위가 있다는 것을 보여준다. 구문 추출은 같은 코드면 같은 결과라 가장 믿을 수 있고, 의미 해석은 호출 관계까지 풀어내지만 동적인 코드 앞에서는 일부를 놓칠 수 있어 한 단계 낮다. LLM 서술은 가장 유연하지만 환각이 섞일 수 있어 별도 검증이 필요하다. 핵심은 "틀리게 잇느니 차라리 빠뜨린다"는 보수적 태도다 — 빠진 호출은 나중에 보강하면 되지만, 거짓 호출은 위키의 신뢰 자체를 무너뜨리기 때문이다.

같은 저장소 안의 호출만

의미 해석으로 잇는 호출 관계는 같은 저장소 안으로 한정했다. 저장소 경계를 넘나드는 연결(다른 서비스의 포트를 호출하거나 다른 프로젝트의 스크립트를 부르는 경우)은 의미 해석이 아니라 구문 단계에서 잡은 신호로 따로 다룬다. 함수 단위의 정밀한 의미 해석을 저장소 경계 너머까지 밀어붙이는 건 비용 대비 이득이 적다고 보고 범위를 좁혔다.

효과: 무엇이 가능해졌나

호출 그래프: "어느 함수가 어느 함수를 부르는가"가 의미 수준에서 그래프에 들어왔다. 스무 개 남짓의 저장소에서 약 3천 개의 호출 관계가 단 몇십 초 만에 추출됐다.
영향 범위 추적: "이 함수를 바꾸면 어디가 영향받지?"를 호출 관계를 따라 답할 수 있다.
가벼움: 별도 프로세스(데몬)도, 다른 런타임도 필요 없다. 내 파이썬 코드 안에서 함수처럼 바로 부른다. 구문 단계가 만들어 둔 함수 목록을 받아 참조만 조회하므로, 파일을 새로 훑는 비용도 없다.
신뢰할 수 있는 엣지: 보수적 정책 덕분에, 그래프에 박힌 호출 관계는 "확실한 것만"이다. 라인 앵커와 결합하면 호출이 일어난 자리까지 검증 가능해진다.

정직한 한계

파이썬 전용: 구문 추출은 여러 언어를 다루지만, 호출 관계까지 푸는 의미 해석은 현재 파이썬에 한정된다. 다른 언어는 함수·모듈 골격까지만 잡힌다.
동적 호출 누락: 실행해야 정해지는 호출은 놓칠 수 있다. 이는 정적 분석의 본질적 한계이고, 보수적으로 "확실한 것만" 남기는 대가다.
같은 저장소 안만: 저장소 경계를 넘는 정밀한 호출 관계는 의미 단계가 아니라 구문 단계의 신호로 근사한다.

내 코드 위키 자동생성 시스템과의 연결

코드를 읽어 문서를 자동으로 써내는 시스템에서, "이 함수가 저 함수를 호출한다"는 한 줄의 서술조차 글자 매칭의 어림짐작이 아니라 의미에 근거해야 한다. 그래야 위키가 코드의 실제 동작을 반영한다고 말할 수 있다.

그래서 내 시스템은 구문 추출(tree-sitter) 위에 의미 해석(jedi)을 한 층 더 얹었다. 구문 단계가 "어떤 함수가 어디 있는가"를 결정적으로 깔아 두면, jedi가 그 위에서 "무엇이 무엇을 부르는가"를 의미 수준으로 풀어내 호출 관계 엣지를 더한다. 무거운 언어 서버를 띄우는 대신 가벼운 라이브러리를 코드 안에서 직접 부르는 길을 택해, 사람 없이 도는 밤마다의 추출 작업에 딱 맞췄다. 구문이 코드의 뼈대라면, 의미 해석은 그 뼈대에 흐르는 핏줄을 그려 넣는 일이다 — 이 둘이 합쳐져야 비로소 "코드에 단단히 묶인, 따라가며 읽을 수 있는 지도"가 완성된다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

언어가 하나 늘 때 코드를 고치지 않으려면 — 표준 tags.scm 쿼리로 다언어 추출하기

타이젠 개발자, 윤진 — Sun, 5 Jul 2026 22:00:42 +0900

배경: 한 언어로 시작했지만, 여러 언어를 다뤄야 했다

나는 여러 코드 저장소(repo)를 읽어 설명 문서(코드 위키)를 자동 생성하는 개인 프로젝트를 만들고 있다. 그 첫 단계는 코드에서 "어떤 함수와 모듈이 어디에 있는가"를 뽑아내는 추출기다. 처음엔 대상 저장소가 전부 파이썬이라, 추출기도 파이썬 한 언어 전용으로 충분했다.

그런데 다루는 저장소가 늘면서 본체가 타입스크립트(TypeScript)·C#·PHP·C·자바스크립트(JavaScript)인 코드까지 들어왔다. 이런 저장소는 파이썬 파일이 거의 없어서, 파이썬 전용 추출기로는 함수·모듈이 하나도 안 잡힌다. 그러면 그 저장소의 위키는 텅 비게 된다. "모든 저장소에 위키"를 만들려면, 추출기가 이 언어들의 함수·모듈도 담아야 했다.

문제: 언어를 늘릴 때마다 코드가 불어나면 안 된다

가장 손쉬운 방법은 "언어별로 갈래를 나누는 것"이다. 파이썬이면 이렇게, 타입스크립트면 저렇게, C#이면 또 다르게… 이른바 조건 분기(if/elif)로 처리하는 방식이다. 처음 한두 언어는 그럭저럭 굴러간다. 하지만 언어가 늘수록 갈래가 곱절로 늘고, 각 갈래마다 비슷한 추출 코드가 복사되어 붙는다.

다이어그램 설명. 조건 분기 방식이 언어가 늘 때 어떻게 커지는지 보여준다. 파일이 어떤 언어인지 차례로 묻고, 맞으면 그 언어 전용 추출 코드로 들어간다. 문제는 새 언어를 지원할 때마다 질문 갈래가 하나 더 붙고, 그 아래에 또 한 벌의 추출 코드가 복사된다는 점이다. 함정은 이 복사된 코드들이 거의 비슷하다는 데 있다 — 한 곳에서 버그를 고치면 나머지 갈래에도 똑같이 고쳐야 하고, 빠뜨리면 언어마다 동작이 달라진다.

정리하면 필요한 건 이것이다. 언어는 얼마든지 늘리되, 추출기 코드 자체는 거의 손대지 않는 구조. 그리고 가능하면, 이런 일을 위해 이미 널리 쓰이는 표준 방식이 있다면 그걸 따르는 게 낫다.

해결: 언어별 "무엇이 함수인가"를 표준 쿼리(tags.scm)로 선언한다

핵심 직관 — 다른 점은 데이터로, 그 데이터의 표준 형식을 쓴다

핵심 발상은 단순하다. 언어마다 실제로 다른 것은 결국 "이 언어에서 무엇을 함수·메서드 정의로 볼 것인가"뿐이고, 나머지 절차(파일을 파싱해 트리를 만들고, 정의를 골라 이름과 줄 범위를 읽는 일)는 모든 언어가 똑같다. 그렇다면 다른 부분만 데이터로 선언하고 같은 절차는 하나의 공통 엔진으로 두면 된다.

그런데 이 "무엇이 함수인가"를 선언하는 일에는 이미 널리 쓰이는 표준 형식이 있다. tree-sitter의 tags.scm 쿼리다. tags.scm은 각 언어 문법이 "이런 모양의 마디는 함수 정의, 저런 모양은 클래스 정의, 이건 호출"이라고 선언해 둔 쿼리 파일이다. 각 언어 문법 패키지에 표준으로 동봉되며, 깃허브(GitHub)의 코드 내비게이션 같은 도구들이 바로 이 tags.scm으로 심볼을 찾는다.

비유하자면 만능 리모컨과 같다. 리모컨 본체(추출 엔진)는 하나이고, "기기별 신호 코드표"(언어별 tags.scm 쿼리)만 갈아 끼운다. 더구나 이 코드표는 업계 표준 규격이라, 대부분의 언어는 코드표가 이미 만들어져 동봉돼 있다.

다이어그램 설명. 표준 쿼리 방식의 전체 그림이다. 언어마다 표준 tags.scm 쿼리가 따로 있고, 모든 쿼리가 가운데의 같은 엔진으로 흘러 들어간다. 조건 분기 방식과의 결정적 차이는, 언어가 늘어도 엔진 코드에 갈래가 생기지 않고 그 언어의 표준 쿼리를 끼우기만 한다는 점이다. 핵심은 "무엇이 함수인가"를 코드가 아니라 표준 데이터(쿼리)로 표현했다는 것 — 엔진은 그 쿼리를 실행할 뿐이다.

tags.scm 쿼리는 무엇을 선언하나

tags.scm의 한 패턴은 "이런 모양의 마디를 찾아, 그 전체와 이름을 표시(캡처)하라"는 규칙이다. 예를 들어 파이썬의 함수 정의 규칙은 (function_definition name: (identifier) @name) @definition.function 한 줄로 표현된다. 풀어 읽으면 "함수 정의 마디를 찾아 그 전체를 @definition.function으로, 그 안의 이름을 @name으로 표시하라"는 뜻이다.

다이어그램 설명. 쿼리 한 줄의 속을 펼쳐 보면 세 가지를 담는다. 어떤 모양의 마디를 찾을지, 그 정의 전체를 어디에 표시할지(시작·끝 줄을 읽는 데 씀), 그 이름을 어디에 표시할지다. 핵심은 이름 추출까지 쿼리가 책임진다는 점이다 — 예전에는 "C는 이름이 선언자 안쪽에 숨어 있으니 따로 파고들자" 같은 특수 코드를 내가 짜야 했는데, 이제는 그 언어의 표준 쿼리가 이름을 어디서 꺼낼지 이미 알고 있다.

엔진이 결과에서 골라내는 것

tags.scm은 함수만 선언하지 않는다. 클래스 정의, 함수 호출, 상수까지 함께 표시한다. 그래서 엔진은 쿼리 결과 중 함수·메서드 정의 표시만 골라, 그 이름과 줄 범위를 읽는다.

다이어그램 설명. 표준 쿼리를 돌리면 함수뿐 아니라 클래스·호출·상수까지 한꺼번에 표시되므로, 엔진은 그중 함수·메서드 정의에 해당하는 표시만 추려 쓴다. 핵심은 "정의 전체 표시"에서 줄 범위를, "이름 표시"에서 이름을 따로 읽어 함수 노드를 만든다는 점이다.

표준을 쓰며 부딪힌 세 가지 현실

"표준 쿼리를 그대로 쓴다"는 말처럼 깔끔하지만은 않았다. 세 가지 현실적 보정이 필요했다.

C#은 표준 쿼리가 없다: 대부분 언어는 tags.scm이 문법 패키지에 동봉돼 있는데, C#만 빠져 있었다. 그래서 C#용 tags.scm은 표준 관례를 따라 직접 한 벌 작성해 넣었다.
타입스크립트는 혼자선 부족하다: 타입스크립트의 표준 tags.scm은 타입 시그니처(본문 없는 선언)만 잡고 실제 함수 본문은 안 잡는다. 타입스크립트가 자바스크립트의 확장이기 때문인데, 그래서 표준 관례대로 자바스크립트 쿼리에 타입스크립트 추가분을 합쳐서 쓴다.

설명. 두 가지 모두 "표준을 쓰면 공짜로 다 된다"가 환상임을 보여준다. 표준은 강력하지만, 빠진 언어는 직접 채워야 하고(C#), 언어 간 상속 관계를 알아야 한다(타입스크립트). 핵심은 그럼에도 자체 규격을 고집하기보다 표준에 맞추는 편이, 장기적으로 더 적은 코드와 더 넓은 호환을 준다는 점이다.

효과: 언어 추가가 "표준 쿼리 한 줄"이 된다

다이어그램 설명. 이 설계가 주는 가장 큰 효과를 보여준다. 새 언어를 지원하려 해도 추출 엔진 코드는 한 줄도 건드리지 않고, 그 언어의 표준 쿼리를 연결하기만 하면 된다. 핵심은 "확장의 비용"이 코드 수정에서 표준 데이터 연결로 내려갔다는 점이다 — 코드를 고치지 않으니 기존에 잘 돌던 언어들이 새 언어 때문에 깨질 위험도 사라진다.

다이어그램 설명. 이 패턴이 따르는 오래된 설계 원칙을 그림으로 옮긴 것이다. 위쪽은 "확장에는 열려 있다" — 언어별 표준 쿼리를 계속 더할 수 있다. 아래쪽은 "수정에는 닫혀 있다" — 그래도 공통 엔진 코드는 그대로다. 이 두 성질이 합쳐지면, 기능이 늘어나는데도 기존 코드가 흔들리지 않는다. 핵심은 "자주 바뀌는 것(언어 목록)"과 "거의 안 바뀌는 것(추출 절차)"을 갈라, 변화를 표준 데이터 쪽에만 가둔 데 있다.

핵심 효과 정리

표준 채택: 자체 규격 대신 널리 쓰이는 tags.scm 쿼리를 따른다. 대부분 언어는 표준 쿼리가 이미 만들어져 있어 그대로 쓴다.
이름 추출을 쿼리에 위임: C의 선언자 중첩이나 명명 화살표 함수 같은 까다로운 경우를, 내가 손으로 짠 특수 코드 없이 그 언어의 표준 쿼리가 처리한다.
언어 추가가 데이터: 엔진 코드 변경 없이 표준 쿼리를 연결하면 새 언어가 처리된다.
일관성: 모든 언어가 같은 추출 엔진을 지나므로, 결과의 형태(노드·주소 규칙)가 언어마다 어긋나지 않는다.

내 코드 위키 자동생성 시스템과의 연결

코드를 읽어 위키를 자동 생성하려면, 다루는 모든 저장소에서 함수·모듈을 빠짐없이 뽑아야 한다. 그런데 저장소마다 주력 언어가 다르다. 만약 언어를 늘리는 일이 매번 추출기 코드를 뜯어고치는 일이었다면, 언어 확장은 곧 위험하고 더딘 작업이 됐을 것이다.

그래서 내 시스템은 "무엇이 함수인가"를 코드가 아니라 표준 tags.scm 쿼리로 선언하고, 추출 절차는 하나의 엔진으로 통일했다. 덕분에 파이썬에서 출발한 추출기가, 엔진을 거의 고치지 않고도 타입스크립트·C#·PHP·C·자바스크립트 저장소까지 함수·모듈을 담을 수 있게 됐다. 더 좋은 점은, 이게 내가 발명한 사설 방식이 아니라 코드 도구들이 두루 쓰는 표준이라는 것이다 — 표준에 올라타면, 빠진 조각(C# 쿼리)만 채우고 나머지는 생태계가 만들어 둔 것을 그대로 빌려 쓸 수 있다. 이 결정 하나가 "모든 저장소에 위키"라는 목표를, 매번의 코드 수술이 아니라 표준 데이터 연결의 문제로 바꿔 놓았다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

코드를 글자가 아니라 구조로 읽기 — tree-sitter로 함수와 모듈을 뽑아내기

타이젠 개발자, 윤진 — Sun, 5 Jul 2026 21:00:44 +0900

배경: 위키를 자동 생성하려면 먼저 "구조"를 알아야 한다

나는 여러 코드 저장소(repo)를 읽어 설명 문서(코드 위키)를 자동으로 생성하는 개인 프로젝트를 만들고 있다. 사람이 손으로 위키를 쓰는 게 아니라, 코드 자체를 진실의 원천으로 삼아 기계가 위키를 써내는 시스템이다.

그러려면 가장 먼저 풀어야 할 질문이 있다. "이 저장소 안에 어떤 함수와 모듈이 있고, 각각 몇 번째 줄에 있는가?" 이걸 모르면 "이 함수는 이런 일을 한다"는 문장을 단 한 줄도 근거 있게 쓸 수 없다. 즉 위키의 모든 서술은 "코드의 어디"라는 좌표 위에 세워져야 하고, 그 좌표 목록을 만드는 일이 모든 작업의 출발점이다.

문제: 글자만 봐서는 "진짜 함수"를 못 짚는다

가장 단순한 방법은 grep으로 def (파이썬 함수 선언 키워드) 같은 패턴을 찾는 것이다. 빠르고 쉽다. 하지만 grep은 코드를 글자(텍스트)로만 본다. 코드의 문법 규칙을 모르기 때문에 다음을 구별하지 못한다.

주석 속 단어: # def process를 호출하지 말 것 같은 주석 안의 글자도 함수 선언으로 오해한다.
문자열 속 단어: 로그 메시지 "def process started" 안의 글자도 잡아온다.
여러 줄에 걸친 정의: 매개변수가 여러 줄로 나뉘거나 데코레이터가 붙으면 어디가 진짜 함수의 시작이고 끝인지 모른다.
언어마다 다른 규칙: 파이썬은 def, 자바스크립트는 function, C#은 또 다르다. 언어마다 정규식을 새로 짜야 한다.

▲ 글자로 읽기 — grep

다이어그램 설명. 글자 검색이 왜 "진짜 함수"를 못 짚는지 보여준다. "def process"라는 글자를 텍스트로 찾으면, 그 글자가 함수 선언 자리에 있든 주석 안에 있든 로그 문자열 안에 있든 가리지 않고 전부 후보로 올라온다. 코드의 문법을 모르기 때문에 "어느 것이 진짜 함수 정의인가"를 끝내 가려내지 못한다. 함정은, 검색이 빠르다는 장점에 가려 "틀린 후보를 섞어 준다"는 약점이 잘 안 보인다는 점이다 — 자동 생성 문서에서는 단 하나의 오탐도 거짓 서술의 씨앗이 된다.

▲ 구조로 읽기 — tree-sitter

다이어그램 설명. 구조 파싱이 같은 코드를 어떻게 다르게 읽는지 보여준다. tree-sitter는 먼저 코드를 문법 규칙으로 파싱해 구문 트리로 바꾸고, 그 트리에서 "함수 정의"라는 종류의 마디만 골라낸다. 주석이나 문자열, 여러 줄 정의는 문법상 애초에 다른 종류의 마디로 분류되므로 함수 후보에 끼지 못한다. 핵심은 "글자가 같은가"가 아니라 "문법상 무엇인가"로 판단한다는 점이다 — 그래서 같은 "def process"라도 진짜 함수 정의 자리만 정확히 집어낸다.

해결: tree-sitter로 코드를 "문법 트리"로 바꾼다

핵심 직관 — 글자를 구조로 승격시킨다

여기서 쓰는 도구가 tree-sitter다. tree-sitter는 소스 코드를 빠르게 파싱(parsing — 문법 규칙에 따라 구조를 분석)해서 구문 트리(syntax tree — 코드의 문법 구조를 나무 모양으로 표현한 것)로 만들어주는 파서다. 깃허브(GitHub)에서 출발해 지금은 수많은 에디터와 코드 도구의 구문 분석 엔진으로 널리 쓰인다.

비유하자면, grep은 문장을 글자들의 나열로만 보는 반면, tree-sitter는 문장을 읽고 "이건 주어, 이건 동사, 이건 목적어"라고 문법 성분으로 분해하는 것과 같다. 일단 문법 구조를 손에 쥐면, "동사만 모아줘" 같은 요청에 정확히 답할 수 있다. 코드에서 "함수 정의만 모아줘"가 바로 그런 요청이다.

다이어그램 설명. 추출의 한 흐름을 한 줄로 보여준다. 소스 코드를 파서에 넣으면 문법 구조가 나무 모양으로 나오고, 그 나무에서 표준 쿼리로 "함수 정의"에 해당하는 가지만 골라내면, 함수의 이름과 그것이 차지하는 줄 범위가 깔끔하게 떨어진다. 핵심은 중간의 구문 트리 단계다 — 글자를 구조로 한 번 승격시켜 두면, 그 뒤의 모든 질문이 "구조에서 골라내기"라는 정확한 작업으로 바뀐다.

구문 트리는 어떻게 생겼나

구문 트리는 코드의 문법 성분을 부모-자식 관계로 표현한다. 예를 들어 함수 하나는 "함수 정의"라는 노드(node — 트리의 마디)가 되고, 그 아래에 "이름", "매개변수 목록", "본문" 같은 자식 노드가 달린다.

다이어그램 설명. 파일 하나가 어떻게 구조로 펼쳐지는지 보여준다. 파일 전체가 맨 위 마디이고, 그 아래에 함수 정의 마디가 달리며, 함수 정의 마디는 다시 이름·매개변수·본문이라는 자식 마디로 나뉜다. 내 추출기는 이 나무에 표준 쿼리(tags.scm)를 돌려 "함수 정의" 마디와 그 안의 이름 마디를 골라, 이름·시작·끝 위치를 읽는다.

여러 언어를 하나의 추출기로 — 표준 tags.scm 쿼리

내 시스템은 파이썬뿐 아니라 타입스크립트(TypeScript), 자바스크립트(JavaScript), C#, PHP, C까지 다룬다. 언어마다 추출 코드를 따로 짜면 언어가 늘 때마다 코드가 불어난다. 그래서 "무엇이 함수인가"를 코드가 아니라 각 언어의 표준 쿼리로 선언하고, 하나의 엔진이 그 쿼리를 실행하게 했다. 여기 쓰는 표준 형식이 tree-sitter의 tags.scm 쿼리다 — "이런 모양의 마디는 함수 정의, 저런 모양은 클래스 정의"라고 선언해 둔 쿼리 파일로, 깃허브 코드 내비게이션 같은 도구도 같은 방식을 쓴다.

대부분 언어(파이썬·자바스크립트·PHP·C 등)는 표준 tags.scm 쿼리가 문법 패키지에 이미 동봉돼 있어 그대로 쓴다.
C#만 동봉된 쿼리가 없어, 같은 표준 관례를 따라 직접 한 벌 작성해 넣었다.
타입스크립트는 자바스크립트의 확장이라, 자바스크립트 쿼리에 타입스크립트 추가분을 합쳐서 쓴다(타입스크립트 쿼리만으로는 함수 본문을 못 잡는다).

다이어그램 설명. 언어가 늘어도 추출 코드는 하나로 유지되는 구조를 보여준다. 가운데의 추출 엔진은 그대로 두고, 위쪽에 그 언어의 표준 쿼리만 연결하면 그 언어의 파일도 같은 방식으로 처리된다. 핵심은 언어별 차이를 코드 분기가 아니라 표준 데이터(쿼리)로 옮긴 것 — 더구나 내가 만든 사설 규격이 아니라 업계 표준이라, 대부분 언어는 쿼리가 이미 만들어져 있다.

무엇을 뽑아 어떻게 저장하나 — 주소와 라인

추출기는 각 파일에서 저장소·모듈(파일)·함수를 노드로 만들고, "저장소가 모듈을 소유하고(OWNS), 모듈이 함수를 소유한다"는 포함 관계를 엣지(edge — 노드 사이의 연결선)로 잇는다. 파이썬 파일에 대해서는 import 의존(DEPENDS_ON)도 함께 뽑는다.

다이어그램 설명. 추출 결과가 어떤 모양으로 쌓이는지 보여준다. 저장소 아래에 파일이, 파일 아래에 함수가 매달리는 단순한 포함 관계다. 가장 중요한 건 맨 아래 함수에 붙는 주소다 — 저장소와 커밋, 언어, 파일 경로, 함수 이름, 그리고 줄 번호까지 담아 "이 함수는 세상에서 단 하나뿐인 이 자리"라고 못 박는다. 이 주소가 있어야 같은 이름의 함수가 여러 개여도 헷갈리지 않고, 위키의 모든 서술에 "그 근거는 이 파일 이 줄"이라는 검증 가능한 좌표(라인 앵커)를 달 수 있다.

일부러 안 한 것들

가벼움과 정확성을 위해 의도적으로 범위를 좁힌 결정들이 있다.

무거운 언어 서버를 쓰지 않는다: 정확한 분석을 위해 언어별 서버를 띄우는 방식도 있지만, 설치·기동·통신이 무겁다. tree-sitter는 의존성 없이 충분히 빠르고 결정적이라, "가벼운 결정적 추출"이라는 원칙에 더 맞았다.
이름 없는 익명 함수는 노드로 만들지 않는다: 이름이 없는 함수는 안정적인 주소를 붙일 수 없어 라인 앵커의 근거가 되지 못한다. 그래서 익명 함수는 제외한다(반면 이름 있는 화살표 함수는 표준 쿼리가 이름을 근거로 잡아 포함한다).

여기까지가 tree-sitter의 일 — 그 너머는?

중요한 경계가 하나 있다. tree-sitter는 "여기 process를 호출하는 자리가 있다"는 구문까지는 안다. 하지만 "이 process가 어느 정의를 가리키는가"라는 의미는 모른다. 이름 해석은 tree-sitter의 일이 아니다.

다이어그램 설명. tree-sitter가 어디서 멈추는지를 분명히 한다. 구문 파서는 "이건 함수 호출이고 이름은 process"까지는 정확히 알지만, 같은 이름의 정의가 여럿일 때 "지금 이 자리의 process가 그중 무엇인가"는 답하지 못한다. 그 의미 해석은 다음 단계의 몫이다. 함정은 "구조를 안다"는 사실 때문에 "의미도 안다"고 착각하기 쉽다는 점 — 구조를 아는 것과 이름이 무엇을 가리키는지 아는 것은 엄연히 다른 층위다.

효과: 무엇이 가능해졌나

결정적 추출: 같은 코드를 넣으면 항상 같은 트리, 같은 함수 목록이 나온다. 추측이나 환각이 끼어들 여지가 없어, 위키 검증의 단단한 토대가 된다.
다언어를 하나로: 여섯 가지 언어를 같은 엔진과 표준 tags.scm 쿼리로 처리한다. 언어 추가는 그 언어의 표준 쿼리를 연결하는 일이다.
오류에 강함: 코드 한 곳에 문법 오류가 있어도 파서가 그 부분만 건너뛰고 나머지를 파싱한다. 깨진 파일 하나가 전체를 멈추지 않는다.
빠름: 버전 관리에 등록된 파일만 골라 파싱하고, 바뀌지 않은 저장소는 이전 결과를 재사용해 다시 파싱하지 않는다.
라인 앵커의 출처: 모든 함수에 "파일 몇 번째 줄"이라는 검증 가능한 좌표가 붙는다. 위키의 모든 주장을 코드에 묶어두는 첫 단추다.

내 코드 위키 자동생성 시스템과의 연결

코드를 읽어 문서를 자동으로 써내는 시스템에서, 모든 서술은 "실제로 그 코드 어디에 있는가"로 검증 가능해야 한다. 그 검증의 출발점이 바로 "이 저장소에 어떤 함수·모듈이 어디에 있는가"라는 정확한 목록이고, tree-sitter가 그 목록을 결정적으로 만들어 준다.

그래서 내 시스템의 추출 첫 단계는 전적으로 tree-sitter 위에 서 있다. 코드를 구문 트리로 바꾸고, 각 언어의 표준 tags.scm 쿼리로 여러 언어의 함수·모듈을 같은 방식으로 뽑고, 각 함수에 "저장소·커밋·언어·경로·이름·줄"이라는 주소를 달아 그래프에 심는다. 이렇게 만든 결정적 골격 위에, 다음 단계가 "이 함수가 저 함수를 호출한다" 같은 의미 관계를 얹고, 최종적으로 라인 앵커로 모든 주장을 검증한다. tree-sitter가 없으면 위키는 "그럴듯하지만 코드 어디에도 묶이지 않은 글"이 되고, 있으면 "코드의 구조에 단단히 박힌 지도"의 첫 장이 된다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

코드를 그래프로 본다는 것 — 호출 그래프부터 코드 속성 그래프까지

타이젠 개발자, 윤진 — Sat, 4 Jul 2026 22:00:11 +0900

집에 작은 AI 서버를 한 대 두고, 내 코드들을 읽어 설명 문서(위키)를 자동으로 써 주는 도구를 만들며 놀고 있다. 그러다 한 가지를 절실히 깨달았다. 코드를 "그림(그래프)"으로 바꿔 보면 평소 안 보이던 것이 보인다. 그런데 같은 코드라도 "어떤 그림으로 그리느냐"에 따라 보이는 게 완전히 달라진다.

어떤 그림은 "누가 누구를 부르는가"만 보여주고, 어떤 그림은 "이 값이 어디로 흘러가 무슨 일을 일으키는가"까지 보여준다. 이 글은 그 그림들의 스펙트럼을 얕은 것부터 깊은 것까지 차근차근 풀어 본다.

왜 코드를 "그래프"로 보게 됐나

프로그램은 결국 글자의 나열이다. 하지만 도구가 코드를 분석하려면 글자 그대로 보는 것으로는 부족하다. "이 함수가 저 함수를 부른다", "이 변수의 값이 저기로 흘러간다" 같은 관계를 알아야 하기 때문이다.

비유하자면, 도시를 이해하는 지도는 여러 가지다. 어떤 지도는 도로망만, 어떤 지도는 지하철 노선만, 어떤 지도는 상하수도 배관만 그린다. 같은 도시지만 무엇을 그리느냐에 따라 답할 수 있는 질문이 다르다. 도로 지도로는 "여기서 저기까지 차로 갈 수 있나"를 답하지만, "여기서 물을 잠그면 어느 집이 단수되나"는 배관 지도가 있어야 답한다.

코드도 똑같다. 프로그램을 그래프(노드와 엣지로 이뤄진 그림 — 노드(node)는 '점', 엣지(edge)는 '점과 점을 잇는 선')로 표현하는 방법은 여러 가지이고, 각각이 답할 수 있는 질문이 다르다.

다이어그램 설명. 위 그림은 같은 소스 코드를 두고도 우리가 던지는 질문이 여러 종류라는 것을 보여준다. "누가 이 함수를 부르나" 같은 단순 연결 질문부터 "이 값이 어디로 흘러가나" 같은 속뜻(의미) 질문까지 폭이 넓다. 핵심은 이 질문들이 하나의 만능 그래프로 다 풀리지 않는다는 점이다 — 질문마다 그에 맞는 그래프 표현이 따로 있다. 흔히 "콜그래프 하나면 되지 않나" 생각하기 쉬운데, 맨 아래 값 흐름 질문은 콜그래프로는 손도 못 댄다.

얕은 그래프만으로는 답할 수 없는 질문이 있다

코드 분석에서 가장 흔하고 만들기 쉬운 두 그래프는 호출 그래프와 의존 그래프다. 둘 다 "구조"와 "연결" — 즉 누가 누구와 이어져 있는가를 답한다.

호출 그래프(Call Graph): 노드는 함수, 엣지는 호출 관계. "A 함수가 B 함수를 부른다"를 화살표로 그린다.
의존 그래프(Dependency Graph): 노드는 모듈·패키지·빌드 단위, 엣지는 의존 관계. "이 모듈이 저 모듈을 가져다(import) 쓴다"를 그린다.

이 둘은 분명 유용하다. "이 함수를 고치면 어떤 함수들이 영향받을까?"를 대략 짚어 준다. 하지만 한계가 분명하다. 이들은 연결의 존재 여부만 알지, 그 연결 안에서 무슨 일이 벌어지는지는 모른다.

예를 들어 어떤 함수가 사용자 입력을 받아 여러 단계를 거친 뒤 위험한 명령 실행 함수로 그 값을 넘긴다고 하자. 호출 그래프는 "입력 받는 함수 → … → 명령 실행 함수"로 화살표가 이어진다는 것만 보여준다. 하지만 그 입력값이 실제로 명령 실행까지 그대로 흘러가는지, 아니면 중간에 안전하게 검증·정제되는지는 알 수 없다. 화살표는 "통로가 있다"만 말하지, "그 통로로 무엇이 흐르는가"는 말하지 않기 때문이다.

다이어그램 설명. 위 그림은 호출 그래프의 한계를 그대로 드러낸다. 입력을 받는 함수, 중간 처리 함수, 명령을 실행하는 함수가 화살표로 이어져 있다는 사실은 알 수 있다. 그러나 그 사이로 위험한 값이 정말 끝까지 흘러가는지, 아니면 중간 처리 단계에서 안전하게 걸러지는지는 이 그래프만으로는 판단할 수 없다. 즉 "연결됨"은 알아도 "흐름"은 모른다는 게 얕은 그래프의 근본적 한계다. 보안 점검에서 특히 치명적인데, "통로가 있다"는 사실만으로는 그 통로가 실제 공격 경로인지 가려낼 수 없기 때문이다.

점점 깊어지는 그래프들

핵심 아이디어를 직관으로 먼저 말하면 이렇다. 그래프를 깊게 만들수록, "연결" 질문에서 "의미(흐름)" 질문으로 답할 수 있는 범위가 올라간다. 얕은 그래프는 도시의 도로 지도, 깊은 그래프는 "이 수도꼭지를 틀면 물이 어느 경로로 어느 집까지 가는가"를 그린 배관 흐름도라고 보면 된다. 얕음에서 깊음 순서로 보자.

(1) 제어흐름 그래프 (CFG, Control-Flow Graph)

한 함수 내부의 실행 순서와 분기를 그린다. if 문에서 갈라지고 반복문에서 되돌아오는 경로를 노드와 엣지로 표현한다. 호출 그래프가 "함수들 사이"를 본다면, 제어흐름 그래프는 "함수 한 개 안쪽"을 현미경으로 들여다본다. "이 코드에서 어떤 실행 경로가 가능한가"를 답한다.

(2) 데이터흐름 그래프 (DDG, Data-Flow / Data Dependence Graph)

"한 곳에서 만든 값이 다른 곳의 변수에 영향을 준다"는 관계를 그린다. 즉 이 값이 어디서 와서 어디로 흘러가나를 추적한다. 앞서 본 "사용자 입력이 명령 실행까지 정말 흘러가는가" 질문에 답할 수 있는 게 바로 이 그래프다.

(3) 프로그램 의존 그래프 (PDG, Program Dependence Graph)

데이터 의존(값의 흐름)과 제어 의존(실행이 어떤 조건 아래 일어나는가)을 하나로 합친 그래프. "이 줄을 바꾸면 영향받는 부분만 골라낸다" 같은 작업(프로그램 슬라이싱, 영향 분석)의 기반이 된다.

(4) 코드 속성 그래프 (CPG, Code Property Graph)

구문 트리(AST, Abstract Syntax Tree — 코드의 문법 구조를 나무 모양으로 표현한 것)에 더해 제어흐름과 프로그램 의존을 하나의 거대한 그래프로 통합해, 그 위에서 질의(쿼리)할 수 있게 만든 것. 표현력이 가장 높다. 이 개념은 Yamaguchi 등의 논문 "Modeling and Discovering Vulnerabilities with Code Property Graphs"(IEEE S&P 2014)에서 제안됐는데, 출발 동기 자체가 보안 취약점을 그래프 질의로 찾자는 것이었다.

다이어그램 설명. 위 그림은 그래프들을 얕음에서 깊음으로 층층이 쌓은 스펙트럼이다. 맨 위의 호출 그래프와 의존 그래프는 "누가 누구와 이어지는가"라는 구조·연결 질문에 답한다. 아래로 내려가 제어흐름과 데이터흐름, 프로그램 의존을 거쳐 맨 아래 코드 속성 그래프에 이르면 "이 변경이 어떤 값과 경로로 파급되는가"라는 의미·흐름 질문에 답할 수 있게 된다. 놓치기 쉬운 함정은 "아래로 갈수록 무조건 좋다"는 생각이다 — 아래로 갈수록 표현력은 커지지만 그래프를 만드는 비용도 함께 커진다. 그래서 늘 맨 아래층을 택하는 게 답은 아니다.

같은 코드, 다른 그래프

같은 코드 한 조각이 각 그래프에서 무엇을 노드와 엣지로 보는지 표로 나란히 놓아 보자.

그래프	노드(점)	엣지(선)	답하는 질문
호출 그래프	함수	"부른다"	누가 이 함수를 부르나
의존 그래프	모듈·패키지	"가져다 쓴다(import)"	무엇이 무엇에 의존하나
제어흐름 그래프	문장 블록(코드 한 덩어리)	"다음에 실행될 수 있다"	한 함수 안 실행 경로는
데이터흐름 그래프	값을 만들거나 쓰는 지점	"이 값이 저기에 영향 준다"	이 값이 어디로 흐르나
코드 속성 그래프	위 모두를 통합한 노드	종류 표시된 선(문법·실행·값흐름)	골라가며 무엇이든

표 설명. 이 표는 똑같은 코드를 다섯 가지 그래프 렌즈로 들여다봤을 때 무엇이 점이 되고 무엇이 선이 되는지를 나란히 보여준다. 호출 그래프에서는 함수가 점이고 "부른다"가 선이지만, 데이터흐름 그래프에서는 값을 만들거나 쓰는 지점이 점이고 "이 값이 저기에 영향을 준다"가 선이 된다. 같은 코드라도 무엇을 점과 선으로 삼느냐에 따라 보이는 세계가 완전히 달라진다는 것이 핵심이다. 맨 아래 코드 속성 그래프는 이 모든 렌즈를 한 그래프에 합쳐, 필요할 때 원하는 종류의 선만 골라 따라가며 질문할 수 있게 만든 것이다.

이걸 실제로 해 주는 도구들

Joern: 오픈소스 코드 속성 그래프 엔진. C/C++/Java/Python 등을 파싱해 그래프 데이터베이스로 올린 뒤 질의한다.
CodeQL(GitHub): 소스 코드를 관계형 데이터베이스로 "컴파일"한다. 구문 트리·데이터흐름·제어흐름·타입 계층·호출 그래프를 모두 담아, 오염 추적(taint — 위험한 입력이 어디까지 번지는지 따라가는 분석) 같은 데이터흐름 질의를 한다.
Semgrep: 파일·함수 경계를 넘는 데이터흐름과 오염 추적을 지원한다.

무엇이 좋아졌고, 무엇이 한계인가

깊은 그래프가 생기면서 답할 수 있는 질문의 차원이 달라졌다. 대표적으로 "함수의 인자(매개변수) 형태를 바꿨을 때 무슨 일이 벌어지나"를 보자.

다이어그램 설명. 위 그림은 "함수의 인자 형태를 바꾼다"는 하나의 변경이 두 그래프에서 얼마나 다르게 보이는지를 비교한다. 호출 그래프만 있으면 그 함수를 부르는 쪽의 목록까지는 알 수 있지만, 바뀐 값이 각 호출처 안에서 어디로 흘러 무엇을 깨뜨리는지는 알 수 없어 "여기 영향이 있을 수도 있다" 수준에 머문다. 반면 데이터흐름 그래프가 있으면 바뀐 값이 어떤 변수로 받아져 어떤 계산과 분기를 거쳐 최종적으로 어디까지 흘러가는지를 지점 단위로 짚어낸다. 단순 연결 정보와 흐름 정보의 차이가 곧 분석 정밀도의 차이다.

한계와 트레이드오프도 분명하다.

구축 비용: 코드 속성 그래프는 표현력이 가장 높은 대신 만드는 작업이 무겁다. 깊이 파싱하고 여러 그래프를 통합해야 하므로 시간·자원이 많이 든다.
동적 언어의 정밀도 한계: 파이썬(Python)처럼 실행 중 타입·동작이 유연하게 바뀌는 동적 언어에서는, 미리 코드만 보고 데이터흐름을 정확히 추적하기 어렵다.
현실적 절충: 그래서 실무에서는 풀(full) 코드 속성 그래프를 다 만들기보다, "함수 시그니처(이름·인자·반환 형태) + 한 단계(1-hop) 데이터흐름" 정도만 가볍게 뽑아 쓰는 경량 추출이 흔하다.

코드 위키를 자동 생성하는 일에 왜 핵심인가

코드를 읽고 사람이 이해할 문서를 자동으로 써 주는 일에서, "코드를 어떤 그래프로 보느냐"는 결과물의 깊이를 직접 좌우한다. 얕은 그래프만 가진 시스템은 "이 모듈이 저 모듈을 쓴다", "이 함수가 저 함수를 부른다" 수준의 구조 설명까지만 자신 있게 쓸 수 있다. 반면 "이 설정값을 바꾸면 어떤 동작이 어디까지 달라지는가" 같은 의미·파급 질문에 답하려면 더 깊은 흐름 그래프가 필요하다.

현실적으로는 표현력 최고의 통합 그래프를 모든 코드에 무겁게 구축하는 것이 비용 대비 효율이 낮고, 동적 언어에서는 정밀도까지 떨어진다. 그래서 자동 문서화 시스템은 보통 가장 얕은 두 층(연결·구조)을 안정적으로 확보하고, 필요한 곳에만 가벼운 흐름 정보를 덧대는 절충을 택한다. 이 스펙트럼을 이해하면 자동 생성 문서가 "여기까지는 자신 있게 말할 수 있고, 그 이상은 흐름 분석이 있어야 한다"는 경계를 의식적으로 그을 수 있다. 그 경계 인식이 곧 신뢰할 수 있는 문서와 과장된 문서를 가르는 기준이 된다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

코드를 그래프로 질문하기 — 코드 속성 그래프(CPG) 한 번에 이해하기

타이젠 개발자, 윤진 — Sat, 4 Jul 2026 21:00:49 +0900

들어가며 — 코드에게 "질문"을 던지고 싶었다

나는 정적 분석(static analysis: 프로그램을 실행하지 않고 소스 코드만 들여다보며 성질을 알아내는 기법)을 공부하면서 한 가지 욕심이 생겼다. 코드를 그냥 "읽는" 게 아니라, 검색 엔진에 검색어를 넣듯이 "사용자 입력이 검증 없이 위험한 함수까지 흘러가는 곳을 다 찾아줘" 같은 질문을 던지고 싶었다. 마치 도서관에서 "위험물 보관법을 어긴 책 다 가져와"라고 사서에게 부탁하는 느낌으로 말이다.

그런데 막상 해보니, 코드를 분석하는 도구들은 저마다 한 가지 측면만 답해 줬다. 문법을 묻는 도구는 실행 흐름을 모르고, 실행 흐름을 아는 도구는 값이 어디로 흐르는지 몰랐다. 이 글은 그 답답함을 풀어준 코드 속성 그래프(CPG, Code Property Graph)를 내가 이해한 대로 정리한 학습 노트다. 이 개념은 제어 흐름 → 데이터 흐름 → 프로그램 의존으로 점점 깊어지던 스펙트럼의 통합 종착점이다. 앞의 세 가지를 다 합친 것이 바로 CPG다.

CPG가 무엇인가 — 세 그래프를 하나로 겹친 지도

먼저 용어부터 한 줄씩 풀어두자.

약어	이름	한 줄 풀이
AST	구문 트리(Abstract Syntax Tree)	코드의 문법 구조를 나무 모양으로 표현한 것. "이 줄은 함수 호출이고, 그 안에 변수가 들어 있다" 같은 골격.
CFG	제어흐름 그래프(Control Flow Graph)	프로그램이 실제로 실행될 때 어떤 순서·갈래로 문장이 이어지는지를 그린 그래프.
PDG	프로그램 의존 그래프(Program Dependence Graph)	"이 값이 저 계산에 영향을 준다" 같은 의존 관계만 추려 그린 그래프.
CPG	코드 속성 그래프(Code Property Graph)	위 셋을 하나의 속성 그래프로 통합해, 그 위에서 질의할 수 있게 만든 것.

여기서 속성 그래프(property graph)란, 노드(점)와 엣지(선)에 종류와 속성을 붙일 수 있는 그래프를 말한다. 단순히 "A와 B가 연결됨"이 아니라, "A(함수 호출)와 B(변수)가 문법 관계로 연결됨" 또는 "값 흐름 관계로 연결됨"처럼 선마다 꼬리표를 단다.

CPG의 핵심 아이디어는 이렇다. 세 그래프가 공통의 노드를 공유하게 만든 다음, 그 위에 각 그래프의 엣지를 겹쳐(overlay) 올린다. 그리고 각 엣지에 "이건 문법 엣지", "이건 실행 흐름 엣지", "이건 값 흐름 엣지"라는 종류 라벨을 붙인다. 그러면 하나의 지도 위에서 원하는 종류의 선만 골라 따라갈 수 있다.

다이어그램 설명. 위쪽은 문법·실행 순서·값 의존을 각각 따로 답하던 세 그래프이고, 아래쪽은 이들을 공통 노드 위에 겹쳐 하나로 통합한 코드 속성 그래프다. 핵심 흐름은 "세 갈래의 정보가 한 지도로 모인다"는 것. 왜 합치냐면, 실제로 알고 싶은 질문이 한 그래프만으로는 답이 안 나오기 때문이다. 함정은 합쳤다고 정보가 사라지는 게 아니라 엣지 종류 라벨로 보존된다는 점 — 원할 때 다시 한 종류만 떼어 볼 수 있다.

배경 — "보안 취약점을 그래프 질의로 찾자"

CPG는 Yamaguchi, Golde, Arp, Rieck이 발표한 "Modeling and Discovering Vulnerabilities with Code Property Graphs"(IEEE Symposium on Security and Privacy, 2014)에서 제안됐다. 출발 동기 자체가 보안이었다. 취약점을 사람이 일일이 코드를 읽어 찾는 대신, 그래프 질의 한 줄로 패턴을 찾아내자는 발상이었다.

비유하자면, 예전에는 탐정이 사건 현장을 직접 발로 뛰며 단서를 모았다면, CPG는 모든 단서를 하나의 데이터베이스에 넣어 두고 "흉기가 부엌에서 거실로 옮겨진 사건만 보여줘"라고 한 줄로 검색하는 것에 가깝다. 단서가 따로 흩어져 있으면 이런 교차 질문이 불가능하다.

어떤 문제였나 — 취약점은 세 그래프에 "걸쳐" 있다

왜 굳이 합쳐야 했을까. 세 그래프는 각자 답할 수 있는 질문이 정해져 있다.

그래프	답할 수 있는 질문	답하지 못하는 질문
구문 트리(AST)	어디가 사용자 입력이고 어디가 위험한 호출인가? (문법)	그 둘이 실제 실행에서 이어지는가?
제어흐름 그래프(CFG)	이 문장에서 저 문장으로 실행이 도달하는가? (경로)	중간에 값이 정말 그쪽으로 흘러가는가?
프로그램 의존 그래프(PDG)	이 값이 저 계산에 영향을 주는가? (의존)	그게 문법적으로 어떤 호출이고 위험한가?

문제는 실제 취약점이 이 셋에 동시에 걸쳐 있다는 점이다. 대표적인 예가 이런 시나리오다 — "사용자가 입력한 값이, 정제(검증/무해화) 단계를 거치지 않고, 위험한 명령 실행 함수까지 흘러간다." 이 한 문장을 검증하려면 세 가지를 한꺼번에 봐야 한다.

다이어그램 설명. 하나의 취약점 질문이 문법·실행흐름·값흐름이라는 세 갈래의 하위 질문으로 갈라지고, 셋 모두 충족될 때만 진짜 취약점으로 판정되는 흐름을 보여준다. 왜 중요하냐면, 세 갈래 중 하나라도 따로 보면 가짜 경보가 쏟아진다 — 위험한 함수가 있어도 입력이 안 닿으면 무해하고, 경로가 있어도 값이 중간에 검증되면 안전하다. 함정은 셋을 따로 가진 도구로는 이 교차 조건을 한 번에 질의할 방법이 없었다는 것이다.

2014년 이전의 도구들은 이 세 그래프를 각각 따로 만들고 따로 분석했다. 그래서 "문법은 맞는데 실행 경로가 닿는지", "경로는 닿는데 값이 흐르는지"를 사람이 머릿속에서 짜맞춰야 했다. 교차 질문을 자동화할 단일한 데이터 구조가 없었던 것이다.

어떻게 해결했나 — 겹치고(overlay), 라벨 붙이고, 질의한다

CPG의 해결책은 세 단계로 요약된다.

1단계 — 공통 노드 위에 세 그래프를 겹친다

세 그래프가 사실 같은 코드를 다르게 본 것이므로, 같은 코드 요소(예: 한 변수, 한 함수 호출)는 하나의 노드로 공유한다. 그 공유 노드 위에 AST 엣지, CFG 엣지, PDG 엣지를 모두 올린다. 투명 필름 세 장을 같은 지도 위에 포개는 것과 같다.

2단계 — 엣지마다 종류 라벨을 붙인다

포개고 나면 선이 뒤섞이므로, 각 엣지에 "문법", "실행흐름", "값흐름" 같은 종류 라벨을 단다. 이게 속성 그래프의 힘이다. 질의할 때 원하는 종류의 선만 골라 따라갈 수 있다.

다이어그램 설명. 같은 세 노드 사이를 종류가 다른 엣지(값흐름·실행흐름·문법)가 동시에 잇는 모습으로, 한 지도 위에 세 겹의 정보가 라벨로 구분되어 공존함을 보여준다. 흐름은 입력을 읽어 변수에 담고 위험 호출로 이어지는 경로다. 왜 라벨이 핵심이냐면, 오염 추적(taint tracking)을 할 때는 값흐름 라벨만 따라가면 되고, 도달 가능성을 볼 때는 실행흐름 라벨만 따라가면 되기 때문이다. 함정은 라벨 없이 선만 합치면 어느 게 어떤 의미인지 구분할 수 없게 된다는 점.

3단계 — 그래프 데이터베이스에 올려 순회 질의한다

이렇게 만든 CPG를 그래프 데이터베이스(graph database: 데이터를 표 대신 노드·엣지 형태로 저장하는 DB)에 올린다. 그러면 순회(traversal) 질의 언어로 패턴을 찾을 수 있다. 순회 질의란 "이 노드에서 출발해 값흐름 엣지를 따라가다가, 중간에 검증 노드를 거치지 않고 위험 호출에 도달하는 경로"처럼 그래프를 걸어 다니며 조건을 거는 검색이다.

다이어그램 설명. 입력 노드에서 출발해 값흐름 엣지를 한 걸음씩 따라가며, 검증을 거쳤는지와 위험 호출에 도달했는지를 차례로 판단해 취약점 후보만 걸러내는 순회 질의의 흐름이다. 이것이 흔히 말하는 오염 추적(taint tracking) 스타일 — 신뢰할 수 없는 "오염된" 값이 어디까지 번지는지 따라가는 방식이다. 왜 좋냐면 사람이 머릿속으로 짜맞추던 교차 조건을 질의 한 줄로 표현하기 때문. 함정은 경로가 너무 많으면 질의가 느려질 수 있다는 점이라, 출발 노드를 잘 좁히는 게 중요하다.

효과 — 표현력은 최고, 비용도 최고

CPG의 가장 큰 효과는 취약점 탐지를 "그래프 질의"로 표현할 수 있다는 것이다. 앞서 본 오염 추적 스타일의 질문을 코드로 적어 두면, 같은 패턴의 취약점을 코드베이스 전체에서 자동으로 찾아낸다. 한 번 질의를 잘 써 두면 사람마다 다른 직관에 기대지 않고 일관되게 적용된다.

또 하나의 장점은 여러 언어에 적용 가능하다는 점이다. AST·CFG·PDG라는 개념 자체는 특정 언어에 묶이지 않으므로, 언어별 파서만 갖추면 같은 질의 모델을 재사용할 수 있다. 대표적인 오픈소스 도구로 Joern이 있다.

다만 공짜는 아니다. 아래 표처럼 분석 모델이 깊어질수록 표현력은 커지지만 구축 비용도 함께 커진다. CPG는 그 스펙트럼의 끝에 있다 — 표현력은 최고지만 구축 비용도 가장 크다.

분석 모델	보는 것	표현력	구축 비용
구문 트리(AST)	문법 구조	낮음	낮음
제어흐름 그래프(CFG)	실행 순서	중간	중간
프로그램 의존 그래프(PDG)	값·제어 의존	높음	높음
코드 속성 그래프(CPG)	위 셋의 통합	최고	최고

다이어그램 설명. 문법만 보는 가벼운 모델에서 출발해, 실행 경로와 값 의존을 차례로 더해 마침내 셋을 통합한 모델에 이르는 점층적 스펙트럼을 보여준다. 흐름은 "정보가 한 겹씩 쌓이며 깊어진다"는 것. 왜 이 순서가 중요하냐면, 각 단계가 앞 단계 위에 정보를 더하는 구조라 통합 모델은 진짜로 앞의 셋을 모두 포함하기 때문이다. 함정은 끝으로 갈수록 빌드 시간·메모리 비용이 가파르게 오른다는 점 — 모든 코드에 무조건 최상위 모델을 쓰는 게 능사는 아니다.

코드 위키 자동 생성에 왜 핵심인가

마지막으로, 내가 이 개념에 끌린 진짜 이유. CPG는 보안 취약점 탐지에서 출발했지만, 그 본질은 "코드를 질의 가능한 그래프로 만든다"는 것이다. 이건 코드를 자동으로 설명·문서화하는 작업, 즉 코드 위키 자동 생성에 그대로 쓰인다.

코드 위키를 자동으로 쓰려면, 글쓰기 도구가 코드의 구조를 정확히 "알아야" 한다. 단순히 텍스트로 읽는 것과, "이 함수가 어떤 함수들을 부르고, 어떤 값이 어디서 와서 어디로 가는가"를 그래프로 질의하는 것은 정확도가 다르다. CPG가 있으면 다음 질문들에 사실 기반으로 답할 수 있다.

위키가 답해야 할 질문	CPG의 어떤 엣지로 답하나
이 모듈은 어떤 함수들로 이뤄져 있나? (구성)	문법 엣지(AST)
이 기능을 실행하면 어떤 경로로 흘러가나? (동작)	실행흐름 엣지(CFG)
이 설정값은 어디서 와서 어디에 쓰이나? (데이터 파이프라인)	값흐름 엣지(PDG)

다이어그램 설명. 진실의 원천인 소스 코드에서 통합 그래프를 짓고, 순회 질의로 검증 가능한 사실을 뽑아, 그 근거 위에서 글쓰기 도구가 서술을 작성하고 다시 코드 위치로 grounding하는 전체 파이프라인이다. 흐름의 핵심은 "코드 → 그래프 → 사실 → 서술"이라는 단방향 의존. 왜 핵심이냐면, 서술이 코드에서 직접 파생되므로 코드가 바뀌면 같은 파이프라인으로 다시 생성하면 되고, 모든 문장이 근거를 동반해 환각(hallucination: 사실이 아닌 내용을 그럴듯하게 지어내는 현상)을 줄인다. 함정은 그래프 구축 비용이라, 변경된 부분만 다시 인덱싱하는 식의 최적화가 현실적으로 필요하다.

정리하면, CPG는 "코드에게 구조화된 질문을 던지는 공통 기반"이다. 보안에서는 그 질문이 "취약점이 어디 있나"였고, 코드 위키에서는 "이 코드가 무엇을 어떻게 하나"가 된다. 질문만 다를 뿐, 코드를 질의 가능한 그래프로 만들어 두면 둘 다 같은 토대 위에서 풀린다는 점이 내게는 가장 큰 배움이었다.

마치며

처음의 욕심 — "코드에게 질문을 던지고 싶다" — 으로 돌아가 보면, CPG는 그 욕심에 대한 가장 완성된 답이다. 문법·실행흐름·값흐름을 한 지도에 겹쳐 두고 엣지 라벨로 구분하니, 흩어져 있을 때는 불가능했던 교차 질문이 질의 한 줄로 가능해졌다. 표현력의 끝인 만큼 구축 비용도 끝이라는 트레이드오프는 있지만, 코드를 "읽는 대상"이 아니라 "질의하는 데이터"로 바꿔 놓았다는 점에서, 정적 분석과 코드 인텔리전스(code intelligence: 코드의 구조·의미를 자동으로 이해해 활용하는 기술 전반)를 공부하는 사람이라면 한 번은 깊이 들여다볼 가치가 있는 개념이다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

한 문장이 다른 문장에 기대는 두 가지 방식 — 프로그램 의존 그래프(PDG)

타이젠 개발자, 윤진 — Fri, 3 Jul 2026 23:00:35 +0900

들어가며 — 두 가지 "기댐"을 한 그림에

코드를 읽다 보면 한 줄이 다른 줄에 기대고 있다는 느낌을 자주 받는다. 그런데 가만히 보면 그 "기댐"은 한 종류가 아니다. 어떤 줄은 앞 줄이 만든 값을 가져다 쓰기 때문에 앞 줄에 기댄다. 또 어떤 줄은 위에 있는 조건문이 참이어야만 실행되기 때문에 그 조건에 기댄다. 나는 이 두 가지가 본질적으로 다른 기댐인데도, 정작 코드를 분석하는 도구들이 이걸 따로따로 본다는 게 늘 답답했다.

프로그램 의존 그래프(PDG, Program Dependence Graph)는 바로 이 두 가지 기댐을 한 장의 그림에 합쳐 놓은 표현이다. PDG는 정적 분석(static analysis, 프로그램을 실행하지 않고 소스 코드만 보고 성질을 알아내는 분석)에서 쓰는 그래프 표현 중 하나다. 이 글은 내가 "왜 합치지?"라는 의문에서 시작해 "아, 합쳐야만 풀리는 문제들이 있구나"로 도착한 학습 노트다.

PDG란 무엇인가

PDG의 정의는 의외로 간단하다.

구성요소	PDG에서의 의미
노드(node)	문장(statement) 하나, 또는 조건(predicate) 하나
엣지(edge) — 데이터 의존	"이 문장이 만든 값을 저 문장이 읽는다"
엣지(edge) — 제어 의존	"이 조건의 결과가 저 문장의 실행 여부를 결정한다"

여기서 predicate(조건)는 if (x > 0)처럼 참/거짓을 따져 흐름을 가르는 지점을 뜻한다. PDG의 핵심은 엣지가 두 종류라는 점이다. 데이터 의존(data dependence)과 제어 의존(control dependence)을 같은 그래프 위에 같이 그린다.

다이어그램 설명. 위 그림은 PDG가 무엇으로 이뤄지는지를 한눈에 보여준다. 문장과 조건이 점이 되고, 거기에 "값이 흐른다"는 선과 "실행 여부를 가른다"는 선 두 종류가 동시에 얹힌다. 핵심 함정은 이 두 선을 하나로 뭉뚱그리는 것 — 둘은 의미가 완전히 다르므로 같은 그래프에 있어도 색이 다른 선으로 구분해 두어야 한다.

일상 비유 — 요리 레시피

나는 PDG를 요리 레시피로 이해한다. "달걀을 푼다 → 푼 달걀을 팬에 붓는다"는 데이터 의존이다. 앞 단계가 만든 결과물(푼 달걀)을 뒷 단계가 쓰기 때문이다. 반면 "프라이팬이 충분히 달궈졌으면 기름을 두른다"는 제어 의존이다. '달궈졌는가'라는 조건이 참일 때만 '기름 두르기'가 일어난다. 레시피 한 장 안에 이 두 종류의 화살표가 섞여 있는 게 정확히 PDG다.

배경 — 어디서 왔나

PDG의 대표 문헌은 Ferrante, Ottenstein, Warren의 "The Program Dependence Graph and Its Use in Optimization"(ACM TOPLAS, 1987)이다. 이 그래프는 갑자기 등장한 게 아니라, 이미 컴파일러가 쓰고 있던 두 가지 토대 위에 세워졌다.

하나는 제어 흐름 그래프(CFG, Control Flow Graph)다. CFG는 "문장들이 어떤 순서로 실행될 수 있는가"를 그린다. 다른 하나는 데이터 흐름 분석(data-flow analysis)이다. 데이터 흐름 분석은 "어떤 변수의 값이 어디서 만들어져 어디서 쓰이는가"를 추적한다. PDG는 이 둘에서 뽑아낸 정보를 의존 관계라는 한 가지 시각으로 재배열한 결과다.

다이어그램 설명. 이 그림은 PDG가 무에서 나온 게 아니라 이미 있던 두 분석을 재료로 조립됐음을 보여준다. 실행 순서를 그린 그래프에서 "어떤 조건이 어떤 문장을 좌우하는가"라는 제어 의존을 뽑고, 값 추적에서 "누가 만들고 누가 읽는가"라는 데이터 의존을 뽑아, 둘을 한 그래프로 모은다. 함정은 CFG의 화살표(실행 순서)와 제어 의존 화살표를 같은 것으로 착각하는 것 — 실행 순서가 곧 의존은 아니다.

어떤 문제를 풀려 했나

그렇다면 왜 굳이 합쳐야 했을까. 내가 찾은 답은 이렇다. 컴파일러 최적화, 프로그램 슬라이싱, 자동 병렬화 같은 작업은 "어떤 값이 무엇에 의존하나"와 "무엇이 어떤 조건 아래 실행되나"를 동시에 봐야 한다. 그런데 CFG만 보면 값의 흐름이 안 보이고, 데이터 흐름 그래프만 보면 조건의 영향이 안 보인다. 두 그래프를 따로 펼쳐 놓고 사람 머릿속에서 합치는 건 비효율적이고 실수가 잦다.

다이어그램 설명. 위 그림은 분석 작업이 던지는 두 질문과, 단일 그래프만으로는 각각 반쪽만 답한다는 한계를 보여준다. 흐름은 "한 작업이 두 질문을 동시에 던지는데, 따로 보는 그래프는 한 질문씩만 답한다"는 것이다. 함정은 "둘 중 더 중요한 하나만 보면 되지 않나"라고 타협하는 것 — 실제 작업은 두 답을 교차해야 정확해진다.

왜 따로 보면 부족한가 — 짧은 코드 예

아래 코드를 보자. 마지막 줄 print(total)이 어디에 기대고 있는지 따져보면 두 종류의 의존이 함께 등장한다.

줄	코드	의존
1	`total = 0`	—
2	`if items > 0:`	—
3	`total = total + price`	2번 조건에 제어 의존, 1번 값에 데이터 의존
4	`print(total)`	1번·3번 값에 데이터 의존

합계를 더하는 줄은 조건이 참일 때만 실행되므로 조건에 제어 의존하고, 동시에 이전 합계 값을 읽으므로 그 값에 데이터 의존한다. 한 줄이 두 종류로 동시에 기댄다. 이게 바로 두 그래프를 합쳐야 하는 이유다.

어떻게 해결했나 — 두 의존을 한 그래프에

해결책은 단순하면서도 강력하다. 데이터 의존과 제어 의존을 같은 그래프에 함께 그려 넣는다. 그러면 한 문장을 골랐을 때, 그것이 기대고 있는 것(들어오는 엣지)과 그것에 기대는 것(나가는 엣지)을 그래프 탐색만으로 한 번에 따라갈 수 있다. 위의 짧은 코드를 PDG로 그리면 이렇게 된다.

다이어그램 설명. 이 그림은 앞의 4줄 코드를 PDG로 옮긴 것이다. 점선은 제어 의존(조건이 합산 문장의 실행 여부를 가른다)이고 실선은 데이터 의존(값이 흘러간다)이다. 흐름을 보면 출력 문장은 초기화와 합산 양쪽에서 값을 받는다. 함정은 실선과 점선을 같은 의미로 읽는 것 — 점선이 끊긴다고 값이 안 흐르는 게 아니고, 실선이 있다고 항상 실행되는 것도 아니다.

효과 — 프로그램 슬라이싱이 도달성 문제가 된다

PDG의 진가는 프로그램 슬라이싱(program slicing)에서 드러난다. 슬라이싱이란 "프로그램의 특정 지점에 영향을 주는 문장들만, 또는 그 지점이 영향을 미치는 문장들만 골라내는" 기법이다. 슬라이싱 개념 자체는 Mark Weiser가 1981년에 제시했고, Ottenstein & Ottenstein이 1984년에 이를 PDG 위에서 계산하는 방법을 보였다.

핵심은 이거다. 일단 PDG가 있으면, "이 변수가 여기서 가진 값에 영향을 준 모든 문장"을 구하는 일은 그래프 위의 도달성(reachability) 문제로 환원된다. 도달성이란 "어떤 점에서 출발해 화살표를 거꾸로(또는 앞으로) 따라가 닿을 수 있는 모든 점을 모으는" 단순 탐색이다. 복잡한 의미 분석이 평범한 그래프 순회로 바뀌는 것이다.

다이어그램 설명. 이 그림은 백워드 슬라이스(특정 지점에 영향을 준 문장 모으기)를 계산하는 절차다. 흐름은 관심 지점을 고른 뒤 그곳으로 들어오는 의존 엣지를 거꾸로 따라가, 닿는 모든 문장을 슬라이스로 모으는 것이다. 왜 강력하냐면 "영향 추적"이라는 어려워 보이는 질문이 그래프 역방향 탐색이라는 익숙한 알고리즘으로 떨어지기 때문이다. 함정은 데이터 의존만 따라가는 것 — 제어 의존 엣지도 같이 따라가야 "어떤 조건 때문에 실행됐는가"까지 슬라이스에 포함된다.

슬라이싱 외의 쓰임

같은 구조가 여러 작업에 재활용된다. 자동 병렬화에서는 서로 의존하지 않는(엣지로 연결되지 않은) 문장들을 찾아 동시에 실행할 후보로 삼는다. 리팩토링에서는 한 함수에서 떼어낼 코드 덩어리가 바깥과 어떤 의존으로 묶여 있는지 본다. 변경 영향 분석(change impact analysis)에서는 한 줄을 고쳤을 때 그 영향이 어디까지 번지는지를 포워드 슬라이스(나가는 엣지를 따라가기)로 가늠한다.

작업	PDG에서 무엇을 보나
최적화	의존이 없는 부분 = 자유롭게 재배치 가능
프로그램 슬라이싱	도달성 = 영향 주고받는 문장 집합
자동 병렬화	엣지로 안 묶인 문장 = 동시 실행 후보
변경 영향 분석	포워드 슬라이스 = 변경이 번지는 범위

관계 정리 — CFG, 데이터흐름, 그리고 코드 속성 그래프

마지막으로 여러 그래프 표현들이 어떻게 층층이 쌓이는지를 정리하면 머릿속이 깔끔해진다. 실행 순서를 보는 층(CFG), 값의 흐름을 보는 층(데이터흐름), 조건의 영향을 보는 층(제어 의존)을 통합한 게 PDG다. 그리고 여기에 코드의 문법 구조인 구문 트리(AST, Abstract Syntax Tree — 코드를 괄호·연산자·블록 같은 문법 단위로 나눈 트리)까지 합치면 코드 속성 그래프(CPG, Code Property Graph)가 된다.

다이어그램 설명. 이 그림은 표현들이 쌓이는 층위를 보여준다. 흐름은 아래쪽 기본 분석들이 모여 데이터·제어 의존을 합친 그래프가 되고, 거기에 문법 구조 트리까지 더해 가장 풍부한 통합 그래프로 올라가는 것이다. 왜 중요하냐면 이 사다리에서 어느 층까지 올라가느냐가 곧 분석의 표현력을 결정하기 때문이다. 함정은 맨 위 통합 그래프가 아래 층들을 대체한다고 보는 것 — 사실은 아래 층 정보를 품고 올라가는 것이다.

코드 위키 자동 생성에 왜 핵심인가

내가 이 주제에 끌린 진짜 이유는 따로 있다. 나는 코드를 읽고 코드 위키(문서)를 자동 생성하는 일에 관심이 있는데, 그 일의 본질이 결국 "이 함수가 무엇에 기대고, 무엇이 이 함수에 기대는가"를 정확히 말하는 것이기 때문이다. 위키 한 줄이 "이 함수는 설정 값이 로드된 뒤에만 의미가 있다"고 주장하려면, 그 주장을 코드에서 검증 가능한 의존 관계로 뒷받침할 수 있어야 한다.

PDG는 바로 그 "기댐"을 기계가 따라갈 수 있는 형태로 만들어 준다. 문서가 "이 줄을 바꾸면 저쪽 출력이 달라진다"고 적으려면 포워드 슬라이스가 그 범위를 알려주고, "이 결과는 이 조건과 이 입력에서 비롯된다"고 적으려면 백워드 슬라이스가 근거 문장들을 모아준다. 즉 자연어 서술의 모든 의존 주장이 PDG 위의 도달성으로 grounding(근거 연결)될 수 있다.

다이어그램 설명. 이 그림은 코드에서 시작해 의존 그래프를 거쳐 검증 가능한 위키 서술에 도달하는 흐름이다. 흐름은 코드가 진실의 원천이고, 의존 그래프가 거기서 "기댐"을 뽑아내며, 그 위에서 위키의 주장이 슬라이스로 뒷받침되는 것이다. 왜 핵심이냐면 "근거 없는 문서"를 "코드로 검증 가능한 문서"로 바꾸는 다리가 바로 이 의존 구조이기 때문이다. 함정은 의존 그래프 없이 LLM의 인상만으로 서술하는 것 — 그러면 그럴듯하지만 검증할 수 없는 문장이 남는다.

정리

한 줄로 요약하면 PDG는 "값의 흐름"과 "조건의 영향"이라는 두 가지 기댐을 한 그래프에 합친 표현이다. 합쳤기 때문에 최적화·슬라이싱·병렬화처럼 두 가지를 동시에 봐야 하는 작업이 그래프 도달성이라는 단순한 문제로 환원된다. 나에게 가장 값진 깨달음은 "두 개를 따로 보는 것"과 "두 개를 합쳐 보는 것" 사이에 표현력의 질적 도약이 있다는 점이었다. 그리고 이 도약이 코드에서 근거 있는 문서를 길어 올리는 일의 토대가 된다는 것까지가 이번 학습의 결론이다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

값은 어디서 와서 어디로 가는가 — 데이터흐름 그래프(DDG)로 코드 읽는 법 배우기

타이젠 개발자, 윤진 — Fri, 3 Jul 2026 22:00:21 +0900

들어가며 — 코드를 읽다가 매번 막히는 그 질문

남이 짠 코드를 읽다 보면 거의 반사적으로 떠오르는 질문이 하나 있다. "이 변수의 값, 도대체 어디서 온 거지?" 함수 한가운데에 total이라는 변수가 떡하니 쓰이고 있는데, 그 값이 어느 줄에서 만들어졌는지, 중간에 누가 바꿔치기했는지를 스크롤을 위아래로 한참 굴려야 겨우 짐작한다. 반대 방향의 질문도 있다. "여기서 계산한 이 값, 나중에 쓰이긴 하나?" 애써 구한 값이 사실은 아무도 안 읽는 죽은 값이라면, 그 계산은 그냥 낭비다.

이 두 질문이 사실은 같은 뿌리에서 나온다는 걸 알게 된 게 이번 학습의 출발점이었다. 둘 다 "값의 흐름"을 묻고 있다. 어디서 만들어져(정의), 어디로 흘러가(사용) 닿는가. 이 흐름을 사람이 머릿속에서 추적하는 대신 그래프로 그려둔 것이 바로 데이터흐름 그래프(Data-Flow Graph), 혹은 데이터 의존 그래프(Data Dependence Graph)다. 줄여서 DDG라고 부른다. 이 글은 내가 이 개념을 처음부터 더듬어가며 정리한 학습 노트다.

DDG란 무엇인가 — 값의 흐름을 그린 지도

DDG는 한 문장으로 이렇게 말할 수 있다. "한 곳에서 만든 값이 다른 곳의 변수에 영향을 준다"는 값의 흐름을 그린 그래프. 그래프이니 노드와 엣지로 이뤄지는데, 각각의 의미가 명확하다.

정의(definition)란 변수에 값을 넣는 지점이다. x = 5처럼 어떤 변수에 값이 들어가는 순간. 사용(use)이란 값을 읽는 지점이다. y = x + 1에서 x를 읽어오는 순간. DDG의 노드는 바로 이 정의가 일어나는 곳, 그리고 사용이 일어나는 곳이다. 그리고 엣지는 "이 정의가 만든 값이 저 사용처에 닿는다"는 데이터 의존을 나타낸다.

다이어그램 설명. 값이 만들어진 지점에서 그 값이 읽히는 지점으로 화살표가 이어진다. 다섯이라는 값을 담은 변수가 다음 줄에서 읽혀 새 계산에 쓰이고, 그 결과가 또 다음 줄로 흘러간다. 화살표 하나하나가 "이 값이 저기서 쓰인다"는 의존을 뜻한다. 흐름은 위에서 아래로, 값이 태어난 곳에서 소비되는 곳으로 향한다. 주의할 점은 이 화살표가 "줄 순서"가 아니라 "값의 출처"를 따라간다는 것 — 코드가 멀리 떨어져 있어도 값이 흐르면 엣지가 생긴다.

비유하자면 택배 배송 지도 같은 것이다. 어떤 물건이 어느 창고(정의)에서 출발해 어느 집(사용)으로 배달되는가. 코드의 줄 번호 순서는 "내가 오늘 어느 동네를 먼저 들렀나"라는 동선일 뿐이고, DDG는 "이 택배가 정확히 어느 창고에서 와서 어느 집에 도착하는가"라는 출발지-도착지 연결을 그린다.

배경 — 컴파일러가 먼저 필요로 했다

이 개념은 갑자기 코드 분석 도구를 위해 생긴 게 아니다. 뿌리는 컴파일러의 데이터흐름 분석(data-flow analysis), 즉 프로그램 안에서 값이 어떻게 전파되는지를 정적으로 계산하는 기법에 있다. 1973년 게리 킬달(Gary Kildall)이 발표한 논문 "A Unified Approach to Global Program Optimization"(POPL 1973)이 전역 데이터흐름 분석을 하나의 통합된 틀로 정리한 출발점으로 꼽힌다.

왜 컴파일러가 이걸 필요로 했을까. 컴파일러의 일 중 하나는 최적화다. 더 빠르고 더 작은 기계어를 뽑아내려면 코드의 의미를 이해해야 하는데, 대표적인 두 가지 최적화가 값의 흐름 정보를 절실히 요구했다.

하나는 상수 전파(constant propagation): 어떤 변수가 항상 같은 상수값을 가진다면 그 변수를 아예 상수로 바꿔치기하는 최적화다. x = 5 다음에 y = x + 1이 온다면, 컴파일러는 y = 5 + 1, 더 나아가 y = 6으로 미리 계산해둘 수 있다. 단 이렇게 하려면 "이 사용처에 닿는 값이 정말 항상 5인가"를 알아야 한다. 다른 하나는 죽은 저장 제거(dead store elimination): 값을 만들어 변수에 넣었는데 그 값을 아무도 읽지 않는다면 그 저장 자체를 지우는 최적화다. 둘 다 "값이 어디서 와서 어디로 가나"를 모르면 손도 댈 수 없다.

어떤 문제 — CFG만으로는 답이 안 나온다

여기서 먼저 짚어야 할 게 제어흐름 그래프(CFG, Control-Flow Graph): 프로그램이 어떤 순서로 실행되는지, 어디서 분기하고 어디서 합쳐지는지를 그린 그래프다. 컴파일러와 정적 분석의 기본 토대인데, CFG는 강력하지만 한계가 분명하다. CFG는 '실행 순서'는 알려주지만 '어떤 값이 어떤 값에 의존하는지'는 모른다.

다이어그램 설명. 이것은 CFG다. 입력을 받고, 조건을 검사해 두 갈래로 나뉘었다가, 다시 한 지점으로 합류해 출력으로 끝난다. 화살표는 "다음에 어디로 실행이 넘어가는가"라는 순서만 말한다. 하지만 이 그림만 봐서는 마지막에 출력되는 값이 위쪽 곱셈에서 온 것인지 아래쪽 영(0) 할당에서 온 것인지, 그 출처의 연결이 직접 그려져 있지 않다. 흐름의 방향은 실행 순서를 따르며, 함정은 바로 여기 — 순서를 안다고 출처를 아는 게 아니다.

CFG가 답하지 못하는 질문을 다시 적어보면 이렇다. "이 변수의 값은 어디서 왔나? 이 값이 나중에 쓰이긴 하나?" 실행 순서를 줄줄 따라간다고 해서 이 질문이 저절로 풀리지 않는다. 분기와 반복이 얽히면, 한 사용 지점에 도달할 수 있는 값의 출처가 여러 군데일 수도 있고, 멀리 떨어진 곳일 수도 있다. 사람이 매번 눈으로 추적하기엔 금방 한계가 온다.

어떻게 해결하나 — 도달 정의와 정의-사용 연쇄

해결의 핵심은 이렇다. CFG 실행 흐름 위에서 각 변수의 정의와 사용을 계산하고, 한 정의에서 그 값이 도달하는 사용처로 데이터 의존 엣지를 잇는다. 즉 실행 순서 그래프를 토대 삼아, 그 위에 값의 흐름을 새 층으로 얹는 것이다. 이 계산의 중심에 도달 정의(reaching definitions): 어떤 정의가 특정 사용 지점까지 살아서 도달하는가를 따지는 분석이 있다.

"살아서 도달한다"는 표현이 핵심이다. 어떤 변수에 값을 넣었더라도, 그 값이 쓰이기 전에 다른 정의가 같은 변수를 덮어쓰면(redefine) 앞의 정의는 그 지점까지 "도달하지 못한다." 마치 칠판에 글씨를 썼는데 누가 그 위에 다시 다른 글씨를 덮어쓰면 원래 글씨는 더 이상 읽히지 않는 것과 같다. 도달 정의 분석은 각 사용 지점에서 "지금 이 변수에 살아있는 정의가 어떤 것들인가"를 계산한다.

다이어그램 설명. 같은 변수에 두 번 값을 넣은 뒤 그 변수를 읽는 상황이다. 점선은 첫 번째 할당이 읽기 지점까지 살아서 닿지 못함을, 굵은 화살표는 두 번째 할당의 값이 실제로 닿음을 보여준다. 흐름은 위에서 아래로, 그러나 "닿는다/못 닿는다"는 중간에 덮어쓰기가 있었는지에 따라 갈린다. 함정은 코드 줄 순서만 보면 두 정의가 다 위에 있지만, 읽기 지점에 실제로 도달하는 건 마지막 것 하나뿐이라는 점이다.

이렇게 "어떤 정의가 어떤 사용에 도달하는가"를 계산해 그 둘을 엣지로 이으면, 정의-사용 연쇄(def-use chain): 하나의 정의에서 출발해 그 값을 읽는 모든 사용 지점을 사슬처럼 연결한 것이 만들어진다. 정의 하나가 머리, 그 값을 읽는 여러 사용처가 줄줄이 매달린 사슬이다.

다이어그램 설명. 하나의 정의에서 여러 사용처로 화살표가 부챗살처럼 퍼진다. 가격이라는 값 하나가 세금 계산, 화면 표시, 합계 계산 세 곳에서 읽히고 있다. 이 부챗살 전체가 하나의 정의-사용 연쇄다. 이 그림이 있으면 "가격 정의를 고치면 어디가 영향받나"가 한눈에 보인다 — 화살표가 닿는 세 곳 전부다. 함정은 이 연쇄가 코드상 인접하지 않을 수 있다는 것 — 세 사용처가 파일 곳곳에 흩어져 있어도 의존은 하나로 묶인다.

효과 — 최적화에서 보안 추적까지

값의 흐름을 그래프로 손에 쥐면 할 수 있는 일이 확 늘어난다. 학습하며 정리한 효과를 표로 묶어봤다.

활용	무엇을 하나	DDG의 어떤 정보가 쓰이나
상수 전파	항상 같은 상수인 변수를 미리 계산해 치환	"이 사용처에 닿는 정의가 항상 같은 상수값인가"
죽은 저장 제거	아무도 읽지 않는 저장을 삭제	"이 정의에서 출발하는 사용 엣지가 하나도 없는가"
프로그램 슬라이싱	특정 값에 영향을 주는 코드 조각만 추려내기	정의-사용 연쇄를 거꾸로 거슬러 올라간 데이터 부분
오염 추적(taint)	위험한 외부 입력이 어디까지 번지는지 따라가기	오염된 정의에서 출발하는 데이터 의존의 전파 경로

앞서 본 상수 전파와 죽은 저장 제거는 컴파일러 최적화의 직접적 응용이다. 더 흥미로운 건 그다음이다. "이 값이 어디서 와서 어디로 가나"라는 추적 능력은 곧바로 다른 영역으로 번진다.

프로그램 슬라이싱(program slicing)이란 "이 결과에 영향을 준 코드만 남기고 나머지를 잘라내는" 기법이다. 어떤 변수의 최종 값에 관심이 있을 때, 그 값에 기여한 정의들을 데이터 의존을 따라 거꾸로 거슬러 모으면 관련 코드 조각만 추려진다. 이때 따라가는 사슬이 바로 정의-사용 연쇄다.

다이어그램 설명. 외부에서 들어온 입력값이 변수에서 변수로 복사되며 결국 데이터베이스 실행 지점까지 흘러가는 경로다. 시작점의 입력을 "오염됐다"고 표시하면, 데이터 의존을 따라 그 오염이 어디까지 번지는지가 그대로 드러난다. 흐름은 입력에서 위험 지점으로 향하고, 이 경로가 끊기지 않고 닿는다는 사실 자체가 보안 경고가 된다. 함정은 중간에 값이 검증·정제되는 단계가 끼어 있으면 오염이 "씻기는데", 그 단계를 그래프가 알아채지 못하면 오탐이 생긴다는 점이다.

이것이 오염 추적(taint analysis): 신뢰할 수 없는 입력이 프로그램 안에서 어디까지 퍼지는지를 따라가는 보안 분석이다. 사용자 입력처럼 위험할 수 있는 값을 "오염원"으로 찍어두고, 데이터 의존을 따라 그 오염이 데이터베이스 질의나 명령 실행 같은 "위험 지점"에 닿는지를 본다. 닿으면 보안 취약점 후보다. 컴파일러 최적화에서 출발한 값의 흐름 그래프가, 결국 보안 분석의 토대까지 떠받치는 것이다.

DDG의 자리 — CFG 위, PDG 아래

여러 그래프가 나와서 헷갈리기 쉬운데, 셋의 관계를 정리하면 머릿속이 깔끔해진다. 비교를 위해 블록을 나눠 본다.

▲ 제어흐름 그래프 — 실행 순서의 층

다이어그램 설명. 제어흐름 그래프는 "다음에 무엇을 실행하나"라는 순서와 분기·합류만을 그린다. 화살표는 시간의 흐름, 곧 실행의 진행 방향이다. 값에 대한 정보는 여기 없다 — 오직 "어디로 가는가"만 있다.

▲ 데이터흐름 그래프 — 값의 흐름 층

다이어그램 설명. 데이터흐름 그래프는 CFG에 "값이 어디서 와서 어디로 가나"를 얹은 층이다. 화살표는 시간이 아니라 데이터 의존 — 정의에서 사용으로 향한다. 같은 코드라도 제어흐름 그래프와는 전혀 다른 모양의 그림이 나오며, 둘은 서로를 대체하는 게 아니라 보완한다.

▲ 프로그램 의존 그래프 — 둘을 합친 층

다이어그램 설명. 프로그램 의존 그래프(PDG)는 데이터 의존과 제어 의존을 한 그래프에 합쳐 그린 것이다. 한 종류의 화살표는 "이 조건 때문에 실행된다"는 제어 의존을, 다른 종류는 "이 값을 넘겨받는다"는 데이터 의존을 나타낸다. 슬라이싱처럼 "이 결과에 영향을 준 모든 것"을 묻는 분석은 두 의존을 모두 따라가야 하므로 이 합친 그래프가 필요하다.

정리하면, DDG는 CFG(실행 순서)를 보완하기 위해 값의 흐름을 다룬 층이다. 그리고 여기에 제어 의존(control dependence): 어떤 문장이 실행될지가 어느 조건의 참·거짓에 달려 있는 관계까지 합쳐지면 프로그램 의존 그래프(PDG)가 된다. CFG는 토대, DDG는 그 위의 한 층, PDG는 데이터와 제어 두 층을 합친 상위 구조. 이 계단을 알고 나니 정적 분석 문서를 읽을 때 길을 잃지 않게 됐다.

코드 위키 자동생성에 왜 핵심인가

마지막으로, 내가 이 개념에 끌린 진짜 이유다. 요즘 관심을 두고 있는 게 코드에서 자동으로 설명 문서(코드 위키)를 생성하는 일인데, 그 작업의 한가운데에 바로 이 값의 흐름 정보가 있다.

코드 위키를 그럴듯하게 자동 생성하려면, 단순히 "이 함수는 이런 줄들로 이뤄져 있다"를 나열하는 것으로는 부족하다. 진짜 가치 있는 설명은 "이 함수가 받은 입력이 내부에서 어떻게 변형되어 무엇으로 흘러나가는가"다. 사람이 코드를 이해할 때 머릿속으로 그리는 그 값의 흐름을, 도구가 DDG로 미리 계산해두면 설명의 근거가 단단해진다.

다이어그램 설명. 소스 코드에서 출발해 실행 순서 그래프를 만들고, 그 위에서 정의와 사용을 계산해 데이터 의존을 이어 값의 흐름 그래프를 얻은 뒤, 그 흐름을 근거로 설명 문장을 짓고 최종적으로 위키 페이지가 된다. 흐름은 코드라는 사실에서 검증 가능한 그래프를 거쳐 설명으로 향한다. 함정은 중간 그래프를 건너뛰고 코드를 바로 글로 옮기면 "왜 그렇게 말하는가"의 근거가 사라진다는 점 — 그래프가 곧 설명의 출처 증거다.

특히 매력적인 건 추적 가능성이다. "이 설정값이 어디서 읽혀 어떤 결정에 쓰이는가" 같은 문서 한 줄이, 막연한 짐작이 아니라 실제 정의-사용 연쇄에 근거한다면, 그 문서는 코드가 바뀔 때 어디를 다시 써야 하는지도 함께 알려준다. 값이 흐르는 경로가 곧 "이 설명이 의존하는 코드 지점"이기 때문이다. 코드가 진실의 원천이고 문서가 거기서 파생된 산출물이 되려면, 둘 사이를 잇는 검증 가능한 연결이 필요한데, 데이터 의존이 바로 그 연결의 한 축을 맡는다.

마치며

처음엔 그저 컴파일러 최적화 기법 중 하나려니 했던 데이터흐름 그래프가, 알고 보니 "값은 어디서 와서 어디로 가는가"라는 단 하나의 질문을 집요하게 파고든 결과물이었다. 그리고 그 질문은 코드를 읽는 사람이라면 매일 던지는 질문이고, 최적화·슬라이싱·보안 추적·문서 자동생성이 모두 그 답을 필요로 한다. CFG가 실행의 줄거리라면 DDG는 값의 족보다. 둘을 겹쳐 보는 눈을 갖추는 것 — 이번 학습의 가장 큰 수확이었다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

코드는 일직선이 아니다: 제어흐름 그래프(CFG)로 함수 속 길을 그려보기

타이젠 개발자, 윤진 — Fri, 3 Jul 2026 21:00:16 +0900

집에 작은 AI 서버를 한 대 두고, 코드를 넣으면 그 코드의 구조를 설명하는 코드 위키를 자동으로 만들어보는 취미 프로젝트를 굴리고 있다. 함수를 읽고 "이 함수는 무엇을 하고, 어디로 갈라지고, 어디서 되돌아오는가"를 글로 풀어내려면, 그 전에 기계가 코드의 흐름을 이해할 수 있는 형태로 바꿔야 한다. 그 첫 번째 도구가 바로 제어흐름 그래프였다. 이 글은 내가 그걸 공부하며 정리한 노트다.

1. 제어흐름 그래프(CFG)란 무엇인가

제어흐름 그래프(CFG, Control-Flow Graph)는 함수나 프로시저 하나의 내부에서, 실행이 어떤 순서로 진행되고 어디서 갈라지는지를 그린 방향 그래프다. 한마디로 "이 함수 안에서 실행이 흘러갈 수 있는 모든 길의 지도"다.

이 지도에는 두 가지 부품이 있다.

노드(node) = 기본 블록(basic block). 중간에 갈라지거나 끼어드는 일 없이, 들어오면 끝까지 일직선으로 쭉 실행되는 코드 덩어리다. 한번 들어가면 도중에 빠져나가거나 건너뛰지 않는다.
엣지(edge) = "이 블록 다음에 저 블록이 실행될 수 있다"는 제어 이동. if로 갈라지거나, 반복문으로 되돌아가거나, return으로 빠져나가는 것을 화살표로 그린다.

그리고 길의 시작과 끝을 분명히 하기 위해 진입 노드(entry)와 종료 노드(exit)를 둔다. 모든 길은 진입에서 시작해 종료로 모인다.

다이어그램 설명. 가장 단순한 함수, 즉 분기도 반복도 없이 위에서 아래로만 흐르는 경우다. 진입에서 시작해 입력을 읽고 계산하고 반환한 뒤 종료로 모인다. 이렇게 갈림길이 없는 코드는 사실 전부 하나의 기본 블록으로 묶을 수도 있다. 여기서 굳이 세 칸으로 나눈 것은 다음 그림과의 대비를 위해서다. 함정은 이 그림처럼 "코드는 원래 일직선"이라고 착각하는 것인데, 실제 코드는 대부분 다음부터 나오는 갈림길 모양이다.

2. 배경: 컴파일러 최적화 시대에 태어났다

CFG는 1970년 즈음 컴파일러 최적화가 본격화되던 시기에 자리 잡았다. 컴파일러는 사람이 쓴 코드를 기계어로 번역하는 프로그램인데, 단순 번역에 그치지 않고 "같은 결과를 더 빠르게, 더 적은 자원으로" 만들도록 코드를 다듬는다. 이 다듬기를 최적화라고 부른다.

그런데 최적화를 하려면 컴파일러가 코드의 "실행 모양"을 알아야 한다. 어떤 계산이 반복문 안에서 매번 똑같이 일어나는지, 어떤 코드는 절대 실행될 일이 없는지, 어떤 변수가 어느 지점에서 살아 있는지를 파악해야 안전하게 손댈 수 있다. 이 모든 분석의 밑바탕으로, 프랜시스 E. 앨런(Frances E. Allen)이 1970년에 발표한 Control Flow Analysis가 토대를 놓았다. 코드의 흐름을 그래프로 정식화한 이 작업이 이후 거의 모든 컴파일러 최적화의 출발점이 되었다.

핵심 통찰은 단순하다. 코드의 텍스트 순서와 실행 순서는 다르다. 그렇다면 실행 순서를 따로 그려두면, 거기에 대고 분석을 돌릴 수 있다는 것이다.

3. 어떤 문제를 풀려고 필요한가

코드를 처음 펼치면 글자가 위에서 아래로 죽 나열되어 있다. 마치 책의 한 문단처럼 일직선으로 읽힌다. 하지만 실제로 그 코드가 돌아갈 때는 전혀 일직선이 아니다.

if를 만나면 길이 둘로 갈라진다.
반복문을 만나면 아래로 가던 흐름이 위로 되돌아온다.
return이나 예외를 만나면 중간에서 빠져나간다.

그래서 "이 함수에서 도대체 어떤 실행 경로들이 가능한가? 어디서 갈라지고, 어디로 되돌아오는가?"라는 질문은, 글자만 위아래로 훑어서는 답하기 어렵다. 사람의 머릿속에서도 if가 세 개만 겹쳐도 가능한 경로 조합이 금방 헷갈린다. 기계라면 더더욱 "텍스트"로는 이걸 다룰 수 없다.

다이어그램 설명. 텍스트로 적힌 코드 한 덩어리에 세 가지 핵심 질문을 던지면 모두 "글자만 봐서는 막힌다"는 같은 벽에 부딪힌다. 위에서 아래로 질문들이 모두 한 벽으로 수렴하는 모양으로 그린 것은, 표현 형식(텍스트)과 우리가 알고 싶은 것(흐름) 사이에 근본적인 간극이 있음을 한눈에 보이기 위해서다. 함정은 "코드를 더 꼼꼼히 읽으면 된다"고 여기는 것인데, 문제는 꼼꼼함이 아니라 표현 형식 자체가 흐름을 담고 있지 않다는 데 있다.

4. 어떻게 해결했나: 코드를 블록으로 쪼개고 화살표로 잇는다

해결책은 의외로 직관적이다. 두 단계로 나뉜다.

4-1. 기본 블록으로 쪼개기

먼저 코드를 기본 블록 단위로 자른다. 규칙은 간단하다. "이 줄로 점프해 들어올 수 있는 곳"이나 "여기서 어디론가 점프해 나가는 곳"을 경계로 삼아 자른다. 그 경계 사이의 일직선 구간이 하나의 블록이다. 블록 안에서는 첫 줄에 들어오면 마지막 줄까지 무조건 순서대로 실행된다 — 중간에 새지 않는다.

4-2. 가능한 점프를 엣지로 잇기

그다음, 블록과 블록 사이에 "여기서 저기로 실행이 넘어갈 수 있다"는 점프를 방향 있는 화살표로 잇는다. if/else면 한 블록에서 두 블록으로 화살표가 갈라지고, 반복문이면 아래쪽 블록에서 위쪽 조건 블록으로 화살표가 되돌아온다. 이렇게 되돌아오는 화살표를 백 엣지(back-edge)라고 부른다. 반복(루프)의 정체가 바로 이 백 엣지다.

다이어그램 설명. if/else가 들어간 함수의 모습이다. 조건을 묻는 칸에서 화살표가 둘로 갈라졌다가, 양쪽 처리가 끝나면 다시 하나의 합류 칸으로 모이고 종료로 빠진다. 이렇게 "갈라졌다 모이는" 다이아몬드 모양이 CFG에서 가장 흔한 기본 패턴이다. 이 패턴 덕분에 "이 함수에는 두 가지 경로가 있다"는 사실이 그림만 봐도 즉시 드러난다. 함정은 합류 칸을 빠뜨리는 것인데, 합류 지점을 명시하지 않으면 이후 공통 코드가 어느 경로에 속하는지 분석이 모호해진다.

다이어그램 설명. 반복문(루프)을 그린 것이다. 본문을 실행한 뒤 다시 조건 칸으로 올라가는 화살표가 핵심인데, 이것이 바로 되돌아오는 백 엣지다. 위에서 아래로 흐르다가 한 화살표만 거꾸로 올라가도록 그린 이유는, 그 한 줄이 "여기 루프가 있다"는 사실을 그래프 차원에서 증명하기 때문이다. 컴파일러는 바로 이 거꾸로 가는 화살표를 찾아 루프를 자동으로 식별한다. 함정은 이 백 엣지를 일반 화살표와 똑같이 취급하는 것인데, 사이클(되돌아옴)을 무시하면 무한히 도는 경로를 분석기가 끝없이 따라가게 된다.

5. 효과: 하나의 그래프가 여러 분석의 토대가 된다

일단 함수를 이 그래프로 바꿔두면, 텍스트로는 어려웠던 분석들이 그래프 위의 자연스러운 질문으로 바뀐다.

분석	그래프 위에서는 이런 질문
죽은 코드(dead code) 탐지	진입에서 출발해 화살표를 따라가도 절대 닿지 못하는 블록이 있는가? (도달 불가능 = 죽은 코드)
루프 식별	거꾸로 올라가는 화살표(백 엣지)가 어디에 있는가?
레지스터 할당	각 변수가 어느 블록 구간에서 살아 있는가? (겹치지 않으면 같은 레지스터 재사용)
테스트 커버리지	테스트가 실제로 밟고 지나간 화살표는 전체 중 몇 개인가?

여기서 죽은 코드란 어떤 실행 경로로도 도달할 수 없어 실행될 일이 없는 코드를 뜻하고, 레지스터 할당이란 한정된 CPU 내부 저장 공간(레지스터)에 변수들을 효율적으로 배치하는 일을 뜻한다.

다이어그램 설명. 죽은 코드 탐지를 보여준다. 진입에서 출발해 화살표를 따라가면 처음 두 블록을 거쳐 종료에 닿지만, 따로 떨어져 종료로만 연결된 블록에는 어떤 경로로도 도착할 수 없다. 들어오는 화살표가 하나도 없는 외톨이 블록으로 그린 이유는, "도달 불가능"이 그래프에서 곧 "들어오는 엣지가 없음"으로 깔끔하게 정의되기 때문이다. 컴파일러는 이런 블록을 안전하게 지워 결과물을 줄인다. 함정은 예외 처리나 동적 호출처럼 그래프에 안 보이는 진입 경로가 있을 때인데, 그걸 놓치면 멀쩡한 코드를 죽은 코드로 오인할 수 있다.

다이어그램 설명. 테스트 커버리지를 그래프 위에서 본 모습이다. 실선 화살표는 테스트가 실제로 지나간 경로, 점선 화살표는 한 번도 밟히지 않은 경로다. 분기 지점에서 한쪽 가지만 실선인 것을 보면 "거짓일 때의 코드는 테스트가 안 됐다"가 즉시 드러난다. 흐름을 위에서 아래로 두고 안 밟힌 가지만 점선으로 구분한 이유는, 커버리지가 결국 "전체 화살표 중 밟은 화살표의 비율"이라는 그래프 문제임을 보이기 위해서다. 함정은 모든 줄을 한 번씩 실행했다고 안심하는 것인데, 줄(라인)을 다 밟아도 분기(엣지)의 한쪽은 영영 안 밟힐 수 있다.

한 번 그려둔 그래프 하나로 이렇게 여러 분석이 갈라져 나온다는 점이 CFG의 진짜 힘이다. 각 분석마다 코드를 다시 읽는 게 아니라, 공통의 흐름 지도 위에서 서로 다른 질문을 던지는 것이다.

6. 코드 위키 자동생성에 왜 핵심인가

다시 내 취미 프로젝트로 돌아오면, 작은 AI 서버가 코드를 읽고 위키를 쓰게 하려면 코드를 "설명할 수 있는 구조"로 먼저 바꿔야 한다. 함수 본문을 글자 그대로 모델에 던지는 것과, "이 함수는 진입 후 한 번 갈라졌다가 한 번 되돌아오는 루프를 거쳐 두 갈래로 끝난다"는 흐름 구조를 함께 주는 것은 결과물의 정확도가 다르다.

그리고 CFG는 끝이 아니라 시작이다. CFG는 함수 한 개의 안쪽 흐름만 본다. 여기에 "어떤 값이 어디서 만들어져 어디서 쓰이는가"를 더하면 데이터흐름 그래프가 되고, 제어와 데이터 의존을 함께 묶으면 프로그램 의존 그래프가 되며, 이들을 통합하면 코드 속성 그래프가 된다. 이 스펙트럼에서 CFG는 가장 안쪽 — 함수 하나의 흐름을 보는 — 첫 번째 층이다.

다이어그램 설명. CFG에서 출발해 점점 더 많은 정보를 얹어가는 표현의 스펙트럼이다. 함수 안쪽 흐름만 보는 가장 단순한 표현이 맨 위에 있고, 아래로 내려갈수록 값의 이동과 의존 관계가 더해져 풍부해진다. 위에서 아래로 한 줄로 쌓은 이유는 이들이 경쟁 관계가 아니라 층층이 쌓이는 관계임을 보이기 위해서다. 가장 안쪽 층을 제대로 세워두지 않으면 그 위 층들도 흔들린다 — 그래서 코드 위키든 정적 분석이든, 출발점은 결국 함수 하나의 흐름을 그리는 이 그래프다.

정리하면, 제어흐름 그래프는 "코드는 일직선이 아니다"라는 단순한 사실을 정직하게 그림으로 옮긴 것이다. 컴파일러를 위해 태어났지만, 죽은 코드 탐지부터 테스트 커버리지, 그리고 코드를 설명하는 위키 자동생성까지 — 함수 속 길을 알아야 하는 모든 일의 공통 출발점이 되었다. 집의 작은 서버에서 코드를 이해시키는 일을 하다 보니, 가장 먼저 손이 가는 도구가 이것이라는 게 새삼 납득됐다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

스킬의 끝은 스크립트인가 — 하네스 엔지니어링에서 스크립트는 '지능을 파낸 빈자리'다

타이젠 개발자, 윤진 — Thu, 2 Jul 2026 21:00:42 +0900

AI에게 어떤 일을 자동으로 시키는 작업을 하다 보면, 거의 항상 전용 스크립트가 하나씩 떨어진다. 특정 파이프라인을 돌리는 스킬을 만들고 있으면, 그 안에서 결국 그 파이프라인만을 위한 스크립트를 짜게 된다. 그래서 최근에 누군가에게 하네스 엔지니어링이라는 개념을 설명하던 중에 이런 질문을 받았다.

"그러면 스킬의 끝은 결국 스크립트 아니에요? 스킬을 잘 만들면 만들수록 스크립트가 완성되는 거고, 그 스크립트가 나오면 스킬의 역할은 끝나는 거잖아요."

좋은 문제 제기이다. 그 자리에서 "그건 아니다, 스킬은 스크립트 앞뒤로 벌어지는 일까지 포괄한다"고 정리되었는데, 끝나고 나니 핵심을 제대로 못 박은 느낌이 들었다. 답은 맞았지만 왜 그런지를 한 문장으로 못 박지 못했다. 이 글은 그 못다 한 설명을 다이어그램으로 정리한 것이다.

결론부터 한 문장으로 박아 두면 이렇다.

스크립트는 "이미 풀린 문제를 고정한 것"이고, 스킬은 "문제를 푸는 행위 전체를 소유한 것"이다. 그래서 스크립트는 스킬이 만들어내는 부산물이지 목적지가 아니다.

먼저 용어 정리 — 하네스 엔지니어링과 스킬

본론 전에 두 단어를 풀어 둔다. 도메인 밖 독자가 이 둘을 모르면 나머지가 통째로 막히기 때문이다.

하네스(harness) 엔지니어링은, LLM(Large Language Model, 대규모 언어 모델)을 한가운데 두고 그 주위에 가드레일·재시도·검증 같은 통제 장치를 짜 넣어 "혼자 두면 들쭉날쭉한 모델"을 "믿고 맡길 수 있는 일꾼"으로 만드는 설계 작업이다. 말(馬)에 마구(harness)를 채워 마차를 끌게 하는 것에 비유하면 된다 — 말의 힘(LLM의 생성 능력)은 그대로 두되, 가고 싶은 방향으로만 가도록 묶는다. 여기서 주된 행위자(main actor)는 어디까지나 LLM이고, 코드는 그 LLM을 감싸 보조한다. (참고로 LLM을 보조하는 이 구조를 "하네스"라 부르고, 사람의 개입 없이 스스로 판단하고 행동하는 자율 행위자를 "에이전트"라 부른다 — 둘은 통제의 주체가 다르다.)

스킬(skill)은 그 하네스를 특정 작업에 맞춰 묶어 둔 "재사용 가능한 일 처리 묶음"이다. 절차서(이 일은 어떤 순서로, 무엇을 보고 하는지) + LLM의 판단 + 필요하면 호출하는 스크립트가 한 덩어리로 들어 있다. "캘린더를 정리해 줘" 한마디에 알아서 일을 끝내는 것이 스킬이다.

1. 질문자의 머릿속 그림 — 일직선 모델

질문자가 그린 그림은 이랬다. 스킬은 스크립트를 만들어내는 도구이고, 스크립트가 완성되면 임무가 끝난다는 일직선이다.

다이어그램 설명. 질문자의 모델을 그대로 그린 것이다. 핵심 메시지는 "스킬은 스크립트를 뽑아내기 위한 거푸집이고, 스크립트가 나오면 거푸집은 버려진다"는 일직선 인과다. 이 그림이 자연스러워 보이는 이유가 있다 — 실제로 스킬을 만들다 보면 손에 잡히는 산출물이 스크립트 한 개라서, 그게 결과물의 전부처럼 느껴진다. 함정은 이 그림에 "스크립트를 돌리기 전에 무엇을 판단했는가"와 "스크립트가 끝난 뒤 그 결과로 무엇을 하는가"가 통째로 빠져 있다는 점이다. 그 빠진 부분이 사실 스킬의 본체다.

2. 실제 그림 — 스크립트는 가운데 끼인 한 토막

실제 스킬은 일직선이 아니라, 스크립트를 가운데에 끼워 넣은 더 큰 루프다.

다이어그램 설명. 같은 작업을 실제 동작 순서대로 그린 것이다. 읽는 순서는 위에서 아래, 그리고 막히면 결과를 판단하는 마지막 단계에서 첫 판단 단계로 화살표가 되돌아간다. 스크립트를 실행하는 칸은 흐름의 한가운데 한 토막일 뿐이고, 그 앞에서 "무엇을·어떻게·지금 할까"를 정하는 판단과 그 뒤에서 "결과 해석·예외 처리·다음 행동"을 정하는 판단에 인간이 하던 일이 그대로 남아 있다. 일직선 모델과의 결정적 차이는 결과를 판단하는 단계에서 다시 처음 판단으로 돌아가는 화살표다 — 결과가 이상하면 다시 판단해서 다른 파라미터로 스크립트를 또 돌린다. 일직선에는 이 되먹임(feedback)이 없다. 질문자가 본 것은 이 그림에서 스크립트를 실행하는 한 칸뿐이었고, 그 칸을 둘러싼 판단 단계들을 못 본 것이다.

3. 스킬을 해부하면 세 개의 층이 나온다

왜 스크립트가 한 토막에 불과한지를 더 정확히 보려면, 스킬이 인간이 하던 일을 세 종류로 쪼개 각각 다른 것으로 대체한 묶음이라는 점을 봐야 한다.

다이어그램 설명. 스킬 내부를 세 층으로 분해한 그림이다. 핵심 메시지는 "스킬은 한 덩어리가 아니라, 인간 노동의 세 가지 다른 측면을 각각 대체한 합본"이라는 것이다. 반복 노동은 스크립트로, 판단력은 LLM으로, 전문성·순서 감각은 절차서로 대체된다. 화살표를 보면 절차서가 LLM을 지휘하고, LLM이 필요할 때만 스크립트를 호출하며, 스크립트 결과는 다시 LLM에게 돌아간다. 즉 스크립트는 LLM의 손발이지 머리가 아니다. 질문자는 이 셋 중 스크립트만 보고 "그게 끝 아니냐"고 한 것인데, 절차서와 LLM 판단이 빠지면 그건 스킬이 아니라 그냥 정해진 시각에 실행되는 스크립트일 뿐이다.

4. 지능은 어디로 갔나 — 스크립트의 "앞뒤"로 밀려난다

여기가 이 글에서 가장 중요한 대목이다. 스킬을 만든다고 지능이 사라지는 게 아니다. 지능은 결정적 코어(스크립트) 바깥, 즉 앞과 뒤로 밀려날 뿐이다.

다이어그램 설명. 한 작업을 "스크립트 전 / 스크립트 / 스크립트 후" 세 구간으로 가른 그림이다. 가운데 스크립트는 입력만 정해지면 항상 같은 출력을 내는 결정적(deterministic) 코어라서 지능이 필요 없다 — 오히려 여기에 LLM의 비결정성이 끼어들면 매번 결과가 달라져 해롭다. 반면 양쪽 구간은 본질적으로 애매하다. 스크립트 전 단계에서는 입력이 지저분하게 들어오고, 스크립트 후 단계에서는 세상이 예외를 던지고 결과를 누군가 해석해야 한다. 핵심 결론은 "지능은 없어진 게 아니라 결정적 코어의 가장자리로 밀려났다"는 것. 질문자가 본 스크립트는 정확히 이 그림 한가운데 박스 하나였고, 그 위아래의 판단 영역 두 개를 못 본 셈이다. 놓치기 쉬운 함정은 "스크립트가 잘 짜이면 양쪽 판단도 줄어들 것"이라는 기대인데, 실제로는 반대다 — 결정적인 부분을 스크립트로 떼어낼수록, 남는 것은 점점 더 "판단할 수밖에 없는 것"만 농축된다. 그 이유를 다음 그림에서 본다.

5. 스크립트는 어떻게 생겨나는가 — "동결"의 과정

스크립트는 처음부터 목표였던 적이 없다. 작업을 LLM에게 시키다 보면 "이 부분은 매번 똑같네"라는 조각이 눈에 띄고, 그 조각만 떼어 코드로 굳히는(freeze) 것이 스크립트다.

다이어그램 설명. 스크립트가 태어나는 과정을 시간순으로 그린 것이다. 출발점은 작업 전체를 LLM이 매번 판단으로 처리하는 상태 — 가장 유연하지만 느리고 비싸고 불안정하다. 진행하면서 "여기는 항상 같은 절차로 흘러간다"는 결정적 조각을 발견하면, 그 부분만 스크립트로 굳힌다. 그러면 남는 것은 정의상 "굳힐 수 없어서 남은 것", 즉 판단이 대체 불가능한 핵이다. 그리고 이 과정은 한 번으로 끝나지 않고, 남은 핵에서 다시 새로 굳힐 조각을 찾아 처음으로 돌아가는 루프를 돈다 — 작업을 더 하다 보면 또 굳힐 조각이 보인다. 여기서 짚을 점은, 스크립트로 떼어내는 기준 자체가 "여기엔 LLM 판단이 아무 가치를 더하지 않고 비용·위험·들쭉날쭉함만 더한다"는 것이라는 사실이다. 그러니 떼어내고 남는 부분은 논리적으로 반드시 "판단이 필요한 부분"일 수밖에 없다.

6. 그래서 스크립트는 "지능을 파낸 빈자리"다

앞 그림의 결론을 비유 하나로 못 박아 보자. 조각(彫刻)에는 두 방식이 있다. 돌을 깎아 형상을 튀어나오게 만드는 양각(陽刻)과, 반대로 형상 부분을 파내어 움푹 들어가게 만드는 음각(陰刻)이다. 스크립트는 작업에서 지능을 파내고 남은 음각이다 — 여기서는 이 표현을 비유로 쓴다.

다이어그램 설명. 음각 비유를 구조로 그린 것이다. 작업 전체에서 결정적인 부분을 파내면, 손에 잡히는 조각(스크립트)과 파낸 자리(판단의 핵)가 동시에 생긴다. 질문자는 손에 잡히는 조각을 가리키며 "이게 결과물 아니냐"고 했지만, 스킬이 진짜로 다루는 것은 그 옆의 빈자리, 즉 판단의 핵이다. 비유를 끝까지 밀면 이렇다 — "스킬의 끝은 스크립트냐"는 질문은, 조각가에게 "조각의 완성은 깎아내서 바닥에 떨어진 돌가루냐"고 묻는 것과 같다. 돌가루(스크립트)는 작업의 부산물이고, 작품은 그것을 파내고 드러난 형상(판단 구조) 쪽이다.

7. 판별 기준 — 끝이 스크립트인 작업 vs 끝이 스킬인 작업

그러면 "끝이 정말 스크립트인 작업"은 아예 없는가? 있다. 다만 그런 작업은 애초에 스킬로 만들 필요가 없는 작업이다. 이 구분이 질문자에게 줄 수 있는 가장 실용적인 판별 기준이다. 비교를 위해 두 경우를 따로 그린다.

▲ 닫힌 작업 — 끝이 스크립트인 경우

▲ 열린 작업 — 끝이 스킬인 경우

두 다이어그램 설명. 같은 질문(가장자리가 결정적인가?)에서 갈라지는 두 갈래를 위아래로 나눠 그렸다. 위쪽 닫힌 작업은 입력·예외·결과 해석이 전부 미리 정해져 있어 판단할 게 없다 — 로그 회전처럼. 이런 건 예약 실행 한 줄과 스크립트면 충분하고, 굳이 스킬로 감쌀 이유가 없다. 아래쪽 열린 작업은 가장자리가 애매해서, 입력을 해석하고 예외를 수습하고 결과를 판단하는 일이 남는다 — 여기서만 스킬이 의미를 갖고, 스크립트는 그 안의 부품이 된다. 여기서 한 번 더 꼬는 결론이 나온다. "우리가 어떤 작업을 굳이 스킬로 만들고 있다"는 사실 자체가, 그 작업의 가장자리에 판단이 남아 있다는 증거다. 닫힌 작업이었다면 애초에 스크립트만 짜고 끝냈을 테니까. 즉 "스킬로 만드는 중"이라면 답은 이미 "끝은 스크립트가 아니다"로 정해져 있다.

8. 비유로 마무리 — 조종사와 오토파일럿

마지막으로 이 관계를 가장 직관적으로 보여주는 비유 하나. 비행기의 조종사와 오토파일럿(autopilot, 자동 비행 장치) 관계가 스킬과 스크립트의 관계와 똑같다.

다이어그램 설명. 한 번의 비행을 스킬-스크립트 구조에 대입한 그림이다. 오토파일럿(스크립트)은 지루하고 결정적인 순항 구간을 대신 맡는다 — 항로가 정해지면 같은 입력에 같은 동작을 반복하는, 사람이 굳이 손댈 이유가 없는 부분이다. 하지만 이륙·착륙처럼 변수가 많은 국면과, 난기류 같은 예외 상황에서는 통제가 다시 조종사(판단)에게 돌아온다. 누구도 "오토파일럿이 있으니 조종사는 필요 없다"거나 "비행의 끝은 오토파일럿이다"라고 말하지 않는다. 오토파일럿은 조종사가 비행을 더 잘 수행하기 위한 도구일 뿐, 비행의 주체는 끝까지 조종사다. 스크립트와 스킬의 관계가 정확히 이것이다.

그래서, 질문에 다시 답하면

"스킬의 끝은 스크립트인가?" — 아니다. 그리고 그 이유는 "스킬이 스크립트보다 뭔가 더 많은 일을 하기 때문"이라는 양적인 설명보다, 구조적인 설명이 더 정확하다.

스크립트는 작업에서 "이미 풀려서 굳힐 수 있는 부분"만 떼어낸 음각이다. 떼어내는 기준이 "여기엔 판단이 불필요하다"이므로, 떼어내고 남는 것은 정의상 "판단이 대체 불가능한 핵"이다.
지능은 스킬을 만든다고 사라지지 않고, 결정적 코어의 앞뒤로 밀려난다. 요청 해석·실행 여부 판단(앞)과 결과 해석·예외 수습·다음 행동(뒤)이 스킬의 본체다.
"스킬로 만들고 있다"는 사실 자체가 답을 정해 준다. 가장자리가 완전히 결정적인 닫힌 작업이었다면 스크립트만 짜고 끝냈을 것이다. 굳이 스킬로 감쌌다면, 그 작업엔 스크립트로 굳힐 수 없는 판단이 남아 있다는 뜻이다.

스크립트는 스킬의 목적지가 아니라, 스킬이 일하면서 떨어뜨리는 부산물이다. 조각가가 형상을 드러내며 떨어뜨린 돌가루처럼. 우리가 정말 만들고 있는 것은 그 돌가루가 아니라, 그것을 파내고 드러난 판단의 형상 — 즉 "이 일을 어떻게 판단하며 끝까지 끌고 갈 것인가"라는 구조 그 자체다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.