Using Claude for technical documentation and code comments

Documentation is the most tolerated technical debt in existence: everyone knows it's missing, nobody finds the time to write it, and the cost is paid with every new developer who joins the project. Using Claude for technical documentation is one of the cases where AI gives the most in return for the effort, because the source material, the code, already exists. In this article we describe how we do it, with the prompts that work and the limits to keep in mind.

Why documentation is the ideal task for an AI model

Writing documentation requires two skills: reading code and explaining in clear language. These are exactly the strengths of a model like Claude. Unlike generating new code, where the AI can head down wrong paths, here the scope is defined: the code is the source, the task is to describe it.

The formats where we get the best results:

• project READMEs: structure, requirements, installation, main commands;
• comments and docstrings: descriptions of functions and classes, parameters, return values, edge cases;
• API documentation: endpoints, request and response formats, error codes;
• onboarding guides: how the repository is organized, where things live, how to start the local environment;
• explanations of inherited code: when we take over a project written by others, having the main modules explained to us shortens the settling-in phase considerably.

The prompts that work (and why)

The difference between useful documentation and generic prose lies in the instructions. Three rules we always apply.

Define the reader. "Document this function" produces a paraphrase of the code. "Document this function for a developer who needs to integrate it without reading its implementation" produces what's needed: what it does, what it expects, what it returns, when it fails.

Impose a format. Ask for the exact structure: README sections, the language's docstring standard, a table for parameters. A consistent format makes documentation browsable, and lets you regenerate it without upending everything at each change.

Ask it to document the why, not just the what. The comment "increments the counter" above a line that increments a counter is noise. Explicitly ask it to flag non-obvious decisions: why that check exists, what would happen if that condition were removed. And ask the model to state when an intention can't be deduced from the code, instead of inventing it: that's where hallucinations otherwise arise.

Claude Code: documenting the repository, not the snippet

The step change comes when the model sees the whole project instead of a single file pasted into chat. Claude Code, Anthropic's agentic coding tool, works directly on the repository: you use it from the terminal, as a desktop app for Mac and Windows, from the browser at claude.ai/code or inside IDEs with the VS Code and JetBrains extensions.

For documentation this changes the outcome: it can read the real dependencies between modules, check how a function is used across the rest of the code, and update documentation files directly in the project. In our workflows we use it to generate the first draft of READMEs and to keep comments aligned after extensive refactoring work, with a developer's review before the commit. The current model family covers different needs: the most capable models for analyzing complex code, the lighter ones for repetitive tasks across large volumes of files.

The limits to know before trusting it

Enthusiasm should be calibrated against three concrete limits.

First: the model documents what the code does, not what it should do. If there's a bug, the generated documentation will describe the wrong behavior with a confident tone. Human review remains a step in the workflow, not an optional extra.

Second: business context isn't in the code. The reason a rule calculates VAT a certain way or excludes certain customers lives in the head of whoever made the decision. That knowledge has to be added by hand, and it's the part of the documentation worth the most.

Third: generated documentation ages just like hand-written documentation. Without a process that updates it when the code changes, after six months it lies. The solution is organizational: regenerating and reviewing the documentation is part of closing out every significant piece of work, not an annual project.

A partner that documents the code (and writes it)

We build custom software with a simple principle: the client must receive understandable, documented code, not a black box. We use AI where it speeds up the work and human review where judgment is needed. If you have a project to build, or inherited software nobody dares touch anymore, book a free call: we'll analyze it and tell you how to get it back in order.