Cursor로 여러 파일을 고칠 때, 왜 호출부 절반을 빠뜨릴까?

Cursor나 Claude Code로 여러 파일에 걸친 수정(인터페이스 변경, 함수 이름 바꾸기, 모듈 분리——수십에서 수백 파일까지 이어지기도 함)을 해봤다면, 호출부 업데이트 누락, 잘못된 파일 수정, 공유 모듈 오염을 여러 번 겪었을 겁니다. 모델은 조각은 읽어도 시스템 전체는 못 읽습니다. 2026년 Agent는 테스트 실행과 PR 생성까지 자동화하지만, 팀이 커지고 저장소가 오래될수록 이 실패 패턴은 그대로입니다. 근본 원인은 종종 모델 부족이 아니라 조회 가능하고 증분 갱신되며 공유 가능한 코드 지식 그래프(Code Knowledge Graph)가 없기 때문입니다. 이 글은 그 그래프가 무엇인지, 벡터 RAG와 초장문 컨텍스트만으로는 왜 부족한지, Agent용 구조화된 '저장소 기억'을 어떻게 만들지 정리합니다.

Agent의 사각지대: 컨텍스트 창은 '지도'가 아니다

현대 AI 코딩 Agent의 전형적 흐름은 사용자 질문 → 관련 파일 검색 → 컨텍스트 주입 → diff 생성입니다. 검색 수단에는 @ 파일, ripgrep, embedding 유사도, 제품 내 codebase index 등이 있습니다. 이들은 '어떤 텍스트가 답과 닮았는가'에는 강하지만 '여기를 고치면 누구에게 파급되는가'에서는 체계적으로 실패합니다. 이유는 다음과 같습니다.

• 텍스트 chunk에 토폴로지가 없다: 분할이 호출 체인을 깨뜨립니다. 주석이 비슷한 두 함수가 함께 끌려와도 실제 호출 관계는 다른 chunk에 있습니다.
• grep은 문자열뿐이고 타입이 없다: 오버로드, 제네릭, 매크로 생성 코드, Swift extension 때문에 '같은 이름 ≠ 같은 심볼'입니다.
• 컨텍스트 예산은 제로섬: 200개 파일을 넣어도 경로상 허브 5개 파일이 무엇인지 모릅니다.
• 세션은 stateless: 지난 리팩터에서 나눈 모듈 경계를 다음 대화에서 다시 추측합니다.

시니어 엔지니어가 의존하는 것은 전체 코드 암기가 아니라 계층화된 지도——모듈 경계, 의존 방향, 테스트 위치입니다. 코드 지식 그래프는 그 지도를 외부화하고 기계가 읽으며 버전 관리 가능하게 만듭니다.

코드 지식 그래프란

좁은 의미에서 소프트웨어 공학용 속성 그래프(Property Graph) 또는 이종 그래프입니다. 노드는 코드 개체, 엣지는 검증 가능한 관계를 나타냅니다. 일반 '지식 그래프'와 달리 대부분의 엣지는 정적 분석이나 빌드 로그에서 결정적으로 도출되며 LLM 환각에 의존하지 않습니다.

가치는 노드 수가 아니라 다중 홉 추론의 재현성에 있습니다. '사용자 클릭부터 DB SQL까지'가 매번 추측이 아니라 고정 경로로 따라갈 수 있어야 합니다.

벡터 RAG와 비교: 의미적 유사 ≠ 구조적 관련

벡터 검색은 코드를 자연어 문단처럼 다루어 '결제 처리 같은 로직'을 찾기에 좋습니다. 다음 작업은 본질적으로 그래프 순회입니다.

• 폐기 flag 삭제 전 if (featureX)의 실제 참조(매크로·생성 코드 포함)를 열거.
• sync에서 async API로 바꿀 때 전 저장소 호출 스택과 테스트 더블 목록.
• God class 분리 시 응집 서브그래프와 외부 fan-out 식별.

실무에서는 하이브리드 검색이 정석입니다. 의도 분류 후 구조형은 그래프 도구, 탐색형은 벡터로 보냅니다. 결과는 '그래프 경로상 노드 우선'으로 정렬해 컨텍스트에 자릅니다. embedding만 쌓고 엣지를 만들지 않으면 파일과 의존이 많은 monorepo에서 PR 머지율이 천장에 닿기 쉽습니다.

LSP / IDE 인덱스와 비교: 세션 안 vs 조직 전체

Language Server는 점프, 참조, 이름 바꾸기를 제공하며 그래프 노드와 크게 겹칩니다. 차이는 수명 주기와 소비자입니다.

• LSP는 지금 연 워크스페이스에 묶이며 CI나 원격 Runner의 Agent에는 같은 LSP가 없는 경우가 많습니다.
• API 이름 바꾸기는 대화형입니다. Agent에는 배치·스크립트 가능한 get_callers(symbol_id)가 필요합니다.
• 그래프에는 업무 메타데이터(owner, deprecated 날짜, 컴플라이언스 태그)를 붙일 수 있습니다——LSP는 여기를 모델하지 않습니다.
• 브랜치 비교(main vs feature)는 그래프에서 두 부분 그래프 diff로 다룰 수 있습니다.

현실적인 길은 LSP / 컴파일러 프론트를 사실 소스로, 그래프를 영속화와 Agent 프로토콜 계층으로 쓰는 것입니다. 바퀴를 다시 만들지 마세요.

권장 아키텍처: 3층 기억, 중앙에 그래프

Agent의 '저장소 이해'를 3층으로 나누면 개념 혼란이 줄어듭니다.

구조층(코드 지식 그래프)

답하는 질문: 코드는 무엇이고 어떻게 연결되는가. 정적 분석, Bazel/Gradle/Xcode 프로젝트 그래프, OpenAPI/Proto에서 생성. 갱신 트리거: merge, 주기적 풀, 파일 watch. 저장: 그래프 DB 또는 인접 인덱스 SQLite. 외부 노출: MCP tools.

의미층(벡터 인덱스)

답하는 질문: 어떤 구현이 사용자 설명과 '닮았는가. 함수 본문, 주석, ADR, Issue를 embedding. 그래프와 동일 symbol_id를 공유해 'chunk는 찾았는데 심볼을 못 찾는' 상황을 막습니다.

에피소드층(작업·설계 기억)

답하는 질문: 지난번 왜 그렇게 고쳤는가. PR 요약, Runbook, 또는 OpenHuman류 Memory OS Topic 노드. 그래프를 대체하지 않고 '논의됨', '폐기' 같은 가중치를 엣지에 얹습니다.

그래프가 직접 개선하는 5가지 Agent 작업

1. 다중 파일 리팩터: 이름 바꾸기, 인터페이스 추출, 패키지 이동——호출 엣지를 따라 일괄 수정해 누락 파일을 줄입니다.
2. 결함 위치 찾기: 스택 top에서 calls 엣지를 따라 공유 중간 계층을 찾습니다. 오류 문자열 전체 검색보다 정확합니다.
3. 신규 멤버 onboarding: '결제 모듈 진입점' = UI route에서 service까지 부분 그래프. README보다 빠릅니다.
4. 테스트 선택: 변경 노드의 covers 엣지로 최소 테스트 세트를 골라 CI를 단축——TestFlight 검증 파이프라인과 같은 머신에서 편성할 수 있습니다.
5. 보안·컴플라이언스: 민감 API의 reachable_from 쿼리는 정규식보다 정확합니다.

구축 요점: 증분, 실패 허용, 언어 인식

최소 파이프라인(앞 HowTo schema와 일치):

• 파싱: tree-sitter(다언어), SourceKit(Swift), rust-analyzer 등으로 AST 심볼 테이블 출력.
• 엣지 구축: 호출은 보수적 근사(누락보다 오탐을 피함). 상속·구현은 엄격히.
• 증분: 파일 단위 hash. 변경 파일의 상하 2-hop 이웃을 국소 무효화.
• 버전: 그래프에 commit_sha. Agent 도구 인자에도 필수로 넣어 브랜치 혼용 방지.
• 도구면: 6~10개 고수준 API(get_callers, get_module_graph 등). ad-hoc Cypher는 모델에 쓰게 하지 않음.

{
  "symbol": "PaymentService.charge",
  "callers": [
    {"id": "CheckoutViewModel.submit", "file": "ios/Checkout/VM.swift", "line": 88},
    {"id": "SubscriptionRenewalJob.run", "file": "jobs/renewal.ts", "line": 41}
  ],
  "graph_version": "a3f9c2e"
}

Apple / iOS 대규모 코드베이스의 특수성

Swift, Objective-C, SPM, Xcode project 조합에서는 '순수 텍스트 RAG'가 특히 불리합니다. extension, 조건부 컴파일, @objc 브리지로 정적으로는 안 보이고 런타임에 드러나는 엣지가 생깁니다. 그래프 구축 시 다음을 염두에 둡니다.

• Xcode와 동형 macOS 환경에서 파싱(로컬 Mac 또는 Mac mini M4 클라우드 호스트). Linux CI에서 조용히 스킵되는 실패를 피합니다.
• .xcodeproj / SPM target 의존을 Module급 엣지로 만들고 심볼급으로 내려갑니다.
• Flutter iOS 혼합 저장소에서 Dart ↔ Platform Channel 크로스 언어 엣지(수동 주석 + 생성 코드 스캔).

인덱스는 CPU/디스크를 많이 쓰고 시간도 깁니다. 전용 Cloud Mac에서 7×24 증분 실행하고 로컬 Cursor는 SSH/MCP로 원격 그래프 API를 소비——노트북은 가벼운 클라이언트만 유지합니다. Mac VPS vs Cloud Mac에서 말한 '연산과 디스크 분리'와 같은 결론입니다. 그래프 서비스를 oversubscribed VPS와 I/O 경쟁시키지 마세요.

OpenClaw, agentmemory와 역할 분담

OpenClaw 같은 다채널 Agent는 예약 작업, Webhook, 외부 도구 오케스트레이션에 강합니다. 코드 지식 그래프는 그중 '저장소 읽기' 계열의 구조화 백엔드입니다. OpenHuman Memory Tree 같은 개인 기억은 결정과 대화 맥락을 남기는 것이지 호출 그래프 대체가 아닙니다.

권장 통합: OpenClaw / Cursor MCP에 code_graph_* 도구 등록. Memory OS에는 '이번 리팩터로 팀 X에 알림 완료' 같은 메타데이터만 두고, 검색 시 그래프 버전을 감사 로그에 기록.

흔한 함정과 안티패턴

• LLM에 호출 관계 '추측'시키기: 회귀 테스트 불가. merge 후 그래프가 썩습니다.
• 그래프와 소스 비동기: 그래프가 없는 것보다 위험——Agent가 자신 있게 잘못된 파일을 고칩니다.
• 파일급 노드만: @folder와 큰 차이 없어 rename/refactor를 못 받칩니다.
• 그래프 전문을 prompt에 dump: 도구 호출 + 다중 홉 자르기가 맞습니다.
• 생성 코드와 lockfile 무시: Protobuf, GraphQL codegen, Swift macro는 빌드 훅에 포함.

FAQ

벡터 RAG와 택일? 아닙니다. 그래프는 구조, 벡터는 의미. 같은 symbol_id로 연결.

LSP만으로 충분? 개인·단일 세션에는 가깝지만 조직 Agent에는 LSP 출력을 그래프에 영속화.

소규모에도 필요? '호출부를 매번 누락' 신호가 보이면. 비용은 managed index로 분산 가능.

갱신 주기? main merge마다 증분. 긴 작업 전 graph_version 검증.

제품 index 있는데 자체 구축? CI 연동, 감사, 도구 간 단일 진실 원천이 필요하면 yes.

클라oud Mac 용도? 영속 그래프 DB, Swift/ObjC 파싱, Xcode 동기, SSH로 로컬 IDE 소비.

보안? 모듈 구조와 심볼명 포함. 권한은 소스와 동급. 공개 LLM 로그에 내보내지 않음.

Memory OS와? 그래프 = 구조적 사실. 기억 = 결정과 선호. 인터페이스로 조합.

결론

AI 코딩 Agent의 상한은 점점 저장소 구조 이해에 달리며, 한 번의 prompt 기교로는 결정되지 않습니다. 코드 지식 그래프는 호출 체인, 모듈 경계, 테스트 매핑을 조회·버전·감사 가능한 데이터로 외부화하고 벡터 검색·개인 Memory OS와 3층으로 보완합니다. 2026년에도 '더 큰 컨텍스트 + 파일 검색'만 믿는 팀은 다중 파일 변경이 많은 monorepo와 Apple 툴체인에서 누락 수정 비용을 반복 지불할 것입니다. macOS 파싱과 영속 디스크라는 올바른 환경에 인덱스를 두는 것——Agent를 '코드를 쓸 수 있는' 수준에서 '시스템을 고칠 수 있는' 수준으로 올리는 최소 공학 투자입니다.