AI 드리븐 코드베이스 문서화 (1편) - 22만 줄 코드를 AI가 읽게 만들어야 했던 이유

TL;DR

• 증상: 22만 줄 코드베이스에서 AI가 관련 파일을 못 찾고 토큰만 소진 (한 번에 5,000 토큰+), 엉뚱한 레거시 파일 수정 시도
• 원인: AI가 프로젝트 구조, 도메인 경계, 비즈니스 규칙을 모르고 전체 탐색, 컨텍스트 윈도우 제한으로 부분적 이해
• 해결: 4계층 문서 시스템 구축 (오케스트레이션 → 요약 → 인덱스 → 상세), 트리거 기반 문서 선택, YAML 메타데이터 스키마
• 효과: 토큰 90% 절약 (13,000 → 2,000), AI 응답 시간 67% 단축 (30초 → 10초), 정확도 85% → 95%, 할루시네이션 감소
• 한계: 문서 작성 초기 비용 (2주), 문서 최신화 부담 (주 1회 필요), 팀 전체 학습 필요, 중소 프로젝트엔 오버엔지니어링

글 머리말

“계약 도메인 API 수정해줘”

Cursor에게 이 한 마디를 던졌을 때, AI는 수천 개의 파일을 탐색하기 시작했습니다. 토큰은 순식간에 소진되고, 결과는 엉뚱한 레거시 파일을 수정하려는 코드였습니다.

22개 도메인, 약 4,000개 파일, 22만 줄 이상의 코드. 우리 팀의 임대 관리 플랫폼은 AI가 한 번에 이해하기엔 너무 컸습니다.

결국 우리는 “AI가 우리 코드베이스를 효율적으로 탐색할 수 있도록” 체계적인 문서 시스템을 설계하고 구축했습니다. 이 글에서는 왜 이 작업이 필요했는지, 기존 방식의 한계는 무엇이었는지를 공유합니다.

기존 문제점 - AI 도입 후 오히려 생산성이 떨어졌다

프로젝트 구조 파악에 막대한 토큰 소모

처음 Cursor를 도입했을 때 기대가 컸습니다. “이제 AI가 코드 찾아주고, 수정도 해주겠지”

현실은 달랐습니다.

사용자: "재계약 API 로직 수정해줘"
AI: (전체 코드베이스 탐색 시작...)
    → domain/ 폴더 탐색 (3,000개 파일)
    → 관련 없는 파일들도 읽음
    → 토큰 5,000개 소진
    → 결과: "관련 파일을 찾을 수 없습니다"

한 번의 질문에 토큰 5,000개 이상을 써버리는 일이 빈번했습니다. API 비용은 올라가고, 응답 시간은 길어지고, 정작 원하는 답은 안 나왔습니다.

도메인 경계 및 비즈니스 규칙 이해 부족

더 심각한 문제는 할루시네이션이었습니다.

AI가 코드베이스를 대충 훑고 “그럴듯한” 코드를 생성했는데, 실제로는 우리 프로젝트의 규칙과 맞지 않았습니다.

// AI가 생성한 코드
@Transactional
public void processRenewal(Long contractId) {
    Contract contract = contractRepository.findById(contractId);
    contract.setStatus(ContractStatus.RENEWED);  // ❌ 상태 전이 규칙 위반
    contractRepository.save(contract);
}

// 실제로 필요한 코드
@Transactional
public void processRenewal(Long contractId) {
    Contract contract = contractRepository.findById(contractId);
    contractStateManager.transition(contract, ContractStatus.RENEWED);  // ✅ 상태 전이 규칙 준수
    feeService.calculateRenewalFee(contract);  // ✅ 요금 연동 필수
    contractRepository.save(contract);
}

우리 팀에서는 계약 상태 변경 시 반드시 ContractStateManager를 경유해야 합니다. 직접 setStatus()를 호출하면 상태 전이 로그가 남지 않고, 연관된 요금 계산도 누락됩니다.

AI는 이런 비즈니스 규칙을 알 수 없었습니다.

코딩 컨벤션 미준수

팀마다 네이밍 규칙이 있습니다. 우리 팀은 Entity는 *Model, JPA Repository는 *Jpa, Service는 *Service 형식으로 이름을 짓습니다.

하지만 AI는 이런 규칙을 모르고 ContractRepository, ContractController 같은 일반적인 이름으로 코드를 생성했습니다. 코드 리뷰 때마다 “네이밍 컨벤션 안 맞아요”라는 피드백이 반복됐죠.

관련 파일 탐색에 시간 소요

“이 API 관련 파일 다 찾아줘”라고 하면, AI는 수백 개의 파일을 나열합니다. 그중에 진짜 중요한 건 3~4개뿐인데, 어떤 게 핵심인지 알 수 없습니다.

AI 응답: "다음 파일들이 관련되어 있습니다"
- ContractService.java
- ContractServiceForAdmin.java
- ContractAdminApi.java
- ContractApi.java
- ContractModel.java
- ContractJpa.java
- ContractMybatis.java
- ContractMapper.java
- ContractDto.java
... (50개 이상)

개발자: "이 중에 뭐부터 봐야 하는 건데?"

신규 팀원/AI 온보딩 시간 과다

새로운 팀원이 합류하면 프로젝트 구조를 파악하는 데 1~2주가 걸렸습니다. AI 도구를 써도 마찬가지였습니다. AI가 코드베이스를 이해하지 못하니, 사람이 직접 알려줘야 했거든요.

“이 프로젝트 어디서부터 봐야 해요?”라는 질문에 AI도, 사람도 명확하게 답하기 어려웠습니다.

기존 문서화 방식의 한계

저희 팀도 Notion과 Confluence에 문서를 작성하고 있었습니다. 아키텍처 문서, API 명세, 도메인 설명 등 꽤 많은 문서가 있었습니다.

하지만 세 가지 문제가 있었습니다.

첫째, 문서가 코드와 분리되어 있었습니다.

코드는 Git에, 문서는 Notion에. 코드를 수정해도 문서는 업데이트되지 않았습니다. 시간이 지나면서 문서와 실제 코드가 점점 달라졌습니다.

문서: "ContractService에서 재계약 로직 처리"
실제: ContractService는 더 이상 재계약을 처리하지 않음
      → RenewalService로 분리됨

둘째, AI가 접근할 수 없었습니다.

Notion에 아무리 좋은 문서가 있어도, Cursor나 Copilot은 그 문서를 읽을 수 없습니다. AI는 코드베이스 내부의 마크다운 파일만 참조할 수 있거든요.

셋째, 검색이 비효율적이었습니다.

“계약 관련 문서 어디 있어?”라고 물어봐도, AI는 Notion 링크를 알 수 없습니다. 결국 사람이 직접 찾아야 했습니다.

JavaDoc, Swagger 같은 자동 생성 도구도 고려했습니다. 하지만 이런 도구들은 “무엇이 있는지”는 알려주지만, “왜 이렇게 되어 있는지”, “이걸 수정하면 어디에 영향이 가는지”는 알려주지 못합니다.

결국 AI가 코드베이스를 의미있게 이해하려면, 사람이 작성한 맥락이 필요했습니다.

솔직하게, AI 도구의 현실적 한계

컨텍스트 윈도우 제한

Claude, GPT-4 같은 LLM은 한 번에 읽을 수 있는 토큰 수가 제한되어 있습니다. 22만 줄의 코드를 한 번에 읽는 건 물리적으로 불가능합니다.

graph LR
    A[22만 줄 코드] --> B{컨텍스트 윈도우}
    B -->|넘침| C[일부만 읽음]
    C --> D[불완전한 이해]
    D --> E[할루시네이션]

    style A fill:#ffebee
    style E fill:#ffebee

AI가 전체 코드를 읽지 못하니, 부분적인 정보만으로 추측합니다. 그래서 엉뚱한 코드가 생성되는 거죠.

매번 전체 코드베이스를 탐색하면 토큰 비용도 급증합니다. 간단한 질문 하나에 토큰 5,000개 이상을 소진하는 일이 빈번했습니다. 문서화 후에는 600개 정도로 줄었지만요.

도구마다 코드베이스를 참조하는 방식도 다릅니다. Cursor는 .cursorrules 파일을 자동 참조하지만, ChatGPT는 대화 시작 시 파일을 첨부해야 하고, Copilot은 열린 파일만 참조합니다.

통일된 문서 구조가 없으면, 도구마다 다르게 대응해야 합니다.

목표 설정 - 무엇을 달성할 것인가

이런 문제들을 해결하기 위해 명확한 목표를 설정했습니다.

정량적 목표:

• 토큰 사용량 70% 이상 절감
• AI 응답 시간 50% 이상 단축
• 신규 팀원 온보딩 시간 1~2일 단축

정성적 목표:

• AI가 코딩 컨벤션을 자동으로 준수
• 도메인 간 의존성 규칙을 AI가 이해
• 코드와 함께 진화하는 Living Document
• Cursor, ChatGPT, Copilot 모두 활용 가능

어떤 방식을 선택할까 - Trade-off 분석

자동 생성 도구는 표면 정보만 제공하고 맥락이 없었습니다. 기존 Notion 문서는 AI가 접근할 수 없었습니다.

결국 “사람이 작성하되, AI가 읽기 쉬운 형식으로” 라는 방향을 잡았습니다.

최종 선택: 4계층 정보 구조

핵심 아이디어는 Progressive Disclosure(점진적 공개)입니다.

graph TB
    L1[Layer 1: 오케스트레이션<br/>어떤 작업에 어떤 문서를 읽을지 결정]
    L2[Layer 2: 요약/프록시<br/>토큰 절약용 대표 컨텍스트]
    L3[Layer 3: 인덱스<br/>코드/문서 위치 빠른 탐색]
    L4[Layer 4: 상세<br/>도메인별 상세 문서]

    L1 --> L2
    L2 --> L3
    L3 --> L4

    style L1 fill:#e3f2fd
    style L2 fill:#e8f5e9
    style L3 fill:#fff3e0
    style L4 fill:#fce4ec

AI가 필요한 만큼만 정보를 읽도록 설계했습니다. 전체 프로젝트 파악이 필요하면 Layer 1~2만, 특정 도메인 작업이면 해당 Layer 4까지만 읽으면 됩니다.

다음 글에서 이 4계층 구조를 상세히 다루겠습니다.

시스템 점검 체크리스트

저도 AI 문서 시스템을 구축할 때 이 항목들을 확인합니다. AI 드리븐 문서화를 고려한다면 참고하시면 좋을 것 같습니다.

• 프로젝트 규모: 코드베이스가 10만 줄 이상인가? (작으면 이 시스템이 오버)
• 토큰 사용량 측정: 도입 전과 후의 토큰 사용량을 측정하고 있는가?
• 문서 최신화 주기: 주 1회 이상 문서를 업데이트하는 루틴이 있는가?
• 팀 교육: 팀원 전체가 문서 시스템을 이해하고 사용할 수 있는가?
• AI 응답 정확도: 할루시네이션이 줄어들었는가? 실제 코드와 일치하는 답변을 하는가?

마무리

AI 코딩 도구를 도입하면서 깨달은 게 있습니다. 도구가 좋아도 컨텍스트가 없으면 무용지물이라는 것.

22만 줄의 코드베이스에서 AI가 길을 잃지 않으려면, 누군가는 지도를 그려줘야 합니다.

이 시리즈에서는 그 지도를 어떻게 설계하고 구축했는지 공유합니다.

다음 글에서는 4계층 정보 구조를 상세히 설명하고, 실제로 어떤 문서들을 만들었는지 공유하겠습니다.

참고 :

https://docs.cursor.com/
https://modelcontextprotocol.io/
https://martinfowler.com/bliki/DocumentationAsCode.html

읽어주셔서 감사합니다.🖐