Keep Docs in Sync With Code: A Prompt That Catches Drift

The README says the function takes three arguments. Someone added a fourth six months ago. Nobody updated the docs, because nothing forced them to. That's documentation drift, and it's the default state of every codebase that ships faster than it documents. A prompt to keep docs in sync with code re-couples the two: feed it the diff and the docs, and it points at the exact sentences the change made false.

This space is crowded with tools and thin on method. DeepDocs' roundup of documentation tools is product marketing that never exposes the drift-detection logic (deepdocs.dev). Document360's drift article quotes a scary stat ("60% of documentation becomes outdated within six months") and then pivots to booking a demo, with no copyable workflow (document360.com). What nobody hands you is the prompt that does the diff-to-docs check yourself.

So here it is, structured so the output is a list of specific fixes, not a rewrite of the whole page.

What you can do with a docs-sync prompt

• Catch the doc sections a PR just made wrong, before merge
• Flag renamed parameters, removed endpoints, and changed defaults
• Get a proposed edit per drifted section, not a vague "update this"
• Check a README, API reference, or runbook against a diff
• Run it as a review-gate step so stale docs block the PR
• Spot example code in docs that no longer compiles against the new API
• Skip the sections the change didn't touch, so the noise stays low

The signal here is the diff. Most drift tools read docs in isolation and guess at staleness from a "last updated" date. A prompt that gets the actual change knows precisely what's now false, which is a different and much sharper job.

Why "read the docs and check them" doesn't work

Hand a model a README and ask "is this accurate?" and it'll either rubber-stamp it or rewrite the whole thing in its own voice. It has no way to know what changed. The fix is to give it the change.

Pass the diff alongside the docs and the question becomes answerable: "this diff renamed timeout to timeout_ms and the docs reference timeout in two places, so both are now wrong." That's a finding you can act on. The diff is the ground truth that turns vague review into a targeted one.

Anatomy of the prompt

Role, the two inputs, and a contract that forces a per-section verdict. The verdict structure is what keeps it from rewriting things that didn't drift.

Role:    You are a technical reviewer checking docs against a code change.
Inputs:  {{code_diff}}, {{current_docs}}, {{doc_scope}}
Task:    Find every doc section the diff made inaccurate; propose fixes.

Output contract:
1. Drift findings — a table: Doc location | What's now wrong | Evidence from diff
2. Severity — Breaking (will mislead) | Minor (cosmetic) per finding
3. Proposed edit — the corrected text for each finding
4. New docs needed — anything the diff added that has no docs yet
5. Clean — sections checked and confirmed still accurate

The "clean" section earns its keep. Without it, the model reports drift everywhere to look useful. Forcing it to list what it checked and found fine keeps the findings honest. Claude follows this verdict structure tightly; GPT-4o occasionally needs "do not propose edits to sections not affected by the diff" pinned to the last line, or it'll helpfully rewrite your whole intro.

Step-by-step usage

1. Get the diff

The output of git diff for the change, or the PR diff. Don't paste the whole file. The diff alone tells the model what moved.

2. Scope the docs

{{doc_scope}} keeps it focused. Point it at the README, the API reference, or the relevant runbook, not the entire docs folder. A wide scope buries the real findings.

3. Run it

Read the breaking findings first. A renamed public parameter that the docs still reference will mislead every reader; a cosmetic typo can wait.

4. Apply the proposed edits

The model gives you corrected text per finding. Review each against the diff before accepting. It's usually right on the mechanical changes (renames, signature changes) and worth a second look on anything that needs judgment about intent.

5. Wire it into review

The real win is running this on every PR, not once a quarter. Drop it into your review checklist or a CI step so docs drift gets caught at the moment it's created, while the author still remembers why they changed the code.

Prompt-craft patterns that keep it honest

Force the "clean" list. The instinct is to ask only for problems. Ask also for what the model checked and found accurate. This single addition turns an over-eager rewriter into a reviewer, because it has to account for every section, not just hunt for things to flag.

List every doc section you checked. For each, mark it
DRIFTED (with evidence from the diff) or CLEAN. Do not
edit sections marked CLEAN.

Tie evidence to the diff, not the docs. Each drift finding should quote the specific diff hunk that caused it. "The docs say X, but the diff at line 42 changed it to Y." A finding that can't point at the diff is a guess, and guesses about doc accuracy erode trust fast.

Separate "wrong" from "missing." Drifted docs and undocumented additions are different fixes. A new optional parameter with no docs isn't drift, it's a gap. Splitting them stops the model from conflating "update this sentence" with "write a new section."

That's the opinionated part: most docs tooling treats every change as a rewrite trigger. It shouldn't. The job is surgical — touch only what the diff broke.

Variables you'll set

Getting started

1. Grab the PR diff for the change you're reviewing.
2. Paste the relevant docs as {{current_docs}} and set a tight {{doc_scope}}.
3. Run the prompt in Claude or ChatGPT, diff first.
4. Read the breaking findings, then apply the proposed edits after a review.
5. Check the "new docs needed" section for additions that slipped through.
6. Add the prompt to your PR review checklist so it runs every time.
7. Re-run after edits to confirm the docs and diff finally agree.

If you'd rather wire this into the pipeline than copy-paste per PR, the Docs-Code Sync Harness ships the diff-first contract and the clean/drifted verdict as an agent pack. The Confluence Documentation pack handles the case where your docs live in a wiki instead of the repo.

Drift detection pairs with the rest of your PR automation. Run it alongside the AI PR review prompt so the same diff gets checked for both code quality and doc accuracy, and the release notes prompt turns the changes into customer-facing notes once the internal docs are fixed. One diff, three checks, no stale README left behind.