graphify·Serena를 너무 늦게 도입한 것

AI에게 코드를 고치라고 하면, AI는 먼저 파일을 잔뜩 읽습니다. 어디를 고쳐야 할지 모르니까요. 이 “읽기”가 토큰을 태우고, 컨텍스트를 채우고, 결국 환각을 부릅니다. 코드를 그냥 “읽을 텍스트 더미”가 아니라 탐색할 지도이자 정밀하게 다룰 심볼로 대하는 두 도구를 — graphify와 Serena를 — 훨씬 일찍 깔았어야 했습니다. 이 글은 “전부 읽고 고치기가 왜 비싼지”, “지도와 메스가 각각 무엇을 하는지”, “둘을 어떤 순서로 엮는지”를 풀어 쓴 기록입니다.

”전부 읽고 고치기”의 비용

초기엔 AI가 코드를 이렇게 다뤘습니다. 함수 하나를 바꾸려고 관련된 파일 여러 개를 통째로 읽고, 그 내용으로 컨텍스트(작업 기억)를 가득 채운 다음, 추측으로 수정 범위를 정했습니다. 사람이라면 “정의로 이동”, “참조 찾기” 같은 IDE 기능을 쓸 자리를, AI는 전체 읽기로 때운 것입니다.

용어: 컨텍스트(context)

AI가 한 번에 들고 있을 수 있는 “작업 기억”의 양입니다. 읽은 파일·대화가 여기에 쌓입니다. 한정돼 있어서, 큰 파일을 통째로 읽으면 금세 가득 찹니다. 가득 차면 비싸지고(토큰↑), 흐려지고(집중력↓), 헛것이 보이기 시작합니다(환각).

이 방식의 문제는 셋이었습니다.

• 토큰 폭증 — 큰 파일을 읽을수록 비용이 올라갑니다. 한 줄 고치려고 천 줄을 읽으면, 그 천 줄이 매번 값으로 청구됩니다.
• 파급범위 누락 — 그 함수를 누가 호출하는지 다 못 보고 고쳐서, 엉뚱한 다른 곳을 깨뜨렸습니다. 눈앞에 로드된 파일만 보고 판단하니까요.
• 환각(hallucination) — 컨텍스트가 가득 차면 AI의 집중이 흐려져, 존재하지 않는 함수를 지어내거나 필드 이름을 틀립니다.

이건 모델의 한계가 아니라 도구의 부재였습니다. 사람 개발자에게서 IDE의 코드 탐색 기능을 빼앗으면 똑같이 헤맵니다. AI에게도 그에 해당하는 도구가 필요했는데, 저는 그걸 한참 비워뒀습니다.

같은 한 줄을 고칠 때 읽는 양의 차이(개념도). 전부 읽기는 파일 전체를 컨텍스트로 끌어옵니다. 그래프 질의 + 심볼 편집은 필요한 노드·심볼만 봅니다 — 토큰도 환각도 함께 줄어듭니다.

두 도구 — 지도와 메스

5월까지 자리 잡은 두 도구는 역할이 또렷이 갈립니다. 하나는 지도, 하나는 메스입니다.

graphify — 코드를 지식그래프로

graphify는 코드베이스 전체를 지식그래프로 만듭니다. 함수·모듈이 노드(점)가 되고, “A가 B를 호출한다” 같은 관계가 간선(선)이 됩니다. 그러면 수정 전에 그래프에 이렇게 물어볼 수 있습니다 — “이 함수를 건드리면 영향이 어디까지 가는가?”

용어: 지식그래프 / god node

코드를 점(함수·모듈)과 선(호출 관계)의 그래프로 표현한 것입니다. 그중 들어오는 선이 유독 많은 노드, 즉 수십 곳에서 호출되는 함수를 god node라 부릅니다. 이걸 잘못 건드리면 수십 곳이 동시에 깨집니다 — 그래서 손대기 전에 사람에게 보고하도록 규칙으로 묶었습니다.

특히 god node를 미리 탐지하는 게 컸습니다. “이 함수는 호출처가 너무 많으니, 손대기 전에 멈추고 사람에게 보고하라”는 규칙을 그래프에 연결했습니다. 전체 그래프 리포트를 통째로 읽으면 또 토큰 폭증이라, *필요한 노드만 질의(query)*하게 했습니다 — “전체 스캔 금지”가 원칙이었습니다.

Serena — 심볼 단위 정밀 편집

graphify가 지도라면 Serena는 메스입니다. 파일을 통째로 읽고 텍스트를 통째로 치환하는 대신, 심볼(함수·클래스) 단위로 찾고 바꿉니다.

• “이 함수의 본문만 교체” — 파일 전체를 로드하지 않고 그 함수만.
• “이 심볼을 참조하는 곳을 모두 찾아라” — 시그니처를 바꾸기 전에 영향처를 정확히 확인.
• “이 심볼을 안전하게 삭제” — 참조가 없는지 확인한 뒤에만.

읽는 양이 줄면 토큰도 환각도 함께 줍니다. 큰 수술을 작은 절개로 바꾸는 셈입니다.

스택 순서가 핵심

둘은 따로 노는 게 아니라 한 줄로 엮였습니다. 순서가 중요합니다.

1. graphify (지도 펼치기) — 수정 대상 함수를 그래프에 질의해 파급범위와 god node 여부를 먼저 확인합니다.
2. Serena (메스로 도려내기) — 확인된 범위 안에서 심볼만 정밀하게 고칩니다. 파일 전체를 읽지 않습니다.
3. graphify —update (지도 갱신) — 큰 변경(새 모듈·스키마 등) 후에는 그래프를 다시 갱신해 지도를 최신으로 유지합니다.

“전체 스캔 금지”가 원칙

이 도구들의 핵심 가치는 “더 많이 읽게 해주는 것”이 아니라 **“덜 읽고도 정확하게 하는 것”**입니다. 그래서 도구를 쓸 때도 절제 규칙을 같이 걸었습니다 — 같은 질의를 반복하지 말고, 한 번 본 결과는 세션 안에서 재활용하고, 전체 리포트를 통째로 읽지 말 것. 도구를 잘못 쓰면 오히려 토큰을 더 태웁니다. (그래프 추출처럼 무거운 보조 작업은 더 저렴한 모델에 맡기도록 강제하는 게이트까지 뒀습니다.)

도구	비유	해결하는 문제	핵심 동작
graphify	지도	파급범위 누락 · god node 사고	”누가 이 함수를 부르나” 질의
Serena	메스	토큰 폭증 · 환각	심볼만 찾아 본문 교체

god node가 막아주는 사고

지도(graphify)의 가치가 가장 또렷한 순간은 god node를 만났을 때입니다. 어떻게 사고를 막는지 단계로 펼쳐 봅니다.

1. 수정 요청 — “이 공통 유틸 함수의 동작을 살짝 바꿔주세요.”
2. 그래프 질의 — 고치기 전에 graphify에 묻습니다. “이 함수를 부르는 곳이 몇 군데인가?”
3. god node 판정 — 호출처가 수십 군데로 나옵니다. 이건 god node입니다. “살짝 바꾸기”가 수십 곳에 동시에 파급된다는 뜻입니다.
4. 멈추고 보고 — 규칙에 따라 곧장 고치지 않고 사람에게 보고합니다. “이 함수는 영향 범위가 큽니다. 정말 바꿀까요, 아니면 새 함수를 만들까요?”
5. 안전한 결정 — 영향 범위를 알고 내린 결정이라, 모르고 고쳐서 수십 곳을 깨뜨리는 사고를 피합니다.

지도가 없었다면 2~3 단계가 통째로 빠집니다. AI는 눈앞에 로드된 파일만 보고 “그냥 고치면 되겠지” 하고 손을 댑니다. 그리고 한참 뒤, 전혀 관련 없어 보이는 다른 화면이 깨졌다는 보고를 받고서야 파급을 깨닫습니다. 지도는 “고치기 전에 영향을 보는” 단계를 강제로 끼워 넣어, 이 뒤늦은 발견을 앞으로 당깁니다.

늦게 깐 대가

이 두 도구가 자리 잡기 전까지, 같은 작업에 더 많은 토큰을 태웠고, 파급범위를 놓쳐 생긴 버그를 따로 잡아야 했습니다. 도구 하나하나가 비쌌던 게 아니라, 도구가 없어서 매 작업이 비쌌습니다. 일찍 깔았다면 그 누적 비용을 통째로 아꼈을 것입니다.

코드 비대화가 어떻게 토큰·환각으로 번지는지는 별도의 코드 품질 이야기와 맞물립니다. 큰 파일을 통째로 읽어야 하는 상황 자체가 — god 파일이 — 토큰·환각의 근원이기 때문입니다. 지도와 메스는 그 근원을 우회하는 도구입니다.

함정: “도구 도입은 나중에”

“일단 기능부터 만들고, 개발 도구는 나중에 정비하자”는 흔한 순서입니다. 그런데 코드 탐색 도구는 있고 없고가 매 작업의 단가를 바꿉니다. 나중으로 미룰수록, 도구 없이 태운 토큰과 놓친 파급범위 버그가 복리로 쌓입니다. 이건 “멋진 기능”이 아니라 기본 인프라입니다 — 첫 주에 까는 게 맞습니다.

교훈

AI에게 코드는 “읽을 텍스트 더미”가 아니라 탐색할 그래프이자 편집할 심볼이어야 합니다. graphify로 파급범위를 먼저 보고(god node 탐지) → Serena로 심볼만 정밀하게 고치고 → 큰 변경 후 그래프를 갱신하면 — 토큰·환각·파급 누락이 동시에 줍니다. 단, 도구의 가치는 “더 읽기”가 아니라 “덜 읽고 정확하기”이니 전체 스캔은 금지입니다. 이 코드 지능화 도구는 멋진 기능이 아니라 AI 협업의 기본 인프라입니다. 첫 주에 깔았어야 했습니다.

---

이 글은 SL.AIMS를 만들며 겪은 현장 회고 중 하나입니다. 전체 그림은 〈사례연구: SL.AIMS〉에, 이 도구를 떠받치는 규칙·게이트는 〈루프를 닫다〉에 있습니다.