If you’re using Claude Code on a daily basis, you’re probably starting to modify your CLAUDE.md file. You obviously want to avoid adding a bunch of rules without structure, or any other missteps that can make things more confusing for an LLM. Our team has been studying these processes for months, and we’ve found a few pro tips to get better results and keep token spend low.
Above all, break it up
Your CLAUDE.md doesn’t need to be one massive file. Reference other files using @ref/other/files.md syntax within your main CLAUDE.md. You might structure your files like below:
project-root/
├── CLAUDE.md # Main context and overview
├── claude/
│ ├── testing-guide.md # Detailed testing procedures
│ ├── deployment.md # Deploy process specifics
│ └── current-sprint.md # Feature-specific instructions
Your main CLAUDE.md keeps the architectural overview, general notes, and any “global” behaviors for a project. You can add more context to specific processes in sub-files. This is good for keeping instructions organized, both for yourself and for Claude. Similar steps are grouped together and thus are easier for Claude to interpret.
Pro tip: run /init from your Claude Code session to generate a CLAUDE.md file
What to include (and what not to)
The CLAUDE.md for a repo should be a shared team resource. Check it into git so your teammates can get similar behavior from Claude, and so Claude follows team-wide conventions.
Include:
- Code conventions: How you name things, where you put things, what patterns you follow
- Important file locations: “Config lives in
src/config/, migrations are indb/migrations/” - Commands that actually work: Test runners, build commands, maybe just reference your Makefile
- Anti-patterns to avoid : “Don’t use our legacy auth system, use the new middleware instead”
- Known tech debt: Be honest about the messy parts. Claude can use them as examples of what to avoid
- MCP debugging setups: If you’ve got useful debugging configurations, share them here
Keep out:
- Feature implementation plans: These belong in a
claude/ordev-plans/folder - Super specific subtask instructions: You don’t want to burn tokens on edge cases. These might be better for your individual prompts
The specificity sweet spot
Even with detailed instructions, an LLM will occasionally go offtrack. Smaller, focused files can help prevent this. But you still need to be specific about your workflows and rules.
If you have a deployment process that you want to use consistently, write it down step-by-step. Include shell commands and references to your files (using the @ operator). Don’t make Claude figure out your workflow from scratch every time: it probably won’t get it right.
Let Claude help write CLAUDE.md
Many devs recommend using Claude to help write better Claude prompts. You can also use Claude to help write your CLAUDE.md. Beyond the /init command, Claude’s great at expanding brief requirements into detailed specs. You’ll just need to double check that Claude interpreted your prompt as intended.
Try this: give Claude a short prompt like “make sure to use actual database services so queries are tested properly” and “test all valid inputs plus error cases.” Then ask it to write detailed testing instructions for your CLAUDE.md. Revise as needed.
Real-world example structure
In this CLAUDE.md file, we’ve given Claude references to other specific sub-files (e.g. for architecture and dev). We’ve also defined our testing workflow, so Claude can figure it out from here instead of searching for a Makefile or package.json.
# Project Context
## Architecture Overview
@ref/claude/architecture.md
## Development Workflow
@ref/claude/dev-cycle.md
## Code Conventions
- Use TypeScript strict mode
- Components go in src/components/
- Tests co-located with source files
## Commands
- `npm test` - run all tests
- `npm run build` - production build
- See Makefile for deployment commands
## Known Issues & Goals
- Legacy API endpoints in /v1/* need migration
- Working toward 100% test coverage
- Database queries need optimization (see performance.md)
Keep on top of your token spend
Remember that every line in your CLAUDE.md uses tokens. Be concise but complete. If Claude needs to understand your codebase architecture, include it. If it’s a one-off feature requirement, put it in a separate file. Every time you start a Claude session, it’ll read your CLAUDE.md file, but only once. So if you have an instruction you’d repeat throughout the session, it is better put in the CLAUDE.md to save tokens.
Anthropic recommends keeping them concise, and breaking out specific processes into referenced files. Too much context can send Claude off the rails, as it’ll recognize fewer patterns when its context window fills up.
Version control strategy
Treat your CLAUDE.md like any other important project documentation. Use PRs, get reviews from your team, and iterate on what works. Your future self (and your teammates) will thank you when someone new joins the project and can use the CLAUDE.md to understand your project structure, conventions, commands, etc.
Your CLAUDE.md file is never really complete. You should be continuously adding new rules and deleting those that no longer make sense in there. At the end of the day, you’re writing a spec that makes Claude more effective and your dev process more predictable. Start simple, add the bare minimum, and expand it as you learn what works for your team (and for Claude).
Complete your agentic dev loop
You’ll get the most value from your agents when they’re not confined to your local dev environment. With ephemeral environments, they can push code and quickly see how it performs running on production-like infrastructure. Agents can pull logs and resolve bugs that happen later in the pipeline, so you can ship features faster and more confidently. The best part is that you can test multiple features in parallel with multiple agents.
Try Shipyard today and get unlimited full-stack, production-like environments. We promise you (and your agents) will be more productive than ever.
