덕삼
블로그

100만 줄 넘는 코드베이스에서 에이전트는 모듈 경계 안에 가둔다 — 600만 줄 저장소에서 다시 본 원칙

· 수정 2026-11-18

100만 줄이 넘는 코드베이스에서 AI 코딩 에이전트에게 무엇을, 얼마나 보여 줘야 할까요?

답부터 적습니다. 전체를 보여 주려는 시도를 버립니다. 모듈 경계로 에이전트가 읽을 범위를 가두고, 검색으로 필요한 조각만 주고, 자동 검사로 안전을 확인합니다. 8월에 쓴 이 원칙을 석 달 동안 두 저장소에 적용했습니다. 대부분은 맞았습니다. 틀린 곳은 “정확 검색 도구를 먼저 들인다"였습니다. 화면끼리 문자열 ID 로 이어진 레거시에서는 범용 코드 그래프가 영향 범위의 1~4% 만 찾았습니다. 아래 수치는 2026-11-18 에 다시 셌습니다.

울타리로 칸을 나눈 거대한 서고. 에이전트 로봇은 모듈 B 칸 안에서 책 한 권만 들고 있고, 옆 칸에는 자물쇠와 변경 금지 팻말이 걸려 있다. 칸 밖의 사서 로봇이 색인 카드 서랍에서 카드 한 장을 꺼내 건넨다

그림으로 줄이면 이렇습니다. 에이전트는 서고 전체가 아니라 울타리 친 한 칸에서 일합니다. 필요한 책은 사서가 색인으로 찾아 건네고, 잠긴 칸은 열지 않습니다.

이 글은 측정 보고서가 아니라 설계 원칙입니다. 문서 200줄, 컨텍스트 40~50%, 주 1회 같은 기준은 제가 쓰는 눈금이고 실험값이 아닙니다.

근거로 쓴 저장소는 두 곳입니다

둘 다 비공개 저장소라 이름과 커밋 해시는 적지 않습니다.

항목레거시 분석 저장소에이전트 작업 저장소
추적 파일58,5962,773
줄 수약 602만 (JS·JSP·XML·Java·HTML)약 13.5만 (소스)
커밋975 (2026-05-13 부터)1,120 (2026-09-23 부터)
에이전트 계정 이름의 커밋35841 (75%)
코드 그래프 인덱스파일 34,499, 노드 120,510, 간선 570,272없음

레거시 쪽은 웹 시스템의 운영 소스 사본과 새 프로젝트를 함께 담습니다. 큰 덩어리는 화면 JS 318만 줄, 서비스 XML 119만 줄, JSP 78만 줄입니다. 작업 저장소는 그 시스템에 붙일 MCP 서버와 분석 도구를 에이전트가 주로 짭니다. 레거시 쪽 커밋은 대부분 사람 계정으로 남아서 에이전트가 쓴 커밋 수는 알 수 없습니다.

모듈 경계가 곧 컨텍스트 경계입니다

100만 줄에서 에이전트의 성능을 정하는 것은 프롬프트가 아니라 모듈 경계입니다. 한 작업에서 읽을 코드가 모듈 하나(수천~수만 줄)에 갇히도록 경계를 잡습니다. 순환 의존이나 모든 것을 아는 거대 모듈(god module)이 있으면 어떤 컨텍스트 전략도 통하지 않습니다. 그래서 에이전트를 들이기 전에 모듈화가 먼저일 수 있습니다.

레거시 저장소에서는 최상위 폴더가 그대로 경계가 됐습니다. 파일 수가 가장 많은 세 폴더(27,753개, 11,610개, 10,584개)는 운영 소스 사본이고 “읽기만, 수정 금지"입니다. 에이전트가 고치는 곳은 새 프로젝트 폴더뿐입니다. 은행 시스템처럼 계정계·정보계·채널계로 이미 나뉜 곳도 그 경계를 작업 경계로 쓰는 편이 안전합니다.

지도 파일은 줄 수보다 바이트를 잽니다

문서는 3단으로 둡니다. 레거시 저장소는 루트 AGENTS.md 138줄이 목차이고, 하위 프로젝트 8곳에 18~254줄짜리 AGENTS.md 가 있습니다.

단계담는 것레거시 저장소의 실제
L0 루트 지도하위 영역 목록과 어디에 무엇이 있는지루트 AGENTS.md 138줄
L1 영역 규칙불변 규칙, 금지 사항, 담당 인터페이스하위 AGENTS.md 8개
L2 경로별 규칙특정 경로를 고칠 때만 실리는 규칙.claude/rules/ 10개

Claude Code 공식 문서도 같은 구조를 권합니다. 대형 코드베이스 안내는 루트와 하위 폴더의 2단 CLAUDE.md 를 “A common split"으로 소개합니다. 메모리 문서는 파일 하나를 200줄 아래로 두라고 적습니다.

그런데 줄 수는 속일 수 있었습니다. 작업 저장소의 루트 AGENTS.md 는 191줄이라 200줄 기준을 통과합니다. 크기는 35,825바이트입니다. 한 줄이 길어서입니다. Codex 는 AGENTS.md 를 합쳐 기본 32KiB(32,768바이트)까지 싣습니다. 공식 문서는 한도에 닿으면 파일을 더 붙이지 않는다고 적습니다. 이 파일 하나가 그 한도를 3,057바이트 넘습니다. Codex 가 넘친 부분을 실제로 읽지 못하는지는 이번에 재지 않았습니다. 지도는 줄 수가 아니라 바이트로 잽니다.

범용 코드 그래프는 문자열로 이어진 화면을 읽지 못했습니다

옛 글은 정확 검색(LSP, ctags, tree-sitter, 저장소 전문 검색)을 먼저 들이라고 했습니다. import 와 함수 호출로 이어진 코드에서는 지금도 맞습니다. 레거시 화면 코드에서는 틀렸습니다.

2026-11-14 에 작업 저장소에서 오픈소스 코드 그래프 도구(graphify 0.9.108, LLM 을 쓰지 않는 코드 전용 추출)를 레거시 화면 코드에 돌렸습니다. 정답을 아는 변경 요청 4건으로 영향 범위 재현율을 쟀습니다.

측정범용 코드 그래프이 시스템 전용 분석기
변경 요청 4건의 재현율1~4%83~95%
화면 JS 5,018개 중 함수를 뽑은 파일272 (5%)해당 없음
파일 10,325개 그래프의 파일 사이 간선1,265해당 없음
대조군: Next.js 파일 1,102개의 파일 사이 간선20,260해당 없음

원인은 둘입니다. 화면 함수가 큰 객체 리터럴 안의 속성 함수와 콜백이라 심볼로 뽑히지 않았습니다. 화면 이동과 서버 호출은 move("화면ID") 처럼 문자열이라 호출 간선이 생기지 않았습니다. 같은 도구가 import 로 이어진 Next.js 코드에서는 간선을 20,260개 만들었습니다.

해석은 이렇습니다. 정확 검색이 기본이라는 원칙은 코드의 연결이 파서에 보일 때만 맞습니다. 연결이 문자열이면 그 문자열을 풀어 주는 전용 색인이 필요합니다. 이 결과를 보고 화면 영향도에는 전용 분석기를 유지하기로 했습니다. 범용 인덱스는 버리지 않았습니다. 레거시 저장소의 지침은 “코드 위치·호출 경로 탐색은 grep 전에 codegraph explore” 를 씁니다. 위치를 찾는 일과 영향 범위를 재는 일은 다른 도구가 맡습니다.

저장소 전문 검색 도구도 바뀌었습니다. Sourcegraph 는 2024-08 에 핵심 코드를 비공개 저장소로 옮겼습니다. 오픈소스로 쓸 것은 Apache-2.0 인 Zoekt 이고, 활발한 저장소는 sourcegraph/zoekt 입니다(2026-11-18 확인).

벡터 검색은 지금도 뒤로 미룹니다

작업 저장소의 코드 검색은 키워드(BM25) 검색으로 시작했습니다. 의미 검색은 설계 문서에 “열린 질문"으로 남아 있습니다. 옛 글이 든 벡터DB 의 위험 세 가지는 그대로입니다.

  1. 재인덱싱이 코드 변경을 못 따라가면 지워진 함수를 돌려줍니다. “결과 없음"보다 나쁩니다.
  2. 임베딩은 생김새가 비슷한 코드와 뜻이 이어진 코드를 잘 가르지 못합니다.
  3. 상위 k개 검색은 늘 무언가를 돌려주고, 무관한 조각이 컨텍스트를 더럽힙니다.

앤트로픽의 2026-05-14 글도 1번과 같은 이유를 듭니다. 에이전트가 직접 검색하면 “there’s no embedding pipeline or centralized index to maintain” 이라는 것입니다. 들일지는 “grep 으로 못 찾아 고생한 개념 검색이 주에 몇 번인가"로 정합니다.

변경 금지 구역은 문장보다 스크립트가 지킵니다

작업 지시서에는 작업 모듈, 읽어야 할 계약 문서, 변경 금지 구역, 완료 기준(CI 통과)을 적습니다. 경계 밖 수정이 필요하면 멈추고 보고하게 합니다. 그 수정은 별도 지시서와 세션으로 처리합니다.

문장만으로는 부족했습니다. 작업 저장소에는 배포본에서 되살린 프로젝트 파일이 있습니다. 한 작업의 중간 판에서 에이전트가 이 파일을 고쳤다가 다음 판에서 되돌렸습니다. 그날(2026-09-24) 수정 금지 규칙을 더하면서 스크립트도 막았습니다. 파일을 다시 쓰는 재생성 스크립트는 허용 환경 변수가 없으면 실행을 거부합니다. 정식 클론은 main 에 고정하고, 작업은 배치마다 worktree 에서 합니다. 에이전트 하나가 worktree 를 셋 이상 열려고 하면 관리 스크립트가 거절합니다.

검사는 자동으로 옮기되, 검사 비용도 잽니다

100만 줄에서 사람이 에이전트의 모든 변경을 읽을 수는 없습니다. 모듈 사이 계약 테스트, 바뀐 모듈만 도는 영향 범위 테스트, 레거시의 특성화 테스트를 둡니다. 영향 범위 테스트 도구는 2026-11 기준 Nx 24.0.6, Turborepo 2.11.11, Bazel 9.3.2 가 최신입니다.

솔직히 적으면 두 저장소 모두 계약 테스트와 영향 범위 테스트가 아직 없습니다. 레거시 저장소의 CI 는 하위 프로젝트 두 곳에만 있고, 작업 저장소에는 CI 가 없습니다. 이 절은 제가 운영해서 확인한 내용이 아니라 원칙입니다.

검사 비용은 재 봤습니다. 레거시 저장소의 커밋 게이트는 처음에 에이전트의 셸 호출마다 돌았습니다. 14일 동안 Go 빌드와 go vet 이 약 2,000번 돌았고 p95 7초, 최대 38초였습니다. 지금은 git commit 일 때만 돕니다. 규모가 크면 검사를 어디에 거는지도 설계 대상입니다.

세션 운영은 공식 문서와 제 눈금이 다릅니다

Claude Code 의 모범 사례 문서는 “그만해도 되는 일"에 컨텍스트를 공격적으로 관리하는 것을 넣었습니다. 대부분의 모델이 100만 토큰 창을 쓰고 압축이 저절로 돌아서 “running out is rare” 라는 것입니다. 컨텍스트를 지키려고 서브에이전트를 쓰는 것도 같은 목록에 있습니다.

그래도 저는 40~50% 에서 세션을 넘깁니다. 바닥나지 않아도 무관한 작업이 쌓이면 매 턴 다시 읽히고 답이 흐려집니다. 공식 문서도 작업 사이 /clear 는 여전히 권합니다. 넘기는 법은 Claude Code 실전 가이드 2편에 있습니다.

운영 규칙옛 글지금
세션 넘김50%40~50%. 공식 문서는 바닥날 일이 드물다고 본다
탐색과 수정다른 세션그대로. 앤트로픽 글도 읽기 전용 서브에이전트로 지도를 먼저 만들라고 한다
병렬 에이전트모듈당 하나, worktree배치당 worktree 하나, 에이전트당 동시 2개
인수인계영역별 HANDOFF.md이슈 트래커의 handoff 라벨 이슈. 트래커가 있으면 파일을 만들지 않는다

병렬 운영의 세부는 실전 가이드 3편에 따로 적었습니다.

도입 순서

  1. 에이전트에게 저장소를 분석시켜 목차형 루트 지도를 만듭니다. 줄 수와 바이트를 함께 잽니다.
  2. 순환 의존과 경계 위반을 목록으로 만들고, 심한 곳은 에이전트 투입을 미룹니다.
  3. 경계가 깨끗하고 테스트가 있는 모듈 하나에서 하위 문서와 작업 지시서를 시험합니다.
  4. 범용 심볼 인덱스를 먼저 깔고, 파일 사이 간선이 실제로 생기는지 셉니다. 안 생기면 전용 색인을 설계합니다.
  5. 계약 테스트와 영향 범위 테스트를 넣습니다. 레거시는 특성화 테스트부터 씁니다.
  6. 통한 패턴을 다른 영역으로 복제하고, 문서가 가리키는 경로가 있는지 CI 로 검사합니다.

이 판단이 틀리는 경우

  • 코드 대부분이 import 로 이어진 현대 코드라면 4번의 전용 색인은 필요 없습니다. 범용 인덱스와 LSP 로 충분합니다.
  • 개념 검색이 주에 여러 번 막힌다면 벡터 검색을 미룰 이유가 줄어듭니다.
  • 모듈 경계가 무너진 코드베이스에서는 이 글의 순서가 통하지 않습니다. 모듈화가 먼저입니다.
  • 계약 테스트를 직접 운영해 보지 않았습니다. 그 비용이 이득보다 큰 저장소가 있을 수 있습니다.

정리

100만 줄부터는 전체 맥락을 주지 않습니다. 모듈 경계로 범위를 가두고, 색인으로 조각을 주고, 자동 검사로 확인합니다. 다만 색인은 코드가 서로를 부르는 방식에 맞아야 합니다. 규모가 커질수록 에이전트 관리는 프롬프트 문제에서 소프트웨어 엔지니어링 문제로 바뀝니다.

먼저 확인할 것은 하나입니다. 쓰는 코드 인덱스에서 큰 모듈 하나를 골라 파일 사이 간선 수를 세어 봅니다. 파일 수보다 훨씬 적다면 그 인덱스는 영향 범위를 모릅니다.

이 글은 2026-08-25 에 옛 블로그에 올린 글을 2026-11-18 에 다시 확인하고 고쳐 쓴 것입니다.