[DOCS] [SDK Docs] Contradiction regarding automatic loading of CLAUDE.md files

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts

Section/Topic

The "Method 1: CLAUDE.md files (project-level instructions)" section, specifically the "How CLAUDE.md works with the SDK" subsection.

Current Documentation

The document contains two conflicting statements within the same section:

Statement A (Introductory paragraph):

"CLAUDE.md files provide project-specific context and instructions that are automatically read by the Agent SDK when it runs in a directory."

Statement B (How it works subsection):

"IMPORTANT: The SDK only reads CLAUDE.md files when you explicitly configure settingSources (TypeScript) or setting_sources (Python)."

What's Wrong or Missing?

There is a major internal contradiction. Statement A implies that simply having the file in the directory is enough for the SDK to "automatically" use it (similar to how the Claude Code CLI functions). However, Statement B (marked as "IMPORTANT") clarifies that this is an opt-in behavior requiring specific configuration of settingSources.

This is highly confusing for developers. If a user follows the introductory text, they will find that their agent ignores all project instructions because they didn't realize a configuration change was required to enable the feature.

Suggested Improvement

The introductory paragraph should be updated to remove the word "automatically" and instead mention the required configuration immediately to set proper expectations.

Suggested Text:

"CLAUDE.md files provide project-specific context and instructions that the Agent SDK can leverage when running in a directory. To maintain process isolation, the SDK does not access these files by default; you must explicitly enable the 'project' setting source in your options to load them."

Impact

High - Prevents users from using a feature

Additional Context

• This contradiction likely stems from the Agent SDK's recent move toward "isolation by default" (v0.1.0), where it no longer reads local filesystem settings automatically to prevent leakage in multi-tenant or CI/CD environments.
• Related documentation on settingSources can be found here: https://platform.claude.com/docs/en/agent-sdk/typescript#settingsource