cyanluna-git/cyanluna.skills/kanban-gen-wiki

CONFIG=$(cat .claude/kanban.json 2>/dev/null || cat .codex/kanban.json 2>/dev/null)
PROJECT=$(echo "$CONFIG" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['project'])" 2>/dev/null || basename "$(pwd)")
DB="$HOME/.claude/kanban-dbs/${PROJECT}.db"

wiki/
├── INDEX.md                 # 진입점 — 프로젝트 개요 + 토픽 링크
├── architecture.md          # 시스템 아키텍처, 기술 스택, 데이터 흐름
├── goals.md                 # 현재 목표, 마일스톤, 로드맵 (칸반 상태 기반)
├── decisions.md             # 주요 아키텍처 결정 이력 (exploration + decision_log 합성)
└── domains/                 # 도메인별 지식 (프로젝트마다 다름)
    ├── {domain-1}.md        # 예: courses.md, auth.md, upload.md
    ├── {domain-2}.md
    └── ...

---
topic: {토픽명}
generated: {ISO timestamp}
sources: {소스 수}
---
 
# {토픽명}
 
## Summary
{2-3 문단. 이 파일만 읽어도 토픽을 이해할 수 있어야 함.}
 
## {토픽 고유 섹션}
{소스에서 합성한 내용. 구체적 사실 + 파일 경로 인용.}
 
## Open Questions
{아직 결정되지 않았거나 불확실한 사항.}
 
## Sources
-CLAUDE.md
-kanban #ID: {exploration report title}
-README.md

① 프로젝트 컨텍스트 수집
 
   ①-A 칸반 프로젝트 메타데이터 읽기:
   sqlite3 -json "$DB" "SELECT * FROM projects WHERE id='$PROJECT'"
   → purpose, brief, stack, status, category 추출
   → projects 테이블이 비어있으면 CLAUDE.md/README.md에서 직접 추론
 
   ①-B 칸반 보드 요약 읽기:
   sqlite3 -json "$DB" "SELECT id, title, status, priority, level, tags FROM tasks WHERE project='$PROJECT' ORDER BY status, rank, id"
   → 상태별 카드 수, 전체 진행률 파악
 
   ①-C 선별 카드 읽기 (노이즈 방지):
 
   exploration report 카드 찾기:
   sqlite3 -json "$DB" "SELECT id, title, description, tags FROM tasks WHERE project='$PROJECT' AND tags LIKE '%explore-report%'"
 
   주요 결정 카드 찾기 (done + decision_log 있는 것만):
   sqlite3 -json "$DB" "SELECT id, title, decision_log FROM tasks WHERE project='$PROJECT' AND status='done' AND decision_log IS NOT NULL AND decision_log != ''"
 
   진행 중 카드:
   보드 요약에서 todo/plan/impl 상태 카드의 title + priority만 사용.
 
   ①-D 프로젝트 파일 읽기:
   - CLAUDE.md (프로젝트 루트)
   - README.md (있으면)
   - .claude/rules/ 전체 (있으면)
   - claudeos-core/standard/ 전체 (있으면)
 
   ①-E 코드 구조 스캔:
   - 최상위 디렉토리 목록 (`ls` — node_modules 등 제외)
   - package.json (dependencies, scripts)
   - 주요 config (tsconfig.json, next.config.ts 등)
 
② 토픽 구조 결정
 
   수집한 소스를 기반으로 위키 토픽 구조를 결정한다.
 
   고정 토픽 (모든 프로젝트):
   - INDEX.md — 전체 개요
   - architecture.md — 시스템 아키텍처
   - goals.md — 현재 목표 + 마일스톤
   - decisions.md — 주요 결정 이력
 
   도메인 토픽 (프로젝트별 자동 결정):
   - app/ 하위 라우트 그룹, components/ 하위 디렉토리, 또는
     칸반 카드의 explore 태그에서 도메인 추출
   - 도메인이 3개 미만이면 domains/ 디렉토리 생략, architecture.md에 통합
   - 도메인이 8개 초과이면 관련 도메인 묶기 (예: upload + storage → data-pipeline)
 
   토픽 구조를 사용자에게 제시하고 확인받기 (AskUserQuestion):
   "다음 구조로 위키를 생성합니다. 수정할 토픽이 있나요?"
   - 토픽 목록 표시
   - "이대로 진행" / "토픽 수정" 선택
 
③ 위키 파일 생성
 
   wiki/ 디렉토리 생성 후, 각 토픽 파일을 작성한다.
 
   ③-A INDEX.md 작성:
   ```markdown
   ---
   topic: 프로젝트 개요
   generated: {ISO timestamp}
   sources: {총 소스 수}
   ---
 
   # {프로젝트명} Wiki
 
   > 마지막 생성: {날짜} | 토픽: {N}개 | 소스: {N}개
 
   ## 프로젝트 개요
   {project purpose + brief 기반 2-3 문단}
 
   ## 기술 스택
   {stack 정보 테이블}
 
   ## 토픽
   | 토픽 | 설명 | 소스 수 |
   |------|------|---------|
   | [architecture](architecture.md) | 시스템 구조, 데이터 흐름 | N |
   | [goals](goals.md) | 현재 목표, 진행 상태 | N |
   | [decisions](decisions.md) | 주요 아키텍처 결정 | N |
   | [{domain}](domains/{domain}.md) | {한 줄 설명} | N |
 
   ## 현재 상태 (칸반)
   | 상태 | 카드 수 |
   |------|---------|
   | todo | N |
   | in progress | N |
   | done | N |
   ```
 
   ③-B architecture.md 작성:
   소스: CLAUDE.md 아키텍처 섹션 + claudeos-core/standard/00.core/ + 코드 구조 스캔
   - 시스템 다이어그램 (텍스트)
   - 디렉토리 구조 + 역할
   - 의존성 방향
   - 기술 스택 상세
 
   ③-C goals.md 작성:
   소스: project brief (projects 테이블 또는 CLAUDE.md) + 칸반 보드 상태 + 진행 중 카드 제목
   - 프로젝트 목적 (왜 만들었나)
   - 현재 마일스톤 / 진행 중 작업
   - 완료된 주요 작업 (done 카드 중 의미 있는 것)
   - 다음 단계 (todo 카드에서 추론)
 
   ③-D decisions.md 작성:
   소스: exploration report 카드 + done 카드의 decision_log
   - 시간순 정렬
   - 각 결정: 날짜, 맥락, 결정 내용, 근거
   - exploration report는 "방향 선택" 섹션으로 포함
   - 사소한 구현 결정은 제외 (아키텍처 수준만)
 
   ③-E domains/{domain}.md 작성 (각 도메인별):
   소스: 해당 도메인의 코드 구조 + CLAUDE.md/rules 중 관련 부분 + 관련 칸반 카드
   - 도메인 목적
   - 주요 파일/컴포넌트
   - 데이터 흐름
   - 제약사항/금지 패턴 (rules에서)
 
④ 완료 출력
 
   생성된 파일 목록 + 각 파일의 소스 수 표시:
 
   | 파일 | 소스 수 | 주요 소스 |
   |------|---------|-----------|
   | INDEX.md | — | 전체 합성 |
   | architecture.md | N | CLAUDE.md, standard/, package.json |
   | goals.md | N | project brief, 칸반 보드 |
   | decisions.md | N | exploration reports, decision_logs |
   | domains/courses.md | N | app/courses/, components/courses/ |
 
   > Wiki generated: N files in `wiki/`.
   > Run `/kanban-gen-wiki update` after significant changes to refresh.

① 변경 감지
 
   ①-A 현재 wiki/ 파일의 generated 타임스탬프 읽기 (frontmatter)
   → $LAST_GENERATED
 
   ①-B 변경된 소스 식별:
 
   칸반 변경:
   sqlite3 -json "$DB" "SELECT id, title, decision_log FROM tasks WHERE project='$PROJECT' AND status='done' AND completed_at > '$LAST_GENERATED' AND decision_log IS NOT NULL AND decision_log != ''"
   → completed_at > $LAST_GENERATED인 done 카드 중 decision_log가 있는 것
   → 새로 생성된 exploration report 카드 (created_at > $LAST_GENERATED, tags LIKE '%explore-report%')
   → projects 테이블의 brief 변경 여부 (CLAUDE.md mtime으로 대체 판단 가능)
 
   파일 변경:
   → CLAUDE.md, README.md의 mtime > $LAST_GENERATED
   → .claude/rules/ 변경 여부
   → 주요 디렉토리 구조 변경 (새 route, 새 component 디렉토리)
 
   ①-C 변경 없으면:
   "No changes detected since {$LAST_GENERATED}. Wiki is up to date."
   → 종료
 
② 영향받는 토픽 결정
 
   변경된 소스 → 어떤 토픽이 영향받는지 매핑:
 
   | 변경 소스 | 영향받는 토픽 |
   |-----------|-------------|
   | project brief 변경 | INDEX.md, goals.md |
   | 새 done 카드 (decision_log) | decisions.md |
   | 새 exploration report | decisions.md |
   | CLAUDE.md 변경 | architecture.md, INDEX.md |
   | .claude/rules/ 변경 | architecture.md, 해당 domain |
   | 새 라우트/컴포넌트 디렉토리 | architecture.md, 새 domain 토픽 생성 |
   | 칸반 보드 상태 변경 | goals.md |
 
   변경 요약을 사용자에게 표시:
   "다음 토픽을 업데이트합니다:"
   - goals.md (3 new done cards, brief updated)
   - decisions.md (1 new exploration report)
 
③ 선택적 재생성
 
   영향받는 토픽만 재생성한다.
   변경 없는 토픽은 그대로 유지.
 
   재생성 시:
   - 기존 파일 내용을 읽고
   - 새 소스의 내용을 반영하여 업데이트
   - generated 타임스탬프 갱신
   - 기존 내용 중 여전히 유효한 부분은 보존 (전체 재작성 아님)
 
   INDEX.md는 항상 재생성 (토픽 테이블, 칸반 상태 갱신).
 
④ 완료 출력
 
   | 파일 | 상태 | 변경 사유 |
   |------|------|-----------|
   | INDEX.md | updated | 칸반 상태 갱신 |
   | goals.md | updated | 3 new done cards |
   | decisions.md | updated | 1 new exploration report |
   | architecture.md | unchanged | — |
   | domains/courses.md | unchanged | — |
 
   > Wiki updated: N files changed, M unchanged.