CLAUDE.md

A protocol for generating and maintaining project documentation from the code. Drop this at a repository root and Claude will use it to write or refresh the docs that a project needs and keep them in sync as the code changes.

Documentation rots because it lives apart from the code that defines it. This protocol treats docs as a function of the codebase: derive them from what is actually there, regenerate the parts that drifted, and skip the parts that maintain themselves.

When to run this

• A service or library has no README, or one that no longer matches the code.
• A refactor changed public surface (exports, routes, CLI flags, config keys) and the docs still describe the old shape.
• A new contributor could not get the project running from the existing docs alone.
• The architecture changed and no written record explains the new layout.

1. Analyze project structure

Before writing anything, read the project.

• Detect the project type from manifests: package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gemfile.
• Identify the entry points: main, bin, server bootstrap, exported package index.
• Map the public surface: exported functions and classes, HTTP routes, CLI commands, environment variables, config keys.
• Locate existing docs: README, docs/, CONTRIBUTING, inline comments, doc-comment blocks.
• Note what runs the project: install command, build command, test command, start command.

Do not document what you have not read. A guessed API reference is worse than none.

2. Generate or update the README

A README answers four questions in order: what is this, how do I run it, how do I use it, where do I go next.

• One-paragraph description of what the project does, derived from the code and manifest, not invented.
• Install and setup: the actual commands, with required runtime versions and environment variables.
• Usage: the shortest path to a working result. A code block that runs.
• Pointers: links to API reference, architecture notes, and contributing docs if they exist.

If a README already exists, update the sections that drifted and leave the rest. Do not rewrite a hand-tuned introduction to insert generated prose.

3. Generate the API reference

For each public export, route, or command:

• Name and signature.
• What it does, in one sentence.
• Parameters with types and whether they are required.
• Return value or response shape.
• One usage example that reflects real call sites in the codebase.
• Known errors or edge cases the code actually handles.

Document the public surface. Skip private helpers unless a public function's contract depends on them.

4. Write architecture notes

When the project has more than one moving part, record how the parts relate.

• A short overview of the major components and their responsibilities.
• The data flow: where a request or input enters, what transforms it, where it exits.
• Component relationships as a plain list or an ASCII or Mermaid diagram in markdown.
• Design decisions that are not obvious from the code, and the constraint that drove each one.

Architecture notes are the docs most likely to be missing and most expensive to reconstruct later. Prioritize them for systems with non-obvious structure.

5. Write setup docs

If install is more than one command, give it its own section or file.

• Prerequisites: runtime versions, system dependencies, accounts or tokens needed.
• Step-by-step from clone to running, each step a command.
• Environment variables in a table: name, what it controls, whether required, example value (never a real secret).
• How to verify the setup worked.

6. Keep docs in sync with code

This protocol is meant to be re-run, not run once.

• On re-run, diff the current code surface against what the docs describe.
• Regenerate the sections whose source changed: a renamed export, a new route, a removed flag, a changed config key.
• Leave untouched the sections whose source did not change.
• Flag docs that reference code that no longer exists.

The value is in the second run and every run after. Docs that regenerate from the code do not rot.

What to document vs what to skip

Document:

• Public API: exports, routes, CLI commands, config keys, environment variables.
• How to install, run, test, and build.
• Architecture and data flow for any non-trivial system.
• Non-obvious design decisions and the constraints behind them.

Skip:

• Private helpers and internal-only functions.
• Self-evident code that a reader can understand faster than a comment.
• Generated files, vendored dependencies, lockfiles.
• Prose that restates the function name in a full sentence.

The test for a doc: would a new contributor be slower without it? If not, the doc is noise.

On committing

Generating docs and committing them are separate steps. Write the files, show a summary of what changed, and let the human decide when to commit. Do not auto-commit unless explicitly asked.

This protocol generates and maintains docs. To assess whether a project's existing documentation and onboarding create friction, see the companion audit: dx-audit-skills.

License: MIT. Use it, fork it, merge it into your own.