Last updated 13 October 2026
Use Claude Code to write project docs
The persistent burden of technical documentation
You finish a complex feature and the last thing you want to do is write the README. Your code works but nobody else will understand the architectural decisions you made at late hours. You can spend an hour typing out descriptions or you can let an agent do the heavy lifting. Claude Code can look at your actual implementation to ensure the documentation matches reality. It does not just guess based on file names but reads the logic to explain the how and why of your functions.
Documentation debt accumulates faster than technical debt. When you skip writing notes for a new module, you create a barrier for the next developer who touches that code. Even if that developer is you in three months, you will struggle to remember why you chose a specific library or how the data flows through your hooks. Using a command line agent allows you to generate these notes while the context is still fresh in your mind. You can turn a vague understanding of a codebase into a structured guide with a few prompts.
Setting the ground rules with project instructions
Start by creating a CLAUDE.md file in your repository root. This file tells the agent how to behave and what documentation standards you follow. You might specify that you prefer a concise style or that every public function needs an example. When Claude Code starts a session, it reads this file first to understand your project context. It ensures the documentation it writes fits the existing patterns of your codebase and follows your specific formatting rules.
You can also use a CLAUDE.md file in a subdirectory to provide localized instructions for that part of the tree. This allows you to have different documentation requirements for your frontend and backend modules. For example, your frontend folder might require documentation for component props while your backend folder focuses on API endpoints. The agent will adapt its writing style and priorities based on which directory it is currently analyzing. This hierarchical control keeps your documentation consistent across a large project.
Scanning the source code for truth
Run the command claude in your terminal to start an interactive session. You can ask the agent to scan your project using the Glob and Read tools to find all relevant source files. It will build a map of your logic and dependencies to ensure accuracy. This preparation prevents the agent from hallucinating features that do not exist. It sees the actual types, imports, and exported members of your modules before it starts writing any text.
If your project is large, the agent might use the Grep tool to search for specific keywords or patterns across the entire repository. This is useful for finding every instance of a particular error code or configuration flag that needs to be documented. By reading the actual implementation, the agent can provide concrete examples of how to use your code. It does not rely on outdated comments or your own potentially flawed memory of how a function works. It provides a grounded summary of the code as it exists on your disk.
Generating and editing files on the fly
Ask the agent to write a README.md file using the Write tool. You can provide a specific outline or let it suggest one based on your code structure. If the file already exists, the agent can use the Edit tool to update specific sections without overwriting your manual notes. It can extract installation steps from your package manager files and usage examples from your test suite. This keeps the documentation grounded in the actual execution of the code.
You have control over how the agent modifies your files through permission modes. By default, the agent will ask for your approval before writing to a file. You can press Shift+Tab to cycle through modes like acceptEdits if you trust the agent to make changes quickly. If you want to see a plan before any tools run, you can switch to plan mode. This allows you to review the proposed documentation structure before any files are actually changed on your system. You can even use the /permissions command to set granular rules for the Write and Edit tools in your settings.json file.
Refining content through session management
A session has a context window that fills with the conversation and the files the agent has read. If the context window gets too full of file contents, use the /compact command to summarize the session so far and free up space. This keeps the agent focused on the high level goals of your documentation task. It prevents the session from becoming sluggish or losing track of the original requirements you set at the start. You can check your current spend and token usage at any time with the /cost and /usage commands.
Use the /review command to have the agent check its own work for clarity and accuracy. It can verify that the generated documentation accurately reflects the code it just read. If you need to revert to a previous state of the conversation, press Escape twice to see earlier messages and go back. This gives you fine control over the drafting process as you refine the technical language. If you find a bug in how the agent is interpreting your files, you can use the /bug command to report it.
Managing parallel documentation tasks
When you manage documentation across many microservices or modules, switching contexts in a single terminal is slow. You can use adhdTerminal to run many Claude Code sessions side by side. Each tile on your wall can focus on a different repository or a different part of a large monorepo. This allows you to keep one session open for the API docs while another tile generates the user guide for a client library. You can see which documentation tasks are still working and which are waiting for your feedback at a glance.
The wall of tiles in adhdTerminal shows the last exchanges of each conversation and can display headlines that your project publishes. If you need to walk away from your desk, the free iPhone app mirrors your wall over an encrypted link. You can review a generated paragraph on your phone and send a quick prompt to refine the wording. This mobility ensures that you can keep the documentation process moving even when you are not sitting at your computer. The app saves your sessions so you can resume exactly where you left off after a restart.
Automating workflows with hooks and agents
You can automate parts of the documentation process using hook events. For example, you can set up logic for the PostToolUse event to trigger a documentation check after every code change. This ensures that your README never falls behind your implementation during a long coding session. These hooks are configured in your .claude/settings.json file and allow you to build a custom workflow that fits your specific development habits. You can also define custom slash commands in the .claude/commands folder to run common documentation tasks with a single word.
If you have a very complex documentation requirement, you can create a subagent. Subagents are markdown files in the .claude/agents folder that define specialized roles for the agent. You might create an agent specifically for writing API references or another for generating tutorials. You can call these agents from within your main session using the /agents command. This modular approach allows you to build a suite of specialized writing tools that understand the specific nuances of your technical stack.
Persistence and session recovery
Finally, save your progress and exit the session with Ctrl+C. If you want to continue the same documentation task later, run claude --continue in the same folder. This carries on the most recent session in that folder with all the previous context and conversation history intact. This persistence makes it easy to handle large documentation projects over several days without repeating yourself. The agent remembers the files it already read and the instructions you previously gave it.
If you have several ongoing documentation drafts, the command claude --resume offers a list of earlier sessions to pick from. You can jump back into a specific drafting session from last week to finish a technical guide. If you only need a quick answer or a single paragraph, use claude -p to run one prompt and print the answer without entering the full interactive interface. This is perfect for generating a quick commit message or a summary of a single file. You can always check the health of your installation with the claude doctor command to ensure everything is working correctly.
Questions people ask
How does the agent handle existing README files that I do not want to fully overwrite?
The agent uses the Edit tool to modify specific blocks of text rather than replacing the whole file. You can instruct it in your prompt or via CLAUDE.md to only update the usage examples or the installation section. This allows you to keep your manual notes while the agent maintains the technical details.
Can I use external technical documentation as a reference for the agent?
Yes, the agent can use the WebSearch and WebFetch tools to find and read external documentation or style guides. You can ask it to search for the best practices of a specific library you are using to ensure your docs follow industry standards. This helps the agent write more professional and accurate technical content.
What happens if I exceed the context limit during a long writing session?
When the context window fills up, you should use the /compact command to summarize the conversation history. This removes the full text of older messages but keeps a summary so the agent remembers the important details. This process frees up space for the agent to read more files and continue writing without losing track of your goals.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.