# 📜 [Python 프로젝트 범용 기본 헌법] v1.5

## 서문 (Preamble)

이 문서는 본 프로젝트의 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** (사용자 인터페이스) | 😊 얼굴 | 데이터를 시각적으로 표현하는 것**만** 담당한다. **비즈니스 로직을 포함해서는 안 된다.** (Console, Web, GUI 모두 해당) |
| **Controller** (중재자) | 🔗 신경망 | 사용자의 입력을 받아 Model을 갱신하고 View에 전달. 흐름 제어. |


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

`core` 패키지를 도입하여 설정과 예외를 중앙 관리한다.

```
project_root/
├── app/
│   ├── core/        # [심장] 프로젝트의 핵심 설정 및 표준
│   │   ├── config.py      # 환경변수, 상수 관리 (하드코딩 금지)
│   │   └── exceptions.py  # 커스텀 예외 정의 (여기 없는 에러 금지)
│   ├── models/      # [뇌] Pydantic 모델, DB 스키마, 비즈니스 로직
│   ├── views/       # [얼굴] UI/UX (Console, Web, GUI)
│   ├── controllers/ # [신경망] 제어 로직
│   └── utils/       # [도구] 로깅, 공통 헬퍼 함수
├── tests/           # 테스트 코드
├── docs/            # 문서 (한글 작성)
└── main.py          # 진입점
```

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

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

### 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는 개발자에게 모호한 답변을 하지 않는다. "그럴 수도 있습니다" 대신, **근거에 기반한 명확한 솔루션**을 제시한다.
- 코드 설명 시, 복잡한 전문 용어보다는 **직관적인 비유와 쉬운 한국어 표현**을 우선한다.
- AI와의 대화, 주석, 문서, 리드미 등 모든 텍스트는 **한국어**로 작성한다.
- **예외:** 코드 문법(키워드)은 영어, 변수명은 명확한 영어 단어 사용.

---

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

### 4.1 Pythonic Style

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

### 4.2 설정 관리 (Configuration)

- **하드코딩 절대 금지:** API 키, DB 주소, 타임아웃 시간 등 모든 설정값은 코드에 박아넣지 않는다.
- 반드시 `app/core/config.py` (Pydantic BaseSettings 등 활용)를 경유하여 호출한다.

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

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

### 4.4 에러 처리의 표준화 (Exception Handling)
- 에러를 침묵시키지 않는다(**`pass` 금지**).
- **표준 예외 사용:** AI가 임의로 `Exception`을 던지지 않는다. 반드시 `app/core/exceptions.py`에 정의된 커스텀 예외(예: `[Domain]Error`, `[Action]Error`)를 사용한다.
- **침묵 금지:** `try-except pass`는 해고 사유다. 모든 에러는 로그를 남기거나 사용자에게 알기 쉽게(한국어로) 전파되어야 한다.

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

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

---
### 4.6 오케스트레이션 및 서비스 생애주기 (Lifecycle & Orchestration)
- **API 중앙화:** 다수의 라우터는 개별적으로 `main.py`에 등록하지 않으며, 반드시 `api_v1.py` 등 중앙 라우터에 `include_router`로 묶어서 퍼사드(Facade) 형태로 진입점을 단일화한다.
- **의존성 중앙화:** 서비스 인스턴스, DB 세션 등의 주입(DI) 함수는 `dependencies.py` 한 곳에서 통합 관리하여 추후 인증/권한 로직 결합에 대비한다.
- **서비스 생애주기 (1 Request = 1 Instance):** 모든 서비스 객체는 FastAPI의 `Depends()`를 통해 주입받으며, HTTP 요청 1건당 생성되고 응답 시 소멸하는 무상태(Stateless)를 엄격히 유지한다.
- **복합 트랜잭션 (Orchestrator/Facade 패턴):** 여러 도메인의 CRUD가 혼합된 복잡한 비즈니스 로직(예: 인수인계)은 라우터에서 개별 호출하지 않고, 해당 도메인을 아우르는 단일 Facade Service(예: `HandoverService`)를 구축하여 **단일 DB 세션(Session) 하에서 원자적(Atomic)으로 묶어 롤백(Rollback)을 보장**해야 한다.

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

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

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

1. **Context Awareness (맥락 인식):** 작업을 시작하기 전에 반드시 전체 파일 구조를 인덱싱하고, 관련 파일(`models.py`, `services/` 등)의 내용을 먼저 읽은 뒤 제안한다.
2. **Sample First (데이터 우선):** 파싱이나 데이터 처리 로직 수정 시, `data/samples/`에 있는 실제 데이터 규격을 최우선으로 참고한다.
3. **Test-Driven Modification (테스트 주도):**
   - 기능을 추가하거나 수정할 때, 해당 기능을 검증할 수 있는 테스트 스크립트(`tests/`)가 있는지 확인한다.
   - 테스트가 없다면 테스트 코드를 먼저 작성하거나 제안하고, 수정 후에는 반드시 테스트 통과 여부를 리포트한다.
4. **Step-by-Step Thinking (단계적 사고):** 복잡한 로직 수정 시 바로 코드를 짜지 말고, `docs/project_spec.md`에 의거한 작업 순서를 먼저 브리핑하고 사용자의 승인을 얻은 뒤 코딩을 시작한다.

### 5.2 로드맵 정합성 (Roadmap Consistency)

- **아이디어 기록:** 새로운 아이디어나 추가 기능은 코드에 바로 넣지 않고 `docs/roadmap.md`에 먼저 기록하여 전체 아키텍처와의 정합성을 검토한다.

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

- **의존성 주입(DI) 준수:** 파일을 분리할 때는 단순히 코드를 자르는 것이 아니라, **의존성 주입(Dependency Injection)** 원칙을 철저히 지켜야 한다.
- **분리 기준:** 단일 파일이 600라인을 초과하거나, 특정 기능(예: DB 처리, API 통신)이 너무 비대해졌을 때 분리를 제안한다.
- **구현 방식:**
  - 분리된 모듈은 생성자(Constructor)나 메서드 인자를 통해 필요한 객체(Dependency)를 주입받아야 한다.
  - 전역 변수나 싱글톤(Singleton) 남용을 지양하고, 명시적인 의존성 관리를 통해 테스트 용이성과 코드의 유연성을 확보해야 한다.

---

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

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

모든 프로젝트는 아래 3종의 문서를 `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)를 먼저 수정하여 제안한 뒤 코딩을 시작한다.


## 제7조: Git (GitHub/Gitea) PR 및 Issue 연동 규칙

### 7.1 브랜치 전략 (Branching)
- `main`: 운영(`prod`) 환경 배포용
- `develop`: 개발(`dev`) 환경 배포용
- `feature/[#이슈번호]-[작업명]`: 개별 기능 개발용 (예: `feature/#12-handover-api`)

### 7.2 Issue 동기화 및 PR (Pull Request) 작성
- **로컬-원격 동기화:** `docs/issue.md`에 기록하는 작업 내역은 원격 Issue 번호와 1:1 매핑되어야 한다.
- **PR 필수 포함 내용:** AI 제안 시 1) 해결 Issue 번호(`Closes #12`), 2) `api_contract.md` 변경 요약, 3) 테스트 통과 여부를 반드시 포함한다.