# 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. 작업 시작, 완료 후 문서 갱신

## 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/에 기록

========================================================
EXE BUILD RULE
========================================================

create_project.py가 수정되면

기존 EXE는 더 이상 최신 버전이 아니다.

반드시 아래 순서로 테스트한다.

1. build_exe.bat 실행
2. 새로운 EXE 생성 확인
3. EXE 실행 테스트
4. 정상 동작 확인
5. 작업 완료 보고

EXE 재빌드 없이 테스트를 완료로 판단하지 않는다.

========================================================
BUILD / TEST POLICY
========================================================

아래 작업은 코드 수정이 아니므로
TASK CONTRACT 및 사용자 승인이 필요하지 않다.

- build_exe.bat 실행
- run.bat 실행
- create_project.py 실행
- EXE 실행
- Validator 실행
- 로그 확인
- 테스트 결과 확인

아래 작업은 반드시 TASK CONTRACT와
사용자 승인을 받은 후 수행한다.

- 코드 수정
- 문서 수정
- 템플릿 수정
- 설정 파일 수정
- 파일 생성
- 파일 삭제
- 프로젝트 구조 변경

========================================================
RELEASE LOCK RULE
========================================================

Version 1.0 Official Release 이후에는

새로운 기능을 즉시 구현하지 않습니다.

새로운 기능은 반드시 아래 절차를 따릅니다.

1. IDEA.md에 아이디어 기록
2. README.md 구현 범위 검토
3. TODO.md 작업 등록
4. TASK CONTRACT 작성
5. 사용자 승인
6. 구현
7. BUILD
8. TEST
9. RELEASE

Version 1.x에서는

기존 기능의 안정성을 최우선으로 합니다.

버그 수정 및 성능 개선은 허용합니다.

새로운 기능 추가는
Version 2.0에서 진행합니다.

========================================================
VERSION POLICY
========================================================

각 Release 시점에 공식 Baseline을 생성한다.

Baseline 경로: baseline/v{major}.{minor}/
예: baseline/v2.0/, baseline/v2.1/

Baseline은 읽기 전용으로 보관한다.
Rollback이 필요한 경우 가장 최근 Baseline으로 복원한다.

Version 명명: Major.Minor 형식
- Major: 프로세스/구조 변경
- Minor: 기능 추가/개선
- Patch: 버그 수정

========================================================
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/
- 작업 중인 임시 문서 폴더
- 확정 후 초기화 또는 삭제
- 공식 문서와 혼동되지 않도록 관리