# AI-WORKS 프로젝트 생성기 업데이트 계획서

## 1. AI-WORKS Standard v2.0 목표

- 프로젝트 설계 단계에서 체계적 문서화 프로세스 표준화
- 7개 신규 템플릿 문서 포함 (REQUIREMENTS, TECHNICAL_DECISIONS, UI_FLOW, ARCHITECTURE, IMPLEMENTATION_PLAN, DESIGN_FREEZE, DOCUMENT_VALIDATION_RULES)
- 문서 품질 자동 검증 (placeholder 검출, 최소 길이 검사, 필수 섹션 검사)
- STATE.json 기반 상태 관리 (Single Source of Truth)
- DESIGN_FREEZE 승인 자동 조건 검사
- 기존 01~04 프로젝트와 호환 유지

## 2. 새로 추가할 템플릿 문서 목록

04-사진줄이기 프로젝트 문제점 해결을 위해 추가

| 템플릿 | 목적 | 추가 이유 |
|--------|------|----------|
| `REQUIREMENTS.md.template` | 핵심 요구사항 및 기능 정의 | 기존 요구사항이 채팅에만 존재해 문서화 필요 |
| `TECHNICAL_DECISIONS.md.template` | 기술적 의사결정 기록 | 기술 결정 변경 문제 해결을 위해 결정 고정 |
| `UI_FLOW.md.template` | 화면 흐름 및 사용자 인터페이스 설계 | UI 설계 없이 코딩 시작으로 수정 반복 |
| `ARCHITECTURE.md.template` | 시스템 아키텍처 및 구조 설계 | 구조를 먼저 확정하기 위해 |
| `IMPLEMENTATION_PLAN.md.template` | 구현 계획 및 작업 단계 | AI가 구현 순서를 임의로 변경하는 것 방지 |
| `DESIGN_FREEZE.md.template` | 설계 확정 내역 | 설계 변경 방지 |
| `DOCUMENT_VALIDATION_RULES.md.template` | 문서 검증 규칙 정의 | placeholder 저장 문제 해결을 위해 검증 절차 추가 |

## 3. Version 2.0 범위 (승인)

### 3.1 포함 기능

| 우선순위 | 항목 | 설명 |
|----------|------|------|
| 1 | 템플릿 변수 치환 | `{PROJECT_NAME}`, `{PROJECT_NUMBER}`, `{CREATED_DATE}` 정상 치환 |
| 2 | Document Validation | 파일 존재, placeholder, 최소 길이, 필수 섹션 검사 |
| 3 | validate_project() 확장 | 신규 7개 문서 검증 추가 |
| 4 | STATE.json 중심 관리 | Single Source of Truth 원칙 적용 |
| 5 | DESIGN_FREEZE 조건 | 모든 설계 문서 PASS 후에만 승인 가능 |

### 3.2 제외 기능 (v2.1 이후 검토)

| 항목 | 사유 |
|------|------|
| State Machine | 범위 확대, 향후 검토 |
| Immutable Zones | 범위 확대, 향후 검토 |
| 독립 Validation Tool | 범위 확대, 향후 검토 |
| Test Harness | 범위 확대, 향후 검토 |
| 기타 Framework 확장 | 핵심 기능 안정화 후 검토 |

## 4. 템플릿 변수 치환

### 4.1 대상 변수

- `{PROJECT_NAME}`: 프로젝트 이름 (예: `사진분류`)
- `{PROJECT_NUMBER}`: 프로젝트 번호 (예: `03`)
- `{CREATED_DATE}`: 생성일자 (예: `2026-07-05`)

### 4.2 적용 위치

모든 `.template` 파일에서 위 변수가 발견되면 자동 치환

### 4.3 함수 설계

`substitute_template_vars(content, project_number, project_name, created_date)`

## 5. create_project.py 수정 계획

### 5.1 새 함수 추가

- `substitute_template_vars(content, project_number, project_name, created_date)`
- `validate_documents(project_folder)` - 포괄적 문서 검증

### 5.2 기존 함수 수정

- `copy_templates(project_number, project_name)` - 변수 치환 추가
- `validate_project(project_number, project_name)` - 신규 7개 문서 추가
- `save_log(project_number, project_name, status)` - 신규 7개 문서 추가

### 5.3 검증 항목 (validate_documents)

1. placeholder 검출
   - 금지 구문: `내용을 입력하세요`, `TODO`, `placeholder`, `N/A` (섹션 전체)
   - 빈 섹션: 헤더만 있고 내용이 없는 경우

2. 최소 길이 검사
   - 모든 문서: 100자 이상
   - 설계 문서 (REQUIREMENTS, ARCHITECTURE 등): 500자 이상 권장

3. 필수 섹션 검사
   - 각 문서별 필수 섹션 존재 확인

4. 결과 리포트
   - PASS / FAIL / WARNING 명확히 구분하여 출력

## 6. DESIGN_FREEZE 승인 조건

### 6.1 자동 검증 로직

DESIGN_FREEZE.md의 상태를 `Frozen`으로 변경하려면:

1. `validate_documents()`로 다음 파일 검증 통과:
   - REQUIREMENTS.md
   - TECHNICAL_DECISIONS.md
   - UI_FLOW.md
   - ARCHITECTURE.md
   - IMPLEMENTATION_PLAN.md

2. DESIGN_FREEZE.md 검증 통과

3. STATE.json의 `document_status`에 모든 설계 문서가 `Approved` 또는 `Frozen`으로 기록됨

### 6.2 검증 실패 시

- 어떤 문서가 FAIL인지 명시
- DESIGN_FREEZE 승인 불가 메시지 출력
- 해당 문서 수정 후 재검증 필요

## 7. 기존 템플릿 수정 목록

| 템플릿 | 수정 내용 |
|--------|------|
| `STATE.json.template` | Standard v2.0 표시, current_phase 업데이트, document_status 필드 추가 |
| `TODO.md.template` | 신규 문서 작업 항목 추가, checkpoint 항목 추가 |
| `SESSION.md.template` | Standard v2.0 표시, 현재 phase 명확히, document_status 반영 |
| `PROJECT_CONTEXT.md.template` | 신규 문서 구조 반영, 누락된 항목 추가 |
| `REQUIREMENTS.md.template` | placeholder 제거, 실제 구조 예시로 변경 |
| `TECHNICAL_DECISIONS.md.template` | placeholder 제거, 실제 구조 예시로 변경 |
| `UI_FLOW.md.template` | placeholder 제거, 실제 구조 예시로 변경 |
| `ARCHITECTURE.md.template` | placeholder 제거, 실제 구조 예시로 변경 |
| `IMPLEMENTATION_PLAN.md.template` | placeholder 제거, 실제 구조 예시로 변경 |
| `DESIGN_FREEZE.md.template` | placeholder 제거, Frozen 상태 관리 추가 |
| `DOCUMENT_VALIDATION_RULES.md.template` | 내용 보강, 실제 검증 규칙으로 변경 |

## 8. STATE.json 중심 상태 관리

### 8.1 원칙

- STATE.json이 유일한 진실 소스 (Single Source of Truth)
- 다른 문서 (TODO.md, PROJECT_CONTEXT.md, SESSION.md)는 STATE.json을 반영하거나 파생
- 상태 불일치 발생 시 STATE.json 기준으로 동기화

### 8.2 STATE.json 필드

```json
{
  "standard_version": "2.0",
  "project": "...",
  "version": "...",
  "updated_at": "...",
  "current_phase": "문서_설계 | 기술결정 | ...",
  "current_checkpoint": "CHECKPOINT_1 | ...",
  "last_completed": "...",
  "in_progress": "...",
  "next_step": "...",
  "blockers": [],
  "decisions": [],
  "history": [],
  "document_status": {
    "REQUIREMENTS": "Draft | Reviewed | Approved | Frozen",
    "TECHNICAL_DECISIONS": "...",
    "UI_FLOW": "...",
    "ARCHITECTURE": "...",
    "IMPLEMENTATION_PLAN": "...",
    "DESIGN_FREEZE": "...",
    "DOCUMENT_VALIDATION_RULES": "..."
  }
}
```

## 9. 기존 01~04 프로젝트 영향 검토

- **영향 없음**: 기존 프로젝트는 신규 템플릿 생성 대상이 아님
- **호환성 유지**: 기존 템플릿 구조 유지, 선택적 업데이트 가능
- **문서 검증**: 기존 프로젝트는 검증 대상에서 제외

## 10. 업데이트 순서

1. `GENERATOR_UPDATE_PLAN.md` 수정 (본 문서)
2. `create_project.py` 수정
   - 템플릿 변수 치환 함수 추가
   - `validate_documents()` 함수 추가
   - `copy_templates()` 함수 수정
   - `validate_project()` 함수 수정
   - `save_log()` 함수 수정
3. `templates/default/` 템플릿 수정
   - STATE.json.template
   - TODO.md.template
   - SESSION.md.template
   - PROJECT_CONTEXT.md.template
   - 7개 신규 템플릿 내용 보강
4. 테스트 실행
   - 새 프로젝트 생성 테스트 (예: 99-test)
   - 변수 치환 확인
   - 문서 검증 확인
   - DESIGN_FREEZE 조건 확인

## 11. 테스트 방법

1. 새 프로젝트 생성 (예: 99-test)
2. 변수 치환 확인: 템플릿 변수가 실제 값으로 대체되었는지 확인
3. 문서 검증 확인: placeholder가 없는지, 길이가 충분한지 확인
4. STATE.json의 current_phase, document_status 확인
5. DESIGN_FREEZE 조건 확인: 설계 문서 PASS 시 DESIGN_FREEZE 가능 여부 확인
6. 로그 파일 확인

## 12. 되돌리기 방법

1. `templates/default/*.template` 백업 후 수정
2. `create_project.py` 수정 전 백업
3. 필요 시 백업 파일 복원

## 13. 수정 전 백업 필요 여부

| 항목 | 백업 필요 | 방법 |
|------|----------|------|
| 템플릿 파일 | 권장 | 별도 폴더에 복사 |
| create_project.py | 필수 | `create_project.py.bak` 생성 |
| 로그 파일 | 불필요 | 기존 로그 유지 |

## 14. Version 2.1 이후 후보 기능 (IDEA)

- State Machine 기반 프로세스 제어
- Immutable Zones (FROZEN 문서 수정 금지)
- 독립 Validation Tool (`validate_project.py`)
- Test Harness (Standard 자체 테스트)
- 프로젝트 체크포인트 시스템 강화
- 지식 전수 메커니즘 자동화

---

**생성기 업데이트 계획 v2.0 승인 완료**
