Zzon Wiki

---
name: zzon-wiki
description: 프로젝트 개발 문서 위키를 만들고 채운다. 신규 프로젝트는 인터뷰로, 기존 프로젝트는 코드 스캔+질문으로 문서를 작성하고, 부족한 내용을 질문하면서 채우는 프로세스를 강제한다. 아키텍처류 문서는 zzon-doc 다이어그램을 그려 임베드한다. "문서 위키 만들어줘", "프로젝트 문서 정리", "개발 문서 작성", "문서 채워줘", "위키 업데이트" 같은 요청에 사용한다.
argument-hint: '[대상 — 비우면 현재 프로젝트]'
---

# 프로젝트 문서 위키 만들기

코드/인터뷰에서 **wiki.json**(단일 상태 소스)과 **docs/*.md**를 저작하고 `scripts/build-wiki.mjs`로
의존성 0짜리 self-contained 위키 사이트(index.html)를 만든다. 산출물은 대상 프로젝트의 `docs/zzon-doc/` 하위에 기존 다이어그램 산출물과 공존한다(구버전 기본값인 루트 `zzon-doc/`가 이미 있으면 그걸 유지).

> 계약 정본: `references/wiki-spec.md`(스키마·md 규약) · `references/doc-catalog.md`(문서 카탈로그·질문 은행).
> 아키텍처·데이터 다이어그램은 **zzon-doc 스킬 절차**(유형 판별→스펙→layout-lint→render)로,
> 시간축 상호작용(요청/응답 왕복·분기)은 **zzon-seq 스킬 절차**(SeqSpec 저작→render-seq)로 그린다.
> 둘 다 같은 specs/→diagrams/→manifest 파이프라인이라 위키 임베드 방법(`@diagram`)은 동일하다.

## 0. 분기 — 첫 행동을 정한다

- `docs/zzon-doc/wiki.json`(또는 구버전 경로 루트 `zzon-doc/wiki.json`)이 **있으면 → 재진입 모드(§4)**. 첫 행동은 무조건 `--status` 실행이다. 이후 명령의 `<docsDir>`는 wiki.json이 발견된 그 폴더다.
- 없으면 → 신규. 코드가 있는 프로젝트면 `projectMode: "existing"`(스캔 우선), 빈/초기 프로젝트면 `"greenfield"`(인터뷰 우선).
- 기존 `docs/zzon-doc/manifest.json`(다이어그램 — 구버전은 루트 `zzon-doc/`)이 있으면 → 승격: 기존 다이어그램을 아키텍처/데이터 문서로 **자동 편입 제안**에 포함한다.

## 1. 스캔 → 제안 → 승인 (게이트 — 어기지 마라)

**순서를 반드시 지킨다: ① 스캔 → ② "티어·섹션" 제안·승인 → ③ 작성.**
**승인 전에는 wiki.json도 docs/의 어떤 파일도 만들지 마라.**

1. **스캔**: README·패키지 구조·라우터·스키마·CI/IaC를 훑어 **"코드에서 읽힌 것"과 "물어야 하는 것"을 분리**한다. (greenfield면 이 단계는 "무엇을 만들려는지" 인터뷰 3~5문으로 대체.)
2. **제안은 반드시 이 형태로** — 티어 3택 + 제외 섹션 + 개수 근거 (**시퀀스 후보를 반드시 센다** — 인증·결제·대표 유스케이스처럼 왕복이 본질인 프로세스는 "시퀀스 M장"으로 제안에 명시):
   > "코드에서 서비스 3·테이블 12·API 24개, 시퀀스 후보 3(인증·공유·다이제스트)을 확인했다. 어느 티어로 갈까?
   > **① 라이트(~15장)** — 개요+아키텍처+데이터+API+퀵스타트+운영 핵심
   > **② 표준(~35장)** — ①에 요구·기획·규약·운영 상세 추가
   > **③ 풀 SI(~90장)** — 발주·감리용 전체
   > 그리고 UX 섹션은 Figma 관리로 보여 제외를 제안한다 — 맞나?"
3. 승인받은 구성으로 **wiki.json을 인스턴스화**한다(카탈로그는 템플릿 — `doc-catalog.md`의 인스턴스화 절차 6개를 따른다. dynamic 노드는 실제 도메인명으로, summary는 프로젝트 문맥으로 재작성, **카탈로그 그대로 복사 금지**, 섹션 `code`는 포함분 기준 `00`부터 연속 재부여).

## 2. 섹션 루프 — 작성은 이 리듬으로

섹션 하나씩: **초안 → 질문 → 빌드 → 마감 확인**. 전 섹션 일괄 자동 생성 금지.

1. **초안**: 코드에서 읽힌 것만으로 문서를 쓴다. **못 읽은 값을 추측으로 채우지 마라** — 그 자리는 ❓ 콜아웃으로 남긴다.
2. **질문은 섹션당 한 묶음(3~5개)**, 번호 목록으로, 각 질문에 "모름/스킵 가능"을 명시한다. 10개 이상 몰아 묻기 금지.
   무응답·모름은 **즉시 wiki.json 질문 대장(q-NNN) + 본문 `> ❓ 미확인(q-NNN): …` 콜아웃**으로 남기고 진행을 막지 마라.
3. **다이어그램 노드**(architecture/data의 `@diagram` 표시)는 zzon-doc(구조·ERD·플로우) 또는 zzon-seq(시퀀스) 스킬 절차로 스펙을 저작해 `specs/`에 두고, 문서에는 `@diagram(slug)` 한 줄만 쓴다. HTML 직접 작성 금지.
   **시퀀스 판별을 건너뛰지 마라**: 문서가 다루는 프로세스가 "누가 누구에게 순서대로 주고받는가"(왕복·활성 구간·alt/loop)면 zzon-seq가 정본이고, seq-flows/usecase/authn 문서는 시퀀스 임베드를 기본값으로 한다. 구조 관점(data-flow)과의 병행은 중복이 아니라 보완이다.
4. 섹션을 마치면 **빌드하고**(아래 명령) 결과를 보여준 뒤 **"이 섹션에 빠진 내용은 없나?"를 반드시 묻는다.** 다음 섹션은 그 답을 반영한 후에.
5. **todo 문서는 빈 md를 만들지 않는다** — wiki.json 엔트리로만 둔다.

## 3. 빌드 — 명령어

```bash
node ${CLAUDE_PLUGIN_ROOT}/skills/zzon-wiki/scripts/build-wiki.mjs ./docs/zzon-doc
```

- 다이어그램(specs/)이 있으면 build-docs를 자식으로 호출해 함께 갱신한다. **index.html은 위키 셸이 차지한다** (다이어그램 갤러리 index는 wiki.json이 있으면 자동으로 양보한다).
- 검증 실패 시 `path: 메시지` 목록이 나온다 → **그 path만 고쳐 재실행.**
- 상태 리포트만: `build-wiki.mjs ./docs/zzon-doc --status` (쓰기 없음).

## 4. 재진입 모드 (wiki.json이 이미 있을 때)

1. **첫 행동: `--status` 실행** → 사람 수정(edited)·파일 유실·미등록 md·열린 질문·todo 잔량을 보고한다.
2. 보고 후 **반드시 4택으로 묻는다**: "① 사람 수정 반영(재독 후 상태·질문 갱신) ② 열린 질문 재개 ③ todo 이어쓰기 ④ 새 문서/섹션 추가 — 뭘 할까?"
3. **사람이 고친 md는 정본이다** — 자동 덮어쓰기 금지. 재독 후 "이 변경을 반영해 상태/질문을 갱신할까?"를 물어서만 갱신한다.
4. "질문 open인데 본문 마커 소멸" 항목은 사람이 답했을 가능성 — 본문을 읽고 확인 질문으로 승격한다.

## 5. 마감 리포트

전체 작업이 끝나면: 완료/초안/todo/na 집계 + **열린 질문 목록** + "다음에 이어서 할 것"을 보고한다.
사이트의 "진행 현황" 페이지가 사람용 로그다 — 별도 로그 md를 만들지 마라.

## 절대 규칙

- 승인 전 파일 생성 금지 / 전 섹션 일괄 자동 생성 금지 / 추측으로 채우기 금지(모르면 ❓+질문 대장) / 빈 md 생성 금지.
- 상태는 wiki.json 단일 소유 — md frontmatter에 상태 쓰지 마라. 로그 파일 이중화 금지.
- 다이어그램은 zzon-doc 스킬로만. `render.mjs`·`build-docs.mjs`·`build-wiki.mjs` 엔진 수정 금지(스펙·md·wiki.json만 작성).
- 라이브러리/프레임워크/CDN 0. 문서·UI 텍스트 한국어(한다체).