# 문서 작성 하네스 아키텍처

## 디렉토리 구조
```text
.
├── GEMINI.md                 # Gemini CLI가 읽는 프로젝트별 문서 작성 규칙
├── .agents/
│   └── skills/
│       ├── document-harness/ # 단계적 문서 작성 Skill
│       └── document-review/  # 문서 리뷰 Skill
├── .gemini/
│   ├── settings.json         # context, skills, hooks 설정
│   ├── commands/             # Harness custom slash commands
│   ├── hooks/                # hook 실행 스크립트
│   └── agents/               # 조사/초안/리뷰 subagents
├── 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            # Gemini CLI headless 기반 step 순차 실행기
    ├── validate_docs.py      # 문서 템플릿 기본 검증
    └── test_execute.py       # execute.py 안전망 테스트
```

## 데이터 흐름
```text
사용자 입력
  -> docs/PRD.md
  -> GEMINI.md 작성 규칙 구체화
  -> Gemini CLI/subagents 웹 검색 및 출처 검증
  -> docs/ResearchNote.md
  -> drafts/ 초안 작성
  -> docs/DraftFeedback.md 사용자 피드백
  -> final/ 최종 문서 작성
  -> docs/FinalFeedback.md 최종 피드백 또는 승인
```

## Step 설계 패턴
권장 phase는 아래 순서를 따른다.

1. `rule-synthesis`: `docs/PRD.md`를 읽고 `GEMINI.md`의 문서 작성 규칙을 프로젝트에 맞게 구체화한다.
2. `research-note`: 웹 검색과 사용자가 제공한 자료를 바탕으로 `docs/ResearchNote.md`를 작성한다. 필요하면 `doc-researcher` subagent를 사용한다.
3. `draft-documents`: `drafts/`에 사용자 검토용 초안을 작성한다.
4. `draft-feedback-gate`: `docs/DraftFeedback.md`가 비어 있으면 `blocked`로 멈추고 사용자 검토를 요청한다.
5. `final-documents`: 피드백을 반영해 `final/`에 최종 문서를 작성한다.
6. `final-feedback-gate`: `docs/FinalFeedback.md`에 승인 또는 추가 수정 요청이 없으면 `blocked`로 멈춘다.

## Gemini CLI 구성 책임
- `GEMINI.md`는 Gemini CLI가 매 작업에서 읽는 짧고 지속적인 규칙을 담는다.
- `.agents/skills/document-harness/`는 phase 생성, research, draft, feedback gate, final 작성 절차를 담는다.
- `.agents/skills/document-review/`는 변경된 Markdown 문서의 리뷰 체크리스트를 담는다.
- `.gemini/commands/`는 반복 작업을 호출하기 위한 project-local slash command를 담는다.
- `.gemini/agents/`는 조사, 초안 작성, 리뷰, 근거 점검 역할을 분리한다.
- `.gemini/settings.json`은 context, skills, hook 실행 설정을 담는다.
- `.gemini/hooks/`는 위험 명령 차단과 AfterAgent 시점 문서 검증을 연결한다.

## 상태 관리
- `pending`: 아직 실행되지 않은 step.
- `completed`: step 산출물이 생성되었고 검증이 끝난 상태.
- `blocked`: 사용자 피드백, 자료 제공, 승인 등 외부 입력이 필요한 상태.
- `error`: 자동 수정 3회 후에도 실패한 상태.

## 파일 책임
- `docs/PRD.md`는 사용자의 의도와 요구사항을 보존한다. Gemini CLI가 임의로 요구사항을 바꾸지 않는다.
- `docs/ResearchNote.md`는 사실 검증의 근거 장부다. 최종 문서의 외부 주장은 이 파일의 출처와 연결되어야 한다.
- `drafts/`는 논의용이다. 문장이 거칠 수 있지만 구조와 근거는 검토 가능해야 한다.
- `final/`은 납품용이다. 사용자 피드백, 출처, 스타일 기준을 반영해야 한다.
- `phases/`의 `index.json`과 `stepN.md`는 독립 실행 가능한 작업 지시서다.