One Claude Code Tip a Day: Update the README from Reality

A stale README is one of the easiest ways to waste a Claude Code session. You ask Claude to add a small feature, it follows the setup instructions, the command fails, and now the session is debugging a documentation lie instead of the actual task. Worse, if you tell Claude to “update the README” at the end, it may write the story it wishes were true: tidy commands, missing environment variables, and a happy path nobody has just verified.

Today's habit is to make README work evidence-driven. Treat documentation changes like code changes: Claude Code should read the repo, inspect the commands, identify the gap between the README and reality, patch only the proven instructions, and review the diff before you accept it.

This post is part of the “One Claude Code Tip a Day” series — a daily guide to using Claude Code more effectively.

The field problem

Imagine a small SaaS repo where onboarding says: install dependencies, copy `.env.example`, run migrations, then start the dev server. A teammate opens a PR that adds a background worker and a new Redis variable, but the README still says only Postgres is required. New developers follow the docs and hit a worker crash. A shallow prompt would be: “Update the README for Redis.” That may add a sentence, but it will not prove the rest of the path still works.

Start with a stricter Claude Code prompt:

Read README.md, package.json, docker-compose.yml, .env.example, and the worker entry point. Do not edit yet. Tell me which setup instructions are contradicted by the current repo. For each claim, cite the file and line or command output that proves it.

This changes the job from copywriting to investigation. Claude Code now has to compare documentation against source files, not invent a polished explanation.

Make Claude verify before writing

The best README updates begin with a reality pass. Ask Claude to run safe checks and inspect the project shape:

Use shell commands only for read-only verification first: pwd, git status --short, package scripts, test commands, and any obvious env examples. If a command would mutate data, explain it instead of running it. Then propose the smallest README patch.

In a Node app, that might mean Claude lists package scripts, reads `docker-compose.yml` to confirm Redis exists, checks `.env.example` for `REDIS_URL`, and inspects the worker startup command. If the README says `npm run dev` but the project now requires `npm run dev:all`, the patch should come from that evidence.

Do not let Claude jump straight to prose. A useful intermediate answer looks like a mini bug report: “README says only Postgres is required; docker-compose defines Postgres and Redis; worker.ts reads REDIS_URL; .env.example is missing REDIS_URL.”

Patch the README narrowly

Once the mismatch is clear, give Claude a small edit contract:

Patch README.md and .env.example only. Add Redis to prerequisites, add REDIS_URL to the environment section, replace the dev command with the script that actually starts web plus worker, and add a short troubleshooting note for connection refused. Do not rewrite the whole README.

That last sentence matters. Claude Code is often tempted to “improve” docs globally: new headings, renamed sections, prettier wording, deleted caveats. Those changes are risky because reviewers cannot tell which lines came from verified facts and which lines came from style preference. For README maintenance, boring diffs are good diffs.

If the project lacks a combined script, ask Claude to say so instead of documenting one:

If there is no single command that starts both processes, document the two-terminal workflow exactly as it exists today. List a follow-up task separately for adding a combined script.

That keeps documentation honest. A README that admits “run these two commands” is better than a README that promises a nonexistent shortcut.

Inspect the documentation diff

After Claude edits, do not accept the patch because the prose sounds right. Ask for a documentation diff review:

Run git diff -- README.md .env.example. For every changed block, label it as verified from file evidence, verified from command output, or unverified. If anything is unverified, either remove it or show the proof.

This is the second-pass correction that turns Claude Code from a writer into a maintainer. It may catch that the README says Redis defaults to port 6379, but docker-compose maps a different local port. It may notice that `.env.example` was updated but the “copy env” step still references an old filename. It may also flag a sentence like “tests require Docker” when no test command was actually run.

For a stronger finish, ask Claude to walk the onboarding path as far as it safely can:

From a clean working tree assumption, walk the README setup steps in order. Do not run destructive commands. Tell me the first step a new developer would still fail on, or say the path is consistent with the files you inspected.

This does not guarantee perfect docs, but it catches the embarrassing class of README bugs: instructions that contradict the repository in front of you.

Failure modes

The first failure mode is aspirational documentation. Claude writes how the project should work after a future cleanup, not how it works now. Counter it with: “Document current reality. Put improvements in a follow-up list.”

The second failure mode is over-broad rewriting. A README patch that changes every heading is hard to review. Counter it with path limits and a diff review.

The third failure mode is unsafe verification. Setup commands can create databases, run migrations, or call external services. Tell Claude which commands are allowed, and require an explanation before anything destructive.

Rule of thumb

When updating docs with Claude Code, never ask for “better README wording” first. Ask for a mismatch report between README claims and repository evidence. Then patch the smallest set of lines, verify the commands or files behind those lines, and review the diff like production code. Good README updates are bug fixes for developer expectations.