{"id":"update-project-docs","name":"update-project-docs","summary":"すべてのコーディングエージェント(Claude Code、Codex、その他)に必須 — 動作、設定、インターフェース、イベント、スキーマ、機能の変更後も、このリポジトリのドキュメントを同期させておくこと。","body":"# Update Project Docs\n\nThis repository keeps an unusually large, multi-surface, multi-language doc set. Docs drift silently because a change often belongs in 6–10 files across 4 languages plus two HTML pages. This skill encodes **which docs exist, which change-types touch which docs, and how to propagate consistently** (including the wiki i18n + cache-bump dance).\n\nAuthoritative inventory with exact section anchors lives in [`references/doc-map.md`](references/doc-map.md) — read it when deciding where a specific change lands. The repo rule [`.claude/rules/docs-markdown.md`](../../rules/docs-markdown.md) (\"update all affected docs together\") and [`.claude/rules/wiki-i18n.md`](../../rules/wiki-i18n.md) are binding.\n\n## When to update (including without being asked)\n\nUpdate docs **in the same change-set (PR/commit) as the code**, before claiming done — do not wait for the user to ask — whenever the change is observable from outside the module:\n\n- **New/changed env var** → every env-var table + `.env.example`.\n- **New event type** (e.g. an `events.event_type` value) → every event-type list/table.\n- **New/changed hook behavior or session/agent state transition** → hook docs + every state-machine diagram.\n- **New/changed API route or response shape** → API docs + route tables + OpenAPI.\n- **DB schema change** (table/column/index) → database docs + ERD.\n- **New WebSocket message type** → client/server WS docs.\n- **New MCP tool** → MCP docs.\n- **New CLI command / script / renamed file referenced in docs** → command lists + onboarding guides.\n- **New user-facing feature / page / background service** → feature tables + landing + wiki + architecture.\n\n**Do NOT** auto-update for: pure internal refactors with no observable/interface/config change, test-only changes, comment/typo fixes, or work the user explicitly scoped as \"no docs\". When unsure whether a change is observable, check the mapping below; if it touches any row, update.\n\n## Change → docs mapping\n\n| Change type | Docs to update |\n|---|---|\n| **Env var** | `README.md`, `README-VN.md`, `README-CN.md`, `README-KO.md` (env tables), `ARCHITECTURE.md` (inline), `server/README.md`, `wiki/index.html` (env table) + wiki i18n, `.env.example` |\n| **Event type** | `README.md`+VN+CN (hook-event table), `ARCHITECTURE.md` (Event types line), `docs/PLUGINS.md`, `wiki/index.html` + i18n, `docs/DATABASE.md` (if it enumerates types) |\n| **Hook behavior / state transition** | `docs/HOOKS.md`, state-machine **mermaid** diagrams in `README.md`+VN+CN + `server/README.md` + `docs/DATABASE.md` + `wiki/index.html`, `ARCHITECTURE.md` (hooks.js row) |\n| **API route / response** | `docs/API.md`, `server/README.md` (routes), `ARCHITECTURE.md` (routes row), `server/openapi*.js` (code) |\n| **DB schema** | `docs/DATABASE.md`, `ARCHITECTURE.md` (ERD/schema) |\n| **WebSocket message** | `client/README.md` (Event Types), `server/README.md`, `wiki/index.html` |\n| **MCP tool** | `mcp/README.md`, `docs/MCP.md` |\n| **Feature / page / background service** | `README.md`+VN+CN (feature table + data-flow list), `ARCHITECTURE.md` (module table), `index.html` (landing blurb), `wiki/index.html` + i18n, `server/README.md` or `client/README.md` |\n| **CLI command / script** | `README.md` commands, `CLAUDE.md` / `AGENTS.md`, `INSTALL.md` / `SETUP.md` |\n| **New language** | `docs/I18N.md`, `client/src/i18n/locales/<xx>/*`, `client/src/i18n/index.ts`, `README-<XX>.md`, wiki i18n |\n\n## Procedure\n\n1. **Classify** the change against the table above. A change can hit multiple rows (a new feature with a new env var hits both).\n2. **Write the canonical English version first** — usually `README.md` and/or `ARCHITECTURE.md`. Get the wording right there; it anchors everything else.\n3. **Propagate to translations** `README-VN.md`, `README-CN.md`, and `README-KO.md`: mirror the SAME edits at the corresponding sections. Keep identifiers, env-var names, event names, and code in English; translate only prose. Render \"Waiting\" as **Đang chờ** (vi) / **等待中** (zh) / **대기 중** (ko). Match each file's existing terminology — read the neighboring lines first.\n4. **Landing page** `index.html`: one concise marketing sentence in the most relevant existing feature card — light touch, no new sections.\n5. **Wiki** `wiki/index.html`: add the detailed prose/table/diagram, then follow `.claude/rules/wiki-i18n.md` — add `zh` + `vi` entries for every new English string to `wiki/i18n-content.js`, then **bump the cache**: increment `CACHE_NAME` in `wiki/sw.js` and the `i18n-content.js?v=` query string in `wiki/index.html`. Skipping the cache bump means returning visitors never see the update.\n6. **Area READMEs / docs/**: update `server/README.md`, `client/README.md`, and the relevant `docs/*.md` per the mapping.\n7. **Diagrams**: when a state transition changes, edit every mermaid `stateDiagram-v2` block that models it (they are duplicated across README/VN/CN/KO, server/README, docs/DATABASE, wiki). Keep transition labels consistent.\n\n## Verify (do not skip)\n\n- **Coverage**: run `scripts/doc-coverage.sh <new-term> [...]` (e.g. the new env var / event type / identifier) and confirm every doc the mapping flags shows a HIT. The matrix is advisory — not every term belongs in every file — but a flagged doc reading `0` is a miss to fix.\n- **Tables**: markdown tables stay pipe-balanced (header column count == every row).\n- **Mermaid**: each edited block still parses (valid `source --> target: label`).\n- **i18n**: every new wiki English string resolves to both `zh` and `vi`; cache versions bumped.\n- **Format/tests**: run `npm run format` (or `prettier --check` on touched files); for any code touched, run the verification from `CLAUDE.md` (`npm run test:server` / `test:client` / `mcp:typecheck`).\n- State exactly which docs were updated and which were intentionally skipped (with reason), mirroring the repo's verification policy.\n\n## Tips\n\n- The fastest way to find where something already lives: `grep -n \"<existing-neighbor-term>\" <doc>` (e.g. grep an adjacent env var to find the env table). `references/doc-map.md` lists the stable anchors per file.\n- Parallelize translations + HTML across subagents when the change is large, but write the canonical English edit yourself first so the translations have a faithful source.\n- One language/area per subagent keeps edits reviewable and tables un-corrupted.","author":"@hoangsonww","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/hoangsonww/Claude-Code-Agent-Monitor/tree/master/.claude/skills/update-project-docs","license":"MIT","category":"document","lang":"en","tokens":1660,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/doc-map.md","size":6310,"sha256":"f47985f74bec23278569a09bc83146c4697e21dd534a6e766c04ff728dfd4859"},{"path":"scripts/doc-coverage.sh","size":1800,"sha256":"d652792fa5fc73977e636fac9391548983fe998adb1deca53fdb30d1aa8475ec"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":[]}}