AI 드리븐 코드베이스 문서화 (3편) - 실제 효과와 운영 가이드

TL;DR

• 증상: 문서 시스템을 만들었지만 실제 효과가 얼마나 있는지 불명확, 투자 대비 효과 판단 불가
• 원인: 정량적 지표 없이는 개선 여부 증명 어려움, Before/After 비교 데이터 부재, 주관적 체감만으로 판단
• 해결: 토큰 사용량, 응답 시간, 정확도, 개발 속도를 측정하여 효과 검증, 트리거 기반 문서 선택 자동화, PR 템플릿에 문서 체크리스트 추가
• 효과: 토큰 85% 절약 (13,000 → 2,000), 응답 시간 67% 단축 (30초 → 10초), AI 정확도 85% → 95%, 개발 속도 3배 향상, 할루시네이션 감소
• 한계: 문서 최신화 부담 (주 1회 필요), 초기 학습 시간 (2주), 중소 프로젝트엔 오버엔지니어링, 측정 비용, 팀 전체 컨센서스 필요

글 머리말

지난 두 편에서 왜 AI 전용 문서화가 필요한지, 그리고 4계층 정보 구조를 어떻게 설계했는지 공유했습니다.

이번 마지막 편에서는 실제로 얼마나 효과가 있었는지 정량적인 수치와 함께 공유합니다. 그리고 이 시스템을 지속 가능하게 운영하기 위한 가이드도 다룹니다.

핵심 기능 - 트리거 기반 문서 선택

키워드 → 도메인 자동 매핑

AI가 사용자의 질문에서 키워드를 추출하고, 해당 도메인의 문서를 자동으로 선택합니다.

# ai-rules.md의 트리거 규칙

| 키워드           | 도메인     | 필수 문서              |
| ---------------- | ---------- | ---------------------- |
| 재계약, 퇴거     | contract   | domains/contract.md    |
| 세금계산서, 발행 | admin/tax  | domains/admin/tax.md   |
| IoT, 도어락      | iot        | domains/iot.md         |
| 고객, 입주민     | customer   | domains/customer.md    |
| 요금, 청구       | fee        | domains/fee.md         |

실제 작업 흐름

sequenceDiagram
    participant U as 사용자
    participant AI as AI Agent
    participant S as START.md
    participant D as domain.md
    participant DD as domains/*.md

    U->>AI: "재계약 신청 API를 수정해줘"
    AI->>S: 키워드 "재계약" 확인
    S-->>AI: contract 도메인 매핑
    AI->>D: contract/domain.md 읽기
    D-->>AI: 메타데이터 (entrypoints, gotchas)
    AI->>DD: 필요시 domains/contract.md 상세 참조
    DD-->>AI: 상태 전이 규칙, 코드 예제
    AI->>U: 정확한 코드 수정안 제시

기존 방식은 프로젝트 이해 (~5,000 토큰) + 도메인 파악 (~3,000 토큰) + 상세 이해 (~5,000 토큰)로 총 ~13,000 토큰이 필요했습니다.

새 방식은 START.md (~300 토큰) + domain.md (~300 토큰) + 필요시만 로딩 (~1,400 토큰)로 총 ~2,000 토큰으로 줄었습니다. 약 85% 토큰 절감입니다.

YAML 메타데이터 스키마 - AI가 이해하는 규격

각 도메인의 domain.md 파일 상단에 YAML 메타데이터를 정의합니다. role, responsibility, dependencies, entrypoints, gotchas 필드로 구성됩니다.

메타데이터 활용 예시

사용자: "계약 도메인에서 새 기능 추가해줘"

AI: (domain.md 메타데이터 읽음)
    → dependencies: [site, room]
       → site, room 도메인만 참조 가능
       → 다른 도메인 직접 호출 금지

    → entrypoints: ["ContractService"]
       → ContractService부터 시작

    → gotchas: ["상태 전이 규칙"]
       → setStatus() 직접 호출 금지
       → ContractStateManager 경유 필수

도구별 통합

Cursor

.cursorrules 파일에서 ai-rules.md를 자동 참조합니다.

# .cursorrules

## 문서 참조

- 작업 시작 전 반드시 `docs/ai-rules.md` 읽기
- 도메인 작업 시 해당 `domain.md` 확인

## 프로젝트 규칙

@include docs/ai-rules.md

효과: 매번 “@ai-rules.md 읽고”라고 말할 필요 없이, AI가 자동으로 규칙을 인지합니다.

ChatGPT/Claude는 대화 시작 시 START.md + 관련 domain.md를 첨부하면 됩니다. GitHub Copilot은 작업할 도메인의 domain.md를 열어둔 상태에서 코딩하면 컨텍스트를 인식합니다.

실제 개선 결과 - 정량적 효과

contract 도메인 기준으로 Claude와 GPT-4에서 실제 요청을 측정했습니다.

프로젝트 파악 토큰은 ~5,000에서 ~600으로 (88% 절감), 도메인 작업 토큰은 ~8,000에서 ~2,000으로 (75% 절감), 전체 이해 토큰은 ~15,000에서 ~4,000으로 (73% 절감), AI 응답 시간은 ~30초에서 ~10초로 (67% 단축) 개선됐습니다.

Before / After 비교

사용자: "재계약 API 수정해줘"
AI: (전체 코드베이스 탐색...)
    → 수천 개 파일 읽기
    → 토큰 5,000개+ 소진
    → 응답 시간 30초+
    → 결과: 레거시 파일 수정 시도 (할루시네이션)

사용자: "재계약 API 수정해줘"
AI: (START.md → contract/domain.md)
    → 키워드 "재계약" → contract 도메인
    → 토큰 2,000개 정도
    → 응답 시간 10초
    → 결과: 정확한 ContractService 수정안

정성적 효과

일관성 (모든 도메인이 동일한 문서 구조로 표준화), 추적성 (문서 ↔ 코드 위치 명확한 연결), 확장성 (새 도메인 추가 시 템플릿 활용 가능), 협업성 (AI와 개발자가 같은 문서 참조), 품질 (코딩 컨벤션 자동 준수, 도메인 경계 침범 방지), 온보딩 (신규 팀원/AI의 프로젝트 이해 시간 1~2일 단축)이 개선됐습니다.

할루시네이션 감소

가장 큰 효과는 할루시네이션 감소입니다.

Before:
- AI가 레거시 코드 수정 시도
- 존재하지 않는 클래스 참조
- 컨벤션과 다른 네이밍
- 도메인 경계 무시한 코드 생성

After:
- gotchas 필드로 주의사항 인지
- dependencies 필드로 참조 가능 도메인 제한
- entrypoints 필드로 정확한 진입점 파악
- conventions.md로 네이밍 규칙 준수

AI 작업 플로우 - 표준 절차

4단계 작업 플로우

flowchart TD
    A[사용자 요청<br/>'재계약 신청 API를 수정해줘'] --> B[STEP 1: START.md 확인<br/>~300 토큰]
    B --> C[키워드 '재계약' → contract 도메인]
    C --> D[STEP 2: contract/domain.md<br/>~300 토큰]
    D --> E{상세 필요?}
    E -->|예| F[STEP 3: domains/contract.md<br/>~1,400 토큰]
    E -->|아니오| G[STEP 4: 코드 작업]
    F --> G
    G --> H[conventions.md 참조<br/>도메인 경계 준수]

    style A fill:#e3f2fd
    style G fill:#e8f5e9
    style H fill:#fff3e0

단계별로는 STEP 1에서 START.md를 확인하여 키워드를 추출하고 (~300 토큰), STEP 2에서 domain.md의 YAML 메타데이터로 컨텍스트를 파악하고 (~300 토큰), STEP 3에서 필요시 상세 문서를 읽고 (~1,400 토큰), STEP 4에서 conventions.md를 참조하여 코드를 작성합니다.

운영 가이드 - 지속 가능한 문서화

새 도메인 추가 시 quick.md + docs/domains/{domain}.md + src/.../domain.md를 업데이트합니다. 엔티티 변경 시 해당 도메인의 domain.md, 새 비즈니스 규칙 추가 시 docs/domains/{domain}.md, 용어 추가 시 glossary.md, 외부 연동 추가 시 layers.md를 업데이트합니다.

PR 템플릿

## Documentation Checklist

- [ ] 관련 도메인의 `src/.../domain.md` 업데이트 완료
- [ ] `docs/domains/*.md` 변경 사항 반영 (필요시)
- [ ] 새 용어가 있다면 `glossary.md`에 추가
- [ ] 새 도메인 추가 시 `quick.md` 업데이트

Domain Owner는 해당 도메인 문서 최신화를 책임지고, Tech Lead는 분기별 전체 문서 정합성을 검토합니다.

PR 시 변경된 도메인의 문서 업데이트 여부를 확인하고, 스프린트 종료 시 전체 문서 정합성을 검토하며, 분기별로 대규모 리팩토링을 반영하고 메타데이터를 점검합니다.

내 프로젝트에 바로 적용하기

Phase 1: 기반 구축 (1주)

# AI Rules

## 트리거 규칙

| 키워드       | 도메인  |
| ------------ | ------- |
| 결제, 환불   | payment |
| 회원, 로그인 | auth    |

## 금지 규칙

- 다른 도메인 Repository 직접 호출 금지
- @Deprecated 클래스 사용 금지

# .cursorrules

@include docs/ai-rules.md

Phase 2: 핵심 도메인 문서화 (2주)

---
role: domain
responsibility: '결제 처리'
dependencies: [order, customer]
entrypoints: ['PaymentService']
gotchas: ['트랜잭션 범위', '환불 정책']
---

Phase 3: 확장 및 자동화 (2주)

체크리스트

• ai-rules.md - 행동 규칙, 트리거, 금지사항
• START.md - AI 진입점, 65줄 이내
• quick.md - 전체 도메인 맵
• conventions.md - 코딩 컨벤션
• glossary.md - 비즈니스/기술 용어집
• 핵심 도메인 domain.md - YAML 메타데이터 + 패키지 구조
• 핵심 도메인 domains/*.md - 비즈니스 규칙 상세
• .cursorrules 설정
• PR 템플릿에 Documentation Checklist 추가

향후 개선 계획

단기 (1~2주)

중기 (1~2개월)

장기 (3개월+)

시스템 점검 체크리스트

저도 AI 문서 시스템을 운영할 때 이 항목들을 확인합니다. 실제 효과 측정을 고려한다면 참고하시면 좋을 것 같습니다.

• 토큰 사용량 측정: Before/After 토큰 사용량을 정량적으로 측정하고 있는가?
• 응답 정확도 추적: AI 답변이 실제 코드와 얼마나 일치하는지 주기적으로 확인하는가?
• 개발 속도 측정: 기능 구현 시간이 실제로 단축되었는가? (Before/After 비교)
• 문서 최신화 주기: 주 1회 이상 문서를 업데이트하는 루틴이 정착되었는가?
• 팀 피드백: 팀원들이 실제로 문서를 활용하고 있는가? 만족도는 어떤가?

마무리

3편에 걸쳐 AI 드리븐 코드베이스 문서화 경험을 공유했습니다.

1편에서는 토큰 낭비, 할루시네이션, 컨벤션 미준수 문제를 다뤘고, 2편에서는 4계층 정보 구조와 56개 문서 산출물을 설명했으며, 3편에서는 토큰 75% 절감 효과와 운영 가이드를 공유했습니다.

목표는 모두 달성했습니다. 토큰 효율화 70%+ (평균 75% 절감), 도메인 경계 준수 (ai-rules.md 가드레일), 코딩 컨벤션 자동 준수 (conventions.md 참조), 온보딩 시간 단축 (1~2일 단축)입니다.

핵심 교훈

솔직히 처음에는 “문서 56개를 만든다고?”라고 생각했습니다. 그런데 막상 해보니, 한 번 만들어두면 그 이후로는 AI가 알아서 찾아 읽습니다.

AI 코딩 도구를 도입했는데 기대만큼 효과가 없다고 느끼시는 분들이 있다면, “AI를 위한 지도를 그려주는 것”을 시도해보시길 권합니다.

도구가 아무리 좋아도, 컨텍스트가 없으면 무용지물입니다. 22만 줄의 코드베이스에서 AI가 길을 잃지 않으려면, 누군가는 지도를 그려줘야 합니다.

이 시리즈가 그 지도를 그리는 데 도움이 되었으면 합니다.

참고 :

https://docs.cursor.com/context/rules-for-ai
https://modelcontextprotocol.io/
https://martinfowler.com/bliki/DocumentationAsCode.html
https://adr.github.io/

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