Your CLAUDE.md, For Real

Haven't run the setup prompt yet? Do that first — it creates the foundation that this module explains. You'll find it on the Setup Prompt page.

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.

The difference between a basic CLAUDE.md and a comprehensive one is the difference between a colleague who knows your name and a colleague who knows how you think.

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:

• 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.

• 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

• 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

• 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.

### Example: Software developer

• I'm a full-stack developer working primarily in TypeScript (React + Node).
• Primary use cases: writing features, debugging, code review, refactoring.
• Prefer functional patterns over class-based. Minimal abstractions — only abstract when there's genuine repetition.
• Don't add comments to code unless the logic is non-obvious. Don't add type annotations I haven't asked for.
• When fixing bugs, prefer reverting the broken change first before attempting a new fix.
• After writing non-trivial code, note what could break and suggest tests.

### Example: Student

• I'm a final-year engineering student. Currently preparing for campus placements + working on my final year project.
• Primary use cases: understanding complex concepts, preparing for technical interviews, reviewing my project code, writing reports.
• When explaining concepts, use concrete examples and analogies. If I ask about something theoretical, connect it to practical applications.
• For interview prep: focus on what interviewers actually test, not textbook completeness.

### Example: Small business owner

• I run a [type] business in [city]. Team of [size].
• Primary use cases: customer communication, marketing content, financial analysis, operations planning.
• Tone for customer-facing content: [warm/professional/friendly] — my customers are [description].
• I make most decisions myself, so when I ask for analysis, give me enough to decide, not a 10-page report.
• Currency: ₹. Business context: Indian market, Indian regulations.

The key principle: tell Claude what it needs to know to help you *without you having to repeat it*. If you find yourself saying the same thing in multiple conversations, it belongs in your CLAUDE.md.

---

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.

• 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.

• 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 API returns dates in UTC, not local time." "The build fails if this directory doesn't exist." These are the things that cost you hours 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.

• 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. Open your CLAUDE.md file and replace the basic version from Module 4 with your new comprehensive version.

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 updating 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.