Verified against Claude Code · 2026-07-23
Generate docs that match what the code actually does, not what it should do
A documentation-generation prompt that derives every claim from real exported signatures, behavior, and tests rather than from the intent behind the code, and forces an explicit flag on any doc statement the reviewer cannot verify against the code itself.
The prompt
Ready to copy — highlighted parts are example details you can swap.
You are writing documentation derived from what this code actually does, verified against its real signatures, behavior, and tests — not from what a comment or a variable name suggests it is supposed to do. A docstring or a variable name is a claim about intent, not proof of behavior, and this documentation should not repeat an intent claim as fact without checking it against the implementation. SCOPE The public API of the lib/prompts/ module: getPromptCategory, searchPrompts, and getPromptsByTag. EXISTING DOCUMENTATION TO RECONCILE AGAINST The current README says searchPrompts returns results ranked by relevance; there is no test confirming ranking behavior, only that it filters by matching tags. PUBLIC API SURFACE TO DOCUMENT getPromptCategory(slug), searchPrompts(query, options), getPromptsByTag(tag) — all exported from lib/prompts/index.ts. AUDIENCE Other engineers on this team integrating the prompt library into a new page — assume TypeScript fluency, no assumption of familiarity with this specific module. FORMAT CONVENTION TO FOLLOW Match the existing style in README.md: H2 per function, a fenced TypeScript signature block, then Parameters, Returns, Example in that order. PROCESS 1. For every entry point in getPromptCategory(slug), searchPrompts(query, options), getPromptsByTag(tag) — all exported from lib/prompts/index.ts., read its actual implementation, not just its name or an existing comment above it, and confirm parameter types, return shape, and error behavior against the real code and, where they exist, its tests — a test that exercises a specific edge case is stronger evidence of real behavior than a docstring making the same claim, since the test is checked by CI and the docstring is not. 2. If The current README says searchPrompts returns results ranked by relevance; there is no test confirming ranking behavior, only that it filters by matching tags. already documents this surface and the documentation matches what the code actually does, keep it, but verify it rather than assuming it is still accurate — code drifts from its own documentation constantly, and an existing doc's presence is not evidence of its current correctness. 3. If the existing documentation and the actual code disagree, flag the discrepancy explicitly rather than silently picking one side to write down as though there was never a conflict — state both what the doc claims and what the code actually does, so a human can decide whether the doc or the code is the one that is wrong. 4. Distinguish the public API surface, meant for external or cross-package consumption, from internal implementation detail; document the former in full, and only mention the latter where it materially affects how the public surface should be used. CONSTRAINTS - Every parameter documented must state its real type and whether it is actually required at runtime, not just what the type signature promises, since a type can promise a value is present while the actual runtime check treats it as optional with a fallback. - Do not describe a function's purpose using only the language already in its name or an existing comment; state what it verifiably does, and if that happens to match the name, that is confirmation, not a reason to skip the verification step. - Calibrate depth and vocabulary to Other engineers on this team integrating the prompt library into a new page — assume TypeScript fluency, no assumption of familiarity with this specific module. — an internal engineering audience needs different detail than an external package consumer who will never see this codebase's internals. - Follow Match the existing style in README.md: H2 per function, a fenced TypeScript signature block, then Parameters, Returns, Example in that order. exactly for headers, code-block style, and section order, rather than defaulting to a generic documentation template that does not match how the rest of this project's docs already read. OUTPUT The documentation in full, following the required format, with any existing-doc-versus-code discrepancy called out in a separate short section at the end rather than silently resolved.
Customize
Optional — swap in your own details for the highlighted parts above.
Why this works
The default failure mode of AI-generated documentation is not fabrication out of nowhere, it is fluent paraphrase of the code's own names and comments presented with the same confidence as verified fact — a function named validateEmail with a docstring claiming it checks format gets documented as doing exactly that, even when the actual implementation only checks for the presence of an @ character and nothing else, because the model is restating intent-bearing signals rather than tracing the real logic. Explicitly ranking a passing test above a docstring as evidence forces a real hierarchy of trust the model would not otherwise apply on its own, since a docstring and a test read as equally authoritative text unless something specifically tells the model that only one of them is actually checked by anything — a test asserting a specific edge case's output is empirical, in the narrow sense that CI actually runs it, while a comment claiming the same thing is unverified prose that could have gone stale the moment the function's logic changed underneath it. Requiring an explicit discrepancy flag when existing documentation disagrees with the actual code, rather than silently resolving the conflict one way or the other, matters because a documentation-generation pass that quietly overwrites a stale doc with new, correct text erases the very evidence a human would need to notice that the code's behavior has drifted from what it was designed to do — sometimes the doc is the one that is stale, but sometimes the doc was right and a later change to the code introduced an unintentional regression, and only a human with context on the original intent can actually tell those two cases apart. Distinguishing public surface from internal detail matters because documenting everything at equal depth wastes the reader's attention on implementation specifics they never needed and, worse, creates a maintenance burden where a purely internal refactor now also requires a documentation update for something nobody outside this module was ever meant to depend on. Calibrating to the audience variable explicitly matters for the same reason it matters in an onboarding walkthrough: Claude Code has no independent way to know who will read this beyond what the prompt tells it, so the audience field is the only channel through which the level of assumed background actually gets set correctly rather than defaulting to whatever generic level a documentation template happens to imply.
Verified against
Claude Code Sonnet 4.6 · 2026-07-23
Changelog
- 2026-07-23 — Initial publish, verified against Claude Code documentation generation (Sonnet 4.6).
Building this for real?
This is a free starting point. If you'd rather have custom software built and running for your business, that's Scult's day job.
EXPLORE CUSTOM SOFTWARE
