Agentic-AI-Template/Writing/Gemini/README.md

Gemini CLI Markdown Document Harness Template

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

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

핵심 아이디어

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

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

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

Gemini CLI 구성

.
├── 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 저장소로 준비합니다.

git init

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

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

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

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

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

예시 프롬프트:

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

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

/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로 순차 실행합니다.

python scripts/execute.py <task-name>

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

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 상태로 멈출 수 있습니다.

초안 피드백:

docs/DraftFeedback.md

최종 피드백:

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에서 다음처럼 요청할 수 있습니다.

@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에 재시도 피드백을 전달합니다.

검증

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

python scripts/validate_docs.py

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

python -m pytest scripts/test_execute.py

현재 기대 결과:

Document harness validation passed.

문서 작성 규칙

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

추천 사용 프롬프트

PRD 검토:

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

조사 노트 작성:

/harness:research

초안 작성:

/harness:draft

문서 리뷰:

/harness:review

주의사항

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