Documentation Management with Claude Code (Claude CLI)

Documentation is an asset that is harder to keep in sync with the code than it is to write. Claude Code (Claude CLI) offers ways to tackle that challenge, from context management with CLAUDE.md, to generating documentation grounded in the code, to automatic updates via Hooks. Here we organize the key points based on our review of English-language blogs.

This article summarizes, in English, the key points from official documentation and technical blogs in the English-speaking world, as reviewed by our company. The source for each technique is listed in the "References" section at the end of the article. Please be sure to check the original articles for details.

Two Memory Layers: the human-written CLAUDE.md and Claude's automatic memory

Claude Code's documentation foundation is divided into two layers by who writes it (Source 1).

For automatic memory, the opening of MEMORY.md (about 200 lines / 25KB) is read every time, while deeper content is split into topic-specific files such as debugging.md and api-conventions.md and referenced when needed. You can append with the # command and audit which files are currently loaded with /memory (Source 1).

/init is a starting point, not a finished product

Every source treats /init as the starting point for generating CLAUDE.md. /init analyzes "package files, existing documentation, configuration files, and code structure" to create an initial setup that fits your project. When existing files are present, it proposes improvements rather than overwriting them (Sources 1 and 3). Sid Bharath puts it this way: "/init looks at the whole project and creates the Claude.md. This becomes the project's memory" (Source 5).

Keep CLAUDE.md short, specific, and pruned

The official documentation provides clear "include / don't include" criteria (Source 2).

• Include: Bash commands Claude cannot guess, code styles that differ from the norm, and testing procedures
• Don't include: detailed API documentation (→ "link to the documentation") and file-by-file explanations

The deciding criterion is "If I delete this line, will Claude make a mistake? If not, remove it." Split details into topic-specific files or .claude/rules/*.md (specifying target paths with YAML paths:), and avoid duplication with @path imports such as @README and @package.json (Sources 1 and 2). In a hierarchical layout (global / project / frontend / backend), "more specific files override more general ones" (Source 5).

Generate documentation from "code," not from "memory"

The most important principle is to derive documentation from the code. The Developer Toolkit guide gives concrete prompts like the following (Source 6).

Read all files in src/services/ and add JSDoc comments to every exported function, class, and type.

• JSDoc: inferred and added from the actual TypeScript types (not from stale memory)
• OpenAPI: extract requests/responses from Zod schemas and save to docs/openapi.yaml
• ARCHITECTURE.md: tie it to reality with "Don't explain abstractly. Reference concrete file paths."
• README: "Run and verify every command you list. If one fails, fix the README, not the command."

Keep sync "deterministic" with Hooks and CI

The biggest cause of documentation going stale is that updates depend on the good intentions of humans (or the model). Automate this with Hooks and CI.

• PostToolUse Hook: automatically prompt an OpenAPI spec update when a route file changes (.claude/settings.json)
• CI freshness check: "compare docs/openapi.yaml against the actual route handlers" to detect stale endpoints
• Update right after a feature is completed: have the documentation updated while the context of the work is still fresh (Sources 5 and 6)

Hooks are preferred because, unlike the advisory CLAUDE.md, they always fire.

Documentation accelerates onboarding and investigation

Well-maintained documentation translates directly into team productivity. Inside Anthropic, the security team has Claude "ingest multiple documentation sources to create Markdown runbooks," and the data team simply hands over the codebase to have it "read the CLAUDE.md, identify dependencies, and explain how the data pipelines connect." On the inference team, ingesting model-specific documentation reportedly means "a Google search that usually takes an hour is done in 10–20 minutes" (Source 4).

Real Config & Usage Examples

Here is how the principles above translate into actual files and commands. Everything below uses only features that ship with Claude Code out of the box.

First, generate a CLAUDE.md draft with /init, then hand-edit in your documentation policy. /init analyzes your code structure and existing docs to create an initial version, but the rule to generate documentation from the code is something you should spell out yourself.

# Run at the project root to generate a CLAUDE.md draft
claude
> /init

Add a documentation policy to the generated CLAUDE.md. The more concretely you state "where, from what, and how to generate," the more stable Claude's output becomes.

# CLAUDE.md (excerpt)
## Documentation policy
- Generate the API spec from Zod schemas and save it to `docs/openapi.yaml`
- Add JSDoc to public functions and types from the actual TypeScript types (not from memory)
- Run and verify the commands in the README; if one fails, fix the README
- Update documentation right after any work that changes code

As a deterministic safeguard against staleness, use a PostToolUse hook in .claude/settings.json to run the doc-generation command automatically after file edits. Unlike the advisory CLAUDE.md, hooks always fire.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run docs:openapi" }
        ]
      }
    ]
  }
}

Turn repeated generation work into a custom slash command for consistency. Save the prompt to .claude/commands/apidoc.md and you can invoke it with arguments like /apidoc src/routes via $ARGUMENTS.

# .claude/commands/apidoc.md
Read the route handlers under $ARGUMENTS, extract the request/response
shapes from the Zod schemas, and output them as OpenAPI 3.1 to `docs/openapi.yaml`.
Add JSDoc comments to exported functions and types from the actual types.