Docs As Code — Claude Code Guide

Docs-as-code keeps documentation in the change set

Docs-as-code means technical documentation lives in the repository, appears in the diff, receives review, and is checked with code. It describes concrete behavior, commands, or procedures rather than living as an unrelated note.

Code changes and stale instructions form incomplete delivery. Update documentation in the same PR when its source of truth changes.

The source of truth is more important than memory

• Compare API descriptions with controllers, DTOs, and tests.
• Verify commands through package scripts, Gradle tasks, or an actual run.
• Compare environment values in README, .env.example, Compose, and application configuration.
• Support runbooks with logs, alerts, and an actual smoke scenario.
• Mark unverified claims as Unknown rather than stating them confidently.

Claude as a documentation checker

1. Pass one document and the files it references.
2. Ask for mismatches in commands, routes, environment names, or examples.
3. Require a file, line, or test reference for every finding.
4. Request a separate list of unverified claims.
5. Prepare a small diff and verify it with a practical run.

Input: README.md and the referenced setup files
Check: commands, ports, environment names, API routes, and examples
Return: mismatches with evidence and minimal edit suggestions
Do not invent endpoints, variables, or recovery commands
Do not edit files before the report is reviewed

Generated text is not current documentation

Generation can create readable prose, but delivery documentation must be verifiable. What matters is whether a command runs, a route matches code, and an example matches the actual DTO.

If an API returns approvalRequired: true with PENDING_APPROVAL, the runbook should explain manual confirmation rather than recommending blind retries.

Documentation gate before merge

• Setup changes update README and onboarding.
• Route or response changes update API documentation.
• Command and request examples are checked practically.
• Documentation contains no secrets or private values.
• Business trade-offs and ADR conclusions receive human review.