In the previous lesson, you learned how to use hooks to intercept and control your agent's behavior at runtime. But there's another dimension to building production-ready agents: giving them persistent knowledge about your project, domain, and conventions. Instead of repeating the same instructions in every prompt, you can store them in configuration files that the SDK can automatically load. In this lesson, you'll build a Travel Planner agent that gets its entire personality and guidelines from a CLAUDE.md file, making your agents smarter and more consistent across your entire team.

Before we dive into how to load configuration, let's understand what files the SDK can work with and where they live. The Claude Agent SDK supports a filesystem-based configuration system with three types of files:

CLAUDE.md: This is a Markdown file that lives in your project root directory. It contains natural language instructions that define your agent's personality, domain knowledge, and approach to problems. Think of it as your agent's training manual.

.claude/ Directory: For more structured configuration, you can create a .claude/ folder in your project root. This directory can contain JSON files with additional settings like tool configurations, environment variables, or custom prompts.

User Settings: The SDK also supports user-level configuration stored in ~/.claude/settings.json in your home directory. These are personal preferences that apply to all your projects.

The key insight is that these files exist at different scopes:

• User files (~/.claude/) apply to all your projects
• Project files (CLAUDE.md, .claude/settings.json) apply to everyone on your team
• Local files (.claude/settings.local.json) apply only to you in this project

By default, the SDK ignores all these files unless you explicitly tell it which ones to load. Let's start with the most powerful one: CLAUDE.md.

The most important file in your project configuration is CLAUDE.md. This is a Markdown file that acts as persistent memory for Claude, providing project-specific instructions that the agent automatically follows without you having to include them in every prompt.

What makes CLAUDE.md special is that it becomes part of Claude's system prompt automatically. Everything you write in this file is loaded before the agent processes any user queries, giving Claude context about your project, domain, and expectations. The content typically includes your agent's role and purpose, guidelines for how it should approach tasks, formatting preferences for outputs, domain-specific terminology, and project conventions.

The real power of CLAUDE.md comes from its shareability. When you commit this file to your repository, everyone on your team gets the same agent behavior without needing to pass around prompt templates or remember special instructions. A new developer can clone your project, run the agent, and immediately get the same thoughtful, domain-aware responses that you get. The same applies to open-source projects — users can download your agent and instantly have access to all the knowledge and conventions you've encoded in CLAUDE.md.

Unlike hooks, which control what the agent can do, CLAUDE.md shapes what the agent knows and how it thinks about problems. Let's see what a real CLAUDE.md file looks like by building one for our Travel Planner agent.

In this lesson we will build a Travel Planner agent by creating the CLAUDE.md file that contains all the instructions defining how our agent should help users plan trips. Create a file named CLAUDE.md in your project root with the following content:

This CLAUDE.md file defines our agent's entire personality and approach. The first section establishes the agent's role as a travel planning assistant. The "Your Approach" section tells Claude to work with whatever information is provided and make reasonable assumptions rather than requesting more details upfront. This creates a more action-oriented agent that focuses on being concise and delivering results quickly. The "Itinerary Format" section specifies how to structure trip plans, while "Budget Categories" defines what each budget level means in concrete terms. The "Research Priority" section tells Claude what information to gather first, and the "Files" section specifies where to save completed itineraries.

Notice that we're writing in natural language with clear, specific instructions rather than vague guidance. This makes the file easy for humans to read and maintain, while still giving Claude precise directions. Now that we have our CLAUDE.md file ready, let's learn how to tell the SDK to load it.

Now that we've created our CLAUDE.md file, we need to tell the SDK to load it. The setting_sources parameter in ClaudeAgentOptions is what controls which configuration files get loaded from your filesystem. This is an opt-in feature, meaning that by default, the SDK doesn't load any configuration files unless you explicitly tell it to.

The setting_sources parameter accepts a list of strings, and the SDK supports three types of configuration sources:

• "user": Loads settings from ~/.claude/settings.json in your home directory for personal preferences.
• "project": Loads settings from .claude/settings.json and CLAUDE.md files relative to your working directory for team-shared conventions.
• "local": Loads settings from .claude/settings.local.json for developer-specific overrides that are typically gitignored.

You can specify multiple sources in the list, and they'll be loaded in order, with later sources overriding earlier ones. For this lesson, we'll focus on the "project" source because it's the most commonly used for building team-friendly agents. When you specify setting_sources=["project"], the SDK will look for our CLAUDE.md file and load its contents into Claude's system prompt automatically.

When you use setting_sources=["project"] or setting_sources=["local"], the SDK needs to know where to look for your configuration files. This is where the cwd (current working directory) parameter comes in. The cwd parameter tells the SDK which directory contains your CLAUDE.md file and .claude/ folder.

Here's the important part: the cwd parameter has a default value. If you don't set it explicitly, it defaults to the directory from which you launched your Python script. Using Path(__file__).parent.absolute() gives you the directory containing your Python script, which is usually your project root. This approach works reliably regardless of where you run the script from. Without an explicit cwd, the SDK might look in unexpected locations depending on where you launched your script.

There's one exception: if you're only using setting_sources=["user"], you don't need to set cwd at all because user settings always live in ~/.claude/settings.json in your home directory. For our Travel Planner agent, we'll use the recommended pattern with an explicit .

Now let's create the Python code that loads our CLAUDE.md configuration and uses it to help plan a trip. We'll configure the agent to automatically load project-level settings and enable the tools needed for travel research.

The key lines here are setting_sources=["project"], which tells the SDK to load our CLAUDE.md file, and cwd=project_root, which tells it exactly where to find that file. We set project_root at the beginning of our function using Path(__file__).parent.absolute() to ensure the SDK always looks in the correct directory, regardless of where we run the script from. Notice that our user query provides specific details about the trip (destination, budget, interests, timing), but doesn't include any instructions about how to plan the trip or what format to use — we're just stating what we want. All the guidance about how to approach this task comes from CLAUDE.md, which the SDK loaded automatically. Let's see what happens when we run this code.

When we run this code, Claude immediately demonstrates that it has absorbed the instructions from CLAUDE.md. Instead of asking clarifying questions, the agent takes action right away by conducting research, exactly as instructed in the "Your Approach" section that says "Work with the information provided—make reasonable assumptions if details are missing."

Look at how Claude is following the instructions from CLAUDE.md without us having to include them in the prompt. The agent immediately launches into research mode, conducting multiple web searches to gather information about Tokyo. Claude doesn't ask for more details about accommodation preferences or group size — it works with the information provided (destination, budget, interests, timing) and will make reasonable assumptions where needed. This demonstrates the "be concise and actionable" directive from our configuration. After completing its research, Claude moves directly to creating the itinerary.

After conducting its research and creating the itinerary file, Claude presents a comprehensive summary that's both structured and actionable. The agent has followed all the guidelines from CLAUDE.md, including the research priorities and file-saving conventions.

Claude used the Write tool to save the itinerary to ./trips/tokyo-itinerary.md, following the "Files" section of our configuration. The response is concise and actionable, organized with clear headers and emoji for visual scanning. The agent researched and presented information following the "Research Priority" list: safety ("Low crime—Tokyo is one of the world's safest cities"), best time to visit ("April Timing Benefits"), must-see attractions (day-by-day highlights), and practical details like transportation and reservations. The budget breakdown reflects the mid-range category from with specific cost estimates for 3-star hotels and restaurant options.

You've now learned how to use setting_sources and CLAUDE.md to give your agents persistent knowledge and consistent behavior. The key concepts are that setting_sources is an opt-in parameter, with "project" being the most common choice, CLAUDE.md contains natural language instructions that become part of Claude's system prompt automatically, and you should always set cwd explicitly when using project settings. In the upcoming practice exercises, you'll create your own CLAUDE.md files for different domains and learn how to structure project settings for maximum reusability.