docs-keeper

docs-keeper

Each record has one job — never blur them:

Templates: templates/*.tpl in this skill's directory. All user-facing prose you write into these docs follows the user's conversation language — write in Korean if the user talks to you in Korean, English if in English, and so on. Match the language they are actually using with you; do not default to any single language. (An existing doc's language wins: if the project's docs are already in one language, keep writing in that one for consistency.)

Token budget (hard rule)

CLAUDE.md is loaded into EVERY session — every line costs tokens forever. Keep it ≤ 120 lines. Detail always goes DOWN into MODULE.md, never up. Never paste MODULE.md content, code, or long lists into CLAUDE.md.

Mode: init

1. Detect state: does the project root have CLAUDE.md / handover.md / CHANGELOG.md? Which top-level folders look like feature folders (contain source files; skip node_modules, .git, dist, venv, __pycache__, build output)?
2. If a file already exists, NEVER overwrite silently — show what is missing versus the template and ask before touching it (AskUserQuestion). --audit mode: only report drift, change nothing.
3. Scaffold the LEAN default only — do NOT create every doc up front. A toy project must not start with more management docs than code.
   • CLAUDE.md: fill 개요/요구사항/실행 방법/함정/결정 기록 by asking the user when not inferable. Write only what the code cannot tell you. Do NOT generate a folder listing, a dependency list, or an architecture overview — Claude can get those from ls/grep in one second, they go stale immediately, and they cost context every session. (Claude Code's own /doctor trims exactly that kind of derivable content and keeps pitfalls, rationale and conventions — don't generate what the platform will delete.) 상세 문서 lists only MODULE.md files that actually exist — never write a pointer to a file you didn't create. It stays empty at init.
   • handover.md from its template.
   • CHANGELOG.md from templates/CHANGELOG.md.tpl (skip if it already exists — never overwrite). 트러블슈팅 기록이 이 플러그인의 핵심이라 CLAUDE.md·handover.md와 같은 급으로 처음부터 만든다. 지연 생성은 "첫 실질 변경 전까진 필요 없다"는 이유였지만, 그 결과 doctor는 없다고 경고하는데 init을 다시 쳐도 안 생기는 막다른 길이 됐다.
   • Do NOT create MODULE.md at init. 폴더별 상세 설계는 그 폴더가 실제로 복잡해졌을 때 생긴다 (step 3a). 처음부터 빈 MODULE.md를 뿌리면 아무도 안 채운 껍데기만 남는다.
   • Do NOT create evidence/METRICS.md at init. 비교 가능한 전후 실측이 처음 생길 때만 templates/METRICS.md.tpl로 만든다. 3a. Lazy docs — create each one the moment it is first needed, not before:
   • <folder>/MODULE.md: create when that folder's design first needs recording — a structural change lands in it, review finds it has grown complex, or the user asks "이 폴더 문서 만들어줘". Pre-fill 주요 파일 from a directory listing, leave 설계 as short TODO prompts, and add a line for it under CLAUDE.md's 상세 문서 in the SAME turn (per the doc-sync contract below). A file listing belongs HERE, next to the design it explains — not in CLAUDE.md, which every session pays for. (CHANGELOG.md는 더 이상 여기 없다 — init이 만든다. 이미 있는 프로젝트를 위해 log 모드는 여전히 없으면 만들지만, 정상 경로에서는 그럴 일이 없다.)
4. Create the .hi-vibe/ marker directory — this is what turns the hooks ON for this project (the gate). Write .hi-vibe/initialized with a one-line note (date + "hi-vibe initialized"), which also creates the dir. The gate is .hi-vibe/, NOT handover.md — a user may already have their own handover.md, so we must not key on it (that would misfire and could let a hook overwrite their file). Do not consider init complete until .hi-vibe/ exists.
5. Ensure .env* (see below), .hi-vibe/, .repo-xray/, handover.md, handover-archive.md, and handover.md.lock (the transient write-lock file for concurrent sessions) are in .gitignore. The two dirs are caches; handover* is a personal session log kept local (not shared to GitHub). The other three docs — CLAUDE.md / MODULE.md / CHANGELOG.md — ARE committed. CLAUDE.md and CHANGELOG.md exist from init; MODULE.md arrives later, per step 3a.