"I told it to use the same format before, yet it answers differently again." "I keep re-explaining the project's rules every session." "The moment context runs out, everything resets to zero." If you use Claude Code daily, these small frictions quietly pile up.
Most of them trace back to one habit: treating CLAUDE.md as a notepad where you jot down whatever comes to mind. Shift your view and design CLAUDE.md as a handover document for a new team member, and Claude Code's behavior becomes remarkably steady. Below I walk through the design principles that proved their worth as an indie developer who handed the upkeep of several blogs off to it.
Treat CLAUDE.md as a Handover, Not a Config File
Claude Code is, in effect, a member joining your project for the first time every session. Last time's context doesn't carry over unless you explicitly leave it behind. That's exactly what CLAUDE.md is for — the place to keep the things you'd want a first-day colleague to know.
From this angle, deciding what to write and what to leave out gets much easier. Drop the temporary notes and stray ideas, and keep only the background knowledge that gets referenced over and over. That's the starting point of good design.
The 3-Tier CLAUDE.md Hierarchy
CLAUDE.md can be placed at three levels. This is the most important design decision you'll make.
Global Settings (~/.claude/CLAUDE.md)
Write your universal "work style" here — coding conventions (indentation, naming), communication language and tone, common tools and library versions, and your role and area of expertise.
The key principle: only write things that never change between projects. Project-specific details here become noise elsewhere.
Project Settings (./CLAUDE.md)
The CLAUDE.md at your project root holds project-specific information: tech stack and architecture, directory structure, deployment steps, API endpoints, and branching strategy.
Think of it as everything you'd explain to someone touching the project for the first time. Claude Code is exactly that newcomer, so this tier delivers the most value.
Project Rules (.claude/rules/)
Place conditional rules as individual files — frontend.md for frontend-only rules, testing.md for testing conventions. This keeps the main file from ballooning and makes adding or removing rules effortless.
A Minimal CLAUDE.md Skeleton to Start From
Aiming for perfection up front makes the writing itself feel like a chore. What stuck for me was starting this thin and adding one line each time I tripped over something.
# Project Overview
A repo that auto-updates blog articles. Next.js + Markdown.
# Tech Stack
- Next.js (App Router) / TypeScript
- Articles live as Markdown under content/articles/
# Dev Flow
1. Add or edit articles under content/
2. Leave the build to CI (no local production build needed)
3. Before pushing, always confirm the article count is as expected
# Behavioral Rules
- Don't commit until checks pass
- Treat file deletion as a last resort
- Never present uncertain info as established fact
# Common Pitfalls
- (append here, with a date, whenever you notice one)Fill those first lines not with feature descriptions but with the pitfalls you've actually fallen into. A single line born from a real mistake does far more for output stability than any explanatory preamble.
Sub-Agent Design — One Agent, One Task
To get the most from Claude Code's sub-agents (the Task tool), separate each agent's responsibility cleanly.
For research workflows you might define a web research agent (gathering), a technical deep-dive agent (code analysis), a critical analysis agent (risk and problem spotting), and an integration agent (synthesizing). Document the invocation pattern in CLAUDE.md and Claude Code reproduces the workflow on its own: "For research tasks, first gather with a web research sub-agent, then run a technical deep-dive sub-agent for code-level review, and finally compile with an integration sub-agent."
Building an External Memory System
Because Claude Code sessions are bounded by the context window, giving it long-term memory through external files is highly effective.
Decision Logs
Create .claude/decisions/ and record important design calls. Structure each entry with date, context, alternatives, the decision, and the rationale, so you can retrace "why we chose this" with precision later.
Style and Tone Configuration
Define documentation and comment style in a dedicated file and Claude Code produces consistently styled output — especially valuable for technical writing and for keeping a team's communication style uniform.
Progress Logs
Add a rule like "record current work status in .claude/progress.md" and a session that runs out of context resumes smoothly from where it left off.
Codifying Behavioral Rules — "When in Doubt, Stop"
Writing behavioral rules into CLAUDE.md is, in my experience, the most underrated technique for stabilizing quality.
"Report errors before attempting a fix." "Always confirm before deleting files." "Never commit when tests fail." "Don't present uncertain information as fact." Rules like these become genuinely practical when you reverse-engineer them from your own list of past missteps.
Running It Across Multiple Projects and Machines
Once CLAUDE.md starts paying off, you'll want the same quality on a second machine. I keep my projects in a cloud-synced folder and share CLAUDE.md and the external memory across devices, so whichever machine I start from, Claude Code reads the same rules and the same handover notes.
But break one assumption behind that sync and the benefit quietly fades. The painful case for me was a mismatch between the "latest policy" in CLAUDE.md and an "old procedure" baked into the automation script that actually runs the work. When you update a policy, update the script that executes it at the same time — neglect that dual maintenance and you end up with a CLAUDE.md that's correct while the ground truth is stale. Writing the rule itself — "when you change a policy, fix the related execution prompt alongside it" — into CLAUDE.md heads off that drift.
The other thing I keep relearning is to treat external memory as a handover note you grow, not config you set. Jot down a stumbling point with a date, and the next time the same situation arises Claude Code reads it back and stops repeating the misstep. Every addition makes your collaborator a little sharper.
Your Next Step
Start by adding a single "behavioral rules" section to the CLAUDE.md of a project you're using right now. Recall one thing you tripped over before, and write the one line that keeps it from happening again. That alone will change how your next session with Claude Code feels.