--- name: kanban-gen-wiki description: 프로젝트의 전체 아키텍처, 목표, 주요 결정사항을 wiki/ 디렉토리에 합성하여 정리합니다. 첫 실행 시 전체 생성, update로 변경분 반영. 매 카드가 아닌 프로젝트 수준의 지식을 정리합니다. --- > Shared context: read `../kanban/shared.md` for DB path and error handling. ## `/kanban-gen-wiki` — 프로젝트 위키 초기 생성 **When to use**: 프로젝트의 전체 맥락(아키텍처, 목표, 도메인 지식, 주요 결정)을 `wiki/` 디렉토리에 정리하고 싶을 때. 매 칸반 카드가 아닌, **프로젝트 수준의 지식**을 합성한다. **이 스킬은 소스 코드를 수정하지 않는다.** ## `/kanban-gen-wiki update` — 변경분 반영 **When to use**: 이미 `wiki/`가 존재하고, 이후 변경된 코드/칸반 상태를 반영하고 싶을 때. --- ### DB 경로 설정 ```bash 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" ``` ### 소스 (읽기 전용 — 합성의 재료) 위키는 아래 4개 소스를 읽어서 합성한다. 소스 자체는 수정하지 않는다. | 소스 | 읽는 것 | 왜 | |------|---------|-----| | **칸반 프로젝트** | project metadata (purpose, brief, stack) + 보드 요약 (todo/done 비율, 마일스톤) | 현재 목표와 진행 상태 | | **칸반 카드 (선별)** | exploration report 태그 카드 + done 카드 중 decision_log가 있는 것만 | 주요 아키텍처 결정만 (구현 디테일 제외) | | **프로젝트 파일** | CLAUDE.md, README.md, .claude/rules/, claudeos-core/standard/ (있으면) | 코딩 규칙, 아키텍처 정의 | | **코드 구조** | 디렉토리 트리, package.json, 주요 config 파일 | 기술 스택, 의존성 | ### 카드 선별 기준 (노이즈 방지) 칸반 카드를 **전수 조사하지 않는다**. 아래 조건에 해당하는 카드만 읽는다: 1. **Exploration report**: `tags`에 `explore-report` 포함 → description 전문 읽기 2. **주요 결정이 있는 done 카드**: `decision_log`가 비어있지 않은 done 카드 → decision_log만 읽기 (impl_notes, review_comments 무시) 3. **진행 중 카드**: todo/plan/impl 상태 카드 → title + priority만 읽기 (현재 방향 파악용) 이 기준으로 보통 전체 카드의 20-30%만 읽게 된다. --- ### 출력 구조: `wiki/` ``` 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 └── ... ``` ### 파일 포맷 모든 위키 파일은 아래 형식을 따른다: ```markdown --- topic: {토픽명} generated: {ISO timestamp} sources: {소스 수} --- # {토픽명} ## Summary {2-3 문단. 이 파일만 읽어도 토픽을 이해할 수 있어야 함.} ## {토픽 고유 섹션} {소스에서 합성한 내용. 구체적 사실 + 파일 경로 인용.} ## Open Questions {아직 결정되지 않았거나 불확실한 사항.} ## Sources - CLAUDE.md - kanban #ID: {exploration report title} - README.md ``` --- ### Procedure: 초기 생성 (`/kanban-gen-wiki`) ``` ① 프로젝트 컨텍스트 수집 ①-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. ``` --- ### Procedure: 업데이트 (`/kanban-gen-wiki update`) ``` ① 변경 감지 ①-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. ``` --- ### Guardrails - **소스 코드 수정 금지**: 이 스킬은 `wiki/` 디렉토리만 생성/수정한다 - **카드 전수 조사 금지**: 선별 기준(exploration report, decision_log 있는 done, 진행 중 title)만 읽는다 - **구현 디테일 제외**: implementation_notes, review_comments, test_results는 읽지 않는다 - **합성, 복사 아님**: 소스를 그대로 복사하지 않고, 프로젝트 수준으로 합성한다 - **기존 위키 보존**: update 시 변경 없는 토픽은 건드리지 않는다 - **SQLite 직접 접근**: 칸반 데이터는 `sqlite3` CLI로 읽는다 - **사용자 확인**: 초기 생성 시 토픽 구조를 사용자에게 확인받는다