Documentation Generation with Claude Code

It is three months since the last documentation update. The README mentions a command that was removed in the last sprint. The API docs reference a field that was renamed. New developers ask the same onboarding questions every week because the architecture document describes a system from two refactorings ago. Nobody updates the docs because updating docs is tedious and there is always a more pressing feature to build.

Claude Code solves this by generating documentation from the code itself — not from memory, not from notes, not from a wiki page that someone edited six months ago. And with hooks, you can keep the docs in sync with every file edit so they never drift again.

What You’ll Walk Away With

• A workflow for generating accurate documentation from your actual codebase
• Prompts for JSDoc/TSDoc, OpenAPI specs, and architecture documents
• Hook configurations that keep documentation in sync with code changes
• Headless mode patterns for automated documentation generation in CI

Generating Documentation from Code

The most reliable documentation is generated from the code it describes. Claude reads your source files and produces docs that reflect what the code actually does, not what someone remembers it doing.

JSDoc and TSDoc generation

Tip

Copy-paste prompt for inline documentation:

Read all files in src/services/ and add JSDoc comments to every
exported function, class, and type. For each one, include:

- A one-line summary of what it does
- @param for each parameter with type and description
- @returns describing the return value
- @throws for any errors the function can throw
- @example with a realistic usage example

Follow the JSDoc style already used in src/lib/database.ts.
Do not change any code logic -- only add documentation comments.

Claude reads the code, understands the types from TypeScript (or infers them from usage in JavaScript), and writes documentation that matches the actual behavior.

OpenAPI specification generation

Read all route handlers in src/routes/ and generate an
OpenAPI 3.0 specification. For each endpoint:

- HTTP method and path
- Request body schema (from the Zod validation schemas)
- Response schemas for success and error cases
- Authentication requirements
- Rate limiting headers
- Example request and response bodies

Save the spec to docs/openapi.yaml. Make it valid --
I'll run it through the OpenAPI validator after.

Architecture documentation

Analyze the entire codebase and generate an ARCHITECTURE.md
that covers:

1. System overview (one paragraph)
2. Tech stack with versions
3. Directory structure with one-line descriptions
4. Key data flows (request lifecycle, background job processing)
5. External dependencies and integrations
6. How authentication works end-to-end
7. How to run, test, and deploy

Reference specific file paths. Do not describe the system
abstractly -- point to the actual code. Keep it under 200 lines.

Keeping Docs in Sync with Hooks

The generated docs are only useful if they stay current. Hooks enforce this automatically.

Reminder hook for doc-touching changes

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'if echo \"$FILE_PATH\" | grep -q \"src/routes/\"; then echo \"NOTE: Route file changed. Update docs/openapi.yaml if the API contract changed.\"; fi'"
      }
    ]
  }
}

Auto-generate JSDoc after file edits

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'if echo \"$FILE_PATH\" | grep -qE \"\\.ts$|\\.tsx$\"; then npx tsc --noEmit \"$FILE_PATH\" 2>&1 | head -5; fi'"
      }
    ]
  }
}

Documentation freshness check in CI

# Run this in your CI pipeline to detect stale docs
claude -p "Compare the OpenAPI spec in docs/openapi.yaml with
the actual route handlers in src/routes/. Report any endpoints
that are documented but don't exist, or exist but aren't
documented. Also check for schema mismatches between the spec
and the Zod validation schemas." --output-format json

Documenting Specific Code Areas

README generation and maintenance

Tip

Copy-paste prompt for README generation:

Read the codebase and generate a README.md that a new developer
needs on day one. Include:

- What this project does (one paragraph, no marketing speak)
- Prerequisites (Node version, database, external services)
- Setup steps that actually work (run them to verify)
- How to run the dev server
- How to run tests
- How to deploy
- Environment variables with descriptions (don't include values)
- Project structure overview

Test every command you include by running it. If a command fails,
fix the README, not the command.

Changelog generation from git history

Read the git log between the last release tag and HEAD.
Generate a CHANGELOG entry following Keep a Changelog format:

### Added
### Changed
### Fixed
### Removed

Group by category. Write from the user's perspective, not the
developer's. "Fixed payment processing for multi-currency orders"
not "Fixed null check in payment.service.ts line 47".

Migration guides

We just released v3 of our API. Generate a migration guide
for developers upgrading from v2. Read both the v2 routes
(in src/routes/v2/) and v3 routes (in src/routes/v3/).

For each breaking change:
1. What changed
2. Why it changed
3. Before code (v2)
4. After code (v3)
5. Automated migration steps if applicable

Documentation for Different Audiences

Developer documentation (internal team)

Generate internal developer documentation for the payment
module. The audience is a new team member who will be modifying
this code next week. Include:

- How the module is structured and why
- Key design decisions and their rationale
- Common gotchas and "traps" in the code
- How to test changes locally
- What to watch out for in code review

API consumer documentation (external developers)

Generate API documentation for external developers who will
integrate with our API. They don't know our codebase. Include:

- Getting started guide (auth, first request, response format)
- Complete endpoint reference with request/response examples
- Error codes and what they mean
- Rate limiting details
- Webhook setup and payload formats
- SDK code examples in JavaScript, Python, and curl

Operational documentation (DevOps/SRE)

Generate a runbook for the operations team. They need to know:

- How to deploy (and rollback) the service
- Health check endpoints and what they verify
- Key metrics to monitor and their thresholds
- Common alerts and their resolution steps
- How to debug production issues
- Database maintenance procedures

Headless Documentation Generation

Automate documentation generation in CI so docs are always fresh:

# Generate docs on every merge to main
claude -p "Read the codebase and update these documentation files:
1. README.md - Verify all commands still work
2. docs/openapi.yaml - Sync with current route handlers
3. docs/ARCHITECTURE.md - Update if structure changed

For each file, only modify sections that are out of date.
Do not rewrite content that is still accurate.
Report what changed." --output-format json > docs-update-report.json

For PR-level documentation:

# Check if a PR needs documentation updates
claude -p "This PR changes these files:
$(git diff --name-only main...HEAD)

Check if any documentation needs updating:
- Does the README mention anything that changed?
- Do the API docs cover any modified endpoints?
- Should the ARCHITECTURE.md be updated?

Report what needs updating and make the changes." \
  --output-format json

Using Sub-agents for Documentation

For large documentation tasks, delegate to sub-agents so each area gets thorough attention without burning through your main context.

Use sub-agents to generate documentation for these three areas:

1. Document every exported function in src/lib/ with JSDoc
   comments. Read existing docs in the directory for style.

2. Generate a database schema document from the Prisma/Drizzle
   schema. Include table descriptions, relationships, and
   index rationale.

3. Create a testing guide that explains our test patterns,
   how to write new tests, and how to run specific test subsets.

Each sub-agent should read enough code to be accurate.
Compile the results into a single PR.

When This Breaks

Generated docs are too verbose. Claude tends to over-explain. Set constraints: “Keep function descriptions to one sentence. Only add @example for functions with non-obvious usage. Total JSDoc for this file should not exceed 30% of the code length.”

OpenAPI spec does not match actual behavior. Claude generated the spec from the route handler code but missed middleware that transforms requests or responses. Tell Claude: “Also read the middleware chain for each route. The rate limiter adds headers, the auth middleware rejects requests, and the error handler shapes error responses.”

Architecture docs become stale immediately. Generate them from code, not from memory. When you update the code, re-run the documentation generation. Better yet, use the CI pipeline to regenerate on every merge and fail the build if the generated output differs from what is checked in.

Documentation duplicates information from the code. Good documentation explains why, not what. The code already shows what it does. Tell Claude: “Do not describe what the code does line by line. Explain why this approach was chosen, what the tradeoffs are, and what a developer needs to know before modifying it.”

Nobody reads the generated docs. Put the docs where developers already look: JSDoc shows up in IDE tooltips, OpenAPI specs power Swagger UI, and the README is the first thing people see on GitHub. If your docs are in a separate wiki that nobody visits, move them closer to the code.

What’s Next

With documentation generated and hooks keeping it in sync, your codebase is ready for the backend-specific workflows that Claude Code handles particularly well.

API Development Build REST and GraphQL APIs with validation, auth, and error handling from the terminal

Codebase Analysis When your documentation is outdated, use Claude Code to understand what the code actually does