In the previous lesson, you learned how to use hooks to intercept and control your agent's behavior at runtime. However, there is another dimension to building production-ready agents: providing them with 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 automatically loads. In this lesson, you'll build a Travel Planner agent that receives 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 configurations, let's understand which files the SDK can work with and where they are located. The Claude Agent SDK supports a filesystem-based configuration system consisting of three types of files:

CLAUDE.md: This is a Markdown file that resides 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, such as tool configurations, environment variables, or custom prompts.

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

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

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 requiring them in every prompt.

What makes CLAUDE.md special is that it automatically becomes part of Claude's system prompt. Everything you write in this file is loaded before the agent processes any user queries, giving Claude context regarding 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 stems from its shareability. When you commit this file to your repository, everyone on your team receives 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 receive 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 .

In this lesson, we will build a Travel Planner agent by creating a CLAUDE.md file that contains the instructions defining how our agent should assist users in planning 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 instructs 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 section tells what information to gather first, and the section specifies where to save completed itineraries.

Now that we've created our CLAUDE.md file, we need to instruct the SDK to load it. The settingSources option in your configuration controls which configuration files are loaded from your filesystem. This is an opt-in feature, meaning that, by default, the SDK does not load any configuration files unless you explicitly instruct it to do so.

The settingSources option accepts an array 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 in your project 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 array, and they will be loaded in order, with later sources overriding earlier ones. For this lesson, we'll focus on the source because it's the most common choice for building team-friendly agents. When you specify , the will locate our file and automatically load its contents into 's .

Now, let's create the TypeScript code that will plan a trip based on the instructions in our CLAUDE.md file. We will configure the agent to load project-level settings automatically and enable the tools needed for travel research.

The key line here is settingSources: ["project"], which instructs the SDK to load our CLAUDE.md file. Notice that while our user prompt provides specific details about the trip (destination, budget, interests, and timing), it does not include instructions regarding how to plan the trip or which format to use — we are simply stating what we want. All guidance regarding how to approach this task comes from CLAUDE.md, which the SDK loaded automatically.

We create a query iterator using the query() function with our configured options, then pass that iterator to to handle the streaming output. 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 immediately by conducting research, exactly as instructed in the Your Approach section, which states: "Work with the information provided — make reasonable assumptions if details are missing."

Observe how Claude follows the instructions from CLAUDE.md without requiring them to be included in the prompt. The agent immediately launches into research mode, conducting multiple WebSearch calls to gather information about Tokyo. Claude does not ask for more details regarding accommodation preferences or group size — it works with the provided information (destination, budget, interests, and timing) and makes 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 is 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, and it is organized with clear headers for visual scanning. The agent researched and presented information following the Research Priority list: best time to visit ("Best Timing for April"), must-see attractions (day-by-day highlights), and practical details like transportation and reservations. The budget breakdown reflects the mid-range category from , providing specific cost estimates and restaurant options.

You have now learned how to use settingSources and CLAUDE.md to provide your agents with persistent knowledge and consistent behavior. The key concepts are that settingSources is an opt-in parameter, with "project" being the most common choice for team-shared configuration. CLAUDE.md contains natural language instructions that automatically become part of Claude's system prompt, and configuration is specified in the Options type when creating a query(). In the upcoming practice exercises, you will create your own CLAUDE.md files for different domains and learn how to structure project settings for maximum reusability.