122 added, 50 removed. Audit A to A.
---
name: clio
description: >
마무리투수(Closer) + 역사의 뮤즈. 파이프라인 최종 점검(GO/NO-GO 판정) +
소스 기반 흐름도 추출 + 문서 산출물(PRD, 기술문서, 매뉴얼) 일괄 생성.
- /clio로 실행.
- triggers:
- - "clio"
- - "클리오"
- - "kleio"
- - "마무리"
- - "최종 점검"
- - "최종점검"
- - "산출물 생성"
- - "closer"
- - "클로저"
- - "final-inspection"
- auto_apply: false
- license: MIT
- metadata:
- version: "2.1.1"
+ /clio, 클리오, 마무리, 최종 점검, 산출물 생성 요청에 실행한다. 레거시 호출명은 /closer와 클로저다.
---
# Clio (클리오) — 마무리투수 + 역사의 뮤즈
> **클리오(Clio / Kleio)**: 그리스 신화 9 뮤즈 중 **역사의 뮤즈**.
> 야구의 마무리투수(Closer)처럼, 모든 파이프라인이 끝난 뒤 최종 점검하고 판정을 내린다.
> 그리고 역사의 뮤즈답게, 확정된 코드를 후대에 남길 기록으로 정리한다.
>
> **마무리투수 → 기록자.** 점검 먼저, 문서는 그 다음.
## Quick Start
```
/clio # 전체 실행 (점검 + 문서)
/clio src/ # 특정 소스 디렉토리 지정
/clio --check-only # 최종 점검만 (Phase 1, GO/NO-GO 판정)
/clio --docs-only # 문서 생성만 (Phase 2~3, 점검 건너뜀)
/clio --flow-only # 흐름도만 추출 (Phase 2)
```
**공식 호출명:** `/clio` (별칭: `클리오`, `마무리`, `최종 점검`, 레거시: `/closer`, `클로저`)
+ ## 내부 소스 모듈 해석 계약 (필수)
+
+ `flow-verifier`, `humanizer`, `mermaid-diagrams`, `pdf`는 Clio가 호출하는 등록 스킬이 아니라
+ 절차·문법·스크립트를 직접 소비하는 source-only 내부 모듈입니다. 각 이름에 대해 해석된
+ `SKILL.md` 절대경로를 `MODULE_SKILL[name]`, 그 부모 디렉터리를 `MODULE_ROOT[name]`으로
+ 기록합니다.
+
+ 각 모듈을 처음 쓰기 전에 다음 순서로 해석합니다.
+
+ 1. 프로젝트 루트의 `skills/<name>/SKILL.md`가 **실제 파일로 존재하고 frontmatter의 `name`이
+ 정확히 `<name>`일 때만** 그 절대경로를 사용합니다. 없거나 이름이 다르면 프로젝트의 다른
+ 경로를 추측하지 않고 2번으로 갑니다.
+ 2. 없으면 현재 런타임의 활성 루트에서 정확한 `skills/<name>/SKILL.md`를 확인합니다. Codex는
+ `$CODEX_HOME/skills`(미설정이면 `~/.codex/skills`), Claude와 Grok 호환 표면은
+ `~/.claude/skills`, Gemini는 `~/.gemini/skills`입니다. 파일 존재와 frontmatter 이름이
+ 모두 일치할 때만 사용하고, 아니면 3번으로 갑니다.
+ 3. 없으면 현재 런타임의 전역 `SKILLS-CATALOG.md`를 읽습니다. Codex는
+ `$CODEX_HOME/SKILLS-CATALOG.md`(미설정이면 `~/.codex/SKILLS-CATALOG.md`), Claude와
+ Grok 호환 표면은 `~/.claude/SKILLS-CATALOG.md`, Gemini는
+ `~/.gemini/SKILLS-CATALOG.md`입니다. 첫 번째 셀이 정확히 `<name>`인 행
+ (`| <name> | ... | ... | <읽을 경로> |`) 하나를 찾아 `읽을 경로`의 절대 `SKILL.md`를
+ 그대로 사용합니다. 정확한 이름의 행이 0개이거나 2개 이상이면 해석 실패이며 다른 행이나
+ 레지스트리 경로를 추측하지 않습니다.
+ 4. 해석한 파일의 존재를 확인하고 `SKILL.md` 전체를 읽은 뒤에만 그 모듈의 기준을 적용합니다.
+ 참조 파일은 `MODULE_ROOT[name]/references/...`, 스크립트는
+ `MODULE_ROOT[name]/scripts/...`로부터 절대경로를 만듭니다.
+
+ 이 과정은 모듈 읽기이지 스킬 호출이 아닙니다. `/flow-verifier`, `/humanizer`,
+ `/mermaid-diagrams`, `/pdf`를 호출하거나 스킬 레지스트리에 등록됐다고 가정하지 않습니다.
+ 프로젝트·활성 루트 파일도 없고 카탈로그의 정확한 행·`읽을 경로`·필수 참조나 스크립트 중 하나라도 없으면
+ `CHECKLIST.md`와 `FINAL-REPORT.md`의 `Module Coverage`에 경로와 이유를 기록하고 다음 한정된
+ native fallback을 사용합니다. fallback도 실행할 수 없는 작업은 `NOT RUN` 또는 `UNVERIFIED`로
+ 남기며 완료나 PASS로 바꾸지 않습니다.
+
+ | 모듈 | 한정된 native fallback |
+ |------|------------------------|
+ | `flow-verifier` | 노드·분기·순서·오류·코드에만 있는 경로를 직접 대조하고 `source: native-fallback` 표기 |
+ | `mermaid-diagrams` | `flowchart TD`, 안정적인 노드 ID, 인용된 label, 명시적 edge만 사용. renderer가 없으면 문법 검증은 `NOT RUN` |
+ | `humanizer` | 아래 S1 금지 패턴과 변경률 가드만 적용하고 전체 한국어 패턴 커버리지는 `UNVERIFIED` |
+ | `pdf` | 대체 변환기를 임의로 설치하거나 호출하지 않고 PDF 산출을 `NOT RUN`으로 기록한 뒤 Markdown 문서는 유지 |
+
## 파이프라인 위치
```
/zephermine → /agent-team → /argos → /minos → /clio
설계사 포세이돈 감리관 QA 실사 마무리투수 + 기록자
```
**전제 조건:** 구현이 완료된 상태. argos/minos는 선행 권장이지만 필수는 아님.
---
## CRITICAL: First Actions
### 1. Print Intro
```
Clio(클리오) — 마무리투수 등판
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
순서: Detect → Phase 1 (최종 점검) → Phase 2 (흐름도) → Phase 3 (문서) → Phase 3.5 (문서 사이트) → Phase 4 (보고서)
"마무리투수가 먼저 점검하고, 역사의 뮤즈가 기록한다."
```
### 2. Detect Project
프로젝트를 감지합니다:
1. `$ARGUMENTS`로 전달된 경로 사용
2. 없으면 현재 디렉토리에서 자동 감지:
- `package.json`, `pom.xml`, `pyproject.toml`, `*.csproj` 등 프로젝트 파일 탐색
- `src/`, `app/`, `lib/` 등 소스 디렉토리 탐색
3. 기존 산출물 수집 (archive/ 경로 제외):
- `docs/plan/*/spec.md` — 설계 산출물
- `docs/plan/*/verify-report.md` — argos 감리 보고서
- `docs/flow-diagrams/` — 기존 흐름도
- Playwright/Cypress 테스트 결과 — minos 결과
상태 출력:
```
📂 프로젝트 감지:
프로젝트: {project-name}
기술 스택: {tech-stack}
소스 경로: {src-path}
📋 기존 산출물:
설계(spec): {있음/없음}
감리(argos): {PASS/CONDITIONAL/FAIL | 없음}
QA(minos): {통과율 N% | 없음}
흐름도: {N개 | 없음}
```
### 3. Archive Previous & Create Output Directory
**기존 산출물이 있으면 아카이브 후 클린 상태로 시작합니다.**
1. `docs/clio/latest/` 디렉토리가 존재하는지 확인
2. 존재하면 → `docs/clio/archive/YYYY-MM-DD-HHMMSS/`로 이동
3. 새 `docs/clio/latest/` 디렉토리 생성
```
docs/
└── clio/
├── latest/ # 항상 최신본 (여기를 참조)
│ ├── CHECKLIST.md # Phase 1 산출물 (최종 점검 결과)
│ ├── flow-diagrams/ # Phase 2 산출물
│ │ ├── system-overview.mmd
│ │ └── {feature-name}.mmd
│ ├── PRD.md # Phase 3 산출물
│ ├── TECHNICAL.md # Phase 3 산출물
│ ├── USER-MANUAL.md # Phase 3 산출물
│ └── FINAL-REPORT.md # Phase 4 산출물
└── archive/ # 이전 실행 이력
```
+ ### 실행 역할과 소유권
+
+ 역할명은 특정 CLI의 에이전트 이름이 아니라 의미 계약입니다. 현재 런타임의 내장 역할 중 계약을
+ 충족하는 것을 사용하며, 특정 모델명이나 spawn 인자 형식을 강제하지 않습니다.
+
+ | 작업 | 의미 역할 | 허용 범위 |
+ |------|-----------|-----------|
+ | 소스 탐색, 흐름 추적, 설계 대조, 문서 사실 검증 | 읽기 전용 탐색·검토 역할 | 코드와 산출물을 읽고 `file:line` 근거 또는 Mermaid 초안을 반환. 파일 수정 금지 |
+ | 테스트·린트·타입 검사 실행 | general-write 역할 | 지정 명령과 도구의 임시 산출물만 허용. 소스 수정 금지 |
+ | 흐름도·문서·문서 사이트 파일 생성 | general-write 역할 | 메인이 지정한 단일 출력 경로 집합만 소유하고 검증 결과와 변경 경로를 반환 |
+
+ 메인 컨텍스트만 archive/latest 전환, GO/NO-GO 판정, 작업 상태, 발견 병합, 출력 파일 소유권
+ 배정 같은 공유 상태를 변경합니다. 두 작업자에게 같은 파일을 배정하지 않습니다. 네이티브 위임이
+ 없거나 실패하면 메인 컨텍스트에서 같은 계약을 Phase 순서대로 실행합니다.
+
---
## Phase 1: 최종 점검 (마무리투수)
**목적:** 모든 파이프라인 결과를 수집하고, 누락·미통과 항목을 탐지하여 GO/NO-GO를 판정한다.
### 1-1. 파이프라인 결과 수집
| 항목 | 수집 방법 | 없으면 |
|------|----------|--------|
| argos 감리 보고서 | `docs/plan/*/verify-report.md` 파싱 | "미실행" 기록 |
| minos QA 결과 | Playwright 테스트 결과 파싱 | "미실행" 기록 |
| 설계 spec | `docs/plan/*/spec.md` | "없음" 기록 |
| 섹션 AC | `docs/plan/*/sections/section-*.md`에서 Acceptance Criteria 추출 | 건너뜀 |
### 1-2. 코드 품질 최종 실행
- 서브에이전트(`model: "sonnet"`)에게 아래를 실행시킵니다:
+ 가능하면 general-write 역할에 아래 검증 명령을 실행시킵니다. 이 역할은 테스트·린트·타입 검사와
+ 도구가 생성하는 지정 임시 산출물만 소유하고, 소스나 Clio 문서를 수정하지 않습니다. 위임할 수
+ 없으면 메인 컨텍스트에서 명령을 순차 실행합니다.
```bash
# 테스트 실행
npm test 2>&1 || pytest 2>&1 || go test ./... 2>&1 || dotnet test 2>&1
# 린트
npx eslint src/ 2>&1 || ruff check . 2>&1 || golangci-lint run 2>&1
# 타입 체크
npx tsc --noEmit 2>&1 || mypy . 2>&1
# 테스트 커버리지 (가능하면)
npx jest --coverage 2>&1 || pytest --cov=src 2>&1
```
프로젝트에 해당 도구가 없으면 건너뜁니다 (에러 무시).
### 1-3. 누락 탐지
- spec이 있으면, **설계 대비 구현 누락**을 탐지합니다:
+ spec이 있으면, **설계 대비 구현 누락**을 읽기 전용 탐색·검토 역할로 확인합니다. 이 역할은
+ 근거와 누락 목록만 반환하고 파일을 수정하지 않습니다. 위임이 없으면 메인이 순차 확인합니다:
1. spec.md에서 기능 목록 추출
2. 소스 코드에서 해당 기능이 구현되었는지 Grep으로 확인
3. Acceptance Criteria가 있으면 각 항목의 충족 여부 확인
4. 누락된 기능/AC 목록 생성
### 1-4. GO / NO-GO 판정
| 판정 | 조건 |
|------|------|
| **GO** | 테스트 1개 이상 존재 + 전체 통과 + 린트 에러 0 + 타입 에러 0 + 누락 기능 0 + (minos 실행 시) minos PASS |
| **CONDITIONAL GO** | 테스트 통과 + Minor 린트 경고만 있음, 또는 argos/minos 미실행, 또는 minos CONDITIONAL, 또는 **테스트가 아예 없음** (0개 통과는 "전체 통과"가 아님 — GO 승격 금지) |
| **NO-GO** | 테스트 실패, 또는 누락 기능 있음, 또는 argos FAIL, 또는 minos FAIL |
> **공허한 통과 방지**: "테스트 전체 통과"는 테스트가 1개 이상 존재할 때만 성립합니다.
> **우회 표기**: `--force` 또는 `--docs-only`로 게이트를 건너뛴 경우, 모든 산출물(FINAL-REPORT 포함) 상단에 "점검 게이트 미통과/미수행 상태로 생성됨"을 표기합니다.
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
마무리투수 판정: {GO / CONDITIONAL GO / NO-GO}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
테스트: {PASS (N/N) | FAIL (N/M)}
린트: {CLEAN | WARN N개 | ERROR N개}
타입 체크: {PASS | FAIL N개}
커버리지: {N% | 미측정}
argos 감리: {PASS | CONDITIONAL | FAIL | 미실행}
minos QA: {N% 통과 | 미실행}
구현 누락: {없음 | N개 항목}
블로커: {없음 | 목록}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**NO-GO 시:**
- 블로커 목록을 사용자에게 보고
- "블로커를 해결한 뒤 `/clio`를 다시 실행해주세요" 안내
- Phase 2~4 진행하지 않음 (문서를 만들어봤자 코드가 바뀔 것)
**CONDITIONAL GO 시:**
- 경고 목록을 보고하고 사용자에게 확인
- 사용자가 승인하면 Phase 2로 진행
**GO 시:**
- Phase 2로 즉시 진행
**Phase 1 출력:** `docs/clio/latest/CHECKLIST.md`
---
## Phase 2: 소스 기반 프로세스 흐름도 추출
**목적:** 최종 확정된 소스 코드에서 실제 프로세스 흐름을 Mermaid 다이어그램으로 추출
### 절차
+ 1, 2, 4번은 같은 읽기 전용 계약을 사용합니다. 3번만 지정된 흐름도 출력 파일을 소유하는
+ general-write 역할이 수행하며, 메인이 초안과 근거를 검증한 뒤 파일 소유권을 배정합니다.
+
1. **엔트리포인트 탐색**
- API: 라우터/컨트롤러에서 엔드포인트 목록 추출
- UI: 페이지/라우트 목록 추출
- 서비스: 주요 public 메서드 추출
- 2. **핵심 흐름 식별** (서브에이전트 `model: "sonnet"`, `subagent_type="Explore"` 사용)
+ 2. **핵심 흐름 식별** (읽기 전용 탐색·검토 역할)
+ - `MODULE_SKILL[mermaid-diagrams]`를 직접 읽어 Mermaid 문법 계약 적용
- 사용자 요청 → 응답까지의 주요 흐름 추적
- 분기(if/else, switch), 에러 처리, 외부 호출 식별
- - 흐름별 Mermaid flowchart 생성
+ - 흐름별 Mermaid flowchart 초안과 `file:line` 근거 반환, 파일 쓰기 금지
- 3. **다이어그램 파일 저장**
+ 3. **다이어그램 파일 저장** (메인이 출력 경로를 배정한 general-write 역할 또는 순차 폴백)
- `docs/clio/latest/flow-diagrams/{feature-name}.mmd`
- 전체 시스템 개요 다이어그램: `system-overview.mmd`
- 4. **기존 흐름도와 비교** (있는 경우)
+ 4. **기존 흐름도와 비교** (읽기 전용 탐색·검토 역할, 있는 경우)
- `docs/flow-diagrams/` 또는 `docs/plan/*/flow-diagrams/`에 기존 다이어그램이 있으면
- - `flow-verifier` verify 모드 로직을 참조하여 기존 설계 ↔ 최종 코드 차이 표시
+ - `MODULE_SKILL[flow-verifier]`에서 직접 읽은 verify 모드로 기존 설계 ↔ 최종 코드 차이 표시
- 차이가 있으면 리포트에 기록 (설계 변경 이력으로 활용)
+ - 모듈 해석 실패 시 위 native fallback을 사용하고 모듈 적용으로 표기하지 않음
**Phase 2 출력:**
```
✅ Phase 2 완료: 프로세스 흐름도 추출
생성: {N}개 다이어그램
시스템 개요: system-overview.mmd
핵심 흐름: {feature-1}.mmd, {feature-2}.mmd, ...
설계 대비 차이: {있음/없음}
```
---
## Phase 3: 문서 산출물 생성
**목적:** Phase 2의 흐름도 + 기존 검증 결과 + 소스 코드를 기반으로 문서 생성
**원칙: "코드가 진실"** — 설계 문서가 아니라 최종 확정된 코드에서 문서를 추출합니다.
3종 문서의 입력/출력 경로 및 포함 항목 상세: See [document-templates.md](references/document-templates.md)
+ 메인은 PRD, 기술 문서, 사용자 매뉴얼, 변경 이해 퀴즈를 서로 겹치지 않는 출력 파일로 나누고
+ 파일별 general-write 역할에 배정합니다. 각 역할은 자기 파일만 생성·윤문하고 변경 경로와 검증
+ 결과를 반환합니다. 위임이 없으면 메인이 아래 순서대로 문서를 하나씩 생성합니다.
+
### Phase 3 시작: 도메인사전 컨텍스트 로드
- `docs/domain-dictionary.md`가 있으면 모든 문서 생성 서브에이전트에게 컨텍스트로 주입합니다. 없으면 이 단계 건너뜀.
+ `docs/domain-dictionary.md`가 있으면 메인이 읽어 각 문서 general-write 역할에 읽기 전용 컨텍스트로
+ 전달합니다. 없으면 이 단계는 건너뜁니다. 사전 원본과 공유 작업 상태는 메인만 갱신합니다.
**문서별 사전 활용:**
| 문서 | 사전 활용 |
|------|----------|
| PRD.md | 기능명/엔터티명을 사전 영문 식별자로 표기 + 한글 표기 병기. 금지 표현 검출 시 정정 |
| TECHNICAL.md | 모듈명/클래스명/타입명이 사전 영문 식별자 따르는지 확인. 위반 시 보고 (코드 수정은 clio 권한 외) |
| USER-MANUAL.md | UI 라벨/메뉴명/메시지가 사전 한글 표기 따르는지 확인. 매뉴얼 본문은 사전 표기로 통일 |
**용어 색인 자동 생성**: 3종 문서 모두에 마지막 부록으로 "용어 색인" 섹션 자동 추가 (사전을 alphabetical로 나열, 한글 표기 + 한 줄 정의).
신규 멤버 온보딩 시 USER-MANUAL.md 한 장으로 도메인 어휘 + 사용법을 동시에 학습 가능.
### Phase 3 공통: 한국어 윤문 (humanizer 연동)
- 한국어로 생성되는 문서는 humanizer 한국어 모듈을 두 단계로 적용합니다.
+ 한국어로 생성되는 문서는 `MODULE_SKILL[humanizer]`와
+ `MODULE_ROOT[humanizer]/references/korean-translationese.md`를 직접 읽어 한국어 모듈을 두 단계로
+ 적용합니다. 둘 중 하나라도 없으면 아래의 축약 fallback만 적용하고 전체 패턴 검사는
+ `UNVERIFIED`로 기록합니다.
- **생성 시 (제약 주입):** 문서 생성 서브에이전트 프롬프트에 포함 —
+ **생성 시 (제약 주입):** 각 문서 general-write 역할의 작업 계약에 포함 —
- 번역투 금지: 연결어미 뒤 쉼표 습관("하며,"·"하고,"), ~성/~적/~화 명사화 남발, 불필요한 진행형, 대명사 직역("그것은"·"이것은")
- AI 문체 금지: 과장 수식어, 3개 나열 습관, 공허한 마무리 문장
**생성 후 (윤문 패스):** 3종 문서 완성 후 humanizer 한국어 모듈로 1회 점검 —
- S1 등급(항상 제거) 패턴 중심, 정량 지표(연결어미 뒤 쉼표 밀도 등)로 빠르게 진단
- 과잉편집 가드 준수: 변경률 30% 경고 / 50% 중단. 고유명사·수치·코드 블록·도메인사전 표기는 수정 금지
- 우선순위: USER-MANUAL.md(외부 공유) > PRD.md > TECHNICAL.md(S1만)
- - 상세 패턴: `skills/humanizer/references/korean-translationese.md`
+ - 상세 패턴: `MODULE_ROOT[humanizer]/references/korean-translationese.md`
### Phase 3 공통: 사실 검증 게이트 (생성 후)
- 윤문 패스 직후, 별도 서브에이전트(`model: "sonnet"`)에게 3종 문서가 단정하는 식별자·수치를 소스 코드와 대조시킵니다. LLM은 외부 피드백 없이 자기 주장을 스스로 교정하지 못하므로, 생성 단계의 주장은 반드시 소스로 역검증해야 합니다.
+ 윤문 패스 직후, 생성 역할과 분리된 읽기 전용 검토 역할에 3종 문서가 단정하는 식별자·수치를
+ 소스 코드와 대조시킵니다. 검토 역할은 근거와 필요한 교정 목록만 반환하며 문서를 수정하지 않습니다.
+ 메인이 근거를 확인한 뒤 해당 문서에 교정을 반영합니다. 위임할 수 없으면 같은 대조를 메인 컨텍스트에서 순차 수행합니다.
**대조 대상:** API/엔터티 이름, 커버리지 %, 의존성·API 개수, NFR("코드에서 감지된 것"으로 적힌 항목).
**절차:** 각 주장의 식별자/수치를 소스에서 Grep으로 확인 → 일치하면 유지, 소스에서 확인되지 않으면 해당 표기를 `[확인 필요]`로 교체.
> **가드(필수):** 소스로 확인되지 않은 수치/식별자는 단정하지 말고 `[확인 필요]`로 표기. 추측으로 숫자/이름을 채우지 말 것.
### 3-1. PRD — `docs/clio/latest/PRD.md`
- `documentation` 에이전트 패턴을 참조하여 서브에이전트(`model: "sonnet"`)에게 생성 위임.
+ Clio의 `references/document-templates.md`를 계약으로 삼습니다.
소스 코드 기준으로 기능 요구사항, 데이터 모델, API 목록, 화면 흐름을 추출합니다.
### 3-2. 기술 문서 — `docs/clio/latest/TECHNICAL.md`
아키텍처 개요(Mermaid C4), 기술 스택, 핵심 모듈, 환경 설정, 빌드/배포 절차를 포함합니다.
### 3-3. 사용자 매뉴얼 — `docs/clio/latest/USER-MANUAL.md`
기능별 사용법, 화면 가이드(UI), 또는 API 레퍼런스(API only), FAQ/트러블슈팅을 포함합니다.
### 3-3b. 변경 이해 퀴즈 — `docs/clio/latest/CHANGE-QUIZ.md`
긴 구현 후에는 리뷰어가 변경 맥락을 놓치기 쉽습니다. PRD/TECHNICAL/USER-MANUAL 생성 직후, 최종 코드와 diff를 기준으로 사람이 이해해야 할 핵심을 5-10문항 퀴즈로 만듭니다.
포함 항목:
- 변경의 의도와 사용자 영향
- 데이터 모델/API/권한/상태 흐름처럼 리뷰어가 잘못 이해하면 위험한 결정
- 테스트와 검증 증거
- `implementation-notes.md`가 있으면 `Deviations`의 이유와 후속 조치
정답과 해설은 각 문항 바로 아래 접기 가능한 형식 또는 별도 "Answer Key" 섹션에 둡니다. 최종 보고에는 "퀴즈 통과 전 병합 금지" 권고를 남깁니다.
**Phase 3 출력:**
```
✅ Phase 3 완료: 문서 산출물 생성
PRD.md — {N}개 기능 요구사항, {M}개 API 엔드포인트
TECHNICAL.md — {N}개 모듈, {M}개 의존성
USER-MANUAL.md — {N}개 기능 가이드
CHANGE-QUIZ.md — {N}개 변경 이해 문항
```
### 3-4. PDF 출력 (한국 기본값: A4 + Pretendard)
**`--no-pdf`가 아니면 진행.** 사용자에게 페이지 구성을 묻고 적합한 옵션으로 PDF를 자동 생성합니다.
**현재 CLI의 질문 방식으로 묻기 (한 번만):**
> 산출물을 PDF로도 출력하시겠어요? (외부 공유/인쇄용)
옵션:
- A) 3종 모두 PDF (PRD + TECHNICAL + USER-MANUAL)
- B) USER-MANUAL만 PDF (외부 공유용)
- C) PDF 출력 안 함
**A 또는 B 선택 시 후속 질문:**
> 페이지 구성은 어떻게 할까요?
옵션:
- A) **출판 모드** — 표지 + TOC + H1마다 새 페이지 (외부 공유, 인쇄)
- B) **간단 모드** — TOC만 (내부 문서)
- C) **메모 모드** — 옵션 없음 (짧은 문서)
> 워터마크가 필요한가요?
옵션:
- A) "초안" (작업 중)
- B) "검토용" (리뷰 요청)
- C) "대외비" + CONFIDENTIAL 푸터
- D) 없음 (최종본)
**PDF 생성 명령 (선택에 따라 자동 구성):**
+ 먼저 `PDF_SCRIPT`를 해석된 절대경로
+ `MODULE_ROOT[pdf]/scripts/markdown_to_pdf.py`로 설정하고 파일 존재를 확인합니다. 아래 명령의
+ `PDF_SCRIPT`에는 상대경로가 아니라 그 절대경로만 넣습니다.
+
```bash
+ # 실행 전에 이 값을 MODULE_ROOT[pdf]에서 파생한 실제 절대경로로 치환
+ PDF_SCRIPT="<absolute MODULE_ROOT[pdf]>/scripts/markdown_to_pdf.py"
+
# 출판 모드 + 워터마크 없음 예시
- python skills/pdf/scripts/markdown_to_pdf.py generate \
+ python "$PDF_SCRIPT" generate \
--cover --toc \
--title "{프로젝트명} 사용자 매뉴얼" \
--author "{팀/저자}" \
--org "{조직}" \
docs/clio/latest/USER-MANUAL.md
# 검토용 워터마크 예시
- python skills/pdf/scripts/markdown_to_pdf.py generate \
+ python "$PDF_SCRIPT" generate \
--cover --toc --watermark "검토용" \
--title "{프로젝트명} PRD" \
docs/clio/latest/PRD.md
# 대외비 예시
- python skills/pdf/scripts/markdown_to_pdf.py generate \
+ python "$PDF_SCRIPT" generate \
--cover --toc --watermark "대외비" --confidential \
--title "{프로젝트명} 기술문서" \
docs/clio/latest/TECHNICAL.md
```
**산출물 위치:**
```
docs/clio/latest/
├── PRD.md + PRD.pdf (--cover --toc)
├── TECHNICAL.md + TECHNICAL.pdf (--cover --toc)
└── USER-MANUAL.md + USER-MANUAL.pdf (--cover --toc, 외부 공유 빈도 높음)
```
**Phase 3-4 출력:**
```
✅ Phase 3-4 완료: PDF 출력
PRD.pdf — {N} 페이지 ({size} KB)
TECHNICAL.pdf — {N} 페이지 ({size} KB)
USER-MANUAL.pdf — {N} 페이지 ({size} KB)
페이지 구성: {출판 모드 / 간단 모드 / 메모 모드}
워터마크: {초안 / 검토용 / 대외비 / 없음}
```
**의존성 자동 점검:**
```bash
- python -c "import playwright, markdown" 2>/dev/null
- if [ $? -ne 0 ]; then
+ PDF_SCRIPT="<absolute MODULE_ROOT[pdf]>/scripts/markdown_to_pdf.py"
+ if [ ! -f "$PDF_SCRIPT" ]; then
+ echo "PDF: NOT RUN — resolved pdf script not found: $PDF_SCRIPT"
+ elif ! python -c "import playwright, markdown" 2>/dev/null; then
echo "⚠️ playwright 미설치. 다음 명령으로 설치:"
echo " pip install playwright markdown pygments"
echo " playwright install chromium"
echo "또는 한 방에:"
- echo " python skills/pdf/scripts/markdown_to_pdf.py setup"
+ echo " python \"$PDF_SCRIPT\" setup"
echo "PDF 출력 건너뜁니다."
fi
```
`/minos` 스킬이 이미 설치되어 있다면 playwright는 중복 없이 재사용됩니다.
- 미설치 시 PDF만 건너뛰고 Phase 3.5로 진행 (블로커 아님).
+ PDF 모듈·스크립트·Python 의존성 중 하나라도 없으면 PDF만 `NOT RUN`으로 기록하고 Phase 3.5로
+ 진행합니다(블로커 아님). 출력 파일이 실제로 생성되고 열리는지 확인하기 전에는 PDF 단계를 완료로
+ 표기하지 않습니다.
- **상세 사용법:** [skills/pdf/SKILL.md](../pdf/SKILL.md) "Markdown → 출판품질 PDF" 섹션 참조.
+ **상세 사용법:** `MODULE_SKILL[pdf]`의 "Markdown → 출판품질 PDF" 섹션을 직접 참조합니다.
---
## Phase 3.5: 문서 사이트 생성 (웹 매뉴얼)
**목적:** Phase 3에서 만든 마크다운 문서를 docs.example.com 같은 문서 웹사이트로 빌드
> 마크다운 파일만 있으면 아무도 안 본다. 웹 문서로 만들어야 실제로 쓰인다.
### 3.5-1. 기존 문서 프레임워크 감지
```bash
# 기존 문서 사이트 감지
_DOC_FRAMEWORK=""
[ -f "docusaurus.config.js" ] || [ -f "docusaurus.config.ts" ] && _DOC_FRAMEWORK="docusaurus"
[ -f "mkdocs.yml" ] && _DOC_FRAMEWORK="mkdocs"
[ -f ".vitepress/config.ts" ] || [ -f ".vitepress/config.js" ] && _DOC_FRAMEWORK="vitepress"
[ -f "astro.config.mjs" ] && grep -q "starlight" "astro.config.mjs" && _DOC_FRAMEWORK="starlight"
echo "DOC_FRAMEWORK: ${_DOC_FRAMEWORK:-없음}"
```
### 3.5-2. 프레임워크 선택 (없으면)
기존 프레임워크가 없으면 프로젝트 스택에 맞게 자동 선택:
| 프로젝트 스택 | 추천 | 이유 |
|-------------|------|------|
| React / Next.js | **Docusaurus** | React 기반, MDX 지원, 버전 관리 |
| Vue / Nuxt | **VitePress** | Vue 기반, Vite 빌드, 가벼움 |
| Python / FastAPI | **MkDocs Material** | pip install 한 줄, 가장 간단 |
| 기타 / 범용 | **VitePress** | 빠르고 가볍고 마크다운 그대로 사용 |
### 3.5-3. 셋업 + 문서 배치
- 서브에이전트(`model: "sonnet"`)에게 실행 위임:
+ 메인이 문서 사이트 출력 경로와 허용되는 manifest 변경을 명시한 뒤 general-write 역할에 실행을
+ 맡깁니다. 이 역할은 지정 경로 밖을 수정하지 않고 변경 경로와 빌드 검증을 반환합니다. 위임이
+ 없으면 메인 컨텍스트에서 아래 셋업과 검증을 순차 실행합니다.
**핵심: 복사가 아니라 직접 참조.** 문서 프레임워크가 `docs/clio/latest/`를 소스로 읽도록 설정하면, md를 수정할 때 Hot Reload로 즉시 반영됩니다.
**VitePress 예시:**
```bash
# 초기화 (docs/clio/latest/를 소스 루트로 지정)
npm add -D vitepress
# .vitepress/config.ts에서 srcDir을 clio 산출물로 지정
# → 별도 복사 불필요, md 수정 시 즉시 반영
```
```ts
// docs/clio/latest/.vitepress/config.ts
export default {
title: '{프로젝트명} 문서',
themeConfig: {
sidebar: [
{ text: '시작하기', items: [
{ text: '소개', link: '/PRD' },
{ text: '사용자 가이드', link: '/USER-MANUAL' },
]},
{ text: '기술 문서', items: [
{ text: '아키텍처', link: '/TECHNICAL' },
{ text: '최종 보고서', link: '/FINAL-REPORT' },
]},
]
}
}
```
```bash
# dev server (md 수정 → 즉시 반영)
npx vitepress dev docs/clio/latest
```
**MkDocs 예시:**
```bash
pip install mkdocs-material
```
```yaml
# mkdocs.yml (docs_dir을 clio 산출물로 지정)
site_name: '{프로젝트명} 문서'
docs_dir: docs/clio/latest
nav:
- 소개: PRD.md
- 사용자 가이드: USER-MANUAL.md
- 기술 문서: TECHNICAL.md
- 최종 보고서: FINAL-REPORT.md
```
```bash
mkdocs serve # md 수정 → 즉시 반영
```
### 3.5-4. 사이드바/네비게이션 자동 생성
Phase 3 문서가 이미 `docs/clio/latest/`에 있으므로 그대로 소스 디렉토리로 사용합니다.
문서가 많아지면 분할하되, **원본 .md 파일이 유일한 소스**입니다:
```
docs/clio/latest/ ← 문서 사이트의 소스 루트
├── .vitepress/config.ts # 또는 mkdocs.yml (사이트 설정)
├── index.md # 프로젝트 소개 (자동 생성)
├── PRD.md # Phase 3 원본 그대로
├── TECHNICAL.md # Phase 3 원본 그대로
├── USER-MANUAL.md # Phase 3 원본 그대로
├── CHECKLIST.md # Phase 1 원본 그대로
├── FINAL-REPORT.md # Phase 4 원본 그대로
└── flow-diagrams/ # Phase 2 원본 그대로
├── system-overview.mmd
└── {feature}.mmd
```
> `.md`를 수정하면 문서 사이트가 즉시 반영됩니다. 별도 빌드/동기화 불필요.
### 3.5-5. 프리뷰 실행
```bash
# VitePress
npx vitepress dev docs
# MkDocs
mkdocs serve
# Docusaurus
npm start
```
사용자에게 프리뷰 URL 안내: `http://localhost:5173` (또는 해당 포트)
### Phase 3.5 건너뛰는 경우
- `--check-only`, `--flow-only` 옵션 사용 시
- 사용자가 "문서 사이트 불필요" 명시 시
- API만 있는 프로젝트에서 사용자가 거부 시
**Phase 3.5 출력:**
```
✅ Phase 3.5 완료: 문서 사이트 생성
프레임워크: {VitePress / Docusaurus / MkDocs}
페이지: {N}개
프리뷰: http://localhost:{port}
빌드: npx vitepress build docs
배포: Vercel / Netlify / GitHub Pages
```
---
## Phase 4: 최종 보고서
- 모든 Phase 결과를 통합한 최종 보고서를 생성합니다.
+ 메인이 모든 Phase 결과를 정규화하고 GO/NO-GO와 미검증 범위를 확정한 뒤, `FINAL-REPORT.md`만
+ 소유하는 general-write 역할에 템플릿 기반 생성을 맡깁니다. 메인이 결과를 검증해 공유 상태에
+ 반영하며, 위임이 없으면 직접 순차 생성합니다.
**출력:** `docs/clio/latest/FINAL-REPORT.md`
보고서 마크다운 전체 템플릿: See [report-template.md](references/report-template.md)
### 사용자에게 안내
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Clio 기록 완료! 마무리투수가 판정하고, 역사의 뮤즈가 기록했습니다.
🏟️ 판정: {GO / CONDITIONAL GO}
📁 산출물 위치: docs/clio/latest/
CHECKLIST.md — 최종 점검 결과 (Phase 1)
flow-diagrams/ — 프로세스 흐름도 (Phase 2)
PRD.md (+ .pdf) — 제품 요구사항 문서 (Phase 3)
TECHNICAL.md (+ .pdf) — 기술 문서 (Phase 3)
USER-MANUAL.md (+ .pdf) — 사용자 매뉴얼 (Phase 3, 외부 공유용)
FINAL-REPORT.md — 최종 보고서 (Phase 4)
📖 문서 사이트: http://localhost:{port} (Phase 3.5)
프레임워크: {VitePress / Docusaurus / MkDocs}
빌드: {빌드 명령어}
📂 이전 이력: docs/clio/archive/
👉 다음 단계:
/commit → 산출물 커밋
/release → 버전 태그 + CHANGELOG
/launch → 배포 전 체크리스트
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
---
## 옵션
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `--check-only` | Phase 1만 실행 (GO/NO-GO 판정만) | false |
| `--docs-only` | Phase 2~3만 실행 (문서 생성만, 점검 건너뜀) | false |
| `--flow-only` | Phase 2만 실행 (흐름도만) | false |
| `--no-site` | 문서 사이트 생성 건너뜀 (Phase 3.5 스킵) | false |
| `--no-pdf` | PDF 출력 건너뜀 (Phase 3-4 스킵) | false |
| `--pdf=user-manual` | USER-MANUAL만 PDF (PRD/TECHNICAL은 마크다운만) | false |
| `--output-dir` | 산출물 디렉토리 변경 | `docs/clio/latest/` |
| `--force` | NO-GO여도 문서 생성 강제 진행 | false |
---
## 예외사항
다음은 **문제가 아닙니다**:
1. **argos/minos 미실행** — CHECKLIST에 "미실행"으로 기록, CONDITIONAL GO로 판정
2. **기존 설계 산출물 없음** — 누락 탐지 건너뜀, 코드 기준으로 문서 생성
3. **UI 없음** — Phase 3에서 API 레퍼런스 매뉴얼로 대체
4. **기존 흐름도 없음** — Phase 2에서 새로 생성 (비교 단계만 건너뜀)
5. **테스트 프레임워크 없음** — CHECKLIST에 "미설정"으로 기록, 경고. 단 판정은 **최대 CONDITIONAL GO** (테스트 0개로 GO 불가)
---
## 연관 스킬
| 스킬 | 역할 | 연결 |
|------|------|------|
| zephermine | 설계 산출물 생성 | spec + AC 참조 (누락 탐지) |
| agent-team | 구현 수행 | 선행 완료 |
| argos | 감리 (준공검사) | Phase 1에서 결과 수집 |
| minos | Playwright QA 실사 | Phase 1에서 결과 수집 |
- | flow-verifier | 프로세스 흐름도 생성/검증 | Phase 2에서 활용 |
- | documentation | 문서 생성 에이전트 | Phase 3 템플릿 참조 |
- | humanizer | 한국어 윤문 (번역투/AI 문체 제거) | Phase 3 생성 시 제약 주입 + 생성 후 윤문 패스 |
- | mermaid-diagrams | Mermaid 문법 가이드 | Phase 2 다이어그램 생성 시 참조 |
+ | flow-verifier (source-only module) | 프로세스 흐름도 생성/검증 | Phase 2에서 `MODULE_SKILL` 직접 읽기 |
+ | humanizer (source-only module) | 한국어 윤문 (번역투/AI 문체 제거) | Phase 3에서 `MODULE_SKILL`과 참조 직접 읽기 |
+ | mermaid-diagrams (source-only module) | Mermaid 문법 가이드 | Phase 2에서 `MODULE_SKILL` 직접 읽기 |
| release-notes | 버전 + CHANGELOG | Phase 4 이후 후속 |
| shipping-and-launch | 배포 전 체크리스트 | Phase 4 이후 후속 |
| documentation-and-adrs | ADR 작성 | Phase 4 보고서에 ADR 목록 포함 가능 |
- | pdf | Markdown → 출판품질 PDF | Phase 3-4에서 PRD/TECHNICAL/USER-MANUAL을 PDF로 출력 |
+ | pdf (source-only module) | Markdown → 출판품질 PDF | Phase 3-4에서 해석한 절대 스크립트 경로 실행 |
| zeus | 전체 파이프라인 | zeus 완료 후 /clio로 마무리 |
## Related Files
| 파일 | 역할 |
|------|------|
| `references/document-templates.md` | 3종 문서 포함 항목 상세 |
| `references/report-template.md` | 최종 보고서 마크다운 템플릿 |
- | `skills/flow-verifier/SKILL.md` | 프로세스 흐름도 생성/검증 로직 |
+ | `MODULE_SKILL[flow-verifier]` | 프로세스 흐름도 생성/검증 로직 |
| `skills/argos/SKILL.md` | 감리 검증 프로세스 |
- | `agents/documentation.md` | 문서 생성 에이전트 (PRD, API, IMPLEMENTATION 템플릿) |
| `skills/minos/SKILL.md` | QA 시나리오 생성 + Playwright 테스트 |
- | `skills/mermaid-diagrams/SKILL.md` | Mermaid 문법 가이드 |
- | `skills/pdf/SKILL.md` | Markdown → 출판 PDF (Phase 3-4에서 호출) |
- | `skills/humanizer/references/korean-translationese.md` | 한국어 번역투 패턴 (Phase 3 윤문 패스) |
- | `skills/pdf/scripts/markdown_to_pdf.py` | PDF 변환 스크립트 (playwright/Chromium) |
+ | `MODULE_SKILL[mermaid-diagrams]` | Mermaid 문법 가이드 |
+ | `MODULE_SKILL[pdf]` | Markdown → 출판 PDF 계약 |
+ | `MODULE_ROOT[humanizer]/references/korean-translationese.md` | 한국어 번역투 패턴 (Phase 3 윤문 패스) |
+ | `MODULE_ROOT[pdf]/scripts/markdown_to_pdf.py` | PDF 변환 스크립트 (playwright/Chromium) |