프로젝트: Codex Markdown Document Harness Template

목적

이 템플릿은 Codex와 Harness Engineering 방식을 이용해 사용자의 목표에 맞는 Markdown 문서를 단계적으로 작성하기 위한 작업 환경이다.

사용자는 docs/PRD.md에 문서의 목적, 개요, 대상 독자, 중요 키워드, 참고 자료를 입력한다. 이후 Codex는 이 정보를 기준으로 작성 규칙을 구체화하고, 조사 노트, 초안, 피드백 반영본, 최종 문서를 순차적으로 만든다.

Codex 구성

AGENTS.md: Codex가 항상 참고하는 프로젝트 규칙.
.agents/skills/document-harness/: 문서 작성 Harness의 단계별 실행 절차.
.agents/skills/document-review/: 문서 변경 사항 리뷰 절차.
.codex/agents/: 조사, 초안, 리뷰에 특화된 Codex custom agents.
.codex/hooks.json: 문서 검증과 위험 명령 방지를 위한 lifecycle hooks.
.codex/config.toml: hooks, multi-agent, live web search 등 이 템플릿에서 권장하는 Codex 기능 설정.

기본 산출물

docs/PRD.md: 사용자가 작성하는 문서 요구사항의 원천.
docs/ResearchNote.md: 웹 조사 결과, 출처, 쟁점, 문서 반영 메모.
drafts/: 사용자 검토를 위한 초안 문서.
final/: 피드백을 반영한 최종 문서.
docs/DraftFeedback.md: 초안 검토 후 사용자가 남기는 피드백.
docs/FinalFeedback.md: 최종 문서 검토 후 사용자가 남기는 피드백.
phases/: Harness step 실행 계획과 상태 파일.

문서 작성 규칙

CRITICAL: docs/PRD.md를 단일 요구사항 원천으로 삼는다. PRD에 없는 목표, 독자, 범위, 톤을 임의로 추가하지 마라.
CRITICAL: 외부 사실, 통계, 최신 정보, 인용, 법/제도/가격/제품 정보는 docs/ResearchNote.md의 출처에 근거해야 한다.
CRITICAL: 출처가 불명확한 주장을 최종 문서에 단정적으로 쓰지 마라. 필요한 경우 "확인 필요" 또는 "출처 필요"로 표시한다.
CRITICAL: 초안 작성 후와 최종 문서 작성 후에는 사용자 피드백을 받아야 한다. 피드백이 필요한 step은 blocked 상태와 구체적인 blocked_reason을 기록한다.
CRITICAL: 최종 문서는 초안과 분리해 final/ 아래에 작성한다. 초안 파일을 최종본처럼 덮어쓰지 마라.
조사 노트에는 검색 일시, 검색어, 출처 URL, 핵심 요지, 문서 반영 여부를 남긴다.
문서 구조는 제목 계층을 유지한다. #는 문서 제목에만 사용하고, 본문 구조는 ##, ###를 사용한다.
사용자의 피드백은 삭제하지 말고 별도 피드백 문서에 보존한다.

Codex 작업 규칙

반복 가능한 절차는 .agents/skills/의 Skill에 둔다. AGENTS.md에는 지속적으로 적용할 짧은 규칙만 유지한다.
문서 작성 Harness를 실행하거나 설계할 때는 $document-harness Skill을 우선 사용한다.
문서 변경 사항을 검토할 때는 $document-review Skill을 사용한다.
병렬 조사나 독립 리뷰가 필요한 경우 .codex/agents/의 custom agents를 명시적으로 선택한다.
scripts/execute.py가 step 실행 후 git commit을 처리하므로, step을 수행하는 Codex 세션은 직접 commit하지 않는다.

권장 워크플로우

사용자가 docs/PRD.md를 채운다.
Codex가 PRD를 읽고 AGENTS.md의 프로젝트별 작성 규칙을 구체화한다.
Codex 또는 Codex subagents가 웹 검색을 수행하고 docs/ResearchNote.md를 작성한다.
Codex가 drafts/에 초안을 만들고 사용자 검토를 요청한다.
사용자가 docs/DraftFeedback.md에 피드백을 남긴다.
Codex가 피드백을 반영해 final/에 최종 문서를 작성한다.
사용자가 docs/FinalFeedback.md에 최종 피드백 또는 승인 여부를 남긴다.

명령어

python scripts/validate_docs.py
python scripts/execute.py <task-name>
python scripts/execute.py <task-name> --push
python -m pytest scripts/test_execute.py

4.0 KiB Raw Blame History