Last updated 13 October 2026
Put API documentation in CLAUDE.md
API hallucinations break your workflow
When you ask Claude Code to integrate a third-party service, it often relies on training data that might be outdated. It might guess the wrong endpoint URL or fail to include a necessary header for authentication. You waste time correcting its mistakes or searching for the right documentation yourself. This friction destroys your focus and forces you to leave the terminal. If the agent cannot see the actual API specification, it will keep making the same errors every time you start a new session.
You might try to fix this by pasting documentation directly into the chat. This works for one session, but the context disappears once you quit or run the /clear command. You need a way to make this knowledge permanent and available to every session in that project. The solution is to use the CLAUDE.md file as a persistent memory store for your specific technical requirements and external dependencies.
CLAUDE.md provides persistent context
Claude Code looks for a file named CLAUDE.md in your project root to understand the rules and environment. This file is the first place the agent checks before it starts any task. By placing API documentation here, you ensure the agent always has the correct schemas, base URLs, and authentication patterns at hand. It treats the contents of this file as authoritative instructions that override its general knowledge.
You do not need to include every single detail from a massive API reference. Focus on the endpoints you use most often and the data structures you expect to receive. Include a section for API base URLs and a clear description of how to handle authentication. When you run the claude command in your repository, the agent reads this file and understands the constraints of your environment immediately.
Structure documentation for readability
The agent processes Markdown efficiently, so use clear headers and code blocks inside your CLAUDE.md file. Use a dedicated heading for each external service. Under each heading, provide a list of common endpoints and their expected request bodies. Use JSON blocks to show the exact structure of the data. This helps the agent use the Edit and Write tools with high precision because it knows exactly what fields to map.
Avoid long walls of text. Short, descriptive sentences work best for the agent to parse. If you have a complex authentication flow involving multiple steps, describe it as a sequence of actions. This ensures that when the agent uses the Bash tool to test an integration, it knows how to construct the shell commands or script parameters correctly without asking you for clarification.
Use directory level files for isolation
If your project integrates with many different services, a single CLAUDE.md in the root might become too large. This can consume too much of the context window and lead to frequent calls for the /compact command. To prevent this, you can place a CLAUDE.md file in a specific subdirectory dedicated to a single integration. For example, if your Stripe integration code lives in a payments folder, put the Stripe documentation in a CLAUDE.md file inside that folder.
Claude Code respects the directory hierarchy. When it works on files inside that subdirectory, it reads the local CLAUDE.md and the root CLAUDE.md. This allows you to keep your main project rules clean while providing deep, specific context for individual modules. This isolation makes it easier to manage large codebases without overwhelming the agent with irrelevant documentation for a simple bug fix in a different part of the tree.
Automate updates with WebFetch and Bash
Documentation changes over time, and manual updates are tedious. You can use the WebFetch tool to pull the latest API specifications directly from a URL. If you have a specific script that pulls documentation and formats it for your project, you can tell the agent to run that script using the Bash tool. This keeps your CLAUDE.md files current without you having to copy and paste text from a browser.
You can even create a custom slash command to handle this. By adding a markdown file in the .claude/commands directory, you can define a command that fetches documentation and updates your local project memory. This ensures that every developer on your team has access to the same updated specifications. It also allows the agent to check for updates itself if it encounters a response from an API that does not match its current instructions.
Manage memory and costs effectively
Adding large documentation files to your project increases the amount of data the agent must process. This can lead to higher token usage which you can monitor with the /cost and /usage commands. If the conversation becomes too long because the agent is constantly referencing the documentation, use the /compact command. This will summarize the session and clear out the old messages while keeping the essential context and project instructions intact.
If you find that the agent is reading too many files at once, you can refine your .gitignore or adjust how you structure your documentation. The agent respects .gitignore, so you can keep raw documentation files out of the session while keeping the summarized CLAUDE.md files available. This balance ensures the agent stays fast and efficient while remaining accurate.
Organizing multiple integrations with adhdTerminal
Running many Claude Code sessions side by side is a useful way to handle multiple integrations. adhdTerminal allows you to run these sessions as separate tiles on a wall. Each tile can focus on a different part of your project, with its own history and specific CLAUDE.md context. This is particularly helpful when you have one session focused on a database migration and another on a third-party payment gateway.
Tiles in adhdTerminal show whether an agent is working, waiting, or idle. They also show the last few exchanges of the conversation. This means you can keep an eye on a long integration task while you work on another tile. If you need to step away from your computer, the free iPhone app mirrors your wall and lets you answer a prompt or send the next task over an encrypted link.
Define custom agents for specific APIs
For very complex integrations, you can go beyond just a CLAUDE.md file and create a custom subagent. Place a markdown file in the .claude/agents directory that describes the persona and specialized knowledge of an agent dedicated to a specific API. When you need to do heavy work on that integration, you can invoke this agent using the /agents command. This agent will follow the specific instructions and documentation you provided in its definition.
This approach is useful when an API has very strict rules or unique quirks that do not apply to the rest of the project. By separating these instructions into a subagent, you reduce the noise in your main session. The subagent can use the same Read and Edit tools but with a much tighter focus on the integration logic. This results in cleaner code and fewer mistakes when dealing with complex external systems.
Questions people ask
Can I put the entire OpenAPI spec in CLAUDE.md?
You can, but it might use a lot of context space. It is better to include only the endpoints you need. If you need the whole spec, keep it in a separate file and tell the agent to use the Read tool to access it when needed.
How do I stop Claude Code from changing my documentation?
You can set permissions in your .claude/settings.json file. Under the permissions key, you can restrict the Edit and Write tools for specific files. This prevents the agent from accidentally modifying your reference material while it works on your source code.
What happens if I have a CLAUDE.md in my home directory?
A file at ~/.claude/CLAUDE.md applies to every session you run on your computer. This is a good place for global preferences or credentials that apply to all projects. Local project files will still take precedence for project-specific details.
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.