Creating Effective CLAUDE.md Files

1. Creating Effective CLAUDE.md Files

The workflow is in place. Now let's make it more effective, starting with the context Claude gets every session.

2. CLAUDE.md Best Practices

You've already run /init. But the real value comes from what happens next. When Claude gets something wrong, update CLAUDE.md. When a convention changes, reflect it there. Think of it less as a config file and more as onboarding docs that improve with every session. But first, let's look at what good context actually looks like.

3. The Project So Far

Let's take stock of where the project stands. The project now has a CLAUDE.md. But having the file isn't enough. What goes in it matters just as much. Too little and Claude lacks context. Too much and it becomes noise. So what belongs?

4. What Goes IN vs. OUT of CLAUDE.md

Think sticky notes, not documentation. Project name, commands, conventions, that's the core. Anything Claude can infer directly from your code doesn't need to be here. And never paste entire files; that's what @ references are for. Let's see it applied.

5. Iterating on CLAUDE.md

Here's a concrete example of CLAUDE.md as a living document. Ask Claude to add error handling and it delivers. But look closely: exception details are leaking into the response, which is a security risk. Flag it, and ask Claude to fix it and update CLAUDE.md. That convention is now captured: log errors internally, never expose them to the client. Same mistake won't happen again.

6. Good vs. Bloated CLAUDE.md

That's the principle in action. Now here's what it looks like side by side. The bloated version pastes entire files and documentation — over 200 lines Claude doesn't need. The lean version is fifteen lines: project name, commands, conventions. Short enough to stay current, specific enough to be useful. When Claude needs a file, point it there directly with an @ reference.

7. File References - Using @

Rather than pasting code into your prompt, use @ to point Claude at a file directly. Type @routes.py and ask what endpoints the API has. Claude reads the file and responds with full context: no copy-pasting, and the answer always reflects the current state of the code.

8. CLAUDE.md + @ Together

You can also use @ references inside CLAUDE.md itself. Add @routes.py, @models.py and Claude reads those files automatically every session. Persistent context plus live file content. That combination gives Claude a complete picture of your project from the moment you start.

9. Three Levels of Context

@ references handle file-level context. But context in Claude Code works at three levels. Project CLAUDE.md goes into git, shared with your team. CLAUDE.local.md is personal and stays off git: local paths, personal preferences. The global file in your home directory applies across every project, ideal for habits like always using type hints.

10. When to Use Each

The split is straightforward. CLAUDE.md holds what the team needs: test commands, conventions, project structure. CLAUDE.local.md holds what only you need: local paths, personal shortcuts. The global file holds what you want everywhere: your defaults.

11. Chapter 1 Recap

That's Chapter 1. Context, planning, and reasoning: each one makes the others more effective. You now have everything you need to work with Claude Code deliberately, not just reactively. Next chapter, we take it to a real codebase.

12. Let's Practice!

Now it's your turn: use @ references to inspect the codebase and keep CLAUDE.md current. Let's go.

Create Your Free Account

By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.