NINI
75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# 문서 작성 하네스 아키텍처
|
|
|
|
## 디렉토리 구조
|
|
```text
|
|
.
|
|
├── AGENTS.md # Codex가 읽는 프로젝트별 문서 작성 규칙
|
|
├── .agents/
|
|
│ └── skills/
|
|
│ ├── document-harness/ # 단계적 문서 작성 Skill
|
|
│ └── document-review/ # 문서 리뷰 Skill
|
|
├── .codex/
|
|
│ ├── config.toml # Codex 기능, live web search, agent 한도 설정
|
|
│ ├── 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/ # Harness task/step 계획과 상태
|
|
└── scripts/
|
|
├── execute.py # codex exec 기반 step 순차 실행기
|
|
├── validate_docs.py # 문서 템플릿 기본 검증
|
|
└── test_execute.py # execute.py 안전망 테스트
|
|
```
|
|
|
|
## 데이터 흐름
|
|
```text
|
|
사용자 입력
|
|
-> docs/PRD.md
|
|
-> AGENTS.md 작성 규칙 구체화
|
|
-> Codex/custom agents 웹 검색 및 출처 검증
|
|
-> docs/ResearchNote.md
|
|
-> drafts/ 초안 작성
|
|
-> docs/DraftFeedback.md 사용자 피드백
|
|
-> final/ 최종 문서 작성
|
|
-> docs/FinalFeedback.md 최종 피드백 또는 승인
|
|
```
|
|
|
|
## Step 설계 패턴
|
|
권장 phase는 아래 순서를 따른다.
|
|
|
|
1. `rule-synthesis`: `docs/PRD.md`를 읽고 `AGENTS.md`의 문서 작성 규칙을 프로젝트에 맞게 구체화한다.
|
|
2. `research-note`: 웹 검색과 사용자가 제공한 자료를 바탕으로 `docs/ResearchNote.md`를 작성한다. 필요하면 `doc_researcher` agent를 사용한다.
|
|
3. `draft-documents`: `drafts/`에 사용자 검토용 초안을 작성한다.
|
|
4. `draft-feedback-gate`: `docs/DraftFeedback.md`가 비어 있으면 `blocked`로 멈추고 사용자 검토를 요청한다.
|
|
5. `final-documents`: 피드백을 반영해 `final/`에 최종 문서를 작성한다.
|
|
6. `final-feedback-gate`: `docs/FinalFeedback.md`에 승인 또는 추가 수정 요청이 없으면 `blocked`로 멈춘다.
|
|
|
|
## Codex 구성 책임
|
|
- `AGENTS.md`는 Codex가 매 작업에서 읽는 짧고 지속적인 규칙을 담는다.
|
|
- `.agents/skills/document-harness/`는 phase 생성, research, draft, feedback gate, final 작성 절차를 담는다.
|
|
- `.agents/skills/document-review/`는 변경된 Markdown 문서의 리뷰 체크리스트를 담는다.
|
|
- `.codex/agents/`는 조사, 초안 작성, 리뷰, 근거 점검 역할을 분리한다.
|
|
- `.codex/hooks.json`은 위험 명령 차단과 Stop 시점 문서 검증을 연결한다.
|
|
|
|
## 상태 관리
|
|
- `pending`: 아직 실행되지 않은 step.
|
|
- `completed`: step 산출물이 생성되었고 검증이 끝난 상태.
|
|
- `blocked`: 사용자 피드백, 자료 제공, 승인 등 외부 입력이 필요한 상태.
|
|
- `error`: 자동 수정 3회 후에도 실패한 상태.
|
|
|
|
## 파일 책임
|
|
- `docs/PRD.md`는 사용자의 의도와 요구사항을 보존한다. Codex가 임의로 요구사항을 바꾸지 않는다.
|
|
- `docs/ResearchNote.md`는 사실 검증의 근거 장부다. 최종 문서의 외부 주장은 이 파일의 출처와 연결되어야 한다.
|
|
- `drafts/`는 논의용이다. 문장이 거칠 수 있지만 구조와 근거는 검토 가능해야 한다.
|
|
- `final/`은 납품용이다. 사용자 피드백, 출처, 스타일 기준을 반영해야 한다.
|
|
- `phases/`의 `index.json`과 `stepN.md`는 독립 실행 가능한 작업 지시서다.
|