תיעוד 130
שימוש בתכונות Claude Code ב-SDK
טעינת הוראות פרויקט, skills, hooks ותכונות נוספות של Claude Code לתוך סוכני ה-SDK שלכם.
ה-Agent SDK בנוי על אותו בסיס כמו Claude Code, מה שאומר שלסוכני ה-SDK שלכם יש גישה לאותן תכונות מבוססות מערכת קבצים: הוראות פרויקט (CLAUDE.md וכללים), skills, hooks ועוד.
כאשר משמיטים את settingSources, הפונקציה query() קוראת את אותן הגדרות מערכת קבצים כמו ה-CLI של Claude Code: הגדרות משתמש, פרויקט והגדרות מקומיות, קובצי CLAUDE.md, וכן skills, סוכנים ופקודות מתוך .claude/. כדי לרוץ בלעדיהם, העבירו settingSources: [], מה שמגביל את הסוכן רק למה שאתם מגדירים באופן תכנותי. הגדרות מדיניות מנוהלת (Managed policy settings) ותצורת ~/.claude.json הגלובלית נקראות ללא קשר לאפשרות זו. ראו על מה settingSources אינו שולט.
#שליטה בהגדרות מערכת הקבצים באמצעות settingSources
אפשרות מקורות ההגדרות (setting_sources ב-Python, settingSources ב-TypeScript) שולטת באילו הגדרות מבוססות מערכת קבצים ה-SDK טוען. העבירו רשימה מפורשת כדי לבחור במקורות ספציפיים, או העבירו מערך ריק כדי להשבית הגדרות משתמש, פרויקט והגדרות מקומיות.
דוגמה זו טוענת גם הגדרות ברמת המשתמש וגם הגדרות ברמת הפרויקט על ידי הגדרת settingSources לערך ["user", "project"]:
Python:
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
import asyncio
async def main():
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}")
asyncio.run(main())TypeScript:
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}`);
}
}כאשר קוד זה רץ, תגובת העוזר מודפסת ל-stdout, ולאחר מכן מודפסת שורת תוצאה סופית עם סיום ההרצה.
כל מקור טוען הגדרות ממיקום מסוים, כאשר <cwd> היא ספריית העבודה שאתם מעבירים דרך האפשרות cwd, או הספרייה הנוכחית של התהליך אם היא לא הוגדרה. להגדרת הטיפוס המלאה, ראו SettingSource (TypeScript) או SettingSource (Python).
| מקור | מה הוא טוען | מיקום |
|---|---|---|
"project" | settings.json ו-hooks של הפרויקט, CLAUDE.md ו-.claude/rules/*.md של הפרויקט, skills, פקודות וסוכני משנה של הפרויקט | <cwd>/.claude/ עבור settings.json ו-hooks, <cwd> וכל ספריית אב עבור CLAUDE.md וכללים, <cwd> וכל ספריית אב עד לשורש המאגר עבור skills, פקודות וסוכני משנה, ובנוסף התיקיות .claude/skills/, .claude/commands/ ו-.claude/agents/ של כל ספרייה שאתם מעבירים דרך האפשרות additionalDirectories או add_dirs, שה-SDK מעביר ל-Claude Code בתור --add-dir |
"user" | settings.json של המשתמש, CLAUDE.md ו-~/.claude/rules/*.md של המשתמש, skills, פקודות וסוכני משנה של המשתמש | ~/.claude/ עבור settings.json, CLAUDE.md וכללים, ~/.claude/skills/, ~/.claude/commands/ ו-~/.claude/agents/ עבור skills, פקודות וסוכני משנה |
"local" | CLAUDE.local.md, .claude/settings.local.json | <cwd>/.claude/ עבור settings.local.json, <cwd> וכל ספריית אב עבור CLAUDE.local.md |
השמטת settingSources שקולה ל-["user", "project", "local"].
האפשרות cwd קובעת היכן ה-SDK מחפש קלטים ברמת הפרויקט. קובץ settings.json ו-hooks של הפרויקט נטענים אך ורק מ-<cwd>/.claude/, ללא חיפוש חלופי בספריות אב.
#על מה settingSources אינו שולט
settingSources מכסה הגדרות משתמש, פרויקט והגדרות מקומיות. מספר קלטים נקראים ללא קשר לערך שלו:
| קלט | התנהגות | כיצד להשבית |
|---|---|---|
| הגדרות מדיניות מנוהלת (Managed policy settings) | מדיניות מנוהלת נקודת קצה, כגון MDM plist, מדיניות registry או קובץ הגדרות מנוהל, נטענת מהמארח. הגדרות מנוהלות שרת נמשכות ב-תצורה זכאית כאשר הסשן מאמת מול התחברות OAuth ארגונית או מפתח API מוגדר ישירות | מדיניות נקודת קצה: הסירו את קובץ ההגדרות המנוהל, ה-plist או מדיניות ה-registry מהמארח. הגדרות מנוהלות שרת: נשלטות על ידי מנהל הארגון שלכם, ולא ניתן להשבית אותן מתוך ה-SDK |
תצורה גלובלית ~/.claude.json | נקראת תמיד | העבירו מיקום באמצעות CLAUDE_CONFIG_DIR ב-env |
זיכרון אוטומטי ב-~/.claude/projects/<project>/memory/ | נטען לתוך הנחיית המערכת (system prompt) בתחילת הסשן. הסוכן כותב לשם זיכרונות חדשים באמצעות כלי Write ו-Edit הרגילים ולא באמצעות כלי זיכרון ייעודי, ולכן כלים אלה חייבים להיות מופעלים כדי שהסוכן ישמור זיכרונות | הגדירו autoMemoryEnabled: false בהגדרות, או CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 ב-env |
| מחברי MCP של claude.ai | נטענים כאשר הסשן מאמת באמצעות התחברות claude.ai שלכם. אינם נטענים כאשר CLAUDE_CODE_OAUTH_TOKEN מכיל טוקן שנוצר מ-claude setup-token, שיכול לבצע רק בקשות מודל. העברת mcpServers: {} אינה מבטלת את המחברים | הגדירו strictMcpConfig: true, disableClaudeAiConnectors: true בהגדרות, או ENABLE_CLAUDEAI_MCP_SERVERS=false ב-env |
רשומות deny תחת sandbox.credentials ורשומות mask של קבצים ב-~/.claude/settings.json | כאשר ארגז החול לפקודות פועל, Claude Code מחיל את רשומות ה-deny ושומר על רשומות ה-mask של credentials.files כמגבלות גם כאשר settingSources אינו כולל הגדרות משתמש. Claude Code משתמש ברשומות אלו רק כדי לצמצם את הגישה של פקודות בתוך ארגז החול | הסירו את הרשומות מ-~/.claude/settings.json |
אזהרה: אל תסתמכו על אפשרויות ברירת המחדל של
query()לצורך בידוד בין דיירים שונים (multi-tenant isolation). מאחר שהקלטים שלמעלה נקראים ללא קשר ל-settingSources, תהליך SDK יכול לקבל תצורה ברמת המארח וזיכרון פר ספרייה. עבור פריסות מרובות דיירים, הריצו כל דייר במערכת קבצים נפרדת והגדירוsettingSources: []יחד עםCLAUDE_CODE_DISABLE_AUTO_MEMORY=1ב-env. הגדרות מנוהלות שרת נמשכות כאשר התהליך מאמת באמצעות פרטי זיהוי ארגוניים, ובידוד מערכת קבצים אינו מסיר אותן. ראו פריסה מאובטחת.
#הוראות פרויקט (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", נטען לפי דרישה כאשר הסוכן קורא קובץ בתת-עץ זה |
| מקומי | <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. ראו שינוי הנחיות מערכת. השתמשו ב-CLAUDE.mdכאשר אתם רוצים שאותו הקשר ישותף בין סשנים אינטראקטיביים של Claude Code לבין סוכני ה-SDK שלכם.
למידע על אופן המבנה והארגון של תוכן CLAUDE.md, ראו ניהול הזיכרון של Claude.
#Skills
Skills הם קובצי markdown המעניקים לסוכן שלכם ידע ייעודי ותהליכי עבודה שניתן להפעיל. בשונה מ-CLAUDE.md (אשר נטען בכל סשן), skills נטענים לפי דרישה. הסוכן מקבל את תיאורי ה-skills בעת ההפעלה, וטוען את התוכן המלא כאשר הדבר רלוונטי.
ה-skills מתגלים ממערכת הקבצים באמצעות settingSources. כאשר משמיטים את אפשרות ה-skills ב-query(), ה-skills שהתגלו עבור המשתמש והפרויקט מופעלים וכלי ה-Skill זמין, בהתאם להתנהגות ה-CLI. כדי לקבוע אילו skills מופעלים, העבירו את skills בתור "all", רשימה של שמות skills, או [] כדי להשבית את כולם. כאשר skills מוגדר, ה-SDK מוסיף את כלי ה-Skill ל-allowedTools באופן אוטומטי. אם אתם מעבירים גם רשימת tools מפורשת, כללו בה את "Skill" כדי ש-Claude יוכל להפעיל skills.
Python:
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio
# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async def main():
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)
asyncio.run(main())TypeScript:
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);
}
}הערה: יש ליצור skills כתוצרי מערכת קבצים (
.claude/skills/<name>/SKILL.md). ל-SDK אין API תכנותי לרישום skills. ראו Agent Skills ב-SDK לפרטים מלאים.
#Hooks
ה-SDK תומך בשתי דרכים להגדרת hooks, והן פועלות זו לצד זו:
- Filesystem hooks: פקודות shell המוגדרות בתוך
settings.json, ונטענות כאשרsettingSourcesכולל את המקור הרלוונטי. אלו אותם hooks שמגדירים עבור סשנים אינטראקטיביים של Claude Code. - Programmatic hooks: פונקציות callback המועברות ישירות אל
query(). אלו רצות בתוך תהליך היישום שלכם ויכולות להחזיר החלטות מובנות. ראו שליטה בביצוע באמצעות hooks.
שני הסוגים מתבצעים במהלך אותו מחזור חיים של ה-hook. אם כבר יש לכם hooks בתוך .claude/settings.json של הפרויקט והגדרתם settingSources: ["project"], אותם hooks ירוצו ב-SDK באופן אוטומטי ללא הגדרה נוספת.
פונקציות callback של hooks מקבלות את קלט הכלי ומחזירות מילון החלטה (decision dict). החזרת {} מאפשרת לכלי להמשיך לפעול. כדי לחסום ביצוע, החזירו אובייקט hookSpecificOutput המכיל permissionDecision: "deny" וכן permissionDecisionReason. הסיבה נשלחת אל Claude בתור תוצאת הכלי. ראו את מדריך ה-hooks עבור חתימת ה-callback המלאה וסוגי ערכי ההחזרה.
Python:
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage
import asyncio
# 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, reserved for future abort-signal support
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 def main():
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)
asyncio.run(main())TypeScript:
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);
}
}#מתי להשתמש בכל סוג hook
| סוג hook | הכי מתאים עבור |
|---|---|
Filesystem (settings.json) | שיתוף hooks בין סשנים של CLI ו-SDK. תומך ב-"command" (סקריפטים של shell), "http" (בקשת POST לנקודת קצה), "mcp_tool" (קריאה לכלי של שרת MCP מחובר), "prompt" (מודל שפה מעריך פרומפט), ו-"agent" (מפעיל סוכן מאמת). אלה מופעלים בסוכן הראשי ובכל סוכני המשנה שהוא מפעיל. |
Programmatic (פונקציות callback ב-query()) | לוגיקה ייעודית ליישום, החלטות מובנות ושילוב בתוך התהליך (in-process). אלה מופעלים גם בתוך סוכני משנה. קלט ה-hook, שהוא הארגומנט הראשון של ה-callback, כולל את השדות agent_id ו-agent_type המזהים איזה סוכן הפעיל את ה-hook. |
הערה: ה-SDK של TypeScript תומך באירועי hook נוספים מעבר ל-Python, כולל
SessionStart,SessionEnd,TeammateIdleו-TaskCompleted. ראו את מדריך ה-hooks עבור תאימות האירועים המלאה.