Claude Code 功能集成

Agent SDK 基于 Claude Code 构建，SDK Agent 可以访问相同的文件系统功能：项目指令（CLAUDE.md）、Skills、Hooks、Slash Commands 等。通过 settingSources 控制加载哪些文件系统配置。

核心机制

settingSources 三个来源：

来源	加载内容	位置
"project"	项目 CLAUDE.md、rules、skills、hooks、settings.json	<cwd>/.claude/ 及父目录
"user"	用户 CLAUDE.md、rules、skills、settings	~/.claude/
"local"	CLAUDE.local.md、settings.local.json	<cwd>/.claude/ 及父目录

默认行为：省略 settingSources 等同于 ["user", "project", "local"]，传空数组禁用文件系统配置。

不受 settingSources 控制的输入：

• Managed policy settings（始终加载）
• ~/.claude.json 全局配置（始终读取）
• Auto memory（~/.claude/projects/<project>/memory/，默认加载到 system prompt）

功能选择指南：

目标	使用	SDK 配置
项目级持久指令	CLAUDE.md	settingSources: ["project"]
按需加载的参考资料	Skills	settingSources + skills 选项
可复用工作流	Skills（可调用）	同上
隔离子任务	Subagents	agents 参数 + allowedTools: ["Agent"]
工具调用拦截/审计	Hooks	hooks 参数或 settings.json
外部服务集成	MCP	mcpServers 参数

关键细节

async for message in query(
    prompt="Help me refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],  # 加载 CLAUDE.md、skills、hooks
        allowed_tools=["Read", "Edit", "Bash"],
    ),
):
    ...

CLAUDE.md 加载层级：项目根目录、父目录（向上到仓库根）、子目录（按需加载）、用户级（~/.claude/CLAUDE.md）。多层级叠加，无硬性优先级，冲突时 Claude 自行解释。

Hooks 两种类型：

• 文件系统 Hooks（settings.json）：支持 shell 命令、HTTP、MCP 工具、prompt 评估、Agent 验证器，在主 Agent 和子 Agent 中都运行
• 编程式 Hooks（代码中注册）：只在主会话中运行，支持返回结构化决策

与其他概念的关联

• modifying-system-prompts - 通过 systemPrompt 注入上下文（vs CLAUDE.md）
• skills - Skills 详细使用指南
• hooks - Hooks 详细使用指南
• subagents - Subagents vs Agent Teams 的区别

实践要点

• 多租户部署必须设置 settingSources: [] 并禁用 auto memory（CLAUDE_CODE_DISABLE_AUTO_MEMORY=1），防止主机配置泄漏
• CLAUDE.md 注入到对话而非 system prompt，与任何 system prompt 配置兼容
• 每个功能都会增加上下文窗口占用，按需启用
• 子 Agent 与 Agent Teams 不同：子 Agent 是临时的、隔离的；Agent Teams 是多个独立 Claude Code 实例协作（CLI 功能）