# RULES.md

## 1. 목표

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

## 2. 문서 작성 규칙

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

### 2.2 STATE.json 업데이트 규칙
작업 시작 전과 완료 후에 반드시 갱신한다:
```json
{
  "updated_at": "ISO8601",
  "current_phase": "문서_설계 | 기술결정 | ...",
  "current_checkpoint": "CHECKPOINT_1 | ...",
  "last_completed": "task_id",
  "in_progress": "task_id",
  "next_step": "task_id",
  "document_status": {
    "REQUIREMENTS": "Draft | Reviewed | Approved | Frozen",
    "TECHNICAL_DECISIONS": "...",
    "UI_FLOW": "...",
    "ARCHITECTURE": "...",
    "IMPLEMENTATION_PLAN": "...",
    "DESIGN_FREEZE": "...",
    "DOCUMENT_VALIDATION_RULES": "..."
  }
}
```

### 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. `document_status` 확인 - Draft 상태 문서부터 진행
6. 작업 시작, 완료 후 문서 갱신

## 5. 검증 강제 규칙 (AI-WORKS v2.0)

### 5.1 완료 보고 조건
다음 모두 충족해야 "완료" 보고 가능:
1. 파일이 생성되어 존재함
2. 파일 내용이 100자 이상 (설계 문서는 500자 이상)
3. placeholder (`내용을 입력하세요`, `TODO`, `placeholder`)가 없음
4. 필수 섹션이 모두 존재함
5. 검증 도구 또는 검사자가 PASS 확인

### 5.2 DESIGN_FREEZE 조건
다음 문서가 모두 검증 통과해야 DESIGN_FREEZE 승인:
- REQUIREMENTS.md
- TECHNICAL_DECISIONS.md
- UI_FLOW.md
- ARCHITECTURE.md
- IMPLEMENTATION_PLAN.md

### 5.3 상태 일관성
STATE.json, TODO.md, PROJECT_CONTEXT.md, SESSION.md의 상태가
상이할 경우 반드시 STATE.json을 기준으로 다른 문서를 동기화한다.

## 6. 프로젝트 유형별 규칙

### 6.1 일반 프로젝트 (01~99)

- `SESSION.md` 사용
- 템플릿 기반 생성
- 표준 문서 구조 준수

### 6.2 생성기 프로젝트 (00-프로젝트생성기)

- **SESSION.md를 사용하지 않는다**
- 구조가 일반 프로젝트와 다르다
- STATE.json, TODO.md, CHANGELOG.md로 상태 관리
- 템플릿을 관리하는 도구이므로 템플릿 자체가 아니다
- 필요한 경우 logs/에 기록

========================================================
COLLABORATION SAFETY RULES
========================================================

## 7. 협업 안전장치 (Working Workspace)

### 7.1 Working Directory
- 모든 수정 작업은 `working/` 폴더에서 먼저 수행
- 공식 문서는 사용자 확정 전까지 직접 수정하지 않음
- 확정 후에만 공식 위치로 반영

### 7.2 Decision Gate
- 결정이 필요한 시점에는 새 작업을 시작하지 않음
- 현재 안건을 먼저 완결한 후 다음 안건으로 이동
- "결정해 주세요" 요청 시 새 아이디어를 추가하지 않음

### 7.3 Apply Gate
- 사용자가 "확정", "적용", "승인"을 명시적으로 요청한 경우에만 공식 반영
- 반영 후 `working/` 폴더를 초기화
- 반영 내용은 CHANGELOG.md에 기록

### 7.4 Snapshot
- 중요한 중간 결과는 `working/snapshots/`에 저장 가능
- 자동 Snapshot 생성은 v2.2 이후 검토

=======================================================
FOLDER ROLES
=======================================================

## 8. 폴더 역할 및 삭제 기준

### build/
- 임시 빌드 결과 폴더
- 필요 없으면 삭제 가능
- create_project.py 수정 전에 삭제 권장

### dist/
- 배포 결과 폴더
- 사용자 배포용으로 보관 가능
- 새 배포 생성 전에 삭제 가능

### baseline/
- 공식 기준 버전 보관 폴더
- 읽기 전용으로 보관
- 삭제 금지
- Rollback이 필요한 경우 복원 source로 사용

### working/
- 작업 중인 임시 문서 폴더
- 확정 후 초기화 또는 삭제
- 공식 문서와 혼동되지 않도록 관리

=======================================================
IMPROVEMENT PRIORITY RULE
=======================================================

## 9. 개선 우선순위 규칙

개선 요청은 다음 순서로 처리한다:

```
Bug → Stability → Framework → Template → Feature
```

| 우선순위 | 대상 | 설명 |
|---------|------|------|
| Bug | 운영 중단, 데이터 손실 | 즉시 조치 (v0.1 Patch 배포) |
| Stability | 성능, 가독성 개선 | 최우선 (v0.x Patch) |
| Framework | 운영 프로세스, 규칙 | 안정화 단계 (v2.x Minor) |
| Template | 템플릿 파일, 구조 | 안정화 단계 (v2.x Minor) |
| Feature | 신규 기능 | 확장 단계 (v3.x Minor) |

=======================================================
RELEASE READY FREEZE RULE
=======================================================

## 10. Release Ready 동결 규칙

Official Release 직전 동결 상태를 유지한다.

### 동결 조건
Release Ready 상태가 되면 다음이 금지된다:

- 새로운 기능 추가
- 구조 변경
- 문서 수정
- 새 아이디어 반영

### 허용 사항
- 버그 수정만 허용

### 확인 방법
사용자가 "Release Ready" 확인 후:
1. CHANGELOG.md에 동결 사실 기록
2. 추가 변경 요구 시 "MUST Restart Release Process"
