Project Configuration with Source Files

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.

your-project/
├── CLAUDE.md              # Main instructions (project root)
├── main.ts
├── package.json
└── tsconfig.json

.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.

your-project/
├── .claude/
│   ├── settings.json       # Team-shared settings
│   └── settings.local.json # Developer-specific overrides (gitignored)
├── CLAUDE.md
├── main.ts
├── package.json
└── tsconfig.json

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:

• User files (~/.claude/) apply to all of 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 of these files unless you explicitly specify which ones to load. In this lesson, we'll focus on using settingSources: ["project"] to load project-level configuration from CLAUDE.md. Let's start by understanding what makes CLAUDE.md so powerful.

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 Travel Planner agent.

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:

# Travel Planner Agent

You help users plan trips by researching destinations, finding activities, and creating itineraries.

## Your Approach

- Work with the information provided — make reasonable assumptions if details are missing
- Research essential facts: safety, weather, local events, visa requirements
- Balance tourist highlights with local experiences
- Be concise and actionable

## Itinerary Format

When creating itineraries, organize by day:
- Morning, afternoon, evening activities
- Include travel time between locations
- Note reservation requirements

## Budget Categories

- Budget: hostels, street food, public transport
- Mid-range: 3-star hotels, casual restaurants, mix of transport
- Luxury: 4–5 star hotels, fine dining, private transfers

## Research Priority

1. Safety advisories for the destination
2. Best time to visit
3. Must-see attractions
4. Local customs and etiquette
5. Transportation options

## Files

Save itineraries to `./trips/{destination}-itinerary.md`

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 Research Priority section tells Claude what information to gather first, and the Files section specifies where to save completed itineraries.

Notice that we are 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 instruct the SDK to load it.

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.

import type { Options } from "@anthropic-ai/claude-agent-sdk";

const options: Options = {
  model: "haiku",
  maxTurns: 10,
  settingSources: ["project"], // Load project-level settings
  allowedTools: ["WebSearch", "WebFetch", "Write", "Read"]
};

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 "project" source because it's the most common choice for building team-friendly agents. When you specify settingSources: ["project"], the SDK will locate our CLAUDE.md file and automatically load its contents into Claude's system prompt.

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.

import { query } from "@anthropic-ai/claude-agent-sdk";
import type { Options } from "@anthropic-ai/claude-agent-sdk";
import { displayResponse } from "./utils";

async function main() {
  // Configure the agent to load project-level settings from CLAUDE.md
  const options: Options = {
    model: "haiku",
    maxTurns: 10,
    // This tells the SDK to look for CLAUDE.md and related settings
    settingSources: ["project"],
    allowedTools: ["WebSearch", "WebFetch", "Write", "Read"]
  };

  // The agent will automatically follow the Travel Planner instructions in CLAUDE.md
  const queryIterator = query({
    prompt:
      "I want to plan a 5-day trip to Tokyo. " +
      "My budget is mid-range and I'm interested in food, history, and anime culture. " +
      "I'm traveling in April.",
    options
  });

  await displayResponse(queryIterator);
}

main();

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 displayResponse() 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."

💬 Claude Response:
I'll help you plan a fantastic 5-day trip to Tokyo! Let me research the essential information for your April visit and create a tailored itinerary.

🔧 [Tool: WebSearch]

🔧 [Tool: WebSearch]

🔧 [Tool: WebSearch]

🔧 [Tool: WebSearch]

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 Response:
Great! Now let me create a comprehensive 5-day Tokyo itinerary tailored to your interests. I'll save it as a file for you.

🔧 [Tool: Write]

💬 Claude Response:
Perfect! I've created a comprehensive 5-day Tokyo itinerary for you. Here's what I've planned:

## Trip Highlights

**Best Timing for April:**
- Cherry blossom season (late March-early April) creates beautiful scenery
- Pleasant weather (15-20°C) perfect for walking and exploring
- Early morning visits help you beat the crowds

**Day-by-Day Breakdown:**

1. **Historical Tokyo** - Start with Sensō-ji Temple (Tokyo's oldest, est. 628) and Asakusa Shrine
2. **Anime Culture Deep Dive** - Akihabara for shopping, Suginami Animation Museum
3. **Meiji Shrine & Harajuku** - Peaceful shrine grounds, plus the Ghibli Museum
4. **Food-Focused Day** - Tsukiji market for fresh seafood, Ginza exploration
5. **Modern Tokyo & Departure** - Tokyo Skytree or Tower for views, final shopping

**Food Strategy:**
- Mix ramen shops (¥800-1,200), casual izakaya, and one nice kaiseki lunch
- Don't miss street food and market experiences

**Budget:** Approximately ¥85,000-150,000 ($580-1,000 USD) for the full 5 days

The itinerary is saved to `./trips/tokyo-itinerary.md`.

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 CLAUDE.md, providing specific cost estimates and restaurant options.

Most importantly, notice what we did not have to include in our prompt — we did not say "research safety," "check the weather," or "save the itinerary to a file." All of that behavior originated from CLAUDE.md, which means that every time anyone on your team uses this agent, they will experience the same action-oriented, research-driven approach to trip planning with consistent output formatting.

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.