문서 작성 하네스 아키텍처

디렉토리 구조

.
├── 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 안전망 테스트

데이터 흐름

사용자 입력
  -> docs/PRD.md
  -> AGENTS.md 작성 규칙 구체화
  -> Codex/custom agents 웹 검색 및 출처 검증
  -> docs/ResearchNote.md
  -> drafts/ 초안 작성
  -> docs/DraftFeedback.md 사용자 피드백
  -> final/ 최종 문서 작성
  -> docs/FinalFeedback.md 최종 피드백 또는 승인

Step 설계 패턴

권장 phase는 아래 순서를 따른다.

rule-synthesis: docs/PRD.md를 읽고 AGENTS.md의 문서 작성 규칙을 프로젝트에 맞게 구체화한다.
research-note: 웹 검색과 사용자가 제공한 자료를 바탕으로 docs/ResearchNote.md를 작성한다. 필요하면 doc_researcher agent를 사용한다.
draft-documents: drafts/에 사용자 검토용 초안을 작성한다.
draft-feedback-gate: docs/DraftFeedback.md가 비어 있으면 blocked로 멈추고 사용자 검토를 요청한다.
final-documents: 피드백을 반영해 final/에 최종 문서를 작성한다.
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는 독립 실행 가능한 작업 지시서다.

4.0 KiB Raw Blame History

문서 작성 하네스 아키텍처

디렉토리 구조

데이터 흐름

Step 설계 패턴

Codex 구성 책임

상태 관리

파일 책임

4.0 KiB

Raw Blame History