# 프로젝트: Gemini CLI Markdown Document Harness Template

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

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

## Gemini CLI 구성
- `GEMINI.md`: Gemini CLI가 읽는 프로젝트 규칙.
- `.agents/skills/document-harness/`: 문서 작성 Harness의 단계별 실행 절차.
- `.agents/skills/document-review/`: 문서 변경 사항 리뷰 절차.
- `.gemini/settings.json`: context, skills, hooks 설정.
- `.gemini/commands/`: Harness workflow용 custom slash commands.
- `.gemini/agents/`: 조사, 초안, 리뷰에 특화된 Gemini CLI subagents.
- `.gemini/hooks/`: 문서 검증과 위험 명령 방지를 위한 lifecycle hook scripts.

## 기본 산출물
- `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, 핵심 요지, 문서 반영 여부를 남긴다.
- 문서 구조는 제목 계층을 유지한다. `#`는 문서 제목에만 사용하고, 본문 구조는 `##`, `###`를 사용한다.
- 사용자의 피드백은 삭제하지 말고 별도 피드백 문서에 보존한다.

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

## 권장 워크플로우
1. 사용자가 `docs/PRD.md`를 채운다.
2. Gemini CLI가 PRD를 읽고 `GEMINI.md`의 프로젝트별 작성 규칙을 구체화한다.
3. Gemini CLI 또는 subagents가 웹 검색을 수행하고 `docs/ResearchNote.md`를 작성한다.
4. Gemini CLI가 `drafts/`에 초안을 만들고 사용자 검토를 요청한다.
5. 사용자가 `docs/DraftFeedback.md`에 피드백을 남긴다.
6. Gemini CLI가 피드백을 반영해 `final/`에 최종 문서를 작성한다.
7. 사용자가 `docs/FinalFeedback.md`에 최종 피드백 또는 승인 여부를 남긴다.

## 명령어
```bash
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
```