Codex Template

Codex를 활용해 어떤 프로그램이든 만들기 위한 제작 양식이다. 이 저장소는 완성된 앱이 아니라, 새 프로젝트를 시작할 때 필요한 도화지와 물감 역할을 한다.

목적

• 아이디어를 docs/PRD.md에 제품 요구사항으로 정리한다.
• 기술 선택과 구조를 docs/ADR.md, docs/ARCHITECTURE.md에 고정한다.
• Codex 작업 규칙은 AGENTS.md에 둔다.
• 큰 작업은 .codex/commands/harness.md 기준으로 phases/{task}/stepN.md로 쪼갠다.
• scripts/execute.py가 각 step을 Codex 세션으로 순차 실행한다.
• hooks가 위험 명령, TDD 위반, 종료 전 검증을 막는다.

빠른 시작

1. AGENTS.md의 {프로젝트명}, 기술 스택, CRITICAL 규칙을 채운다.
2. docs/PRD.md에 만들 프로그램의 목표, 사용자, 핵심 기능을 쓴다.
3. docs/ARCHITECTURE.md와 docs/ADR.md에 구조와 기술 결정을 기록한다.
4. Codex에게 .codex/commands/harness.md 흐름으로 phase와 step 생성을 요청한다.
5. 생성된 phase를 실행한다.

python scripts/execute.py 0-mvp

Codex Hooks

이 템플릿은 repo-local hook을 사용한다.

• SessionStart: Harness 작업 컨텍스트를 Codex에 추가한다.
• PreToolUse Bash: 위험한 명령을 차단한다.
• PreToolUse apply/edit/write: 테스트 없이 구현 파일을 수정하는 것을 차단한다.
• Stop: package.json에 존재하는 lint, build, test를 실행한다.

Codex hook 기능은 .codex/config.toml에서 활성화되어 있다.

[features]
codex_hooks = true

Git Hook

로컬 커밋 전에도 같은 검증을 원하면 한 번만 실행한다.

git config core.hooksPath .githooks

파일 구조

AGENTS.md                  # Codex 작업 규칙
docs/                      # PRD, 아키텍처, ADR, UI 가이드
.codex/commands/           # Codex용 작업 명령 템플릿
.codex/hooks/              # Codex hook 스크립트
scripts/execute.py         # phase step 순차 실행기
scripts/pre_commit_checks.py

운영 원칙

• 먼저 문서로 의도를 고정한다.
• 작은 step으로 나눈다.
• 테스트를 먼저 만든다.
• Codex가 만든 산출물은 hook과 테스트로 검증한다.
• 프로젝트별 구현 코드는 이 템플릿 위에 추가하되, 템플릿의 가드레일은 유지한다.