NINI
260 lines
8.2 KiB
Markdown
260 lines
8.2 KiB
Markdown
# Codex Markdown Document Harness Template
|
|
|
|
Codex 환경에서 Harness Engineering 방식으로 Markdown 문서를 단계적으로 작성하기 위한 템플릿입니다.
|
|
|
|
사용자는 `docs/PRD.md`에 만들고 싶은 문서의 목적, 대상 독자, 개요, 중요 키워드, 조사 요구사항을 작성합니다. 이후 Codex는 PRD를 기준으로 작성 규칙을 구체화하고, 웹 조사, 조사 노트, 초안, 사용자 피드백, 최종 문서를 순서대로 만들어 갑니다.
|
|
|
|
## 핵심 아이디어
|
|
|
|
이 템플릿은 한 번에 최종 문서를 쓰는 방식이 아니라, 다음 흐름을 강제합니다.
|
|
|
|
```text
|
|
PRD 작성
|
|
-> 작성 규칙 구체화
|
|
-> 웹 조사 및 ResearchNote 작성
|
|
-> drafts/ 초안 작성
|
|
-> 사용자 초안 피드백
|
|
-> final/ 최종 문서 작성
|
|
-> 사용자 최종 피드백 또는 승인
|
|
```
|
|
|
|
목표는 빠른 초안 작성보다 사용자의 의도, 출처, 피드백, 최종 산출물을 분리해 관리하는 것입니다.
|
|
|
|
## Codex 구성
|
|
|
|
```text
|
|
.
|
|
├── 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 # 실행기 테스트
|
|
```
|
|
|
|
## 빠른 시작
|
|
|
|
1. 템플릿을 git 저장소로 준비합니다.
|
|
|
|
```bash
|
|
git init
|
|
```
|
|
|
|
`scripts/execute.py`는 브랜치 생성과 커밋을 수행하므로 자동 실행을 쓰려면 git 저장소가 필요합니다.
|
|
|
|
2. `docs/PRD.md`를 채웁니다.
|
|
|
|
최소한 아래 항목은 구체적으로 작성하는 것이 좋습니다.
|
|
|
|
- 문서 목적
|
|
- 대상 독자
|
|
- 최종 산출물
|
|
- 문서 개요
|
|
- 중요 키워드
|
|
- 핵심 질문
|
|
- 포함할 범위와 제외할 범위
|
|
- 톤과 스타일
|
|
- 조사 요구사항
|
|
- 승인 기준
|
|
|
|
3. Codex에서 Harness Skill을 사용합니다.
|
|
|
|
예시 프롬프트:
|
|
|
|
```text
|
|
$document-harness를 사용해서 docs/PRD.md를 읽고 문서 작성 phase를 설계해 주세요.
|
|
```
|
|
|
|
또는 바로 다음처럼 요청할 수 있습니다.
|
|
|
|
```text
|
|
$document-harness를 사용해서 docs/PRD.md 기준으로 작성 규칙 구체화, ResearchNote 작성, 초안 작성 단계까지 진행해 주세요.
|
|
```
|
|
|
|
4. 생성된 초안을 검토합니다.
|
|
|
|
초안은 `drafts/` 아래에 생성됩니다. 검토 후 `docs/DraftFeedback.md`에 피드백을 작성합니다.
|
|
|
|
5. 최종본을 검토합니다.
|
|
|
|
최종 문서는 `final/` 아래에 생성됩니다. 검토 후 `docs/FinalFeedback.md`에 승인 또는 추가 수정 요청을 작성합니다.
|
|
|
|
## 자동 실행 방식
|
|
|
|
Codex가 `phases/{task-name}/` 아래에 step 파일을 만든 뒤, 실행기는 각 step을 `codex exec`로 순차 실행합니다.
|
|
|
|
```bash
|
|
python scripts/execute.py <task-name>
|
|
```
|
|
|
|
원격 저장소에 push까지 하려면 다음 명령을 사용합니다.
|
|
|
|
```bash
|
|
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` 상태로 멈출 수 있습니다.
|
|
|
|
초안 피드백:
|
|
|
|
```text
|
|
docs/DraftFeedback.md
|
|
```
|
|
|
|
최종 피드백:
|
|
|
|
```text
|
|
docs/FinalFeedback.md
|
|
```
|
|
|
|
피드백을 작성한 뒤 해당 step의 상태를 `pending`으로 되돌리고 다시 실행하면 다음 단계가 진행됩니다.
|
|
|
|
## Codex Skills
|
|
|
|
이 템플릿은 repo 공유 Skill을 사용합니다.
|
|
|
|
`document-harness`:
|
|
|
|
- PRD intake
|
|
- 작성 규칙 구체화
|
|
- ResearchNote 작성
|
|
- 초안 작성
|
|
- 피드백 게이트
|
|
- 최종 문서 작성
|
|
|
|
`document-review`:
|
|
|
|
- PRD 정합성 검토
|
|
- 출처 추적 검토
|
|
- 초안/최종본 분리 확인
|
|
- 피드백 반영 확인
|
|
- 문체와 Markdown 구조 검토
|
|
|
|
Codex에서 명시적으로 호출할 수 있습니다.
|
|
|
|
```text
|
|
$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를 항상 자동으로 생성하지 않습니다. 병렬 조사나 독립 리뷰가 필요하면 프롬프트에서 명시적으로 요청하세요.
|
|
|
|
예시:
|
|
|
|
```text
|
|
doc_researcher와 evidence_checker 역할을 사용해 핵심 키워드를 병렬 조사하고 docs/ResearchNote.md를 정리해 주세요.
|
|
```
|
|
|
|
## Hooks
|
|
|
|
`.codex/hooks.json`은 두 가지 기본 hook을 연결합니다.
|
|
|
|
- `PreToolUse`: 위험한 shell 명령을 차단합니다.
|
|
- `Stop`: 응답 종료 시 `python scripts/validate_docs.py`를 실행해 템플릿 구조를 검증합니다.
|
|
|
|
검증 실패 시 Codex가 문제를 고치도록 이어서 작업하게 만드는 용도입니다.
|
|
|
|
## 검증
|
|
|
|
템플릿 구조를 확인합니다.
|
|
|
|
```bash
|
|
python scripts/validate_docs.py
|
|
```
|
|
|
|
실행기 테스트를 실행합니다.
|
|
|
|
```bash
|
|
python -m pytest scripts/test_execute.py
|
|
```
|
|
|
|
현재 기대 결과:
|
|
|
|
```text
|
|
Document harness validation passed.
|
|
51 passed
|
|
```
|
|
|
|
## 문서 작성 규칙
|
|
|
|
- `docs/PRD.md`를 단일 요구사항 원천으로 사용합니다.
|
|
- 외부 사실, 통계, 최신 정보, 법/제도/가격/제품 정보는 `docs/ResearchNote.md`의 출처에 근거해야 합니다.
|
|
- 출처가 불명확한 내용은 최종 문서에 단정적으로 쓰지 않습니다.
|
|
- 초안은 `drafts/`, 최종 문서는 `final/`에 분리합니다.
|
|
- 사용자 피드백 파일은 삭제하거나 덮어쓰지 않습니다.
|
|
- 문서 제목은 `#`, 주요 섹션은 `##`, 하위 섹션은 `###`를 사용합니다.
|
|
|
|
## 추천 사용 프롬프트
|
|
|
|
PRD 검토:
|
|
|
|
```text
|
|
$document-harness를 사용해 docs/PRD.md가 문서 작성을 시작하기에 충분한지 검토해 주세요.
|
|
```
|
|
|
|
조사 노트 작성:
|
|
|
|
```text
|
|
$document-harness를 사용해 docs/PRD.md의 중요 키워드를 웹 조사하고 docs/ResearchNote.md를 작성해 주세요.
|
|
```
|
|
|
|
초안 작성:
|
|
|
|
```text
|
|
$document-harness를 사용해 docs/PRD.md와 docs/ResearchNote.md를 바탕으로 drafts/에 초안을 작성해 주세요.
|
|
```
|
|
|
|
문서 리뷰:
|
|
|
|
```text
|
|
$document-review를 사용해 drafts/와 final/의 변경 사항을 검토해 주세요.
|
|
```
|
|
|
|
## 주의사항
|
|
|
|
- 자동 실행기는 git 저장소를 전제로 합니다.
|
|
- 최신 정보가 중요한 문서는 `docs/ResearchNote.md`에 조사 일시와 기준일을 남겨야 합니다.
|
|
- `AGENTS.md`에는 지속적으로 적용할 규칙만 두고, 긴 절차는 Skill에 둡니다.
|
|
- Claude Code용 `.claude/` 구조는 사용하지 않습니다. 이 템플릿은 Codex의 `AGENTS.md`, Skill, hook, custom agent 구조를 기준으로 합니다.
|