Your CLAUDE.md, For Real

In Module 4, we set up a basic CLAUDE.md — about 200 words covering your preferences, communication style, and a few "don't do this" rules. That was a good start. It saved you from repeating yourself every session.

Now we're going to build the real thing.

A well-crafted CLAUDE.md doesn't just save tokens. It changes what Claude does. It makes Claude proactive instead of reactive. It makes Claude catch mistakes before they happen. It makes Claude route tasks to the right tools automatically instead of waiting for you to ask.

We'll build this in sections. Each section serves a specific purpose, and we'll explain that purpose before adding the content. Nothing goes in without a reason.

This is the section that shapes how Claude talks to you and works with you. Not what it does — how it does it.

Here's what this section looks like:

## Behavioral Preferences
- Clarifying questions before complex tasks — don't assume and proceed.
- No sycophancy. Share opinions directly. If you think my approach is wrong, say so.
- Flag assumptions explicitly and ask before proceeding.
- Track your confidence implicitly. Flag when you're below 90% sure about something.
- When a task has multiple valid approaches, present the options with trade-offs instead of picking one silently.

Why each line matters

"Clarifying questions before complex tasks." Without this, Claude will take a vague request and run with its best guess. Sometimes the guess is right. Often it's not, and you spend tokens correcting course. This one instruction saves more tokens than any other because it prevents wrong-direction work.

"No sycophancy." Claude has a natural tendency to agree with you and tell you your ideas are great. That's pleasant but not useful. If you're about to make a mistake — choosing the wrong architecture, writing a weak argument, missing an obvious flaw — you want Claude to tell you. This instruction gives it permission to push back.

"Flag assumptions." When Claude doesn't have enough information, it fills in gaps with assumptions. Usually reasonable ones. But "usually reasonable" means "sometimes wrong," and you don't discover the wrong assumption until four messages deep. Making assumptions visible lets you catch them early.

"Track confidence." Claude can sound equally certain whether it's 99% sure or 60% sure. This instruction asks it to distinguish between the two. When Claude flags low confidence, you know to verify. When it doesn't flag, you can generally trust the output.

"Present options with trade-offs." By default, Claude picks what it thinks is the best approach and does it. But "best" depends on context Claude might not have. If there are three reasonable ways to structure a document and Claude picks one without telling you, you might have preferred another. Seeing options with trade-offs lets you make informed choices quickly.

This section controls the texture of Claude's responses — length, format, tone.

## Communication Style
- Be concise. Lead with the answer, then explain if needed. Don't lead with reasoning.
- Don't summarise what you just did at the end of responses — I can see the changes.
- When referencing files or code, include the file path and line number.
- Use simple, direct sentences. Avoid filler phrases.
- Only ask one question at a time when you need clarification.

What these prevent

Without communication style instructions, Claude defaults to a pattern that's thorough but inefficient: it explains its reasoning, does the thing, then summarises what it did. That's three messages worth of content in every response. For complex tasks, this adds up fast.

"Lead with the answer" flips the default. Instead of "Let me think about this... considering the options... I think the best approach is X," you get "X. Here's why." Same information, fewer tokens, faster to scan.

"Don't summarise what you just did" is one you'll appreciate within the first session. When Claude edits a file, it naturally wants to list every change it made. You can already see the changes. The summary is redundant tokens.

"One question at a time" prevents a pattern where Claude asks three questions in one message, you answer all three, and then Claude asks two more follow-ups. Single questions keep the conversation moving linearly.

This is where your CLAUDE.md becomes truly yours. The previous sections are broadly useful. This section tells Claude about your specific field of work.

We can't write this section for you — it depends on what you do. But we can show you the pattern and give you examples for different domains.

The pattern

## My Work
- I work as [role] in [domain/industry].
- My primary use cases for Claude: [list the 2-3 things you do most].
- Domain-specific conventions: [anything Claude should know about how your field works].
- Tools I use: [software, platforms, frameworks relevant to your work].

Example: Content creator

## My Work
- I'm a content creator focused on LinkedIn and newsletters.
- Primary use cases: drafting posts, repurposing long-form content into short-form, research for topics.
- Voice: conversational, opinionated, never corporate. Short paragraphs. No hashtag spam.
- I publish on LinkedIn (posts, articles) and Substack (weekly newsletter).
- When I ask for drafts, give me a first draft I can edit — not a polished final version. I write better when I'm reacting to something than starting from blank.

If you use Claude Code to work with files (and you should — it's one of its biggest strengths), this section prevents a common source of chaos.

## File Management
- Default working directory: [your main folder path]
- When creating multiple related files, organise them in a subfolder rather than dumping them flat.
- File naming: lowercase with hyphens (like-this.md, not Like This.md)
- Don't create documentation files (README.md, etc.) unless I specifically ask.
- Use current year for files and folders unless I specify otherwise.

Why this matters

Without file management instructions, Claude Code makes reasonable but inconsistent choices about where to put files, what to name them, and how to organise them. Over time, this creates a mess — files scattered across directories, inconsistent naming, READMEs you didn't ask for cluttering up your folders.

These five lines create consistency. Every file Claude creates follows the same conventions. Every new project gets organised the same way. You spend zero time cleaning up after Claude.

This is the section most people don't think to include, and it's one of the most valuable.

## Self-Maintenance
- After non-trivial fixes or debugging sessions, append what you learned to learnings.md.
- If you notice an error pattern, log it to errors.md.
- When you have ideas for improving my workflow, append them to feature-requests.md.
- Don't silently fix problems — tell me what went wrong and what you did about it.

What this creates

Over time, you build three incredibly useful documents:

learnings.md — A running log of hard-won lessons. "The client prefers bullet points over paragraphs in status updates." "Summaries of financial documents need to keep the exact numbers, not round them." These are the things that cost you time the first time and seconds every time after, because Claude checks its learnings before repeating mistakes.

errors.md — A pattern tracker. If the same type of error keeps appearing, it shows up here and you can address the root cause instead of fixing symptoms.

feature-requests.md — Ideas for your own workflow that emerge naturally during work. Claude notices things you don't — "this task would be faster if we had a skill for it" — and captures them instead of losing them.

These files live in your .claude/ directory and persist across sessions. They're your setup getting smarter over time, not just staying static.

We had a basic version of this in Module 4. Now let's make it comprehensive.

## What I Don't Want
- Don't add features, refactor code, or make "improvements" beyond what I asked for.
- Don't create documentation or README files unless specifically asked.
- Don't add error handling for scenarios that can't happen. Trust internal code.
- Don't over-engineer. Only make changes that are directly requested or clearly necessary.
- Don't use emojis in files or communication unless I explicitly ask.
- Don't announce that you're being direct or honest — just be direct and honest.
- Don't start responses with "Great question!" or similar filler.

Why negative instructions are powerful

Claude is trained to be helpful. Sometimes it's helpful in ways you didn't want — adding documentation to code that didn't need it, refactoring a function that worked fine, creating helper utilities for one-time operations. Each of these costs tokens and creates noise.

Negative instructions are precise. "Don't add comments to code" is clearer than "only add comments when the logic is non-obvious," because Claude's definition of "non-obvious" might be different from yours. When in doubt, be explicit about what you don't want.

You'll discover new items for this section as you work. When Claude does something that annoys you, don't just correct it in the conversation — add it to this section so it never happens again.

Let's put all six sections together. If you ran the setup prompt, your CLAUDE.md already has a comprehensive version based on these sections. Here's how to review and customise it.

A few guidelines:

Keep it under 500 words total. This might seem short given how much we've covered, but remember: your CLAUDE.md loads into every conversation. A 500-word CLAUDE.md is roughly 650 tokens. A 1,000-word one is ~1,300 tokens. The difference compounds across every session, every day. Include what changes Claude's behaviour. Leave out what doesn't.

Be specific, not exhaustive. "Use British English" is specific. "Write clearly and professionally" is vague enough to be useless. Every line should change something concrete about how Claude operates.

Update it as you learn. Your CLAUDE.md isn't a one-time setup. It's a living document that gets sharper as you discover what works. When you notice Claude doing something wrong repeatedly, add an instruction. When an instruction isn't making a difference, remove it.

Test after changes. After editing your CLAUDE.md, start a new Claude Code session and give it a task that would exercise the new instructions. Check whether the behaviour actually changed. If it didn't, the instruction might need to be more specific.

Approximate token cost

Your complete CLAUDE.md should be in the range of 500-700 tokens. That's the "startup cost" of every session. In exchange, you get:

• No wasted tokens on repeating preferences
• No correction rounds for wrong assumptions
• No cleanup of unwanted additions
• Claude that works the way you think, from the first message

The breakeven point is typically within the first 2-3 exchanges of any conversation.

This is a meaningful upgrade from where you were. Your Claude Code now has a comprehensive understanding of how you work, what you want, and what you don't want. Every session starts from a position of context, not cold ignorance.

But we're not done. The CLAUDE.md tells Claude how to behave. The next module gives it capabilities — skills and commands that let Claude do things it couldn't do before.