📘 תיעוד 182

שינוי הנחיות מערכת

בחרו בין ערכת claude_code לבין הנחיית מערכת מותאמת אישית, והתאימו את ההתנהגות באמצעות CLAUDE.md, סגנונות פלט, append, או הנחיה מותאמת אישית במלואה.

הנחיות מערכת מגדירות את ההתנהגות, היכולות וסגנון התשובה של Claude. התחילו מערכת claude_code לכלי קוד בסגנון CLI או IDE, שבהם אדם צופה בעבודה ומכוון אותה. כתבו הנחיה משלכם לסוכנים עם משטח, זהות או מודל הרשאות שונים.

#איך הנחיות מערכת עובדות

הנחיית מערכת היא מערך ההוראות הראשוני שמעצב את אופן ההתנהגות של Claude לאורך שיחה. ל-Agent SDK יש שלוש נקודות התחלה עבורה:

• ברירת מחדל מינימלית: כשלא מגדירים systemPrompt ב-TypeScript או system_prompt ב-Python, ה-SDK משתמש בהנחיה מינימלית שמכסה קריאה לכלים אבל משמיטה את שאר התוכן של ערכת claude_code, כולל הוראות האבטחה והבטיחות שלה. זה שונה מ-claude -p, שמשתמש בהנחיית המערכת של Claude Code כברירת מחדל. אם עוברים מה-CLI ורוצים התנהגות תואמת, מגדירים את ערכת claude_code.
• ערכת claude_code: הנחיית המערכת שבה משתמש ה-CLI של Claude Code, עם הוראות שימוש בכלים והוראות אבטחה ובטיחות. מגדירים systemPrompt: { type: "preset", preset: "claude_code" } ב-TypeScript או system_prompt={"type": "preset", "preset": "claude_code"} ב-Python, ואפשר להוסיף append כדי להוסיף הוראות משלכם בסוף.
• מחרוזת מותאמת אישית: הנחיה שאתם כותבים בעצמכם. ה-SDK שולח רק את מה שאתם מספקים.

#בחירת נקודת התחלה

הגורם המכריע הוא עד כמה הסוכן שלכם דומה ל-Claude Code: סוכן קוד שפועל במאגר, כשאדם צופה בפלט הזורם ומכוון את העבודה. ככל שהמוצר רחוק יותר מזה, כך תרצו יותר לכתוב הנחיה משלכם.

"שונה מ-Claude Code" בדרך כלל אומר אחד מהבאים:

• משטח שונה: הפלט לא נקרא בטרמינל על ידי מי שהפעיל אותו. ממשקי צ'אט, צרכני פלט מובנה ואוטומציה שאינה קוד צריכים כל אחד הנחיה שמתאימה לאופן שבו הפלט שלהם מוצג ונבדק. אוטומציית קוד ללא השגחה, כמו משימת CI שמתקנת שגיאות lint או סוקרת diffs, עדיין מתאימה לערכה, כי העבודה עצמה היא זו שעבורה הערכה נכתבה.
• זהות שונה: הסוכן לא אמור להציג את עצמו כ-Claude Code. בוט תמיכה, עוזר לניתוח נתונים, או כל סוכן ייעודי לתחום צריכים שם, היקף ופרסונה משלהם.
• מודל הרשאות שונה: הסוכן רץ באופן אוטונומי בלי שאדם מאשר כל צעד, או פועל על קבוצת משאבים צרה. ההנחיה של Claude Code מניחה שאדם נמצא בלולאה עם גישה לערכת כלים מלאה.
• משימות שאינן קוד: רוב ההנחיה של Claude Code היא הנחיה לכתיבת קוד. עבור סוכני מחקר, תוכן או תפעול, ההנחיה הזו מתחרה בהוראות שאתם באמת צריכים.

טבלת ההשוואה מראה מה כל שיטת התאמה שומרת.

#התאמת התנהגות הסוכן

append ומחרוזת הנחיה מותאמת אישית משנים כל אחד את הנחיית המערכת ישירות, וסגנון פלט משנה את ההוראות ש-Claude Code נותן ל-Claude לכל תשובה. CLAUDE.md הולך בנתיב אחר: ה-SDK קורא אותו ומזריק את התוכן שלו לשיחה כהקשר פרויקט, כך שהוא מעצב התנהגות לצד הנחיית המערכת שתבחרו. גם Skills, hooks ו-permissions מעצבים התנהגות מחוץ להנחיית המערכת, והם מכוסים בעמודים נפרדים.

#קובצי CLAUDE.md להוראות ברמת הפרויקט

קובצי CLAUDE.md נותנים ל-Claude הקשר והוראות פרויקט מתמשכים. ה-SDK מזריק את התוכן שלהם לשיחה ומשאיר את הנחיית המערכת ללא שינוי, ולכן הם עובדים עם כל הגדרת הנחיית מערכת. למה לשים ב-CLAUDE.md, איפה למקם אותו, ואיך לכתוב הוראות יעילות, ראו מתי להוסיף ל-CLAUDE.md ואת שאר איך Claude זוכר את הפרויקט שלכם. הסעיף הזה מכסה את מה שייחודי ל-SDK: איך CLAUDE.md נטען.

ה-SDK קורא את CLAUDE.md כשמקור ההגדרות התואם מופעל: 'project' טוען את CLAUDE.md או .claude/CLAUDE.md מתיקיית העבודה, ו-'user' טוען את ~/.claude/CLAUDE.md. אפשרויות ברירת המחדל של query() מפעילות את שני המקורות, ולכן CLAUDE.md נטען אוטומטית. אם מגדירים settingSources ב-TypeScript או setting_sources ב-Python במפורש, כללו את המקורות שאתם צריכים. טעינת CLAUDE.md נשלטת על ידי מקורות הגדרות, לא על ידי ערכת claude_code.

#טעינת CLAUDE.md עם ה-SDK

כדי לטעון את CLAUDE.md, הגדירו את settingSources כך שיכלול את הרמה שבה נמצא ה-CLAUDE.md שלכם. הדוגמה למטה טוענת CLAUDE.md ברמת הפרויקט לצד ערכת claude_code, כך של-Claude יש גם את הנחיית סוכן הקוד וגם את המוסכמות של הפרויקט:

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

const messages = [];

for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Use Claude Code's system prompt
    },
    settingSources: ["project"] // Loads CLAUDE.md from project
  }
})) {
  messages.push(message);
}

// Now Claude has access to your project guidelines from CLAUDE.md

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

messages = []


async def main():
    async for message in query(
        prompt="Add a new React component for user profiles",
        options=ClaudeAgentOptions(
            system_prompt={
                "type": "preset",
                "preset": "claude_code",  # Use Claude Code's system prompt
            },
            setting_sources=["project"],  # Loads CLAUDE.md from project
        ),
    ):
        messages.append(message)


asyncio.run(main())

# Now Claude has access to your project guidelines from CLAUDE.md

כשמריצים אחת משתי הדוגמאות, ה-SDK מזרים הודעות בזמן ש-Claude עובד: הודעת init של המערכת, הודעות assistant, הודעות user שנושאות תוצאות כלים, והודעת תוצאה סופית עם תוצאת הסשן.

CLAUDE.md מתמשך בכל הסשנים בפרויקט, משותף עם הצוות דרך git, ומתגלה אוטומטית בלי שינויי קוד. הוא לא נטען אם מעבירים מערך settingSources ריק.

#סגנונות פלט להגדרות מתמשכות

סגנונות פלט הם מערכי הוראות שמורים שמשנים את התפקיד, הטון ופורמט הפלט של Claude. הם נשמרים כקובצי markdown ואפשר לעשות בהם שימוש חוזר בין סשנים ופרויקטים.

#יצירת סגנון פלט

סגנון פלט הוא קובץ markdown עם frontmatter למטא-נתונים, ואחריו תוכן ההנחיה. שמרו אותו ב-~/.claude/output-styles/ לסגנון ברמת המשתמש שזמין בכל פרויקט, או ב-.claude/output-styles/ במאגר לסגנון ברמת הפרויקט שאפשר לבצע לו commit ולשתף עם הצוות.

סגנון פלט מותאם אישית משמיט את הוראות הנדסת התוכנה של ערכת claude_code ומשתמש בהוראות שלכם. כדי לשמור אותן ולהוסיף את ההוראות שלכם מעליהן, הגדירו keep-coding-instructions: true ב-frontmatter. ההוראות האלה קיימות רק בהנחיית המערכת המלאה של Claude Code, ולכן להגדרה אין השפעה בסשן על הנחיית המערכת הקצרה יותר. הגדירו את CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT ל-0 כדי לבחור את ההנחיה המלאה בכל מודל. שמרו אותן כשהסוכן שלכם עדיין עושה עבודת הנדסת תוכנה. השמיטו אותן כשאתם מחליפים את התפקיד לגמרי.

הדוגמה למטה מגדירה פרסונת סקירת קוד ששומרת את הוראות הקוד, כי סקירת קוד עדיין מרוויחה מהנחיות האבטחה ואיכות הקוד של Claude Code. שמרו אותה כ-~/.claude/output-styles/code-reviewer.md כדי שתהיה זמינה בכל הפרויקטים:

---
name: Code Reviewer
description: Thorough code review assistant
keep-coding-instructions: true
---

You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)

#הפעלת סגנון פלט

אחרי היצירה, מפעילים סגנונות פלט כך:

• CLI: הריצו /output-style <style>, לדוגמה /output-style concise, או הריצו /config ובחרו אחד. הפקודה /output-style דורשת Claude Code בגרסה v2.1.269 או מאוחרת יותר.

• הגדרות: הגדירו outputStyle ב-.claude/settings.local.json

• TypeScript SDK: הגדירו outputStyle בתוך אובייקט settings המוטמע שמועבר ל-query(), או כוונו את settings לקובץ הגדרות שמגדיר אותו. outputStyle אינו שדה Options ברמה העליונה:

  העתק

  const options = { settings: { outputStyle: "Explanatory" } };

ב-Python SDK, הגדירו outputStyle דרך אפשרות settings, שמקבלת מחרוזת JSON כמו '{"outputStyle": "Explanatory"}' או נתיב לקובץ הגדרות שמגדיר אותו.

הערה למשתמשי SDK: סגנונות פלט נטענים כשכוללים settingSources: ['user'] או settingSources: ['project'] (TypeScript) / setting_sources=["user"] או setting_sources=["project"] (Python) באפשרויות.

#הוספה לערכת claude_code

אפשר להשתמש בערכת Claude Code עם מאפיין append כדי להוסיף הוראות מותאמות אישית, תוך שמירה על כל הפונקציונליות המובנית.

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

const messages = [];

for await (const message of query({
  prompt: "Help me write a Python function to calculate fibonacci numbers",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "Always include detailed docstrings and type hints in Python code."
    }
  }
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

messages = []


async def main():
    async for message in query(
        prompt="Help me write a Python function to calculate fibonacci numbers",
        options=ClaudeAgentOptions(
            system_prompt={
                "type": "preset",
                "preset": "claude_code",
                "append": "Always include detailed docstrings and type hints in Python code.",
            }
        ),
    ):
        messages.append(message)
        if isinstance(message, AssistantMessage):
            print(message.content)


asyncio.run(main())

#שיפור שמירת הנחיות במטמון בין משתמשים ומכונות

כברירת מחדל, שני סשנים שמשתמשים באותה ערכת claude_code ובאותו טקסט append עדיין לא יכולים לשתף רשומת מטמון של הנחיה כשמיקומי הזיכרון האוטומטי שלהם שונים. הערכה מטמיעה את המיקום הזה בהנחיית המערכת לפני טקסט ה-append שלכם. המיקום ברירת המחדל הוא נתיב מוחלט תחת ~/.claude/projects/, שנקרא על שם הנתיב של המאגר בדיסק, ולכן הוא שונה בין משתמשים, מכונות ועותקים.

תוכן CLAUDE.md ופרטי סביבה כמו תיקיית העבודה, הפלטפורמה, ה-shell וגרסת מערכת ההפעלה לא משפיעים על מטמון הנחיית המערכת, כי Claude Code מוסר אותם בשיחה, לא בהנחיית המערכת.

כדי שהנחיית המערכת תהיה זהה בין סשנים, הגדירו excludeDynamicSections: true ב-TypeScript או "exclude_dynamic_sections": True ב-Python. ההקשר לכל משתמש עובר להודעת המשתמש הראשונה, ובהנחיית המערכת נשארים רק הערכה הסטטית וטקסט ה-append שלכם, כך שהגדרות זהות חולקות רשומת מטמון בין משתמשים ומכונות.

[!NOTE]

excludeDynamicSections דורש @anthropic-ai/claude-agent-sdk בגרסה v0.2.98 או מאוחרת יותר, או claude-agent-sdk בגרסה v0.1.58 או מאוחרת יותר עבור Python. הגדירו אותו רק על צורת אובייקט הערכה. ה-SDK מתעלם ממנו כשמעבירים הנחיה מותאמת אישית במקום הערכה. כדי לשמור את הוראות ההנחיה המותאמת אישית במטמון ב-TypeScript SDK, ראו שמירת החלק הסטטי של הנחיה מותאמת אישית במטמון.

הדוגמה הבאה מצמידה בלוק append משותף ל-excludeDynamicSections, כדי שצי סוכנים יוכל לעשות שימוש חוזר באותה הנחיית מערכת שמורה במטמון:

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

for await (const message of query({
  prompt: "Triage the open issues in this repo",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "You operate Acme's internal triage workflow. Label issues by component and severity.",
      excludeDynamicSections: true
    }
  }
})) {
  // ...
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Triage the open issues in this repo",
        options=ClaudeAgentOptions(
            system_prompt={
                "type": "preset",
                "preset": "claude_code",
                "append": "You operate Acme's internal triage workflow. Label issues by component and severity.",
                "exclude_dynamic_sections": True,
            },
        ),
    ):
        ...


asyncio.run(main())

פשרות: הטקסט שיוצא מהנחיית המערכת עדיין מגיע ל-Claude, אבל בהודעת משתמש. הטקסט הזה הוא לפחות מיקום תיקיית הזיכרון האוטומטי, ולעיתים קרובות כל מקטע הזיכרון האוטומטי. להוראות בהודעת משתמש יש משקל נמוך במעט מאותו טקסט בהנחיית המערכת, ולכן Claude עשוי לעקוב אחרי הנחיות הזיכרון האוטומטי שלו בעקביות נמוכה יותר. הפעילו אפשרות זו כששימוש חוזר במטמון בין סשנים חשוב יותר מזה.

לדגל המקביל במצב CLI לא אינטראקטיבי, ראו --exclude-dynamic-system-prompt-sections.

#הנחיות מערכת מותאמות

אפשר לספק מחרוזת מותאמת כ-systemPrompt כדי להחליף את ברירת המחדל לגמרי בהנחיות שלך.

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

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
  prompt: "Create a data processing pipeline",
  options: {
    systemPrompt: customPrompt
  }
})) {
  messages.push(message);
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage

custom_prompt = """You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices"""

messages = []


async def main():
    async for message in query(
        prompt="Create a data processing pipeline",
        options=ClaudeAgentOptions(system_prompt=custom_prompt),
    ):
        messages.append(message)
        if isinstance(message, AssistantMessage):
            print(message.content)


asyncio.run(main())

ב-Python, טען הנחיה מותאמת גדולה מקובץ באמצעות system_prompt={"type": "file", "path": "..."} במקום להעביר אותה כמחרוזת. ה-Python SDK מעביר הנחיית מחרוזת כארגומנט אחד בשורת הפקודה לתהליך המשנה של ה-CLI, ולכן הנחיה שחורגת ממגבלת אורך הארגומנטים של מערכת ההפעלה נכשלת ביצירת התהליך לפני שנשלחת בקשת API כלשהי. ב-Linux השגיאה היא Argument list too long. ראה SystemPromptFile לסף של כל פלטפורמה ולהתנהגות ב-Windows.

#שמירת החלק הסטטי של הנחיה מותאמת במטמון

ב-TypeScript SDK אפשר להעביר הנחיה מותאמת כמערך של מחרוזות במקום מחרוזת אחת, עם הסמן SYSTEM_PROMPT_DYNAMIC_BOUNDARY בין החלק הסטטי לשאר. השתמש בזה כשההנחיה שלך משלבת הוראות זהות בכל בקשה עם הקשר שמשתנה בכל בקשה, כמו הלקוח או הכרטיס שהסוכן מטפל בו. כשמעבירים את שני החלקים כמחרוזת אחת, שינוי בחלק של הבקשה הנוכחית משנה את כל הנחיית המערכת, ולכן גם ההוראות הסטטיות מפספסות את המטמון. צורת המערך אינה זמינה ב-Python SDK. ClaudeAgentOptions מפרט את הצורות ש-system_prompt מקבל.

[!NOTE]

Claude Code מפצל את ההנחיה רק כשהוא קורא ל-Claude API ישירות או רץ ב-Claude Platform on AWS. בכל תצורה אחרת, כמו Amazon Bedrock, Agent Platform של Google Cloud, Microsoft Foundry, או שער LLM, הוא שולח את כל ההנחיה כבלוק אחד, כמו העברה של מחרוזת אחת. אותו דבר קורה בכל פעם שמגדירים CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

כדי לפצל את ההנחיה, ייבא את SYSTEM_PROMPT_DYNAMIC_BOUNDARY מ-@anthropic-ai/claude-agent-sdk והעבר אותו כרכיב מערך נפרד בין שני החלקים. ה-SDK שולח את המחרוזות שלפני הסמן כבלוק טקסט אחד ואת המחרוזות שאחריו כבלוק שני, לכל אחד נקודת עצירה משלו במטמון. בדוגמה למטה, סוכן תמיכה טוען את הוראות המיון שלו מקובץ ומקבל פרטים על כרטיס אחד בכל בקשה, כך שההוראות נשארות במטמון בזמן שפרטי הכרטיס משתנים:

import { readFile } from "node:fs/promises";
import { query, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from "@anthropic-ai/claude-agent-sdk";

// Identical on every request
const instructions = await readFile("triage-instructions.md", "utf8");
// Different on every request
const ticketContext = "Customer plan: Enterprise. Other open tickets from this customer: 3.";

for await (const message of query({
  prompt: "Triage ticket 4821",
  options: {
    systemPrompt: [instructions, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, ticketContext]
  }
})) {
  // ...
}

מעקב אחר אסימוני מטמון מתאר את השדות cache_creation_input_tokens ו-cache_read_input_tokens בכל הודעת תוצאה.

ה-SDK מרכיב את הבלוקים מהמערך כך:

• ה-SDK מחבר את המחרוזות בכל צד של הסמן עם שורה ריקה ביניהן ומסיר את הסמן עצמו, כך שטקסט הסמן לא מגיע אל Claude.
• אם כוללים את הסמן יותר מפעם אחת, הראשון הוא הפיצול וה-SDK מסיר את האחרים.
• אם משמיטים את הסמן, ה-SDK מחבר את כל המחרוזות לבלוק אחד, כמו העברה של מחרוזת אחת.

עם הדגלים --system-prompt או --system-prompt-file של ה-CLI, ההנחיה היא מחרוזת אחת, ולכן אין מערך שיישא את הסמן. כלול במקום זאת שורה שמכילה רק את __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ בין החלק הסטטי לחלק של הבקשה הנוכחית. Claude Code מפצל את ההנחיה בשורה הראשונה כזו לאותם שני בלוקים ומסיר את השורה הזו. נדרש Claude Code גרסה v2.1.275 או חדשה יותר.

ב-SDK, העדף את צורת המערך, שנושאת את הגבול בלי שורת סמן.

#שינוי ההנחיה של סשן קיים

כברירת מחדל, אם מעבירים append שונה או הנחיה מותאמת כשחוזרים לסשן עם resume או continue, Claude לא רואה אותה בתור הבא. Claude Code רושם את הנחיית המערכת בבקשה הראשונה של סשן ומשתמש מחדש ברשומה הזו עד שהסשן עובר compaction. הטקסט החדש נכנס לתוקף אחרי ה-compaction הזה, או בסשן חדש.

#עדכון ההוראות של Claude באמצע סשן

אם ההוראות ששמת בהנחיית המערכת צריכות להשתנות בזמן שסשן רץ, למשל כי המשתמש שלך העביר את הסוכן למצב קריאה בלבד או ערך את התצורה שלו באפליקציה שלך, שלח את ההוראות החדשות בשיחה במקום לשנות את systemPrompt:

• בהודעה הבאה שלך: כלול את ההוראות החדשות בהודעת המשתמש הבאה שאתה שולח.
• מהוק: החזר additionalContext מ-callback של הוק מסוג UserPromptSubmit או PostToolUse, כתוב כהצהרה עובדתית כמו "The workspace is now read-only". ה-SDK מכניס את הטקסט לשיחה בנקודה שבה ההוק הופעל, כך שההנחיה שנרשמה נשארת ללא שינוי.

#כיבוי הרישום בזמן שמשפרים ניסוח

בזמן שמשפרים ניסוח של הנחיה ורוצים שכל עריכה תגיע לסשן שממשיכים, הגדר את snapshot ל-false בצורת האובייקט של הנחיית המערכת. אז Claude Code בונה מחדש את ההנחיה בכל בקשה. השדה זמין בצורות ה-preset והמותאמת של systemPrompt ב-TypeScript ושל system_prompt ב-Python, ודורש @anthropic-ai/claude-agent-sdk גרסה v0.3.257 או חדשה יותר, או claude-agent-sdk גרסה v0.2.153 או חדשה יותר.

השאר את הרישום דולק בייצור. כשהרישום כבוי, append שונה או הנחיה מותאמת בסשן שהמשיכו מגיעים אל Claude בתור הבא, והבקשה הזו לא יכולה לעשות שימוש חוזר ב-מטמון ההנחיה של הסשן. במקום שבו ה-API אוכף preserved thinking, Claude גם מאבד את החשיבה שלו מתורות קודמים.

מחוץ ל-סשני ענן, אם מפעילים את Claude Code ב-מצב bare על ידי העברת --bare דרך extraArgs או הגדרת CLAUDE_CODE_SIMPLE=1, הרישום נשאר כבוי אלא אם מגדירים snapshot: true.

רישום של append או הנחיה מותאמת כברירת מחדל דורש Claude Code גרסה v2.1.265 או חדשה יותר, ש-TypeScript Agent SDK כולל החל מ-v0.3.265 ו-Python Agent SDK החל מ-v0.2.153. לפני Claude Code גרסה v2.1.268, סשנים שלא מושכים feature flags, כולל סשנים ב-Amazon Bedrock, ב-Agent Platform של Google Cloud וב-Microsoft Foundry, בנו מחדש את ההנחיה בכל בקשה ול-snapshot לא הייתה השפעה.

#הקשר ש-Claude Code מוסיף מחוץ להנחיית המערכת

תזכורות מערכת הן הודעות ש-Claude Code מוסיף לשיחה במהלך סשן כדי לתת ל-Claude הקשר, כמו התוכן של קובצי CLAUDE.md שלך או הערה שקובץ השתנה בדיסק. Claude Code שולח אותן בשיחה, לא בהנחיית המערכת, ולכן רובן מגיעות אל Claude בין אם משתמשים ב-preset של claude_code ובין אם מעבירים מחרוזת משלך כ-systemPrompt.

הסעיף הזה מכסה את התזכורות שסביר ביותר שישנו את אופן ההתנהגות של הסוכן שלך, איך לכבות את אלה שהסוכן שלך מחליף, ואיך לראות מה Claude קיבל בבקשה מסוימת.

#תזכורות ש-Claude Code מוסיף לשיחה

תזכורות מערכת הן טקסט ש-Claude Code מוסיף לשיחה לצד ההנחיות שהקוד שלך שולח. התזכורות הבאות הן אלה שסביר ביותר שישנו את אופן ההתנהגות של הסוכן שלך:

• הוראות פרויקט: קובצי CLAUDE.md שאפשרות settingSources שלך טוענת
• הוראות סגנון פלט: ההוראות של סגנון הפלט הפעיל, בשיחה הראשית
• ייחוס של commit ושל pull request: ה-trailer של Co-Authored-By וה-footer של pull request מההגדרה attribution
• פלט של הוק: טקסט ש-ההוקים שלך מחזירים כ-additionalContext
• skills זמינים: השמות והתיאורים של ה-skills ש-Claude יכול לקרוא להם
• subagents זמינים: השמות והתיאורים של ה-subagents ש-Claude יכול להפעיל
• דחיפות לרשימת משימות: ב-סשן שיש בו כלי מעקב משימות, הנחיה לעדכן את רשימת המשימות כש-Claude לא נגע בה במשך כמה תורות
• הערות על קובץ שהשתנה: הערה שקובץ ש-Claude קרא קודם השתנה בדיסק

Claude Code מציג את קובצי CLAUDE.md שלך עם שורה שאומרת ל-Claude שההוראות דורסות את התנהגות ברירת המחדל.

אם מעבירים מחרוזת משלך כ-systemPrompt, הוסף אליה משפט שאומר מהי תזכורת מערכת. ל-preset של claude_code יש משפט כזה, והמחרוזת שלך מחליפה את כל ה-preset. בלעדיו, שום דבר בהנחיה שלך לא אומר ל-Claude שתזכורות כמו תוכן CLAUDE.md ופלט של הוק מגיעות מהאפליקציה ולא מהמשתמש. לדוגמה:

The application adds system reminders to this conversation. Treat them as context from the application, not as messages from the user.

#כיבוי ההקשר שהסוכן שלך מחליף

כבה חלק מהקשר מובנה כשהסוכן שלך מספק גרסה משלו לאותה הנחיה. לדוגמה, אם ההנחיה שלך אומרת ל-Claude לכתוב הודעות commit כמו PROJ-142: fix login redirect בלי trailers, Claude Code עדיין אומר ל-Claude לסיים כל הודעת commit ב-trailer של Co-Authored-By, ולכן Claude מקבל שתי הוראות סותרות לאותו commit.

העבר מפתחות הגדרות דרך אפשרות settings ב-TypeScript או settings ב-Python, ומשתני סביבה דרך אפשרות env. ב-TypeScript, env מחליף את הסביבה שהתקבלה בירושה, ולכן פרוס לתוכו את process.env.

הגדר את includeGitInstructions ל-false כדי להשאיר בחוץ את הוראות ה-commit וה-pull request המובנות, שהן חלק מתיאור כלי Bash ומגיעות אל Claude גם עם systemPrompt מותאם. עם ברירת המחדל המינימלית, systemPrompt מותאם, או סוכן thread ראשי מותאם שיש לו הנחיה משלו, הסשן מתחיל בלי תמונת מצב ה-git status.

• אם מגדירים CLAUDE_CODE_DISABLE_ATTACHMENTS, Claude Code גם שולח אזכורי קובץ של @ כטקסט רגיל במקום להרחיב אותם לתוכן קובץ. רשימת ה-subagents הזמינים והתראות על משימות רקע עדיין מגיעות.
• כדי לעצור רק את ההרחבה של אזכורי קובץ של @, הגדר CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 במקום זאת, ב-Claude Code גרסה v2.1.299 או חדשה יותר. אז Claude מקבל את הנתיבים שהוזכרו וגם הערה לקרוא אותם עם כלי הקבצים שלו, וההוקים PreToolUse שלך רואים כל קריאת קובץ כקריאת כלי.

הדוגמה הבאה היא לסוכן שנושא כללי commit משלו ב-append. היא מגדירה את שני מפתחות attribution למחרוזות ריקות כדי להסיר את ה-trailer ואת ה-footer, ומכבה את includeGitInstructions כדי שהוראות תהליך העבודה של commit של Claude Code עצמו לא יתחרו בשלך:

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

for await (const message of query({
  prompt: "Commit the staged changes for ticket PROJ-142",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: "Write commit messages as: <ticket id>: <summary>. Add no trailers."
    },
    settings: {
      includeGitInstructions: false,
      attribution: { commit: "", pr: "" }
    },
    allowedTools: ["Bash(git *)"]
  }
})) {
  if (message.type === "result") console.log(message.subtype);
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Commit the staged changes for ticket PROJ-142",
        options=ClaudeAgentOptions(
            system_prompt={
                "type": "preset",
                "preset": "claude_code",
                "append": "Write commit messages as: <ticket id>: <summary>. Add no trailers.",
            },
            settings='{"includeGitInstructions": false, "attribution": {"commit": "", "pr": ""}}',
            allowed_tools=["Bash(git *)"],
        ),
    ):
        print(message)


asyncio.run(main())

כדי לאשר את השינוי, הרץ את הדוגמה במאגר עם שינויים ב-staging ובדוק את ה-commit החדש עם git log -1. ההודעה מסתיימת בלי trailer של Co-Authored-By.

#לראות מה Claude קיבל

זרם ההודעות של ה-SDK לא כולל תזכורות מערכת, ולכן קריאה של ההודעות שהקוד שלך מקבל לא תראה לך מה Claude ראה. כדי לראות אותן, רשום את הבקשות ש-Claude Code שולח:

• רישום בקשות גולמי: הגדר את OTEL_LOG_RAW_API_BODIES ל-file:<dir>. Claude Code כותב כל גוף בקשה לתיקייה הזו.
• שער שבשליטתך: כוון את ANTHROPIC_BASE_URL לפרוקסי שרושם גופי בקשות.

בבקשה שנרשמה, חפש במערך messages. תזכורת מופיעה בתוך הודעת משתמש עטופה בתגיות <system-reminder>, או, בחלק מהמודלים, כהודעה נפרדת עם התפקיד system.

#השוואה בין ארבע הגישות

ארבע שיטות ההתאמה נבדלות במיקום שלהן, בדרך שבה הן משותפות, ובמה שהן שומרות מה-preset claude_code.

"עם append" פירושו שימוש ב-systemPrompt: { type: "preset", preset: "claude_code", append: "..." } ב-TypeScript או ב-system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} ב-Python. CLAUDE.md לא משנה את ה-system prompt עצמו: ה-SDK מזריק את התוכן שלו לשיחה כהקשר פרויקט.

#שילוב גישות

הגישות מצטרפות זו לזו. output style מתמשך או CLAUDE.md קובעים את ההתנהגות לטווח ארוך, ו-append מוסיף שכבת הוראות ספציפיות לסשן מעליהם בלי לגעת בתצורה השמורה.

#שילוב output style עם תוספות ספציפיות לסשן

הדוגמה למטה מניחה ש-output style בשם Code Reviewer כבר פעיל. בלוק ה-append מוסיף שכבת תחומי מיקוד ספציפיים לסשן מעל הפרסונה, כך שסשן סקירה יחיד יכול לתת עדיפות ל-OAuth ולאחסון טוקנים בלי לשנות את ה-output style השמור:

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

// Assuming "Code Reviewer" output style is active (via /config or settings)
// Add session-specific focus areas
const messages = [];

for await (const message of query({
  prompt: "Review this authentication module",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code",
      append: `
        For this review, prioritize:
        - OAuth 2.0 compliance
        - Token storage security
        - Session management
      `
    }
  }
})) {
  messages.push(message);
}

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

# Assuming "Code Reviewer" output style is active (via /config or settings)
# Add session-specific focus areas
messages = []


async def main():
    async for message in query(
        prompt="Review this authentication module",
        options=ClaudeAgentOptions(
            system_prompt={
                "type": "preset",
                "preset": "claude_code",
                "append": """
                For this review, prioritize:
                - OAuth 2.0 compliance
                - Token storage security
                - Session management
                """,
            }
        ),
    ):
        messages.append(message)


asyncio.run(main())

#ראה גם

• Output styles: יצירה, ניהול ושיתוף של output styles עבור ה-CLI, כולל פורמט הקובץ ומיקומי האחסון
• How Claude remembers your project: מה לשים ב-CLAUDE.md, איפה למקם אותו, ואיך לכתוב הוראות פרויקט יעילות
• TypeScript SDK reference: הטיפוס המלא Options, כולל systemPrompt, settingSources ו-settings
• Python SDK reference: הטיפוס המלא ClaudeAgentOptions, כולל system_prompt ו-setting_sources
• Settings: ההפניה ל-settings.json, כולל היכן נשמרים output styles ותצורה אחרת