# 프로젝트 작업 지침

ShortVideoGenerator는 혼자 Codex에서 사용하는 짧은 영상 제작 프로젝트다. 주제와 언어를 제작마다 입력하고 14단계의 역할 지침·스킬·JSON 양식과 사용자 검토를 연결한다. 분야별 장면 제작은 별도 작업으로 구체화하며 Blender 모델·애니메이션과 기존 Remotion + FFmpeg 합성 경로를 연결한다.

## 작업 전에 확인

- docs/standards.md, docs/engineering-notes.md와 변경할 영역의 AGENTS.md를 먼저 읽는다. 결과 구조 변경 전에는 해당 스키마·양식, 시간 설계 전에는 실제 WAV와 구간, 이미지 작업 전에는 사용자 스타일 원본·조사 근거를 확인한다.
- 제작 내용을 작성할 때는 docs/short-video-guide.md의 담당 단계 절을 읽는다. 참고 영상의 소재 사실은 새 자료 조사에서 확인한다.
- 단계 결과·승인·시간·파일을 다룰 때는 docs/workflow-contracts.md와 해당 templates/stages 양식·contracts 스키마를 읽는다.
- 담당 역할은 .codex/agents의 TOML, 반복 작업은 .agents/skills의 SKILL.md를 사용한다. 목록·파일 형식과 실제 도구 실행 성공을 구분한다.

## 유지할 제작 기준

- 필수 입력은 주제·언어, 출력은 세로 9:16·최종 3분 이내·음성 기준 각 컷 5초 이내다. 쉬운 표현은 어린이 전용이라는 뜻이 아니다.
- 원본 references/1.png를 보존하고 단순 형태·정돈된 색을 깔끔한 교육용 3D로 해석한다. 단순한 배경·부드러운 조명·선명한 형태를 사용하며 평면 복제를 강제하지 않는다. 음성은 Qwen3-TTS의 기존 qwen3-tts 환경, 새 시각 제작은 Blender다. 사용자 전체 환경·설정을 변경하거나 도구를 무단 대체하지 않는다.
- topic/story/scenes/final의 실제 사용자 승인 없이 다음 경계를 넘지 않는다. 같은 승인 버전으로 재개하면 다시 묻지 않는다. scenes 승인 전에는 08의 제한된 대표 화면·짧은 움직임만 제작해 검토 근거로 사용하며 정식 10–12 완료로 처리하지 않는다. 새 08·09 승인 전 전체 제작을 시작하지 않는다.
- 새 양식·결과는 계약 1.1, 기존 1.0 결과는 보존·참조한다. .blend 원본은 BlendFile로 기록하며 PNG·MP4 media로 위장하지 않는다. 총괄만 project.json을 작성한다. 담당은 자기 새 버전의 결과·검토를 제출하고 이전 결과를 보존한다. 요청·예상·예제와 실제 결과·실측·승인을 구분한다.

## 프로젝트 구조

```text
ShortVideoGenerator/
├── AGENTS.md                    → Codex 작업 기준과 탐색 시작점
├── CLAUDE.md                    → 같은 프로젝트 작업 기준
├── docs/
│   ├── architecture.md          → 구성과 전달 흐름
│   ├── business-rules.md        → 제작·승인·수정 규칙
│   ├── security.md              → 접근·기록·인증정보 경계
│   ├── standards.md             → 작성·확인의 공통 기준
│   ├── engineering-notes.md     → 반복 작업의 원인과 대응
│   ├── operations.md            → 사용·제출·검증 명령
│   ├── contracts.md             → 사용자·생성 도구 전달 표면
│   ├── workflow-contracts.md    → 단계별 필드·완료·보류 기준
│   ├── short-video-guide.md     → 내용·화면 구성과 검토 메모
│   └── tracking/
│       ├── status.md            → 확인한 기능과 다음 구현
│       ├── verification.md      → 실제 검사 명령·결과·한계
│       ├── findings.md          → 미해결 문제
│       └── decisions/
│           ├── index.md         → 결정 기록 목록
│           └── 0001-local-instructions.md → 로컬 지침·JSON 전달 선택
├── .codex/agents/AGENTS.md       → 8개 역할 설정의 작성 경계
├── .agents/skills/AGENTS.md      → 15개 작업 스킬의 작성 경계
├── contracts/AGENTS.md           → 스키마의 구조·의미 구분
├── templates/AGENTS.md           → 빈 양식·검토 양식의 경계
├── tools/blender/AGENTS.md        → Blender 원본 검사·렌더 실행 경계
├── references/                  → 사용자 그림체와 참고 분석
└── examples/                    → 실제 실행과 구분한 연결 예제
```

## 문제 보고

사용자 승인 우회, 이전 결과의 손실, 다른 제작물·오래된 버전 혼입, 비밀정보 기록, 미확인 파일·시간을 실제 결과로 처리하는 문제는 즉시 사용자에게 보고한다. 부재한 생성 결과는 준비 조건과 돌아갈 단계를 보고하고 기다린다. 현재 범위에서 해결할 수 없는 그 밖의 문제는 원인·영향·보류 이유를 docs/tracking/findings.md에 남긴다.

## 생각하고 필요한 만큼 구현

가정을 먼저 밝히고 불명확한 점을 숨기지 않는다. 해석이 여러 개라면 선택지를 설명하고 중요한 미확정 사항을 질문한다. 더 간단한 방법이 있으면 설명한다. 이해하지 못한 상태에서는 그 지점을 명시하고 확인한다.

요청을 해결하는 최소 변경만 한다. 요청하지 않은 기능·추상화·유연성·설정을 추가하지 않는다. 불가능한 상황을 위한 방어 코드를 만들지 않는다. 선임 개발자가 과도하다고 볼 구성을 줄인다.

## 변경 범위와 검증

관련 없는 코드·주석·서식을 정리하거나 리팩터링하지 않는다. 기존 스타일을 따른다. 기존 불필요한 코드는 발견만 보고하고 삭제하지 않는다. 이번 변경이 새로 불필요하게 만든 항목만 제거한다. 모든 변경은 사용자 요청에 연결되어야 한다.

작업을 확인 가능한 목표로 나누고 짧은 계획과 단계별 검증 방법을 밝힌다. 의미 있는 동작을 검증하고 성공할 때까지 수정한다. 이 프로젝트의 문서·설정·양식에는 형식·참조·예제 흐름 확인을 사용하며 실제 미디어 생성 성공을 주장하지 않는다. 실제 프로그램이 추가되면 해당 동작과 실패 사례를 검증한다.