# Gemini CLI Markdown Document Harness Template

Gemini CLI 환경에서 Harness Engineering 방식으로 Markdown 문서를 단계적으로 작성하기 위한 템플릿입니다.

사용자는 `docs/PRD.md`에 만들고 싶은 문서의 목적, 대상 독자, 개요, 중요 키워드, 조사 요구사항을 작성합니다. 이후 Gemini CLI는 PRD를 기준으로 작성 규칙을 구체화하고, 웹 조사, 조사 노트, 초안, 사용자 피드백, 최종 문서를 순서대로 만들어 갑니다.

## 핵심 아이디어

이 템플릿은 한 번에 최종 문서를 쓰는 방식이 아니라, 다음 흐름을 강제합니다.

```text
PRD 작성
  -> 작성 규칙 구체화
  -> 웹 조사 및 ResearchNote 작성
  -> drafts/ 초안 작성
  -> 사용자 초안 피드백
  -> final/ 최종 문서 작성
  -> 사용자 최종 피드백 또는 승인
```

목표는 빠른 초안 작성보다 사용자의 의도, 출처, 피드백, 최종 산출물을 분리해 관리하는 것입니다.

## Gemini CLI 구성

```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/                   # 단계 실행 계획과 상태 파일
└── scripts/
    ├── execute.py            # Gemini CLI headless 기반 step 순차 실행기
    ├── validate_docs.py      # 템플릿 구조 검증
    └── test_execute.py       # 실행기 테스트
```

## 빠른 시작

1. 템플릿을 git 저장소로 준비합니다.

```bash
git init
```

`scripts/execute.py`는 브랜치 생성과 커밋을 수행하므로 자동 실행을 쓰려면 git 저장소가 필요합니다.

2. `docs/PRD.md`를 채웁니다.

최소한 아래 항목은 구체적으로 작성하는 것이 좋습니다.

- 문서 목적
- 대상 독자
- 최종 산출물
- 문서 개요
- 중요 키워드
- 핵심 질문
- 포함할 범위와 제외할 범위
- 톤과 스타일
- 조사 요구사항
- 승인 기준

3. Gemini CLI에서 Harness Skill 또는 custom command를 사용합니다.

예시 프롬프트:

```text
document-harness Skill을 사용해서 docs/PRD.md를 읽고 문서 작성 phase를 설계해 주세요.
```

또는 custom command를 사용할 수 있습니다.

```text
/harness:plan
/harness:research
/harness:draft
/harness:review
```

4. 생성된 초안을 검토합니다.

초안은 `drafts/` 아래에 생성됩니다. 검토 후 `docs/DraftFeedback.md`에 피드백을 작성합니다.

5. 최종본을 검토합니다.

최종 문서는 `final/` 아래에 생성됩니다. 검토 후 `docs/FinalFeedback.md`에 승인 또는 추가 수정 요청을 작성합니다.

## 자동 실행 방식

Gemini CLI가 `phases/{task-name}/` 아래에 step 파일을 만든 뒤, 실행기는 각 step을 Gemini CLI headless mode로 순차 실행합니다.

```bash
python scripts/execute.py <task-name>
```

원격 저장소에 push까지 하려면 다음 명령을 사용합니다.

```bash
python scripts/execute.py <task-name> --push
```

실행기가 처리하는 일:

- `feat-{task-name}` 브랜치 생성 또는 checkout
- `GEMINI.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`으로 되돌리고 다시 실행하면 다음 단계가 진행됩니다.

## Gemini CLI Skills

이 템플릿은 repo 공유 Skill을 사용합니다. Gemini CLI는 `.agents/skills/` 경로를 workspace skill alias로 인식합니다.

`document-harness`:

- PRD intake
- 작성 규칙 구체화
- ResearchNote 작성
- 초안 작성
- 피드백 게이트
- 최종 문서 작성

`document-review`:

- PRD 정합성 검토
- 출처 추적 검토
- 초안/최종본 분리 확인
- 피드백 반영 확인
- 문체와 Markdown 구조 검토

## Gemini CLI Subagents

`.gemini/agents/`에는 문서 작성에 특화된 subagent 역할이 정의되어 있습니다.

| Agent | 역할 |
|-------|------|
| `doc-researcher` | PRD 키워드 조사, 출처 수집, `docs/ResearchNote.md` 작성 |
| `doc-drafter` | ResearchNote와 PRD를 바탕으로 `drafts/` 초안 작성 |
| `doc-reviewer` | PRD 정합성, 구조, 피드백 반영 여부 리뷰 |
| `evidence-checker` | 문서 주장과 ResearchNote 출처 연결 확인 |

명시적으로 subagent를 호출하려면 Gemini CLI에서 다음처럼 요청할 수 있습니다.

```text
@doc-researcher docs/PRD.md의 핵심 키워드를 조사하고 docs/ResearchNote.md를 정리해 주세요.
```

## Hooks

`.gemini/settings.json`은 두 가지 기본 hook을 연결합니다.

- `BeforeTool`: 위험한 shell 명령을 차단합니다.
- `AfterAgent`: 응답 종료 후 `python scripts/validate_docs.py`를 실행해 템플릿 구조를 검증합니다.

검증 실패 시 `AfterAgent` hook은 Gemini CLI에 재시도 피드백을 전달합니다.

## 검증

템플릿 구조를 확인합니다.

```bash
python scripts/validate_docs.py
```

실행기 테스트를 실행합니다.

```bash
python -m pytest scripts/test_execute.py
```

현재 기대 결과:

```text
Document harness validation passed.
```

## 문서 작성 규칙

- `docs/PRD.md`를 단일 요구사항 원천으로 사용합니다.
- 외부 사실, 통계, 최신 정보, 법/제도/가격/제품 정보는 `docs/ResearchNote.md`의 출처에 근거해야 합니다.
- 출처가 불명확한 내용은 최종 문서에 단정적으로 쓰지 않습니다.
- 초안은 `drafts/`, 최종 문서는 `final/`에 분리합니다.
- 사용자 피드백 파일은 삭제하거나 덮어쓰지 않습니다.
- 문서 제목은 `#`, 주요 섹션은 `##`, 하위 섹션은 `###`를 사용합니다.

## 추천 사용 프롬프트

PRD 검토:

```text
document-harness Skill을 사용해 docs/PRD.md가 문서 작성을 시작하기에 충분한지 검토해 주세요.
```

조사 노트 작성:

```text
/harness:research
```

초안 작성:

```text
/harness:draft
```

문서 리뷰:

```text
/harness:review
```

## 주의사항

- 자동 실행기는 git 저장소와 Gemini CLI 설치를 전제로 합니다.
- 최신 정보가 중요한 문서는 `docs/ResearchNote.md`에 조사 일시와 기준일을 남겨야 합니다.
- `GEMINI.md`에는 지속적으로 적용할 규칙만 두고, 긴 절차는 Skill에 둡니다.
- 이 템플릿은 Gemini CLI의 `GEMINI.md`, Skill, custom command, hook, subagent 구조를 기준으로 합니다.