# RULES.md

## 1. 목표

이 프로젝트의 모든 작업은 다음 원칙을 따른다:
- **AI 이어작업 우선**: 문서와 코드는 AI가 중단 후 재개해도 즉시 맥락을 파악할 수 있도록 작성
- **일관성**: 기존 패턴, 명명 규칙, 디렉터리 구조를 따름
- **안전성**: 파일 조작 시 기존 파일/디렉터리 보존, 덮어쓰기 방지

## 2. 문서 작성 규칙

### 2.1 공통 문서 구조
모든 Markdown 문서는 다음 형식을 따른다:
- 제목: `# 문서명`
- 메타정보: `| 항목 | 값 |` 테이블 (해당 시)
- 마지막 섹션: **AI 재개용 안내** — 현재 상태, 다음 할 일, 참고 파일

### 2.2 STATE.json 업데이트 규칙
작업 시작 전과 완료 후에 반드시 갱신한다:
```json
{
  "updated_at": "ISO8601",
  "current_phase": "설계/구현/테스트",
  "last_completed": "task_id",
  "in_progress": "task_id",
  "next_step": "task_id",
  "blockers": [],
  "decisions": []
}
```

### 2.3 TODO.md 관리 규칙
- `☐` 미완료, `☑` 완료
- 우선순위: `higher`, `medium`, `lower`
- 작업 완료 시 **완료일**과 **결과 요약**을 함께 기록

### 2.4 CHANGELOG.md 규칙
- Keep a Changelog 형식 준수
- 버전은 `0.Y.Z` 형식 (0.x 단계)

## 3. 코드 작성 규칙

### 3.1 Python
- PEP 8 준수
- 타입 힌트 사용 (`typing` 또는 `annotations`)
- 함수/클래스에 독스트링 추가
- 예외 처리: 구체적 예외만 잡고, 로깅 후 재발생

### 3.2 파일명
- snake_case 사용 (모듈, 함수, 변수)
- 클래스는 PascalCase
- 상수는 UPPER_SNAKE_CASE

### 3.3 안전 규칙
1. **덮어쓰기 방지**: 기존 디렉터리/파일이 있으면 즉시 중단 및 오류 출력
2. **입력 검증**: 프로젝트 번호는 숫자, 이름은 한글/영문/공백 구분자로만 구성
3. **에러 처리**: 명확한 오류 메시지와 함께 친절한 안내 제공

## 4. AI 재개 프로토콜

작업 재개 시 다음 순서를 따른다:
1. `STATE.json` 읽어 현재 단계 확인
2. `TODO.md`에서 `in_progress` 항목 확인
3. `PROJECT_CONTEXT.md`의 아키텍처/결정사항 확인
4. `CHANGELOG.md` 최신 항목 확인
5. 작업 시작, 완료 후 문서 갱신