Stop Writing Docs. Start Keeping Them Alive.

#claude #documentation #ai #automation

Documentation lies. Not on purpose — it just stops being true.

You rename a function. You add a required parameter. You retire that env var that never should have existed. And somewhere in your docs, the old name is still there. The old signature. The old example that will throw an error if anyone actually runs it.

It will stay there until someone files a bug. Or a new hire wastes a morning. Or a customer's integration breaks.

The problem isn't that developers don't care about docs. It's that keeping them accurate is invisible work — no CI check, no compiler error, no test failure. Docs rot in silence.

What I built

living-docs is a Claude Code plugin that fixes the feedback loop.

After you make code changes, run /living-docs. It:

Diffs your code since the last commit
Extracts semantic markers — function names, parameters, env vars, CLI flags, config keys, API endpoints
Finds every doc file that references them
Compares what the doc says vs what the code now does
Shows you exactly what's wrong, with a proposed fix
Applies surgical edits to only the stale lines

Here's what the output looks like after renaming an env var and adding a parameter to a function:

Scanning docs against changes since HEAD~1...

  STALE  docs/api.md            2 issues
  STALE  docs/configuration.md  1 issue
  STALE  src/auth.ts (JSDoc)    1 issue
  OK     README.md

─────────────────────────────────────────────────────────
docs/api.md · line 112
─────────────────────────────────────────────────────────
TYPE     outdated signature
CHANGED  authenticate(token) → authenticate(token, options?)

WAS:  authenticate(token) - Validates a JWT
NOW:  authenticate(token, options?)
      options.strict — Reject tokens missing exp. Default: false.
      options.audience — Validate aud claim. Default: not checked.

─────────────────────────────────────────────────────────
docs/configuration.md · line 58
─────────────────────────────────────────────────────────
TYPE     renamed env var
CHANGED  AUTH_SECRET → AUTH_SIGNING_KEY

Apply all 4 fixes? [Y/n/select]

What it catches

Code change	What gets flagged
Function signature changed	Every doc showing the old signature
Parameter added or removed	README examples, API references, docstrings
Env var renamed	Every mention of the old name
CLI flag renamed	Help text, quickstart guides
API endpoint moved	OpenAPI specs, integration guides
New public export	Missing documentation

Supported formats: Markdown, JSDoc/TSDoc, Python docstrings, Go doc comments, OpenAPI/Swagger, reStructuredText.

The important detail

It doesn't rewrite your docs. It makes targeted edits to exactly the lines that are wrong.

Your formatting, your wording, your structure — all untouched. If you say no at the confirmation prompt, nothing changes.

Install

curl -fsSL https://raw.githubusercontent.com/phlx0/living-docs/main/scripts/install.sh | sh

Add to ~/.claude/settings.json:

{ "plugins": ["~/.claude/plugins/living-docs"] }

Then run /living-docs in Claude Code.

CI integration

Block PRs with stale docs:

- name: Check for stale docs
  run: |
    claude --print "/living-docs --dry-run --since origin/main" \
      | grep -q "All docs up to date" || exit 1

DEV Community