# Codex × Antigravity 문서 주도 서비스 개발 PBL

## 프로젝트 질문

대화로 흩어진 요구사항을 사람이 검증할 수 있는 Markdown 계약으로 만들고, 그 계약을 기준으로 실제 서비스를 구현하고 검증할 수 있는가?

## 프로젝트 시나리오

- 고객: 휴대폰에서 샌드위치와 음료를 탐색하고 옵션을 골라 주문한다.
- 관리자: PC에서 메뉴, 재고, 주문 현황을 확인하고 주문 상태를 변경한다.
- 디자인 방향: 신선함, 선택의 즐거움, 단계가 명확한 주문 경험.
- 데이터: 실제 개인정보나 결제 정보가 아닌 가상 메뉴와 가상 주문만 사용한다.
- 도구 역할: Codex는 대화 정리·질문·감사를 돕고, Antigravity IDE는 승인된 MD를 기준으로 구현을 돕는다.

## 최종 목표

1. 대화 기록에서 사실, 가정, 질문, 결정을 구분한다.
2. 계획·구현·검증의 책임이 분리된 폴더와 MD 문서를 만든다.
3. 모바일 고객 주문과 PC 관리자 흐름을 작동하게 구현한다.
4. 설계 검증과 서비스 검증을 분리해 증거로 통과 여부를 판정한다.
5. AI가 만든 결과를 자신의 말로 설명하고 수정·반려한 이유를 제시한다.

## 권장 일정과 배점

| 순서 | 미션 | 권장 시간 | 핵심 결과 | 배점 |
|---:|---|---:|---|---:|
| 1 | 대화 → 요구사항 | 3~4시간 | PROJECT_BRIEF, DECISION_LOG | 25 |
| 2 | MD 명세 패키지 | 4~6시간 | 화면·데이터·API·분석·검증 문서 | 25 |
| 3 | Antigravity 구현 | 6~9시간 | 모바일·PC 서비스, AI_WORK_LOG | 30 |
| 4 | 설계·서비스 검증 | 3~5시간 | 2개 검증 보고서, 결함·회고 | 20 |

## 시작 폴더

```text
kiosk-pbl/
├── README.md                        # 프로젝트 전체 개요 및 실행 안내
├── service-planning/                # [기획] 요구사항 · 화면 · 정책 · 디자인 명세
│   ├── PROJECT_BRIEF.md             # 프로젝트 정의 및 MVP 범위
│   ├── DECISION_LOG.md              # 사실·가정·질문·결정 기록
│   ├── CUSTOMER_ORDER.md            # 고객 모바일 주문 화면 명세
│   ├── ADMIN_CONSOLE.md             # PC 매장 관리자 화면 명세
│   ├── DESIGN_CONCEPT.md            # Fresh Route 디자인 시스템·원리
│   ├── MENU_DATA.md                 # 가상 메뉴 10종+ 및 옵션 스키마
│   ├── API_CONTRACT.md              # 주문·메뉴·상태 전이 API 계약
│   └── TRACEABILITY.md              # 요구사항 추적 매트릭스
├── service-analysis/                # [분석] 지표 · 이벤트 · 데이터 품질 · 분석 API
│   ├── README.md                    # 분석 영역 안내
│   ├── ANALYSIS_DEFINITION.md       # 핵심 지표(KPI) 및 이벤트 정의
│   └── ANALYTICS_API_DEFINITION.md  # 분석 수집·조회 API 명세
├── service-implementation/          # [구현] Antigravity IDE 기반 모바일·PC 앱
│   ├── README.md                    # 실행 · 빌드 · 테스트 안내
│   ├── AI_WORK_LOG.md               # AI 작업 요청 및 사람의 검토·수정 로그
│   └── 앱 소스 (customer / admin / shared)
└── service-validation/              # [검증] 설계 검증 · 서비스 검증 · 결함·회고
    ├── VALIDATION_PLAN.md           # 통합 검증 계획
    ├── DESIGN_VALIDATION.md         # 문서 정합성 검증 결과
    ├── SERVICE_VALIDATION.md        # 모바일·PC 실행 검증 결과
    ├── DEFECT_LOG.md                # 결함 리포트 및 재검증 기록
    └── RETROSPECTIVE.md             # AI 협업 및 의사결정 회고
```

service-analysis는 service-planning의 하위 폴더가 아닙니다. 계획, 분석, 구현, 검증은 서로 다른 책임을 가진 최상위 영역입니다.

## 공통 작업 리듬

1. 학생이 먼저 초안과 모르는 점을 쓴다.
2. Codex에 구조화, 누락 질문, 반례 검토를 요청한다.
3. AI 답변에서 채택·수정·반려할 내용을 학생이 판단한다.
4. 결정과 이유를 DECISION_LOG에 기록한다.
5. 요구사항 ID를 문서, 코드, 테스트 증거에 연결한다.
6. 단계가 끝날 때 통과 게이트를 확인한다.

## ID 규칙

- REQ-###: 사용자·운영 요구사항
- UI-###: 화면과 상호작용
- DATA-###: 데이터 필드·정합성
- API-###: API 계약
- EVT-###: 분석 이벤트
- TEST-###: 검증 시나리오
- DEF-###: 발견 결함
- AI-###: AI 작업 기록
- DEC-###: 사람의 결정

연결 예시:

```text
REQ-004 → UI-007 → DATA-order.status → API-006 → TEST-012 → DEF-002
```

## AI 사용 책임 규칙

- AI를 열기 전에 학생의 초안을 먼저 남긴다.
- AI가 대화에 없는 요구사항을 사실처럼 추가하지 못하게 제한한다.
- 생성된 코드와 문서의 정확성, 보안, 저작권 책임은 제출자에게 있다.
- AI 제안을 그대로 제출하지 않고 실행·검토·수정한 증거를 남긴다.
- AI 제안을 거절한 사례와 이유를 최소 2건 기록한다.
- 최종 발표에서 산출물을 자신의 말로 설명하지 못하면 미완료로 본다.

## 안전·윤리 경계

- 실제 개인정보, 인증 정보, 결제 정보, 비밀 키를 저장하지 않는다.
- 외부 서비스의 로고, 문구, 이미지, 화면, 소스 코드를 복제하지 않는다.
- 레퍼런스는 디자인 원리와 사용자 경험 패턴만 관찰한다.
- 비공개 API 접근, 인증 우회, 이용약관을 위반하는 자동 수집을 하지 않는다.
- 분석 이벤트에 이름, 전화번호, 주소, 결제 정보 원문을 넣지 않는다.

## 최종 제출물

- service-planning 전체
- service-implementation 전체와 실행 안내
- service-validation 전체와 화면·로그 증거
- 진행 기록 MD
- 7분 데모와 5분 근거·회고 발표

## 최종 통과 조건

- 총점 70점 이상
- 네 미션 모두 제출
- 모바일 고객 주문과 PC 관리자 대표 흐름 실행 가능
- 치명 결함 0건, 높음 결함은 수정 후 재검증
- 요구사항부터 테스트까지 핵심 ID가 추적 가능
- AI 사용과 사람의 판단 기록이 확인 가능

