/docs-keeper

name: docs-keeper
description: >-
  Maintains the living records of a hi-vibe project: CLAUDE.md
  (lean project context — constraints, pitfalls, rationale), per-folder
  MODULE.md (detailed design), handover.md
  (session-to-session context log), CHANGELOG.md (substantive change
  history, Keep a Changelog), plus evidence/METRICS.md when measured
  before/after results appear. Use for /hi-vibe:init, :handover, :log,
  :recall, :welcome, and whenever the user asks to 문서 정리, 인수인계
  기록, 체인지로그 작성, CLAUDE.md 갱신, "이 폴더 문서 만들어줘", or after
  a structural change that must be reflected in docs. Also use (mode:
  recall) when the user asks about PAST decisions or work — "예전에 왜
  이렇게 했지?", "저번에 뭐까지 했더라", "이거 언제 바꿨지", "왜 이
  방식으로 결정했었지", why did we choose X — search the handover/archive/
  CHANGELOG records instead of guessing from memory.
user-invocable: false   # 사용자 표면은 /hi-vibe:* 명령 10개다. 스킬까지 슬래시 메뉴에 나오면 16개가 되어 "외울 게 적다"는 약속이 깨진다. Claude의 자동 호출은 그대로 유지된다.

docs-keeper

Each record has one job — never blur them:

| 문서 | 한 줄 정의 | 갱신 시점 | |---|---|---| | `CLAUDE.md` | 코드만 봐선 모를 것 — 제약·함정·결정 (얇게!) | 그것들이 바뀔 때 (파일 이동은 해당 없음) | | `<folder>/MODULE.md` | 그 폴더의 상세 설계 | 폴더 내용이 바뀔 때 | | `handover.md` | 세션 맥락 (왜/어디까지 했나) | 세션 끝·compact 직전 | | `CHANGELOG.md` | 결과 (무엇이 바뀌었나) | 실질 변경 직후 | | `evidence/METRICS.md` | 증명 (정량 성과를 어떻게 재현하나) | 비교 가능한 실측이 생겼을 때만 |

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.

**`.env*`는 특별히 챙긴다** (`.env.example`·`.env.sample`·`.env.template`은 예외 — 값이 아니라 견본이라 커밋하는 게 맞다). 비밀키 검사는 `.env`를 "키를 둬도 되는 자리"로 보고 **검사에서 제외**하므로, 그 파일이 Git에 올라가면 훅도 스캐너도 못 잡는다. 그래서 여기서 두 가지를 한다:

• `.gitignore`에 `.env` 계열이 없으면 추가한다(`.env.example` 등은 negate).
• **이미 추적 중이면 그 사실을 알린다** — `git ls-files` 결과에 `.env`

계열이 있으면 `.gitignore`에 넣어도 이미 올라간 것은 안 빠진다. `git rm --cached <파일>`이 필요하고, **이미 push했다면 히스토리에 남아 있으니 그 키는 폐기(rotate)해야 한다**고 분