اجرای برنامه‌نویسیِ Claude Code

Agent SDK همان ابزارها، حلقه‌ی ایجنت و مدیریتِ کانتکستی را در اختیارت می‌گذارد که Claude Code را به کار می‌اندازد. این SDK هم به‌صورت یک CLI برای اسکریپت‌ها و CI/CD در دسترس است، و هم به‌شکلِ بسته‌های Python و TypeScript برای کنترلِ برنامه‌نویسیِ کامل.

برای اجرای Claude Code در حالتِ غیرتعاملی، -p را همراهِ پرامپتت و هر کدام از گزینه‌های CLI پاس بده:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

این صفحه استفاده از Agent SDK از طریقِ CLI (claude -p) را پوشش می‌دهد. برای بسته‌های Python و TypeScript SDK با خروجی‌های ساختاریافته، callbackهای تأییدِ ابزار و آبجکت‌های پیامِ بومی، به مستنداتِ کاملِ Agent SDK سر بزن.

استفاده‌ی پایه

پرچمِ -p (یا --print) را به هر دستورِ claude اضافه کن تا غیرتعاملی اجرا شود. همه‌ی گزینه‌های CLI با -p کار می‌کنند، از جمله:

--continue برای ادامه‌ی گفتگوها
--allowedTools برای تأییدِ خودکارِ ابزارها
--output-format برای خروجیِ ساختاریافته

این مثال سؤالی درباره‌ی کدبیست از Claude می‌پرسد و پاسخ را چاپ می‌کند:

claude -p "What does the auth module do?"

شروعِ سریع‌تر با bare mode

--bare را اضافه کن تا با رد شدن از کشفِ خودکارِ Hooks، Skills، پلاگین‌ها، سرورهای MCP، حافظه‌ی خودکار و CLAUDE.md، زمانِ راه‌اندازی کاهش یابد. بدونِ آن، claude -p همان کانتکستی را بارگذاری می‌کند که یک نشستِ تعاملی بارگذاری می‌کرد، شاملِ هر چیزی که در دایرکتوریِ کاری یا ~/.claude پیکربندی شده باشد.

bare mode برای CI و اسکریپت‌هایی مفید است که نیاز داری روی هر ماشین نتیجه‌ی یکسانی بگیری. یک hook در ~/.claudeِ یک هم‌تیمی یا یک سرورِ MCP در .mcp.jsonِ پروژه اجرا نمی‌شود، چون bare mode هیچ‌وقت آن‌ها را نمی‌خواند. فقط پرچم‌هایی که صریحاً پاس می‌دهی اثر دارند.

این مثال یک کارِ خلاصه‌سازیِ یک‌باره را در bare mode اجرا می‌کند و ابزارِ Read را از پیش تأیید می‌کند تا فراخوانی بدونِ پرسشِ مجوز کامل شود:

claude --bare -p "Summarize this file" --allowedTools "Read"

در bare mode، Claude به ابزارهای Bash، خواندنِ فایل و ویرایشِ فایل دسترسی دارد. هر کانتکستی که لازم داری را با یک پرچم پاس بده:

برای بارگذاریِ	از این استفاده کن
افزوده‌های پرامپتِ سیستمی	`--append-system-prompt`, `--append-system-prompt-file`
تنظیمات	`--settings <file-or-json>`
سرورهای MCP	`--mcp-config <file-or-json>`
ایجنت‌های سفارشی	`--agents <json>`
یک پلاگین	`--plugin-dir <path>`, `--plugin-url <url>`

bare mode از OAuth و خواندنِ keychain رد می‌شود. احرازِ هویتِ Anthropic باید از ANTHROPIC_API_KEY یا یک apiKeyHelper در JSONِ پاس‌داده‌شده به --settings بیاید. Bedrock، Vertex و Foundry از اعتبارنامه‌های همیشگیِ ارائه‌دهنده‌ی خود استفاده می‌کنند.

کارهای پس‌زمینه هنگامِ خروج

اگر Claude در طولِ یک اجرای claude -p یک کارِ Bashِ پس‌زمینه را آغاز کند، مثلاً یک dev server یا یک watch build، آن کار حدودِ پنج ثانیه پس از آنکه Claude نتیجه‌ی نهاییِ خود را برگرداند و stdin بسته شد، خاتمه می‌یابد. این مهلتِ کوتاه به کاری که درست بعد از نتیجه تمام می‌شود اجازه می‌دهد همچنان خروجی‌اش را تحویل دهد. پیش از نسخه‌ی v2.1.163، یک پراسسِ پس‌زمینه‌ای که هرگز خارج نمی‌شد، فراخوانیِ claude -p را به‌طورِ نامحدود باز نگه می‌داشت.

مثال‌ها

این مثال‌ها الگوهای رایجِ CLI را برجسته می‌کنند. برای CI و سایرِ فراخوانی‌های اسکریپتی، --bare را اضافه کن تا هر چیزی که اتفاقاً به‌صورتِ محلی پیکربندی شده را برندارند.

داده را از میانِ Claude لوله کن

حالتِ غیرتعاملی stdin را می‌خواند، پس می‌توانی مثلِ هر ابزارِ خط‌فرمانِ دیگری داده را به داخل لوله کنی و پاسخ را به بیرون هدایت کنی.

این مثال یک build log را به داخلِ Claude لوله می‌کند و توضیح را در یک فایل می‌نویسد:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

با --output-format json، payloadِ پاسخ شاملِ total_cost_usd و یک تفکیکِ هزینه به‌ازای هر مدل است، پس فراخواننده‌های اسکریپتی می‌توانند هزینه‌ی هر فراخوانی را بدونِ مراجعه به داشبوردِ استفاده رهگیری کنند.

افزودنِ Claude به یک build script

می‌توانی یک فراخوانیِ غیرتعاملی را داخلِ یک اسکریپت بپیچی تا از Claude به‌عنوانِ یک linter یا بازبینِ مخصوصِ پروژه استفاده کنی.

این اسکریپتِ package.json، diff نسبت به main را به داخلِ Claude لوله می‌کند و از آن می‌خواهد تایپوها را گزارش دهد. لوله کردنِ diff یعنی Claude برای خواندنِ آن نیازی به مجوزِ Bash ندارد، و کوتیشن‌های دوگانه‌ی escapeشده اسکریپت را برای Windows قابلِ‌حمل نگه می‌دارند:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

دریافتِ خروجیِ ساختاریافته

از --output-format برای کنترلِ نحوه‌ی برگرداندنِ پاسخ‌ها استفاده کن:

text (پیش‌فرض): خروجیِ متنِ ساده
json: JSONِ ساختاریافته با نتیجه، شناسه‌ی نشست و فراداده
stream-json: JSONِ خط‌به‌خط برای استریمِ بلادرنگ

این مثال یک خلاصه‌ی پروژه را به‌صورتِ JSON همراه با فرادادهٔ نشست برمی‌گرداند، که نتیجه‌ی متنی در فیلدِ result قرار دارد:

claude -p "Summarize this project" --output-format json

برای گرفتنِ خروجی‌ای که با یک schemaِ مشخص هم‌خوان باشد، از --output-format json همراه با --json-schema و یک تعریفِ JSON Schema استفاده کن. پاسخ شاملِ فراداده درباره‌ی درخواست (شناسه‌ی نشست، usage و غیره) است، که خروجیِ ساختاریافته در فیلدِ structured_output قرار دارد.

این مثال نامِ توابع را استخراج می‌کند و آن‌ها را به‌صورتِ یک آرایه از رشته‌ها برمی‌گرداند:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

از ابزاری مثلِ jq برای پارسِ پاسخ و استخراجِ فیلدهای مشخص استفاده کن:

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

استریمِ پاسخ‌ها

از --output-format stream-json همراه با --verbose و --include-partial-messages استفاده کن تا توکن‌ها را همان‌طور که تولید می‌شوند دریافت کنی. هر خط یک آبجکتِ JSON است که یک رویداد را بازنمایی می‌کند:

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

مثالِ زیر از jq استفاده می‌کند تا روی text deltaها فیلتر کند و فقط متنِ در حالِ استریم را نمایش دهد. پرچمِ -r رشته‌های خام (بدونِ کوتیشن) را خروجی می‌دهد و -j بدونِ خطِ جدید به هم می‌چسباند تا توکن‌ها پیوسته استریم شوند:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

وقتی یک درخواستِ API با خطایی قابلِ‌تلاشِ‌مجدد شکست بخورد، Claude Code پیش از تلاشِ مجدد یک رویدادِ system/api_retry منتشر می‌کند. می‌توانی از این برای نمایشِ پیشرفتِ تلاشِ مجدد یا پیاده‌سازیِ منطقِ backoffِ سفارشی استفاده کنی.

فیلد	نوع	توضیح
`type`	`"system"`	نوعِ پیام
`subtype`	`"api_retry"`	این را به‌عنوانِ یک رویدادِ تلاشِ مجدد شناسایی می‌کند
`attempt`	integer	شماره‌ی تلاشِ فعلی، که از ۱ شروع می‌شود
`max_retries`	integer	کلِ تلاش‌های مجازِ مجدد
`retry_delay_ms`	integer	میلی‌ثانیه تا تلاشِ بعدی
`error_status`	integer یا null	کدِ وضعیتِ HTTP، یا `null` برای خطاهای اتصال که پاسخِ HTTP ندارند
`error`	string	دسته‌ی خطا: `authentication_failed`، `oauth_org_not_allowed`، `billing_error`، `rate_limit`، `overloaded`، `invalid_request`، `model_not_found`، `server_error`، `max_output_tokens` یا `unknown`
`uuid`	string	شناسه‌ی یکتای رویداد
`session_id`	string	نشستی که رویداد به آن تعلق دارد

رویدادِ system/init فرادادهٔ نشست را گزارش می‌دهد، شاملِ مدل، ابزارها، سرورهای MCP و پلاگین‌های بارگذاری‌شده. این نخستین رویداد در استریم است مگر اینکه CLAUDE_CODE_SYNC_PLUGIN_INSTALL تنظیم شده باشد، که در آن صورت رویدادهای plugin_install پیش از آن می‌آیند. از فیلدهای پلاگین برای ناموفق کردنِ CI هنگامی که یک پلاگین بارگذاری نشد استفاده کن:

فیلد	نوع	توضیح
`plugins`	array	پلاگین‌هایی که با موفقیت بارگذاری شدند، هر کدام با `name` و `path`
`plugin_errors`	array	خطاهای زمانِ بارگذاریِ پلاگین، هر کدام با `plugin`، `type` و `message`. شاملِ نسخه‌های وابستگیِ برآورده‌نشده و خطاهای بارگذاریِ `--plugin-dir` مثلِ مسیرِ گم‌شده یا آرشیوِ نامعتبر. پلاگین‌های متأثر تنزل می‌یابند و از `plugins` غایب‌اند. وقتی خطایی نباشد این کلید حذف می‌شود

وقتی CLAUDE_CODE_SYNC_PLUGIN_INSTALL تنظیم شده باشد، Claude Code در حالی که پلاگین‌های marketplace پیش از نخستین نوبت نصب می‌شوند، رویدادهای system/plugin_install منتشر می‌کند. از این‌ها برای نمایشِ پیشرفتِ نصب در UIِ خودت استفاده کن.

فیلد	نوع	توضیح
`type`	`"system"`	نوعِ پیام
`subtype`	`"plugin_install"`	این را به‌عنوانِ یک رویدادِ نصبِ پلاگین شناسایی می‌کند
`status`	`"started"`، `"installed"`، `"failed"` یا `"completed"`	`started` و `completed` کلِ نصب را در بر می‌گیرند؛ `installed` و `failed` تک‌تکِ marketplaceها را گزارش می‌دهند
`name`	string، اختیاری	نامِ marketplace، که روی `installed` و `failed` حاضر است
`error`	string، اختیاری	پیامِ شکست، که روی `failed` حاضر است
`uuid`	string	شناسه‌ی یکتای رویداد
`session_id`	string	نشستی که رویداد به آن تعلق دارد

برای استریمِ برنامه‌نویسی با callbackها و آبجکت‌های پیام، به استریمِ بلادرنگِ پاسخ‌ها در مستنداتِ Agent SDK سر بزن.

تأییدِ خودکارِ ابزارها

از --allowedTools استفاده کن تا Claude بتواند بدونِ پرسش از ابزارهای مشخصی استفاده کند. این مثال یک test suite را اجرا می‌کند و شکست‌ها را رفع می‌کند، و به Claude اجازه می‌دهد دستورهای Bash را اجرا کند و فایل‌ها را بدونِ درخواستِ مجوز بخواند/ویرایش کند:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

برای تعیینِ یک خطِ پایه برای کلِ نشست به‌جای فهرست کردنِ تک‌تکِ ابزارها، یک حالتِ مجوز پاس بده. dontAsk هر چیزی را که در قواعدِ permissions.allowِ تو یا مجموعه‌ی دستورهای فقط‌خواندنی نباشد رد می‌کند، که برای اجراهای قفل‌شده‌ی CI مفید است. acceptEdits به Claude اجازه می‌دهد فایل‌ها را بدونِ پرسش بنویسد و همچنین دستورهای رایجِ فایل‌سیستمی مثلِ mkdir، touch، mv و cp را خودکار تأیید می‌کند. سایرِ دستورهای shell و درخواست‌های شبکه همچنان به یک ورودیِ --allowedTools یا یک قاعده‌ی permissions.allow نیاز دارند، وگرنه هنگامِ تلاش برای یکی از آن‌ها اجرا متوقف می‌شود:

claude -p "Apply the lint fixes" --permission-mode acceptEdits

ساختنِ یک کامیت

این مثال تغییراتِ stageشده را بازبینی می‌کند و یک کامیت با پیامِ مناسب می‌سازد:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

پرچمِ --allowedTools از نحوِ قاعده‌ی مجوز استفاده می‌کند. *ِ انتهایی تطبیقِ پیشوندی را فعال می‌کند، پس Bash(git diff *) هر دستوری را که با git diff شروع شود مجاز می‌کند. فاصله‌ی پیش از * مهم است: بدونِ آن، Bash(git diff*) با git diff-index هم تطبیق می‌یافت.

سفارشی‌سازیِ پرامپتِ سیستمی

از --append-system-prompt استفاده کن تا دستورالعمل‌هایی اضافه کنی در حالی که رفتارِ پیش‌فرضِ Claude Code حفظ می‌شود. این مثال یک diffِ PR را به Claude لوله می‌کند و به آن دستور می‌دهد برای آسیب‌پذیری‌های امنیتی بازبینی کند:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

برای گزینه‌های بیشتر از جمله --system-prompt برای جایگزینیِ کاملِ پرامپتِ پیش‌فرض، پرچم‌های پرامپتِ سیستمی را ببین.

ادامه‌ی گفتگوها

از --continue برای ادامه‌ی آخرین گفتگو، یا از --resume همراه با یک شناسه‌ی نشست برای ادامه‌ی یک گفتگوی مشخص استفاده کن. این مثال یک بازبینی را اجرا می‌کند، سپس پرامپت‌های پیگیرانه می‌فرستد:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

اگر چند گفتگو را هم‌زمان اجرا می‌کنی، شناسه‌ی نشست را بگیر تا یکیِ مشخص را ازسر بگیری:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

هر دو دستور را از همان دایرکتوری اجرا کن: جست‌وجوی شناسه‌ی نشست به دایرکتوریِ پروژه‌ی فعلی و git worktreeهای آن محدود است. برای قواعدِ کاملِ دامنه، ازسر گرفتنِ یک نشست را ببین.

گام‌های بعدی

شروعِ سریعِ Agent SDK: نخستین ایجنتت را با Python یا TypeScript بساز
مرجعِ CLI: همه‌ی پرچم‌ها و گزینه‌های CLI
GitHub Actions: از Agent SDK در ورک‌فلوهای GitHub استفاده کن
GitLab CI/CD: از Agent SDK در پایپ‌لاین‌های GitLab استفاده کن