How to Write a CLAUDE.md File for Claude Code

In this tutorial, you’ll write CLAUDE.md files for Claude Code that capture your Python workflow, project commands, and coding rules. You’ll create a global file for personal defaults, a project-level file for repository guidance, and one for local notes that shouldn’t be committed to version control.

To make these ideas concrete, you’ll work through a realistic example: steering Claude Code away from incorrect suggestions for AWS Bedrock global cross-region inference. You’ll turn that recurring correction into CLAUDE.md guidance and learn how to apply the same pattern to your project-specific rules, commands, and preferences that matter in your own codebase:

A good CLAUDE.md file doesn’t document everything about your project. Instead, it records commands, constraints, and workflow preferences that Claude Code can’t easily infer from the repository. The aim is to prevent repeated corrections. You’re not trying to teach Claude Code every detail of Python or your codebase.

You can always use the /init command as a starting point, but recent research found that unnecessarily large and redundant context files often hurt agent performance and recommended keeping them minimal. This means the auto-generated CLAUDE.md should usually be trimmed as it tends to repeat what Claude Code can already discover from the repo and can waste tokens without gain.

With that in mind, you can now build your CLAUDE.md files: first your global defaults, then the project-specific rules, and finally any local notes you may have. Before you start writing, review the prerequisites below to prepare your environment to follow along.

Prerequisites

To follow along, you’ll need Claude Code installed and configured, a text editor for creating Markdown files, plus a Python project or script that you can safely modify. You should also be familiar with how that project handles dependencies, tests, and any linting or formatting it uses.

A concrete Python project or script makes this tutorial more useful. If you don’t already have one, then you can download the sample script below before continuing:

The example Python script uses AWS Bedrock with boto3, which requires Python 3.10 or higher. It also relies on configured AWS CLI credentials to generate output. That said, you don’t have to run the script to follow along. It’s enough to read the prompt and Claude’s responses. Set up AWS only if you want to run it and play with it yourself.

Later on in the tutorial, you’ll see a Bedrock-specific mistake made by Claude regarding the proper way to enable global cross-region inference for AWS Bedrock models. It’s a mistake where the code produced still works but isn’t entirely correct or what you intended. This type of error generalizes to any quirks or project-specific conventions in your own Python project or repo.

Step 1: Audit Claude Code’s Mistakes

Start by observing where Claude actually needs guidance. Don’t write CLAUDE.md from a long list of your favorite Python rules, as that’s mostly unnecessary context. Run Claude Code on a small task in your project and watch for the repeated mistakes it makes.

A short audit can often give you better instructions than a long checklist of rules or directives you think Claude Code needs. Try using this workflow before creating any instruction file for Claude Code:

1. Temporarily move existing global and project-level CLAUDE.md and CLAUDE.local.md files out of the way. You can rename them or move them out of their respective directories so Claude Code doesn’t pick them up. You can verify Claude Code hasn’t loaded them with the /memory command.
2. Ask Claude Code to make a small change to your project.
3. Record each correction you have to give.
4. Sort each correction into global, project-level, or local guidance.

Look for knowledge that Claude Code can’t readily and reliably infer from reading your codebase. Build commands, test commands, environment variables, and team conventions are good starting points. Standard Python advice—apart from preferred defaults Claude may not follow—usually isn’t necessary because Anthropic models are already proficient at writing Python code, and such advice generally wastes tokens in a CLAUDE.md file.

It can still be beneficial to add your preferred Python defaults to CLAUDE.md, but they should only be a small part of it.

When auditing, note the correction, the scope, and the instruction you want Claude Code to follow. For example, you might notice the following corrections in a typical Python repo:

While doing this exercise, use the following flowchart to decide when and where to add a rule: