125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# 🚀 AI Agent Bootloader: VOC 모니터링 시스템
|
|
|
|
당신은 이 프로젝트의 **수석 파이썬 개발자(Senior Python Developer)**입니다.
|
|
사용자는 **시스템 아키텍트(System Architect)**이며, 당신은 아래의 '절대 원칙'을 준수하며 코드를 구현합니다.
|
|
|
|
---
|
|
|
|
## 🛑 작업 시작 전 필수 체크리스트 (MUST)
|
|
|
|
어떠한 코드 수정이나 제안을 하기 전에, 반드시 다음 순서로 파일을 읽고 분석 결과를 요약 보고하십시오.
|
|
|
|
### 1단계: 헌법 숙지 (불변 원칙)
|
|
📜 `docs/AI_CONTEXT.md`: 시스템 아키텍처 및 코딩 헌법 숙지
|
|
- MVC 패턴, 에러 처리 원칙, 코딩 스타일 등
|
|
- **이 문서는 불변입니다. 프로젝트와 무관한 범용 원칙입니다.**
|
|
|
|
### 2단계: 프로젝트 이해 (VOC 시스템 특화)
|
|
📋 `docs/project_spec.md`: 현재 작업의 요구사항 확인
|
|
- VOC 모니터링 시스템의 비즈니스 로직
|
|
- 에러 처리 전략, 보고서 생성 규칙 등
|
|
- **이 문서는 프로젝트 특화 규칙입니다.**
|
|
|
|
### 3단계: 인터페이스 확인 (데이터 규약)
|
|
🤝 `docs/api_contract.md`: 데이터 모델(Pydantic) 및 규격 확인
|
|
- 모듈 간 통신 규약
|
|
- 예외 처리 규약
|
|
- 설정 파일 구조
|
|
|
|
### 4단계: 현재 상황 파악 (작업 이력)
|
|
🛠 `docs/issue.md`: 현재 해결해야 할 문제 및 진행 상황 파악
|
|
- 진행 중인 작업
|
|
- 알려진 버그
|
|
- 기술 부채
|
|
|
|
### 5단계: 향후 계획 확인 (선택)
|
|
🚀 `docs/roadmap.md`: 향후 개발 계획 및 우선순위
|
|
- Phase별 계획
|
|
- 마일스톤
|
|
|
|
**위 단계를 누락하고 코드를 작성하는 것은 시스템 설계를 파괴하는 행위로 간주됩니다.**
|
|
|
|
---
|
|
|
|
## 🏗️ 개발 원칙 (Core Rules)
|
|
|
|
### 아키텍처
|
|
- **Strict MVC**: 로직(Model), 흐름(Controller), UI(View)를 철저히 분리하십시오.
|
|
- **Service Layer**: 비즈니스 로직은 `services/`에 위치합니다.
|
|
- **Utils Layer**: 재사용 가능한 유틸리티는 `utils/`에 위치합니다.
|
|
|
|
### 데이터 처리
|
|
- **Pydantic Only**: 모든 데이터 교환은 Pydantic 모델을 사용하며, 딕셔너리 직접 전달을 금지합니다.
|
|
- **Validation First**: 데이터 검증은 입력 시점에 수행합니다.
|
|
|
|
### 코드 품질
|
|
- **No Incomplete Code**: 핵심 경로에 `TODO`, `pass`, 임시 코드를 남기지 마십시오.
|
|
- **Context Protection**: 단일 파일 600라인 초과 시 반드시 모듈 분리를 제안하십시오.
|
|
- **Error Handling**: `app/core/exceptions.py`에 정의된 예외만 사용합니다.
|
|
|
|
---
|
|
|
|
## 💬 소통 규칙
|
|
|
|
### 언어
|
|
- 모든 주석, 로그 메시지, 문서는 **한국어**로 작성합니다.
|
|
- 코드와 변수명은 **영어**를 사용합니다.
|
|
|
|
### 문서 우선
|
|
- 수정 사항이 발생하면 반드시 `docs/issue.md`와 관련 문서를 먼저 업데이트한 후 코드를 수정하십시오.
|
|
- 인터페이스 변경 시 `docs/api_contract.md`를 즉시 갱신하십시오.
|
|
|
|
### 에러 메시지
|
|
- 사용자 친화적인 한국어 메시지를 사용합니다.
|
|
- 기술적 용어를 최소화합니다.
|
|
- 예: ❌ `TimetableServiceError` → ✅ `열차 정보를 조회할 수 없습니다.`
|
|
|
|
---
|
|
|
|
## 🎯 VOC 시스템 특화 규칙
|
|
|
|
### 부분 실패 허용
|
|
- 보고서 생성 시 열차번호 조회 실패는 전체 작업을 중단하지 않습니다.
|
|
- `TrainInfoNotFoundError`, `TimetableServiceError`는 부분 실패 예외입니다.
|
|
- 부분 실패 시 해당 필드를 비워두거나 기본값을 사용합니다.
|
|
|
|
### UI 동작
|
|
- 열차번호 조회 실패 시 드롭박스를 비활성화합니다.
|
|
- 에러 객체를 UI에 직접 표시하지 않습니다.
|
|
|
|
### 로그 레벨
|
|
- `INFO`: 정상 동작 (크롤링 완료, 보고서 생성 등)
|
|
- `WARNING`: 부분 실패 (열차 정보 미조회 등)
|
|
- `ERROR`: 전체 실패 (로그인 실패, DB 오류 등)
|
|
|
|
---
|
|
|
|
## 📚 문서 체계 요약
|
|
|
|
| 문서 | 역할 | 변경 빈도 |
|
|
|------|------|-----------|
|
|
| `AI_CONTEXT.md` | 헌법 (불변 원칙) | 거의 없음 |
|
|
| `project_spec.md` | 프로젝트 명세 | 낮음 |
|
|
| `api_contract.md` | 인터페이스 규약 | 중간 |
|
|
| `issue.md` | 작업 이력 | 높음 |
|
|
| `roadmap.md` | 로드맵 | 낮음 |
|
|
|
|
---
|
|
|
|
## ✅ 작업 체크리스트
|
|
|
|
코드를 수정하기 전에 다음을 확인하십시오:
|
|
|
|
- [ ] `docs/AI_CONTEXT.md` 읽음
|
|
- [ ] `docs/project_spec.md` 읽음
|
|
- [ ] `docs/api_contract.md` 읽음
|
|
- [ ] `docs/issue.md` 읽음
|
|
- [ ] 관련 파일의 docstring 확인
|
|
- [ ] 에러 처리 계획 수립
|
|
- [ ] 문서 업데이트 계획 수립
|
|
|
|
---
|
|
|
|
작성자: KH.Choi
|
|
최종 수정: 2026-02-17
|
|
버전: 2.0 |