사용자는 docs/PRD.md에 만들고 싶은 문서의 목적, 대상 독자, 개요, 중요 키워드, 조사 요구사항을 작성합니다. 이후 Codex는 PRD를 기준으로 작성 규칙을 구체화하고, 웹 조사, 조사 노트, 초안, 사용자 피드백, 최종 문서를 순서대로 만들어 갑니다.

핵심 아이디어

이 템플릿은 한 번에 최종 문서를 쓰는 방식이 아니라, 다음 흐름을 강제합니다.

PRD 작성
  -> 작성 규칙 구체화
  -> 웹 조사 및 ResearchNote 작성
  -> drafts/ 초안 작성
  -> 사용자 초안 피드백
  -> final/ 최종 문서 작성
  -> 사용자 최종 피드백 또는 승인

목표는 빠른 초안 작성보다 사용자의 의도, 출처, 피드백, 최종 산출물을 분리해 관리하는 것입니다.

Codex 구성

.
├── AGENTS.md                 # Codex가 읽는 프로젝트 기본 규칙
├── .agents/
│   └── skills/
│       ├── document-harness/ # 단계적 문서 작성 Skill
│       └── document-review/  # 문서 리뷰 Skill
├── .codex/
│   ├── config.toml           # hooks, multi-agent, live web search 설정
│   ├── hooks.json            # Stop/PreToolUse hook 연결
│   ├── hooks/                # hook 실행 스크립트
│   └── agents/               # 조사, 초안, 리뷰, 근거 점검 custom agents
├── docs/
│   ├── PRD.md                # 사용자가 채우는 문서 요구사항
│   ├── ResearchNote.md       # 조사 결과와 출처 장부
│   ├── DraftFeedback.md      # 초안 피드백
│   ├── FinalFeedback.md      # 최종 문서 피드백
│   ├── ARCHITECTURE.md       # 템플릿 구조 설명
│   ├── ADR.md                # 주요 설계 결정
│   └── UI_GUIDE.md           # Markdown 문서 스타일 가이드
├── drafts/                   # 초안 문서
├── final/                    # 최종 문서
├── phases/                   # 단계 실행 계획과 상태 파일
└── scripts/
    ├── execute.py            # codex exec 기반 step 실행기
    ├── validate_docs.py      # 템플릿 구조 검증
    └── test_execute.py       # 실행기 테스트

빠른 시작

템플릿을 git 저장소로 준비합니다.

git init

scripts/execute.py는 브랜치 생성과 커밋을 수행하므로 자동 실행을 쓰려면 git 저장소가 필요합니다.

docs/PRD.md를 채웁니다.

최소한 아래 항목은 구체적으로 작성하는 것이 좋습니다.

문서 목적
대상 독자
최종 산출물
문서 개요
중요 키워드
핵심 질문
포함할 범위와 제외할 범위
톤과 스타일
조사 요구사항
승인 기준

Codex에서 Harness Skill을 사용합니다.

예시 프롬프트:

$document-harness를 사용해서 docs/PRD.md를 읽고 문서 작성 phase를 설계해 주세요.

또는 바로 다음처럼 요청할 수 있습니다.

$document-harness를 사용해서 docs/PRD.md 기준으로 작성 규칙 구체화, ResearchNote 작성, 초안 작성 단계까지 진행해 주세요.

생성된 초안을 검토합니다.

초안은 drafts/ 아래에 생성됩니다. 검토 후 docs/DraftFeedback.md에 피드백을 작성합니다.

최종본을 검토합니다.

최종 문서는 final/ 아래에 생성됩니다. 검토 후 docs/FinalFeedback.md에 승인 또는 추가 수정 요청을 작성합니다.

자동 실행 방식

Codex가 phases/{task-name}/ 아래에 step 파일을 만든 뒤, 실행기는 각 step을 codex exec로 순차 실행합니다.

python scripts/execute.py <task-name>

원격 저장소에 push까지 하려면 다음 명령을 사용합니다.

python scripts/execute.py <task-name> --push

실행기가 처리하는 일:

feat-{task-name} 브랜치 생성 또는 checkout
AGENTS.md와 docs/*.md를 매 step 프롬프트에 주입
완료된 step의 summary를 다음 step에 전달
실패 시 최대 3회 재시도
step 상태를 completed, blocked, error로 관리
step 완료 후 문서 변경과 메타데이터를 커밋

피드백 게이트

사용자 검토가 필요한 단계에서는 step이 blocked 상태로 멈출 수 있습니다.

초안 피드백:

docs/DraftFeedback.md

최종 피드백:

docs/FinalFeedback.md

피드백을 작성한 뒤 해당 step의 상태를 pending으로 되돌리고 다시 실행하면 다음 단계가 진행됩니다.

Codex Skills

이 템플릿은 repo 공유 Skill을 사용합니다.

document-harness:

PRD intake
작성 규칙 구체화
ResearchNote 작성
초안 작성
피드백 게이트
최종 문서 작성

document-review:

PRD 정합성 검토
출처 추적 검토
초안/최종본 분리 확인
피드백 반영 확인
문체와 Markdown 구조 검토

Codex에서 명시적으로 호출할 수 있습니다.

$document-harness
$document-review

Codex Custom Agents

.codex/agents/에는 문서 작성에 특화된 역할이 정의되어 있습니다.

Agent	역할
`doc_researcher`	PRD 키워드 조사, 출처 수집, `docs/ResearchNote.md` 작성
`doc_drafter`	ResearchNote와 PRD를 바탕으로 `drafts/` 초안 작성
`doc_reviewer`	PRD 정합성, 구조, 피드백 반영 여부 리뷰
`evidence_checker`	문서 주장과 ResearchNote 출처 연결 확인

Codex는 subagent를 항상 자동으로 생성하지 않습니다. 병렬 조사나 독립 리뷰가 필요하면 프롬프트에서 명시적으로 요청하세요.

예시:

doc_researcher와 evidence_checker 역할을 사용해 핵심 키워드를 병렬 조사하고 docs/ResearchNote.md를 정리해 주세요.

Hooks

.codex/hooks.json은 두 가지 기본 hook을 연결합니다.

PreToolUse: 위험한 shell 명령을 차단합니다.
Stop: 응답 종료 시 python scripts/validate_docs.py를 실행해 템플릿 구조를 검증합니다.

검증 실패 시 Codex가 문제를 고치도록 이어서 작업하게 만드는 용도입니다.

검증

템플릿 구조를 확인합니다.

python scripts/validate_docs.py

실행기 테스트를 실행합니다.

python -m pytest scripts/test_execute.py

현재 기대 결과:

Document harness validation passed.
51 passed

문서 작성 규칙

docs/PRD.md를 단일 요구사항 원천으로 사용합니다.
외부 사실, 통계, 최신 정보, 법/제도/가격/제품 정보는 docs/ResearchNote.md의 출처에 근거해야 합니다.
출처가 불명확한 내용은 최종 문서에 단정적으로 쓰지 않습니다.
초안은 drafts/, 최종 문서는 final/에 분리합니다.
사용자 피드백 파일은 삭제하거나 덮어쓰지 않습니다.
문서 제목은 #, 주요 섹션은 ##, 하위 섹션은 ###를 사용합니다.

주의사항

자동 실행기는 git 저장소를 전제로 합니다.
최신 정보가 중요한 문서는 docs/ResearchNote.md에 조사 일시와 기준일을 남겨야 합니다.
AGENTS.md에는 지속적으로 적용할 규칙만 두고, 긴 절차는 Skill에 둡니다.
Claude Code용 .claude/ 구조는 사용하지 않습니다. 이 템플릿은 Codex의 AGENTS.md, Skill, hook, custom agent 구조를 기준으로 합니다.

README.md

Codex Markdown Document Harness Template