AI가 5분 만에 5,000줄을 쓴다. 그런데 그 코드를 리뷰하는 데 3시간이 걸린다. 테스트는 통과한다. 빌드도 된다. 그런데 팀 리드인 내가 '이 프로젝트가 사용자에게 무엇을 하는가'를 설명할 수 없다면? 이건 AI 도구의 품질 문제가 아니다. 구조적 인식 실패다.
최근 dev.to에 올라온 한 독립 개발자의 글이 이 문제를 정면으로 건드렸다. 그는 AI 생성 코드베이스를 이해하기 위해 콜 그래프, AST 분석, 5-레이어 유니버설 코드 그래프까지 세 차례 시도했고, 세 번 모두 4,080줄을 통째로 삭제하는 것으로 끝났다. 그 실패의 공통 원인은 하나였다. 코드의 구조(함수가 무엇을 호출하는가)와 기능의 구조(사용자에게 무엇을 하는가)는 근본적으로 다른 그래프라는 사실을 무시했다는 것.
콜 그래프는 아름답다. parseRequest() → validateInput() → fetchUser()처럼 흐름이 보인다. 그런데 이건 '스크램블 에그 만드는 법을 물었더니 prepare()가 slice()를 호출한다는 답을 받은 것'과 같다. 구조는 맞다. 의미가 없다. AST 분석도 마찬가지다. auth/login.ts가 utils/jwt.ts를 임포트한다는 사실을 아는 것과, '사용자가 비밀번호를 제출하면 시스템이 검증 후 JWT를 발급한다'는 사실을 아는 것은 전혀 다른 층위다. 전자는 구조, 후자는 이야기다.
그가 최종적으로 도달한 해법은 FCG(Feature & Flow Graph)다. 핵심 아이디어는 역설적으로 단순하다. AI는 이미 각 기능이 무엇을 하는지 안다—자기가 방금 짰으니까. 그러니 AI에게 구조를 분석시키지 말고, 처음부터 사용자 언어로 기능을 서술하게 하면 된다. 코드 변경이 일어날 때마다 AI가 features.json을 업데이트하고, 리뷰어는 코드가 아니라 그 JSON을 읽는다. '함수 A가 함수 B를 호출한다'가 아니라 '1단계가 실행되고, 조건 X면 2단계, 아니면 3단계'라는 흐름으로.
여기서 두 번째 기사가 맞물린다. Claude Code가 낯선 코드베이스를 탐색할 때 어떤 일이 벌어지는가. CodeGraph 프로젝트가 측정한 결과는 충격적이다. Claude Code의 Explore 에이전트는 grep, glob, Read를 반복 호출하며 '어디에 뭐가 있는지'를 발견하는 데만 대부분의 시간을 소비한다. VS Code 코드베이스에서 '익스텐션 호스트가 메인 프로세스와 어떻게 통신하는가'라는 질문에 답하는 데 CodeGraph 없이는 52번의 툴 호출이 필요했다. CodeGraph를 붙이자 3번으로 줄었다. 평균적으로 툴 호출 92% 감소, 탐색 속도 71% 향상이 보고됐다.
두 사례를 겹쳐 읽으면 하나의 구조적 문제가 드러난다. AI는 코드를 생성할 때 의미를 알지만, 그 의미를 코드베이스에 남기지 않는다. 그 결과 인간 리뷰어도, AI 에이전트도 나중에 같은 코드를 다시 이해하려면 처음부터 역산해야 한다. 인간은 3시간을 쓰고, 에이전트는 52번 grep을 돌린다. 둘 다 비효율의 본질은 같다. 코드 생성 시점에 소실된 의미론적 맥락을 사후에 복원하려는 시도.
팀 리드 관점에서 이 문제는 더 현실적인 형태로 온다. AI가 속도를 높일수록 코드베이스는 빠르게 불투명해진다. 이전 글에서도 짚었지만, '테스트 통과'와 '이해된 코드베이스'는 전혀 다른 말이다. 여기에 CodeGraph가 보여주는 비효율까지 더하면—AI 에이전트조차 자기가 만든 코드베이스를 효율적으로 탐색하지 못한다—이건 단순한 도구 선택 문제가 아니다. 코드 생성 워크플로우 자체를 재설계해야 하는 신호다.
실행 가능한 방향은 두 가지다. 첫째, FCG 방식처럼 생성 시점에 의미 명세를 함께 작성하는 관행을 팀 표준으로 만든다. AI가 코드를 짤 때 사용자 흐름 기준의 기능 서술도 함께 출력하도록 프롬프트를 설계하는 것이다. 이는 리뷰 비용을 낮추고, 온보딩 시간을 단축시키며, 다음 번 AI 에이전트가 같은 코드베이스를 탐색할 때의 효율도 높인다. 둘째, CodeGraph처럼 사전 인덱싱된 구조 맵을 CI 파이프라인에 통합한다. 대규모 코드베이스일수록 에이전트의 탐색 비용은 선형 이상으로 증가한다. 이 비용을 런타임에서 빌드 타임으로 옮기는 것만으로도 의미 있는 효율을 확보할 수 있다.
코드 가독성 논의는 오랫동안 '사람이 읽기 좋은 코드'를 기준으로 해왔다. AI-First 시대에는 기준이 바뀐다. AI가 생성하고, AI가 다시 탐색하고, 사람이 검증하는 삼중 루프에서 '이해 가능성(understandability)'은 코드 스타일 문제가 아니라 워크플로우 설계 문제다. 콜 그래프 4,080줄을 삭제한 개발자가 발견한 진짜 교훈이 그것이다. 구조를 시각화하려 하지 말고, AI에게 처음부터 이야기를 쓰게 하라.