사람도 에이전트도, 덜 읽을수록 더 잘 고칩니다

flex 팀이 코드베이스의 모듈 경계 설계가 AI 에이전트의 코드 탐색 효율에 미치는 영향을 실측한 글이다. 193개 에이전트 작업 로그를 분석하고, 잘 나뉜 모듈과 뭉친 모듈을 비교한 결과 — 도메인이 물리 모듈로 분리된 저장소에서 에이전트가 불필요한 파일을 덜 읽고 목표 코드에 더 집중했다. 사람도 에이전트도 컨텍스트 한도가 있어, 무관 코드를 덜 읽을수록 수리 성공률이 높다는 것이 핵심 결론이다.

핵심 포인트

193개 작업 로그 중 67%(129개)에서 에이전트 읽기가 목표 도메인으로 무작위 기준 대비 집중됐고, 집중도 중앙값은 +14%p였다.
잘 갈린 저장소(6파일, 13,891 소스 토큰)와 뭉친 저장소(15파일, 34,695 토큰) 비교에서 에이전트가 읽어야 할 코드가 약 2.5배 차이가 났다.
모듈 경계는 디렉터리 네이밍과 달리 강제력이 있다 — 빌드 파일 선언 없이는 도메인 간 참조가 컴파일 단계에서 차단된다.
컨텍스트 효율과 수리 성공 간 상관계수 0.95(SWE-Explore) — 무관 코드를 덜 읽을수록 결함과 얽힌 코드를 더 오래 컨텍스트에 유지할 수 있다.
목표는 무관 코드를 0으로 만드는 게 아니라 관련 근거가 들어갈 컨텍스트 공간을 확보하는 것이다.

상세 정리

출발 사례: 정산 원장 재봉인 시 기존 라인이 중복 계산될 수 있다는 의혹을 에이전트에게 진단 지시, 에이전트가 열어본 파일은 6개였다.
6개 파일의 공통점: 봉인 로직·원장 모델·저장소 어댑터가 4개 모듈에 분산돼 있었지만 도메인 이름이 모두 "정산"으로 통일, 파일 경로만으로 어느 계층인지 파악 가능했다.
로그 분석 설계: 작업 시작 시 목표 도메인을 먼저 확정하고, 실제 읽기 분포가 목표 도메인의 전체 파일 비중 대비 얼마나 집중됐는지 측정.
측정 결과: 193개 작업 로그에서 목표 도메인 읽기 집중도 중앙값 +14%p, 129개(67%)가 무작위 예상보다 집중됐다.
비교군: 도메인 30개가 한 모듈에 뭉쳐 있는 저장소에서 사용자 도메인 진단 실시, 에이전트는 15파일·4,235줄·34,695 소스 토큰을 읽었다.
뭉친 쪽의 문제: 단일 모듈 내에서는 도메인 간 참조에 제약이 없어 사용자 코드가 직무 체계까지 직접 연결, 에이전트가 불필요한 파일을 따라 읽게 됐다.
여러 도메인 읽는 경우도 있었다: 상태 전이 규약이 여러 도메인에 퍼졌는지 확인하는 작업은 자연스럽게 7개 도메인을 읽었다 — 범위는 작업 목표에 따라 결정된다.
이름 vs. 경계 차이: 디렉터리 네이밍은 표지 역할뿐, 모듈 경계는 빌드 파일 선언을 강제해 선언되지 않은 도메인 간 참조를 컴파일 단계에서 막는다.
연구 뒷받침 1: Du 등은 관련 근거가 완전히 주어진 상황에서도 입력이 길어지면 LLM 추론 성능이 저하됨을 실증했다.
연구 뒷받침 2: SWE-Explore는 저장소 탐색 능력과 수리 성공을 분리 측정, 컨텍스트 효율이 수리 성공과 상관계수 0.95로 가장 강하게 연결됨을 확인했다.
적용 조건: 단일 모듈로 충분한 규모라면 모듈 분할 비용이 편익을 넘는다 — 이미 여러 모듈로 분리했거나 그 결정을 한 팀에게 해당하는 이야기다.