AI 드리븐 코드베이스 문서화 (2편) - 4계층 정보 구조 설계

graph TB
    %% 스타일 정의
    classDef nodeStyle fill:#fff,stroke:#333,stroke-width:1px,rx:5,ry:5

    subgraph Layer1 [Layer 1: 오케스트레이션<br/>]
        A[<b>ai-rules.md</b><br/>어떤 작업에 어떤 문서를 읽을지 결정]:::nodeStyle
    end

    subgraph Layer2 [Layer 2: 요약/프록시<br/>]
        B[<b>START.md</b><br/>토큰 절약용 대표 컨텍스트<br/>약 65줄]:::nodeStyle
    end

    subgraph Layer3 [Layer 3: 인덱스<br/>]
        C[<b>quick.md</b><br/>도메인 맵, 코드/문서 위치<br/>약 120줄]:::nodeStyle
    end

    subgraph Layer4 [Layer 4: 상세<br/>]
        D1[<b>domain.md</b><br/>src 내 코드 위치 요약<br/>30-60줄]:::nodeStyle
        D2[<b>domains/*.md</b><br/>도메인별 상세 문서<br/>100-270줄]:::nodeStyle
    end

    A --> B
    B --> C
    C --> D1
    C --> D2

    style Layer1 fill:#e3f2fd,stroke:#90caf9,stroke-width:2px
    style Layer2 fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px
    style Layer3 fill:#fff3e0,stroke:#ffcc80,stroke-width:2px
    style Layer4 fill:#fce4ec,stroke:#f48fb1,stroke-width:2px

# AI Rules - Epyon API

## 문서 참조 규칙

### 작업 시작 시
1. 먼저 docs/START.md를 읽어 키워드→도메인 매핑 확인
2. 해당 도메인의 src/.../domain.md 읽기
3. 필요시 docs/domains/{domain}.md 상세 참조

### 트리거 기반 문서 선택
(키워드-도메인-필수문서 매핑 표)

## 금지 규칙
- 다른 도메인의 Repository 직접 호출 금지
- @ai-deprecated 태그가 있는 코드는 수정하지 말 것

❌ Bad:
- ai-rules.md: "JPA 우선 사용"
- conventions.md: "MyBatis 우선 사용"
→ 충돌!

✅ Good:
- ai-rules.md: "JPA 우선 사용" (유일한 정의)
- conventions.md: ai-rules.md 참조

# START - AI 진입점

## 프로젝트 개요
(프로젝트 정보 표)

## 키워드 → 도메인 매핑
(키워드-도메인 매핑 표)

## 문서 탐색 가이드
- 프로젝트 전체 구조: docs/quick.md
- 도메인별 상세: docs/domains/{domain}.md
- 코드 위치 요약: src/.../domain/{domain}/domain.md

사용자: "재계약 API 수정해줘"
AI: (START.md 읽음)
    → 키워드 "재계약" → contract 도메인
    → domain/contract/domain.md 읽기
    → 필요시 docs/domains/contract.md 상세 참조

# Quick Reference - 도메인 맵

## 디렉토리 구조
project-root/
├── src/main/java/com/example/
│   ├── domain/           # 도메인별 비즈니스 로직
│   ├── model/            # JPA Entity
│   └── infra/            # 외부 연동
└── docs/
    ├── START.md          # AI 진입점
    └── domains/          # 도메인별 상세

## 핵심 도메인 (5개)
(도메인-역할-파일수-상세문서 표)

## 도메인 간 의존성
(Mermaid 다이어그램)

graph TB
    Site[사이트] --> Room[객실]
    Room --> Contract[계약]
    Contract --> Customer[고객]
    Contract --> Fee[요금]

    style Site fill:#e3f2fd
    style Contract fill:#e8f5e9

AI: (quick.md 읽음)
    → contract 도메인 찾기
    → 파일 수: 19개, 상세 문서: domains/contract.md
    → 의존성: Site → Room → Contract

---
role: domain
responsibility: '계약 관리 - 임대차, 재계약, 퇴거 처리'
dependencies: [site, room]
entrypoints: ['ContractService', 'ContractAdminApi']
gotchas: ['상태 전이 규칙', '암호화 필수', 'FeeService 연동']
---

# Contract Domain

## 패키지 구조

domain/contract/
├── api/ # REST Controllers
├── service/ # Business Logic
├── repository/ # Data Access
└── dto/ # DTOs

## 핵심 클래스

(클래스-역할 표)

## 주의사항 (gotchas)

1. 상태 전이 규칙: ContractStateManager 경유 필수
2. 암호화 필수: 개인정보 저장 시 EncryptService 사용
3. FeeService 연동: 재계약 시 요금 계산 누락 주의

---
role: domain # 역할 (domain, service, infra 등)
responsibility: '한 줄 설명' # 이 도메인이 무엇을 하는지
dependencies: [site, room] # 의존하는 다른 도메인 (읽기 전용)
entrypoints: ['ContractService'] # AI가 건드릴 수 있는 클래스
gotchas: ['상태 전이 규칙', '암호화'] # 주의사항
---

# Contract 도메인 상세

## 비즈니스 개요

임대 계약의 전체 라이프사이클을 관리합니다.

- 신규 계약 (입주)
- 재계약 (연장)
- 퇴거 (종료)

## 상태 전이

<!-- Mermaid 다이어그램은 별도로 렌더링됩니다 -->

## 핵심 비즈니스 규칙

- 상태 전이는 반드시 ContractStateManager 경유
- 재계약 시 FeeService.calculateRenewalFee() 호출 필수
- 퇴거 시 보증금 정산 누락 주의

stateDiagram-v2
    [*] --> 대기중: 계약 생성
    대기중 --> 활성: 입주 완료
    활성 --> 재계약중: 재계약 신청
    재계약중 --> 활성: 재계약 완료
    활성 --> 퇴거중: 퇴거 신청
    퇴거중 --> 종료: 퇴거 완료

사용자: "프로젝트 전체 구조 알려줘"
AI: START.md (65줄) + quick.md (120줄) → 약 600 토큰

사용자: "계약 도메인 상세히 알려줘"
AI: + domain.md (60줄) + domains/contract.md (270줄) → 약 2,000 토큰

# ai-rules.md의 트리거 규칙
"재계약", "퇴거" → contract 도메인
"세금계산서"    → admin/tax 도메인
"IoT", "도어락" → iot 도메인
"고객", "입주민" → customer 도메인

# 메타데이터만으로 파악 가능한 정보
---
role: domain
responsibility: '계약 관리'
dependencies: [site, room] # 어디를 참조하는지
entrypoints: ['ContractService'] # 어디부터 보는지
gotchas: ['상태 전이 규칙'] # 무엇을 조심하는지
---

# PR 템플릿에 추가

## Documentation Checklist

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

docs/
├── START.md                    ← AI 진입점 (65줄)
├── quick.md                    ← 도메인 맵 (120줄)
├── ai-rules.md                 ← AI 행동 규칙 (331줄)
├── conventions.md              ← 코딩 컨벤션 (127줄)
├── layers.md                   ← Global/Infra 상세 (91줄)
├── glossary.md                 ← 용어집 (147줄)
├── ai/
│   └── ai-onboarding-overview.md  ← 아키텍처 개요 (Living Doc)
│
└── domains/
    ├── site.md                 ← 핵심 도메인 (5개)
    ├── room.md
    ├── contract.md
    ├── customer.md
    ├── fee.md
    ├── iot.md                  ← 확장 도메인 (16개)
    ├── auth.md
    ├── goods.md
    ├── ...
    └── admin/                  ← 관리자 하위 도메인 (6개)
        ├── admin.md
        ├── contract.md
        ├── customer.md
        ├── tax.md
        └── ...

src/main/java/.../domain/
└── {각 도메인}/
    └── domain.md               ← 코드 위치 요약 (22개)