# 프로젝트 개발 워크플로우

> 새로운 서비스/프로그램 개발 시 공통 적용되는 6단계 프로세스.
> 핵심 원칙: **충분한 조사 → 완벽한 계획 → 승인 → 일괄 구현**

---

## 0단계: 프로젝트 초기화

### 프로젝트 생성
```bash
cp -r /home/jay/workspace/projects/.template /home/jay/workspace/projects/<project-id>/
```

### manifest.json 필수 항목 작성
- `project_id`: 프로젝트 고유 ID (영문, 하이픈 허용)
- `name`: 프로젝트 한글명
- `description`: 1줄 설명
- `project_path`: 절대 경로
- `allowed_teams`: 투입 가능 팀 목록
- `status`: planning → research → development → released

### CLAUDE.md 작성
- 프로젝트별 격리 규칙 (이 디렉토리 밖 수정 금지)
- 빌드/테스트 명령어
- 프로젝트 고유 규칙

### 격리 원칙
- **코드**: `projects/<id>/` 내부에만 생성/수정
- **memory**: `memory/projects/<id>/` 에 프로젝트별 research/reports/tasks 저장
- **위임**: `dispatch.py --project <id>` 로 프로젝트 명시
- **다른 프로젝트 디렉토리, 시스템 코드 수정 절대 금지**

---

## 1단계: Research (조사/연구)

### 목적
프로젝트에 필요한 모든 지식을 사전에 확보한다.

### 유형별 Research 규칙

#### 기존 구현 파악
- 구현 내용이 있는 폴더를 **깊이 읽고** 어떻게 동작하는지 깊이 이해
- 모든 세부사항을 파악: 파일 구조, 함수 흐름, 데이터 모델, 의존성
- 누락 없이 전체 코드베이스를 읽은 뒤 정리

#### 기술/시스템 연구
- 대상 기술을 **매우 상세히** 연구하고 작동 원리의 모든 것을 파악
- 공식 문서, API 스펙, 제약사항, 비용, 성능 특성 포함
- 직접 테스트/검증 가능한 것은 반드시 실행하여 확인

#### 시장/서비스 조사
- 유사 서비스 분석, 차별점 도출
- 타겟 사용자 니즈, 기존 솔루션의 한계점 파악

### 전문가 미팅 (필요시)
- 조직 내 전문가 집단 미팅을 **3~5회** 진행하여 추가 결론 도출
- 미팅 기록: `memory/meetings/<날짜>-<주제>.md`
- 미팅 결과는 Research에 반영 (양방향 영향)

### 산출물
- `memory/research/INDEX.md`에 항목 추가
- `memory/research/<주제>.md`에 상세 내용 저장
- 목차→요약→상세 원칙 준수

---

## 2단계: Plan 작성

### 목적
Research를 기반으로 **실행 가능한 상세 계획서**를 작성한다.

### plan.md 필수 포함 항목

```
# [프로젝트명] 실행 계획

## 1. 접근방식 상세설명
- 아키텍처 선택 근거
- 기술 스택 선정 이유
- 전체 시스템 흐름도

## 2. 코드 스니펫
- 핵심 로직의 실제 코드 예시
- 기존 코드베이스를 읽고 실제 코드 기반으로 작성
- 인터페이스/타입 정의 포함

## 3. 파일 경로
- 생성할 파일 목록과 경로
- 수정할 기존 파일 목록과 변경 범위
- 디렉토리 구조도

## 4. 트레이드오프
- 선택한 접근법의 장단점
- 대안과 비교하여 왜 이 방법을 선택했는지
- 알려진 제약사항과 리스크

## 5. 단계별 구현 순서
- [ ] Step 1: ...
- [ ] Step 2: ...
- 의존 관계에 따른 순서 명시
```

### 규칙
- **실제 코드베이스를 먼저 읽고** 작성 (가정으로 작성 금지)
- 코드 스니펫은 복붙 가능한 수준으로 구체적
- 모호한 표현 금지 ("적절히 처리", "필요에 따라" 등 불가)

### 산출물 위치
- `memory/plans/<프로젝트명>/plan.md`

---

## 3단계: Plan 검토/개선

### 목적
계획이 **정확하고 완전한지** 반복 검토한다.

### 검토 루프
```
plan.md 작성 → 검토 → 개선사항 발견?
                         ├── Yes → plan.md 업데이트 → 재검토
                         └── No → 4단계로
```

### 검토 체크리스트
- 누락된 파일/기능이 없는가?
- 코드 스니펫이 실제 코드베이스와 정합성이 있는가?
- 트레이드오프를 충분히 고려했는가?
- 구현 순서에 의존성 충돌이 없는가?
- 엣지케이스를 고려했는가?

### 멀티에이전트 미팅 (필요시)
- 검토 중 복잡한 이슈 발견 시 전문가 미팅 진행
- 미팅에서 동시에 여러 관점의 개선사항 도출
- 미팅 결과 → plan.md 업데이트

### 절대 규칙
- **이 단계에서 코드 구현 절대 금지**
- plan.md 문서 업데이트만 수행

---

## 4단계: Plan 확정

### 목적
더 이상 개선사항이 없는 **최종 계획서**를 확정한다.

### 확정 조건
- 3단계 검토 루프에서 더 이상 개선사항 없음
- 모든 트레이드오프가 결정됨
- 구현 순서가 확정됨

### 절대 규칙
- **새로운 고민은 이 단계에서 끝**
- plan.md를 최종 버전으로 업데이트
- **코드 구현 절대 금지**

### 산출물
- `memory/plans/<프로젝트명>/plan.md` (최종 버전, 날짜 표기)

---

## 5단계: 제이회장님 승인

### 목적
최종 계획서를 **제이회장님이 직접 검토**하고 구현 승인을 내린다.

### 프로세스
1. 아누가 plan.md 핵심 요약을 제이회장님께 보고
2. 제이회장님이 계획서를 검토
3. 수정 요청 시 → 3단계로 복귀
4. **승인 시 → 6단계 구현 시작**

### 절대 규칙
- **제이회장님의 명시적 승인 없이 구현 시작 금지**
- 특별한 반복루프를 제이회장님이 아누에게 명령하지 않는 이상, 절대 알아서 코드 작성 금지

---

## 6단계: 구현

### 목적
확정된 계획을 **빠짐없이 완전하게** 구현한다.

### 구현 규칙

#### 완전성
- plan.md의 **모든 단계를 전부 구현**한다
- 중간작업이나 단계를 완료하면 **계획 문서를 업데이트** (완료 체크 표시)
- 모든 작업과 단계가 완료될 때까지 **멈추지 않는다**

#### 코드 품질
- `any`나 `unknown` 타입 사용 금지
- 지속적으로 **typecheck를 실행**하여 새로운 문제를 만들지 않는다
- 모듈화 원칙 준수 (200줄 이하, SOLID, DRY)

#### 마인드셋
- **6단계에서는 새로운 고민 없이 코드만 작성**
- 설계 변경이 필요하면 구현을 멈추고 3단계로 복귀 (제이회장님 판단)
- Plan에 있는 코드 스니펫을 기반으로 빠르게 구현

### 산출물
- 구현된 코드 파일들
- plan.md 업데이트 (각 단계 완료 표시)
- 보고서: `memory/reports/<task_id>.md`

---

## 전체 흐름도

```
[1. Research]
    │ 조사/연구/테스트
    │ 전문가 미팅 3~5회 (필요시)
    │ → research/INDEX.md + 주제별 파일
    ▼
[2. Plan 작성]
    │ 접근방식 + 코드 스니펫 + 파일 경로 + 트레이드오프
    │ → plans/<프로젝트>/plan.md
    ▼
[3. Plan 검토/개선] ◄──────────────────┐
    │ 검토 → 개선사항 발견 → 업데이트 ──┘
    │ 멀티에이전트 미팅 (필요시)
    │ 코드 구현 절대 금지
    ▼
[4. Plan 확정]
    │ 새로운 고민은 여기서 끝
    │ 코드 구현 절대 금지
    ▼
[5. 제이회장님 승인]
    │ 명시적 승인 필수
    │ 수정 요청 시 → 3단계 복귀
    ▼
[6. 구현]
    전부 구현 / 멈추지 않음 / 고민 없이 코드만
    any/unknown 금지 / typecheck 상시 실행
    단계 완료 시 plan.md 업데이트
```

---

## 시스템 고도화 로드맵

> 미팅 근거: `memory/meetings/2026-03-01-multiproject-isolation.md`
> 핵심 원칙: "첫 프로젝트를 돌려보고 진짜 문제가 드러난 후 구조를 확장한다"

### Phase 0: 기본 뼈대 (첫 프로젝트 시작 전) ← 현재
- [x] `projects/` 디렉토리 + `.template/` (manifest.json, CLAUDE.md)
- [x] PROJECT-WORKFLOW.md에 0단계(프로젝트 초기화) 추가
- [ ] `dispatch.py`에 `--project` 파라미터 추가
- [ ] `team_prompts.py`에 프로젝트 경로 + 격리 규칙 주입
- [ ] `task-timer.py`에 파일 락 추가 (동시 쓰기 보호)
- [ ] `task-timer.py`에 project_id 필드 추가

### Phase 1: 첫 프로젝트 경험 후 (프로젝트 1~2개)
- [ ] 실제 운영 경험 기반 구조 보완
- [ ] `memory/projects/<id>/` 네임스페이스 분리 검토
- [ ] `project-isolation.py` → `dispatch.py` 연동 검토
- [ ] 공유 라이브러리 필요성 판단

### Phase 2: 규모 확장 (프로젝트 5개 이상)
- [ ] 시스템 코드 물리적 분리 (`_system/` 또는 별도 repo)
- [ ] 사후 검증 자동화 (파일 변경 범위 체크)
- [ ] 시스템 업데이트 잠금 프로토콜
- [ ] 공유 라이브러리 레지스트리 (`shared/` + SHARED-REGISTRY.md)

### Phase 3: 대규모 운영 (프로젝트 15개 이상)
- [ ] 프로젝트별 독립 git repo (polyrepo)
- [ ] CI/CD 파이프라인 per project
- [ ] 리소스 모니터링/할당 시스템