استفاده از قابلیت‌های Claude Code در SDK

این یک ترجمهٔ غیررسمی از مستندات Claude Code است که توسط مسیر تهیه شده. نسخهٔ مرجع و معتبر، مستندات رسمی انگلیسی است.

Load project instructions, skills, hooks, and other Claude Code features into your SDK agents.

Agent SDK روی همان بنیادِ Claude Code ساخته شده، یعنی ایجنت‌های SDKِ تو به همان قابلیت‌های فایل‌سیستم‌محور دسترسی دارند: دستورالعمل‌های پروژه (CLAUDE.md و قواعد)، Skillها، هوک‌ها و بیشتر.

وقتی settingSources را حذف می‌کنی، query() همان تنظیماتِ فایل‌سیستمِ Claude Code CLI را می‌خواند: تنظیماتِ کاربر، پروژه و محلی، فایل‌های CLAUDE.md، و Skillها، ایجنت‌ها و دستورهای .claude/. برای اجرا بدونِ این‌ها، settingSources: [] را بده، که ایجنت را به آنچه به‌صورتِ برنامه‌نویسی پیکربندی می‌کنی محدود می‌کند. تنظیماتِ سیاستِ مدیریت‌شده و پیکربندیِ سراسریِ ~/.claude.json صرف‌نظر از این گزینه خوانده می‌شوند. آنچه settingSources کنترل نمی‌کند را ببین.

برای مرورِ کلیِ مفهومیِ اینکه هر قابلیت چه می‌کند و کِی به کار می‌رود، Extend Claude Code را ببین.

کنترلِ تنظیماتِ فایل‌سیستم با settingSources

گزینه‌ی setting sources (setting_sources در Python، settingSources در TypeScript) کنترل می‌کند که SDK کدام تنظیماتِ فایل‌سیستم‌محور را بار کند. یک فهرستِ صریح بده تا منابعِ مشخصی را انتخاب کنی، یا یک آرایه‌ی خالی بده تا تنظیماتِ کاربر، پروژه و محلی را غیرفعال کنی.

این نمونه با تنظیمِ settingSources روی ["user", "project"] هم تنظیماتِ سطحِ کاربر و هم سطحِ پروژه را بار می‌کند:

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async for message in query(
    prompt="Help me refactor the auth module",
    options=ClaudeAgentOptions(
        # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
        # Together they give the agent access to CLAUDE.md, skills, hooks, and
        # permissions from both locations.
        setting_sources=["user", "project"],
        allowed_tools=["Read", "Edit", "Bash"],
    ),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if hasattr(block, "text"):
                print(block.text)
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(f"\nResult: {message.result}")

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

for await (const message of query({
  prompt: "Help me refactor the auth module",
  options: {
    // "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
    // Together they give the agent access to CLAUDE.md, skills, hooks, and
    // permissions from both locations.
    settingSources: ["user", "project"],
    allowedTools: ["Read", "Edit", "Bash"]
  }
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") console.log(block.text);
    }
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log(`\nResult: ${message.result}`);
  }
}

هر منبع تنظیمات را از یک مکانِ مشخص بار می‌کند، که در آن <cwd> دایرکتوریِ کاری‌ای است که از طریقِ گزینه‌ی cwd می‌دهی، یا اگر تنظیم نشده باشد دایرکتوریِ فعلیِ فرایند. برای تعریفِ کاملِ نوع، SettingSource (TypeScript) یا SettingSource (Python) را ببین.

منبع	چه چیزی بار می‌کند	مکان
"project"	CLAUDE.md پروژه، .claude/rules/*.md، Skillهای پروژه، هوک‌های پروژه، settings.json پروژه	<cwd>/.claude/ برای settings.json و هوک‌ها؛ <cwd> و هر دایرکتوریِ والد برای CLAUDE.md و قواعد؛ <cwd> و هر دایرکتوریِ والد تا ریشه‌ی مخزن برای Skillها
"user"	CLAUDE.md کاربر، ~/.claude/rules/*.md، Skillهای کاربر، تنظیماتِ کاربر	~/.claude/
"local"	CLAUDE.local.md، .claude/settings.local.json	<cwd>/.claude/ برای settings.local.json؛ <cwd> و هر دایرکتوریِ والد برای CLAUDE.local.md

حذفِ settingSources معادلِ ["user", "project", "local"] است.

گزینه‌ی cwd تعیین می‌کند که SDK ورودی‌های سطحِ پروژه را کجا بجوید. CLAUDE.md و قواعد از <cwd> و از هر دایرکتوریِ والد بار می‌شوند. Skillها از <cwd> و از هر دایرکتوریِ والد تا ریشه‌ی مخزن بار می‌شوند. settings.json و هوک‌های پروژه فقط از <cwd>/.claude/ بار می‌شوند، بدونِ فال‌بکِ دایرکتوریِ والد.

آنچه settingSources کنترل نمی‌کند

settingSources تنظیماتِ کاربر، پروژه و محلی را پوشش می‌دهد. چند ورودی صرف‌نظر از مقدارش خوانده می‌شوند:

ورودی	رفتار	برای غیرفعال‌سازی
تنظیماتِ سیاستِ مدیریت‌شده	همیشه وقتی روی میزبان حاضر باشد بار می‌شود	فایلِ تنظیماتِ مدیریت‌شده را حذف کن
پیکربندیِ سراسریِ ~/.claude.json	همیشه خوانده می‌شود	با CLAUDE_CONFIG_DIR در env جابه‌جایش کن
حافظه‌ی خودکار در ~/.claude/projects/<project>/memory/	به‌صورتِ پیش‌فرض به سیستم‌پرامپت بار می‌شود	autoMemoryEnabled: false را در تنظیمات تنظیم کن، یا CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 را در env
کانکتورهای MCPِ claude.ai	وقتی روشِ احراز هویتِ فعال یک اشتراکِ claude.ai باشد بار می‌شود. دادنِ mcpServers: {} آن‌ها را سرکوب نمی‌کند	strictMcpConfig: true را تنظیم کن، یا ENABLE_CLAUDEAI_MCP_SERVERS=false را در env

احتیاط

برای جداسازیِ چنداجاره‌ای (multi-tenant) به گزینه‌های پیش‌فرضِ query() تکیه نکن. چون ورودی‌های بالا صرف‌نظر از settingSources خوانده می‌شوند، یک فرایندِ SDK می‌تواند پیکربندیِ سطحِ میزبان و حافظه‌ی هر-دایرکتوری را برچیند. برای استقرارهای چنداجاره‌ای، هر اجاره را در فایل‌سیستمِ خودش اجرا کن و settingSources: [] به‌علاوه‌ی CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 را در env تنظیم کن. Secure deployment را ببین.

دستورالعمل‌های پروژه (CLAUDE.md و قواعد)

فایل‌های CLAUDE.md و فایل‌های .claude/rules/*.md به ایجنتت کانتکستِ ماندگار درباره‌ی پروژه‌ات می‌دهند: قراردادهای کدنویسی، دستورهای ساخت، تصمیم‌های معماری و دستورالعمل‌ها. وقتی settingSources شاملِ "project" باشد (مثلِ نمونه‌ی بالا)، SDK این فایل‌ها را در شروعِ نشست به کانتکست بار می‌کند. آن‌گاه ایجنت قراردادهای پروژه‌ات را دنبال می‌کند بی‌آنکه در هر پرامپت تکرارشان کنی.

مکان‌های بارگذاریِ CLAUDE.md

سطح	مکان	کِی بار می‌شود
پروژه (ریشه)	<cwd>/CLAUDE.md یا <cwd>/.claude/CLAUDE.md	settingSources شاملِ "project" باشد
قواعدِ پروژه	<cwd>/.claude/rules/*.md و .claude/rules/*.md در هر دایرکتوریِ والد	settingSources شاملِ "project" باشد
پروژه (دایرکتوری‌های والد)	فایل‌های CLAUDE.md در دایرکتوری‌های بالای cwd	settingSources شاملِ "project" باشد، در شروعِ نشست بار می‌شود
پروژه (دایرکتوری‌های فرزند)	فایل‌های CLAUDE.md در زیردایرکتوری‌های cwd	settingSources شاملِ "project" باشد، on-demand وقتی ایجنت فایلی در آن زیردرخت می‌خواند بار می‌شود
محلی	<cwd>/CLAUDE.local.md و CLAUDE.local.md در هر دایرکتوریِ والد	settingSources شاملِ "local" باشد
کاربر	~/.claude/CLAUDE.md	settingSources شاملِ "user" باشد
قواعدِ کاربر	~/.claude/rules/*.md	settingSources شاملِ "user" باشد

همه‌ی سطوح افزایشی‌اند: اگر هم فایلِ CLAUDE.md پروژه و هم کاربر وجود داشته باشد، ایجنت هر دو را می‌بیند. هیچ قاعده‌ی اولویتِ سخت‌گیرانه‌ای بینِ سطوح نیست؛ اگر دستورالعمل‌ها تناقض داشته باشند، نتیجه به این بستگی دارد که Claude چطور تفسیرشان کند. قواعدِ بی‌تناقض بنویس، یا اولویت را صریحاً در فایلِ مشخص‌تر بیان کن («این دستورالعمل‌های پروژه بر هر پیش‌فرضِ متناقضِ سطحِ کاربر اولویت دارند»).

نکته

همچنین می‌توانی کانتکست را مستقیماً از طریقِ systemPrompt بدونِ استفاده از فایل‌های CLAUDE.md تزریق کنی. Modify system prompts را ببین. وقتی می‌خواهی همان کانتکست بینِ نشست‌های تعاملیِ Claude Code و ایجنت‌های SDKِ تو به اشتراک گذاشته شود، از CLAUDE.md استفاده کن.

برای نحوه‌ی ساختاردهی و سازماندهیِ محتوای CLAUDE.md، Manage Claude’s memory را ببین.

Skillها

Skillها فایل‌های markdown هستند که به ایجنتت دانشِ تخصصی و ورک‌فلوهای قابلِ‌فراخوانی می‌دهند. برخلافِ CLAUDE.md (که هر نشست بار می‌شود)، Skillها on-demand بار می‌شوند. ایجنت توصیفِ Skillها را هنگامِ راه‌اندازی دریافت می‌کند و محتوای کامل را وقتی مرتبط باشد بار می‌کند.

Skillها از فایل‌سیستم از طریقِ settingSources کشف می‌شوند. وقتی گزینه‌ی skills روی query() حذف شده باشد، Skillهای کشف‌شده‌ی کاربر و پروژه فعال‌اند و ابزارِ Skill در دسترس است، مطابقِ رفتارِ CLI. برای کنترلِ اینکه کدام Skillها فعال باشند، skills را به‌صورتِ "all"، یک فهرستِ نامِ Skillها، یا [] برای غیرفعال کردنِ همه بده. وقتی skills تنظیم شده باشد، SDK ابزارِ Skill را به‌صورتِ خودکار به allowedTools اضافه می‌کند. اگر یک فهرستِ صریحِ tools هم بدهی، "Skill" را در آن فهرست بگنجان تا Claude بتواند Skillها را فراخوانی کند.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
    prompt="Review this PR using our code review checklist",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],
        skills="all",
        allowed_tools=["Read", "Grep", "Glob"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

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

// Skills in .claude/skills/ are discovered automatically
// when settingSources includes "project"
for await (const message of query({
  prompt: "Review this PR using our code review checklist",
  options: {
    settingSources: ["user", "project"],
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

یادداشت

Skillها باید به‌صورتِ آرتیفکت‌های فایل‌سیستم ساخته شوند (.claude/skills/<name>/SKILL.md). SDK یک API برنامه‌نویسی‌شده برای ثبتِ Skillها ندارد. برای جزئیاتِ کامل، Agent Skills in the SDK را ببین.

برای اطلاعاتِ بیشتر درباره‌ی ساخت و استفاده از Skillها، Agent Skills in the SDK را ببین.

هوک‌ها

SDK از دو راه برای تعریفِ هوک‌ها پشتیبانی می‌کند، و آن‌ها کنارِ هم اجرا می‌شوند:

• هوک‌های فایل‌سیستم: دستورهای شل که در settings.json تعریف می‌شوند، وقتی settingSources شاملِ منبعِ مربوط باشد بار می‌شوند. این‌ها همان هوک‌هایی هستند که برای نشست‌های تعاملیِ Claude Code پیکربندی می‌کنی.
• هوک‌های برنامه‌نویسی‌شده: توابعِ کال‌بک که مستقیماً به query() پاس داده می‌شوند. این‌ها در فرایندِ اپلیکیشنِ تو اجرا می‌شوند و می‌توانند تصمیم‌های ساخت‌یافته برگردانند. Control execution with hooks را ببین.

هر دو نوع در طولِ همان چرخه‌ی عمرِ هوک اجرا می‌شوند. اگر از قبل در .claude/settings.json پروژه‌ات هوک داری و settingSources: ["project"] را تنظیم کنی، آن هوک‌ها به‌صورتِ خودکار در SDK بدونِ پیکربندیِ اضافی اجرا می‌شوند.

کال‌بک‌های هوک ورودیِ ابزار را دریافت می‌کنند و یک دیکشنریِ تصمیم برمی‌گردانند. برگرداندنِ {} یعنی اجازه‌ی پیشرویِ ابزار. برای مسدود کردنِ اجرا، یک شیءِ hookSpecificOutput با permissionDecision: "deny" و یک permissionDecisionReason برگردان. این دلیل به‌عنوانِ نتیجه‌ی ابزار به Claude فرستاده می‌شود. فیلدهای سطحِ‌بالای decision و reason برای PreToolUse منسوخ‌اند. برای امضای کاملِ کال‌بک و انواعِ بازگشتی، راهنمای هوک‌ها را ببین.

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Destructive command blocked",
            }
        }
    return {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
    prompt="Refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads hooks from .claude/settings.json
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[audit_bash]),
            ]
        },
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

import { query, type HookInput, type HookJSONOutput } from "@anthropic-ai/claude-agent-sdk";

// PreToolUse hook callback. HookInput is a discriminated union on
// hook_event_name, so narrowing on it gives TypeScript the right
// tool_input shape for this event.
const auditBash = async (input: HookInput): Promise<HookJSONOutput> => {
  if (input.hook_event_name !== "PreToolUse") return {};
  const toolInput = input.tool_input as { command?: string };
  if (toolInput.command?.includes("rm -rf")) {
    return {
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "Destructive command blocked",
      },
    };
  }
  return {}; // Empty object: allow the tool to proceed
};

// Filesystem hooks from .claude/settings.json run automatically
// when settingSources loads them. You can also add programmatic hooks:
for await (const message of query({
  prompt: "Refactor the auth module",
  options: {
    settingSources: ["project"], // Loads hooks from .claude/settings.json
    hooks: {
      PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }]
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

کِی از کدام نوعِ هوک استفاده کنیم

نوعِ هوک	بهترین برای
فایل‌سیستم (settings.json)	به اشتراک گذاشتنِ هوک‌ها بینِ نشست‌های CLI و SDK. از "command" (اسکریپت‌های شل)، "http" (POST به یک نقطه‌ی پایانی)، "mcp_tool" (فراخوانیِ ابزارِ یک سرورِ MCPِ متصل)، "prompt" (LLM یک پرامپت را ارزیابی می‌کند) و "agent" (یک ایجنتِ راستی‌آزما تولید می‌کند) پشتیبانی می‌کند. این‌ها در ایجنتِ اصلی و هر ساب‌ایجنتی که تولید کند فعال می‌شوند.
برنامه‌نویسی‌شده (کال‌بک‌ها در query())	منطقِ مخصوصِ اپلیکیشن، تصمیم‌های ساخت‌یافته و یکپارچه‌سازیِ درون‌فرایندی. این‌ها هم داخلِ ساب‌ایجنت‌ها فعال می‌شوند. کال‌بک agent_id و agent_type را دریافت می‌کند تا تفکیک کند.

یادداشت

TypeScript SDK از رویدادهای هوکِ بیشتری نسبت به Python پشتیبانی می‌کند، شاملِ SessionStart، SessionEnd، TeammateIdle و TaskCompleted. برای جدولِ کاملِ سازگاریِ رویدادها، راهنمای هوک‌ها را ببین.

برای جزئیاتِ کاملِ هوک‌های برنامه‌نویسی‌شده، Control execution with hooks را ببین. برای نحوِ هوک‌های فایل‌سیستم، Hooks را ببین.

قابلیتِ درست را انتخاب کن

Agent SDK چند راه برای گسترشِ رفتارِ ایجنتت در اختیارت می‌گذارد. اگر مطمئن نیستی کدام را به کار ببری، این جدول هدف‌های رایج را به رویکردِ درست نگاشت می‌کند.

می‌خواهی…	از این استفاده کن	سطحِ SDK
قراردادهای پروژه‌ای بگذاری که ایجنت همیشه دنبالشان کند	CLAUDE.md	settingSources: ["project"] آن را خودکار بار می‌کند
به ایجنت موادِ مرجع بدهی که وقتی مرتبط باشد بارشان کند	Skills	settingSources + گزینه‌ی skills
یک ورک‌فلوی قابلِ‌بازاستفاده اجرا کنی (deploy، review، release)	Skillهای قابلِ‌فراخوانیِ کاربر	settingSources + گزینه‌ی skills
یک زیرکارِ جداشده را به یک کانتکستِ تازه بسپاری (research، review)	ساب‌ایجنت‌ها	پارامترِ agents + allowedTools: ["Agent"]
چند نمونه‌ی Claude Code را با فهرست‌های وظیفه‌ی مشترک و پیام‌رسانیِ مستقیمِ بین‌ایجنتی هماهنگ کنی	Agent teams	مستقیماً از طریقِ گزینه‌های SDK پیکربندی نمی‌شود. Agent teams یک قابلیتِ CLI است که در آن یک نشست نقشِ سرپرستِ تیم را بازی می‌کند و کار را در میانِ هم‌تیمی‌های مستقل هماهنگ می‌کند
منطقِ دترمینیستیک روی فراخوانی‌های ابزار اجرا کنی (ممیزی، مسدودسازی، دگرگونی)	هوک‌ها	پارامترِ hooks با کال‌بک‌ها، یا اسکریپت‌های شلِ بارشده از طریقِ settingSources
به Claude دسترسیِ ابزارِ ساخت‌یافته به یک سرویسِ بیرونی بدهی	MCP	پارامترِ mcpServers

نکته

ساب‌ایجنت‌ها در برابرِ agent teams: ساب‌ایجنت‌ها زودگذر و جداشده‌اند: گفتگوی تازه، یک وظیفه، خلاصه‌ای که به والد برمی‌گردد. Agent teams چند نمونه‌ی مستقلِ Claude Code را هماهنگ می‌کنند که یک فهرستِ وظیفه به اشتراک می‌گذارند و مستقیماً به هم پیام می‌دهند. Agent teams یک قابلیتِ CLI است. برای جزئیات، What subagents inherit و مقایسه‌ی agent teams را ببین.

هر قابلیتی که فعال می‌کنی به پنجره‌ی کانتکستِ ایجنتت اضافه می‌شود. برای هزینه‌های هر قابلیت و اینکه این قابلیت‌ها چطور روی هم لایه می‌شوند، Extend Claude Code را ببین.

منابعِ مرتبط

• Extend Claude Code: مرورِ کلیِ مفهومیِ همه‌ی قابلیت‌های گسترش، با جدول‌های مقایسه و تحلیلِ هزینه‌ی کانتکست
• Skills in the SDK: راهنمای کاملِ استفاده‌ی برنامه‌نویسی‌شده از Skillها
• Subagents: تعریف و فراخوانیِ ساب‌ایجنت‌ها برای زیرکارهای جداشده
• Hooks: رهگیری و کنترلِ رفتارِ ایجنت در نقطه‌های کلیدیِ اجرا
• Permissions: کنترلِ دسترسیِ ابزار با حالت‌ها، قواعد و کال‌بک‌ها
• System prompts: تزریقِ کانتکست بدونِ فایل‌های CLAUDE.md