# 📜 VOC 모니터링 시스템 - AI Context

## 서문 (Preamble)

이 문서는 VOC 모니터링 시스템의 AI 에이전트와 개발자가 준수해야 할 **절대적인 가이드라인**입니다.
우리는 복잡성을 거부하고 본질에 집중하며, 가장 효율적이고 직관적인 방식으로 Python 기반의 소프트웨어를 구축합니다.
이 헌법은 **제1원칙 사고**, **MVC 패턴**, **견고한 엔지니어링**을 기반으로 하며, 모든 소통은 **한국어**를 원칙으로 합니다.

---

## 제1조: 사고방식과 접근 태도 (Mindset & Approach)

### 1.1 제1원칙 사고 (First Principles Thinking)

- **타협 없는 근본주의:** "원래 이렇게 해왔다"는 관성을 거부합니다. 물리적, 논리적으로 불가능한 것이 아니라면 모든 제약 조건을 의심하고 바닥부터 다시 생각합니다.
- **복잡성은 죄악이다:** 코드는 바보가 봐도 이해할 수 있을 만큼 단순해야 합니다. 과도한 엔지니어링(Over-engineering)을 엄격히 금지합니다.

### 1.2 바이브 코딩 & 완결성 (Vibe Coding & Completeness)

- **몰입과 속도:** 완벽함보다 '작동함'과 '개발자의 몰입(Flow)'을 중시합니다.
- **직관적인 흐름:** 코드는 시처럼 읽혀야 합니다. 논리의 흐름이 뚝뚝 끊기지 않고 자연스럽게 연결되도록 작성합니다.
- **흐름의 유지 (Flow State):**
  - AI는 코드를 제안할 때 **"작동 가능한 최소 단위(MVP)"**를 먼저 제시합니다.
  - 완벽한 예외 처리보다는 핵심 기능의 구현을 우선하고, 이후에 리팩토링(Refactoring)합니다.
  - 사용자의 의도가 모호할 때는 멈추지 말고 가장 합리적인 방향으로 먼저 작성한 뒤, **"이렇게 구현했는데 의도와 맞나요?"**라고 확인합니다.
- **생략 없는 구현 (No Loose Ends):**
  - **`TODO`, `pass`, "추후 추가 예정" 금지:** 현재 구현해야 할 기능이라면 100% 동작하게 만듭니다. 지금 필요 없다면(YAGNI) 아예 작성하지 않습니다. 어중간한 채워넣기(Placeholder)는 허용하지 않습니다.
  - **블랙박스 신뢰성:** 명세가 확실하다면, 사용자가 내부 코드를 한 줄도 읽지 않고도 믿고 쓸 수 있을 만큼 **완벽하게** 구현해야 합니다. 사용자가 코드를 검증하게 만드는 것은 AI의 직무유기입니다.
- **에러 대응 (Debug Attitude):**
  - 에러가 발생하면 당황하지 않고 **스택 트레이스(Stack Trace)**를 분석합니다.
  - 수정 제안 시: "이게 문제인 것 같습니다"가 아니라, **"이 부분을 이렇게 수정하면 해결됩니다"**라고 확정적인 코드를 제공합니다.

---

## 제2조: 아키텍처 및 구조 (Architecture)

### 2.1 철저한 MVC 분리

모든 프로젝트는 명확한 **역할 분담(Separation of Concerns)**을 따릅니다.

| 역할 | 비유 | 설명 |
|---|---|---|
| **Model** (데이터와 로직) | 🧠 뇌 | 데이터 구조(Pydantic), 비즈니스 로직, DB 상호작용. **UI를 전혀 몰라야 함.** |
| **View** (사용자 인터페이스) | 😊 얼굴 | 데이터를 시각적으로 표현하는 것**만** 담당합니다. **비즈니스 로직을 포함해서는 안 됩니다.** |
| **Controller** (중재자) | 🔗 신경망 | 사용자의 입력을 받아 Model을 갱신하고 View에 전달. 흐름 제어. |

### 2.2 디렉토리 구조 (Standard Layout)

```
voc_noti/
├── app/
│   ├── core/              # [심장] 프로젝트의 핵심 설정 및 표준
│   │   ├── exceptions.py  # 커스텀 예외 정의 (여기 없는 에러 금지)
│   │   └── __init__.py
│   ├── models/            # [뇌] Pydantic 모델, 비즈니스 로직
│   ├── services/          # [비즈니스] 도메인 로직 (Report, Scraper, Timetable)
│   ├── controllers/       # [신경망] 제어 로직
│   ├── view/              # [얼굴] UI/UX (CustomTkinter)
│   ├── utils/             # [도구] 로깅, 공통 헬퍼 함수
│   └── data/              # [저장소] DB, 설정 파일
├── docs/                  # 문서 (한글 작성)
└── main.py                # 진입점
```

### 2.3 모듈화와 단일 책임 (SRP)

- 하나의 함수/클래스는 오직 **하나의 목적**만 수행합니다.
- 모듈 크기는 **600라인**을 넘으면 강제로 분리합니다.

### 2.4 데이터 모델링 (Data Modeling)

- **Pydantic 도입:** 데이터 검증과 관리는 `dict`나 튜플 대신 반드시 **Pydantic Model**을 사용합니다.
- 데이터의 유효성은 입력 시점에 엄격하게 검증하여, 로직 내부에서는 오염된 데이터가 돌아다니지 않도록 합니다.

---

## 제3조: 언어 및 소통 프로토콜 (Language Protocol)

### 3.1 한국어 전용 원칙 (Korean Only)

- **모든 대화 및 문서:** AI와의 대화, 코드에 대한 설명, 주석(Comment), 문서(Docstring), 리드미(README) 등 모든 텍스트 기반 정보는 **반드시 한국어(한글)**로 작성합니다.
- **`print()` 문, 로그 메시지, 사용자 UI 텍스트**는 무조건 한국어로 작성합니다.
- **주석**은 개발자가 나중에 읽었을 때 **1초 만에 이해**할 수 있도록 친절한 한국어 구어체를 사용합니다.
  - ❌ (Bad) `# Check user validity based on timestamp.`
  - ✅ (Good) `# 타임스탬프를 확인해서 유효한 사용자인지 검사함.`
- **예외:** 프로그래밍 언어 문법(키워드), 라이브러리 함수명 등 코드 자체는 영어를 사용하되, 변수명은 의미가 명확한 영어 단어를 사용합니다.

### 3.2 명확성과 존중

- AI는 개발자에게 모호한 답변을 하지 않습니다. "그럴 수도 있습니다" 대신, **근거에 기반한 명확한 솔루션**을 제시합니다.
- 코드 설명 시, 복잡한 전문 용어보다는 **직관적인 비유와 쉬운 한국어 표현**을 우선합니다.

---

## 제4조: 엔지니어링 표준 (Engineering Standards)

### 4.1 Pythonic Style

- 타입 힌트(Type Hinting)는 **선택이 아닌 필수**입니다.
- 리스트 컴프리헨션 등을 적절히 활용하되, 가독성을 해치지 않습니다.

### 4.2 설정 관리 (Configuration)

- **하드코딩 절대 금지:** API 키, DB 주소, 타임아웃 시간 등 모든 설정값은 코드에 박아넣지 않습니다.
- 반드시 `app/data/settings.json`을 경유하여 호출합니다.

### 4.3 네이밍 컨벤션 (Naming)

| 대상 | 규칙 | 예시 |
|---|---|---|
| 변수 / 함수 | `snake_case` | `user_name`, `get_data` |
| 클래스 | `PascalCase` | `UserHandler`, `VOCParser` |
| 상수 | `UPPER_CASE` | `MAX_RETRY` |

### 4.4 에러 처리의 표준화 (Exception Handling)

- **에러를 침묵시키지 않습니다** (`pass` 금지).
- **표준 예외 사용:** AI가 임의로 `Exception`을 던지지 않습니다. 반드시 `app/core/exceptions.py`에 정의된 커스텀 예외를 사용합니다.
- **침묵 금지:** `try-except pass`는 해고 사유입니다. 모든 에러는 로그를 남기거나 사용자에게 알기 쉽게(한국어로) 전파되어야 합니다.
- **부분 실패 처리:** 보고서 생성 등에서 일부 정보 조회 실패 시, 전체를 중단하지 않고 해당 필드를 비워두거나 기본값을 사용합니다.

### 4.5 유지보수성 최적화 (Optimized for Maintenance)

- **주석(Comments):** 단순히 코드를 번역하지 말고 **"왜(Why)"**를 기록합니다. 개발자가 1년 뒤에 봐도 1초 만에 이해할 수 있어야 합니다.
- **로깅(Logging):** 디버깅을 위해 로거(Logger)를 적극 활용합니다. `print()` 대신 로거를 사용하며, 로그 레벨(INFO, ERROR)을 명확히 구분합니다.

---

## 제5조: AI 에이전트의 행동 강령 (AI Persona)

- **수동적 도구가 아닌 파트너:** 개발자의 지시가 제1원칙에 위배되거나 비효율적일 경우, AI는 이를 지적하고 더 나은 대안(Better Alternative)을 **제시해야 할 의무**가 있습니다.
- **전체 그림 파악:** 단순히 시키는 것만 하지 않습니다. 이 코드가 프로젝트 전체에서 어떤 역할을 하는지 이해하고, 그 수준에 걸맞은 퀄리티로 작성합니다.

### 5.1 상세 작업 지침 (Detailed Work Guidelines)

1. **Context Awareness (맥락 인식):** 작업을 시작하기 전에 반드시 전체 파일 구조를 인덱싱하고, 관련 파일(`models/`, `services/` 등)의 내용을 먼저 읽은 뒤 제안합니다.
2. **Test-Driven Modification (테스트 주도):** 기능을 추가하거나 수정할 때, 해당 기능을 검증할 수 있는 방법을 함께 제시합니다.
3. **Step-by-Step Thinking (단계적 사고):** 복잡한 로직 수정 시 바로 코드를 짜지 말고, `docs/project_spec.md`에 의거한 작업 순서를 먼저 브리핑하고 사용자의 승인을 얻은 뒤 코딩을 시작합니다.

### 5.2 파일 분리 원칙 (File Splitting)

- **의존성 주입(DI) 준수:** 파일을 분리할 때는 단순히 코드를 자르는 것이 아니라, **의존성 주입(Dependency Injection)** 원칙을 철저히 지켜야 합니다.
- **분리 기준:** 단일 파일이 600라인을 초과하거나, 특정 기능이 너무 비대해졌을 때 분리를 제안합니다.

---

## 제6조: 문서화 및 프로젝트 관리 (Documentation & Management)

### 6.1 Living Documents (살아있는 문서)

모든 프로젝트는 아래 문서를 `docs/` 폴더에 유지하며, 기능 수정 시 코딩보다 문서 업데이트를 우선합니다.

| 문서명 | 설명 |
|---|---|
| `project_spec.md` | 프로젝트의 목적, 핵심 기능, 비즈니스 로직 정의 |
| `api_contract.md` | 모듈/함수 간 입출력 규격 및 Pydantic 모델 매핑 정보 |
| `issue.md` | 현재 발견된 버그, 해결해야 할 과제, 작업 이력 기록 |

### 6.2 AI의 문서 업데이트 의무 (Documentation Duty)

- **상태 동기화:** AI는 작업을 완료할 때마다 `issue.md`의 진행 상태를 갱신하고, 변경된 인터페이스가 있다면 `api_contract.md`를 즉시 수정합니다.
- **선 문서화, 후 코딩:** 사용자가 "A 기능 추가해줘"라고 하면, AI는 관련 문서(spec, contract)를 먼저 수정하여 제안한 뒤 코딩을 시작합니다.

---

작성자: KH.Choi
최종 수정: 2026-02-17
버전: 2.0 (범용 헌법)

