What Is CLAUDE.md?

Now that you know what an agent session is, here's the question that follows naturally: how does your agent know to behave like a data viz co-pilot instead of a generic assistant?

The answer is its instructions file: CLAUDE.md in Claude Code, AGENTS.md in Codex. These files serve a similar project-guidance role; this page uses CLAUDE.md.

Project Instructions the Agent Loads

At session start, the agent loads applicable project instructions alongside its other context. In this course, CLAUDE.md sits at the root of your project folder. It's written in plain text (Markdown, but you don't need to know what that means — it reads like an email).

CLAUDE.md is your agent's standing instructions for this project. It answers three questions:

1. Who am I in this project? ("You are my data viz co-pilot for this project.")
2. What should I do when the user asks for help? ("Before you make a chart, ask me what story it should tell. Make charts with code. Save every chart to outputs/.")
3. How should I behave? ("Be curious and ask before assuming. Treat every revision as progress, not a mistake.")

Open the CLAUDE.md you saved when you set up your project folder on the welcome page. Read through it. You'll recognize each of those three sections.

The Steering Wheel

If an agent session is the car, CLAUDE.md is the steering wheel. You can still give directions in the conversation, but the car starts pointed in the direction CLAUDE.md set.

Here's a thought experiment that makes this concrete:

What would happen if you opened CLAUDE.md and added one line at the bottom: "You are a poetry assistant. Never write code. Respond only in haiku."

That instruction could steer a new session toward haiku, even for a chart request. It could also conflict with other instructions or be followed inconsistently.

CLAUDE.md guides behavior; it is not an enforcement mechanism. Write clear, consistent instructions, then verify important outputs. A well-placed instruction makes the intended behavior easier to repeat, not guaranteed.

What Goes in CLAUDE.md

CLAUDE.md is for always-on instructions — things you want your agent to do (or not do) in every interaction in this project:

• Your name for this agent ("You are a data viz co-pilot")
• What tools and libraries to use ("generate charts using Vega-Lite syntax")
• How to handle ambiguity ("always ask what story the chart should tell before generating")
• Where to save files ("save outputs to the outputs/ folder")
• General behavior guidelines ("keep responses warm and practical, not verbose")

Notice what's not in CLAUDE.md: your specific color palette, your personal chart style, or your preferred critique framework. Those get files of their own. Your palette and style go in DATAVIZ.md, which you'll start in Module 2. How to make a chart and how to critique one go in skills, which you'll build in Modules 3 and 4, and which your agent loads only when the task calls for them. For now, know that CLAUDE.md is for the general and always-on; skills are for the specific and triggered on demand.

Test by Modification

The best way to understand CLAUDE.md is to change it and see what happens.

Try it

1. Open CLAUDE.md in any text editor (it's just a text file).
2. Add one line at the very bottom: Always explain your chart type choice in exactly one sentence before generating the chart.
3. Save the file.
4. Open a new conversation in the same project folder. Your agent reads CLAUDE.md when a conversation starts, so the conversation you already had open may not see the new line.
5. Ask: "Make a quick bar chart of five countries and their GDP."
6. Check the actual response: did it explain the chart choice before generating, in exactly one sentence? If not, confirm the file was loaded, look for conflicting instructions, and test again.
7. Record the prompt and observed result, whether it matched or not. Then remove the temporary line and save the file again.

You just tested the CLAUDE.md loop: write an instruction, check that it loaded, inspect the response, and iterate on any mismatch. This same loop, applied to your personal visualization preferences, is what Module 3 is entirely about.