نحوه‌ی استفاده‌ی Claude Code از prompt caching

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

prompt caching باعث می‌شود Claude Code سریع‌تر و کم‌هزینه‌تر کار کند. بدون کش، API در هر نوبت کلِ تاریخچه‌ات را دوباره پردازش می‌کرد. با کش، آنچه را قبلاً پردازش کرده دوباره استفاده می‌کند و فقط برای چیزی که تغییر کرده کارِ تازه انجام می‌دهد.

Claude Code خودش prompt caching را برایت مدیریت می‌کند، مگر اینکه غیرفعالش کنی. با این حال دانستنِ نحوه‌ی کارِ prompt caching مفید است، چون بعضی اکشن‌ها کش را باطل می‌کنند و پاسخِ بعدی را تا وقتی کش دوباره ساخته شود کندتر و گران‌تر می‌کنند. این صفحه پوشش می‌دهد که این اکشن‌ها کدام‌اند، چرا بعضی تنظیمات تا یک راه‌اندازیِ مجدد اعمال نمی‌شوند، و چطور کارایی کش را وقتی استفاده زیاد به نظر می‌رسد بررسی کنی.

کش چطور سازمان‌دهی شده

هر بار که در Claude Code پیامی می‌فرستی، یک درخواستِ API تازه ساخته می‌شود. مدل چیزی را بین درخواست‌ها به یاد نمی‌آورد، پس Claude Code کلِ کانتکست را دوباره می‌فرستد: system prompt، کانتکستِ پروژه‌ات، هر پیام و نتیجه‌ی ابزارِ پیشین، و پیامِ جدیدت. محتوای جدید در انتها اضافه می‌شود، یعنی بیشترِ هر درخواست عیناً همان درخواستِ قبلی است. prompt caching روشی است که API با آن از پردازشِ دوباره‌ی بخشی که تغییر نکرده پرهیز می‌کند.

API با تطبیقِ ابتدای هر درخواست — که prefix نامیده می‌شود — با محتوایی که اخیراً پردازش کرده، کش می‌کند. در یک نوبتِ عادی، prefix کلِ درخواستِ قبلی است و فقط آخرین رد‌و‌بدل جدید است. تطبیق دقیق است، پس یک تغییر در هر جای prefix همه‌ی چیزی را که بعد از آن می‌آید دوباره محاسبه می‌کند. کشِ per-file یا per-segment وجود ندارد. برای سازوکارِ زیربنایی، نحوه‌ی کارِ prompt caching را در مرجعِ API ببین.

برای بیشترین بهره از تطبیقِ prefix، Claude Code هر درخواست را طوری مرتب می‌کند که محتوایی که بین نوبت‌ها به‌ندرت تغییر می‌کند اول بیاید:

لایه	محتوا	چه‌وقت تغییر می‌کند
System prompt	دستورهای اصلی، تعریفِ ابزارها، output style	وقتی مجموعه‌ی تعریفِ ابزارهای بارگذاری‌شده تغییر کند، یا Claude Code ارتقا یابد
کانتکستِ پروژه	CLAUDE.md، حافظه‌ی خودکار، قواعدِ بدونِ scope	وقتی نشست شروع شود، یا بعد از /clear یا /compact
مکالمه	پیام‌های تو، پاسخ‌های Claude، نتایجِ ابزار	هر نوبت

تغییری در لایه‌ی مکالمه، system prompt و کانتکستِ پروژه را کش‌شده باقی می‌گذارد. تغییری در system prompt همه‌چیز را باطل می‌کند، چون حالا همه‌ی محتوای بعدی پشتِ یک prefixِ متفاوت می‌نشیند. ستونِ سوم به‌جای فهرستی کامل، محرک‌های متداول را می‌آورد، و بخش‌های زیر مجموعه‌ی کامل را پوشش می‌دهند، از جمله محتوایی مثل output style که در شروعِ نشست ثابت می‌شود.

قاعده‌ی تطبیقِ prefix بیشترِ رفتارهای این صفحه را توضیح می‌دهد. برای مثال Plan mode و بارگذاریِ skill دستورهایشان را به‌صورتِ پیامِ مکالمه اضافه می‌کنند، پس prefixِ کش‌شده دست‌نخورده می‌ماند.

دو تنظیم اصلاً بخشی از متنِ prompt نیستند، پس در جدولِ لایه‌ها نمی‌آیند، اما هر دو بخشی از کلیدِ کش‌اند:

• مدل: هر مدل کشِ خودش را دارد. تعویضِ مدل کلِ درخواست را دوباره محاسبه می‌کند حتی وقتی محتوا یکسان است. تعویضِ مدل را در پایین ببین.
• سطحِ effort: هر سطحِ effort برای همان مدل کشِ خودش را دارد. تغییرِ آن در میانه‌ی نشست کلِ درخواست را دوباره محاسبه می‌کند، و Claude Code قبل از اعمالِ تغییر از تو تأیید می‌گیرد. تغییرِ سطحِ effort را در پایین ببین.

نکته

مدل و سطحِ effort را در ابتدای نشست انتخاب کن، بعد /compact را برای وقفه‌های طبیعی بینِ کارها نگه دار. هرچه در میانه‌ی کار تغییرِ کمتری بدهی، نرخِ اصابتِ کشَت بالاتر است.

کش کجا زندگی می‌کند

کش‌گذاری سمتِ سرور انجام می‌شود، در همان زیرساختی که مدلت را سرویس می‌دهد. اینکه آن کجاست بستگی به نحوه‌ی احرازِ هویتت دارد:

• API key، اشتراکِ Claude، یا Claude Platform on AWS: کش در زیرساختِ Anthropic زندگی می‌کند و از طریقِ Claude API دسترسی‌پذیر است
• Bedrock یا Vertex AI: کش در زیرساختِ سرویس‌دهیِ ارائه‌دهنده‌ی ابرت زندگی می‌کند
• Foundry: درخواست‌ها به زیرساختِ Anthropic مسیریابی می‌شوند
• ANTHROPIC_BASE_URL سفارشی یا LLM gateway: کش هرجا که درخواست‌هایت به آن فوروارد می‌شوند زندگی می‌کند، و اینکه کش کار می‌کند یا نه بستگی به gateway دارد

برای اینکه هر ارائه‌دهنده چه چیزی را ذخیره و پردازش می‌کند، data usage را ببین. کش هرجا که باشد، ورودی‌ها بعد از مدتی بی‌فعالیتی منقضی می‌شوند، و طولِ عمرِ کش در پایین TTL و نحوه‌ی تمدیدش را پوشش می‌دهد.

اکشن‌هایی که کش را باطل می‌کنند

این اکشن‌ها باعث می‌شوند درخواستِ بعدی بخشی یا کلِ کش را از دست بدهد. یک نوبتِ یک‌باره‌ی کندتر و گران‌تر می‌بینی، که بعد از آن prefixِ جدید کش می‌شود. بیشترشان وقتی بدانی هزینه دارند در میانه‌ی کار قابلِ پرهیزند. تعویضِ مدل تا وقتی نوبتِ کندِ پس از آن را نبینی ممکن است رایگان به نظر برسد.

• تعویضِ مدل
• تغییرِ سطحِ effort
• روشن‌کردنِ fast mode
• اتصال یا قطعِ یک سرورِ MCP
• فعال یا غیرفعال‌کردنِ یک پلاگین
• انکارِ کاملِ یک ابزار
• Compact‌کردنِ مکالمه
• ارتقای Claude Code

تعویضِ مدل

هر مدل کشِ خودش را دارد. تعویض با /model یعنی درخواستِ بعدی کلِ تاریخچه‌ی مکالمه را بدون هیچ اصابتِ کشی می‌خواند، هرچند محتوا یکسان است.

تنظیمِ مدلِ opusplan در plan mode به Opus و در اجرا به Sonnet می‌رسد، پس هر تغییرِ وضعیتِ plan mode یک تعویضِ مدل است و کشی تازه شروع می‌کند.

Automatic model fallback روی Fable 5 هم یک تعویضِ مدل است. وقتی یک طبقه‌بندِ ایمنی درخواستی را علامت بزند، Claude Code آن را روی مدلِ پیش‌فرضِ Opus دوباره اجرا می‌کند و نشست همان‌جا ادامه می‌یابد.

تغییرِ سطحِ effort

کش علاوه بر مدل، با سطحِ effort هم کلید می‌خورد، پس تعویض با /effort یعنی درخواستِ بعدی کلِ تاریخچه‌ی مکالمه را بدون هیچ اصابتِ کشی می‌خواند. وقتی مکالمه‌ای شروع شده باشد، Claude Code قبل از اعمالِ تغییرِ effortی که کش را باطل کند یک دیالوگِ تأیید نشان می‌دهد. تغییری که به همان سطحِ از قبل فعال برسد — مثلِ تنظیمِ صریحِ پیش‌فرضِ مدل — دیالوگ را رد می‌کند و کش را نگه می‌دارد.

روشن‌کردنِ fast mode

فعال‌کردنِ fast mode یک هدرِ درخواست اضافه می‌کند که بخشی از کلیدِ کش است، پس درخواستِ بعدی کلِ تاریخچه‌ی مکالمه را بدون هیچ اصابتِ کشی می‌خواند. آن توکن‌های ورودیِ بدونِ کش با نرخ‌های fast mode محاسبه می‌شوند، و به همین خاطر روشن‌کردنش در ابتدای نشست کم‌هزینه‌تر از روشن‌کردنش عمیقاً در میانه‌ی یک نشستِ طولانی است. فعال‌کردنِ fast mode از یک مدلِ غیرِ Opus هم مدلت را تعویض می‌کند، که خودش به‌تنهایی کشی تازه شروع می‌کند.

این هزینه یک‌بار به‌ازای هر مکالمه اعمال می‌شود. بعد از اولین نوبتِ fast mode، Claude Code همچنان هدر را می‌فرستد و فقط تنظیمِ سرعتِ درخواست را تغییر می‌دهد، که بخشی از کلیدِ کش نیست. خاموش‌کردنِ fast mode، بازگشتِ خودکار به سرعتِ استاندارد بعد از یک rate limit، و دوباره روشن‌کردنش بعداً، همگی کش را نگه می‌دارند. /clear و /compact این را بازنشانی می‌کنند، چون در آن نقاط کش را به‌هرحال دوباره می‌سازند.

یادداشت

نگه‌داشتنِ هدر در طولِ تغییرِ وضعیت‌ها به Claude Code نسخه‌ی v2.1.86 یا بالاتر نیاز دارد. در نسخه‌های قدیمی‌تر، هر تغییرِ وضعیتِ fast mode و هر بازگشتِ ناشی از rate-limit کش را باطل می‌کند.

اتصال یا قطعِ یک سرورِ MCP

تعریفِ ابزارها در لایه‌ی system prompt می‌نشیند، پس وقتی مجموعه‌ی تعریفِ ابزارهای موجود در درخواست بین نوبت‌ها تغییر کند کش باطل می‌شود. تغییرِ وضعیتِ ابزارِ advisor یک استثناست: تعریفش بعد از نقطه‌ی شکستِ کش می‌نشیند، پس فعال یا غیرفعال‌کردنِ /advisor prefixِ کش‌شده را دست‌نخورده نگه می‌دارد. اینکه تغییرِ یک سرورِ MCP این کار را بکند یا نه بستگی به این دارد که ابزارهایش با tool search به‌تعویق‌افتاده باشند یا در prefix بارگذاری شده باشند:

• ابزارهای به‌تعویق‌افتاده، پیش‌فرض روی مدل‌های پشتیبانی‌شده: اتصال، قطع، یا تغییرِ فهرستِ ابزارهای یک سرور فقط محتوای جدید اضافه می‌کند و چیزی را که از قبل کش شده برهم نمی‌زند.
• ابزارهای بارگذاری‌شده در prefix: هر تغییری در آن‌ها کش را باطل می‌کند. این وقتی رخ می‌دهد که tool search در دسترس نباشد یا غیرفعال باشد، مثلِ مدل‌های Haiku، روی Vertex AI، یا با یک gatewayِ ANTHROPIC_BASE_URL سفارشی. همچنین برای سرور یا ابزاری که alwaysLoad علامت خورده، و برای تعریف‌هایی که با بارگذاریِ مبتنی بر آستانه جلو نگه داشته می‌شوند رخ می‌دهد.

وقتی ابزارها در prefix بارگذاری می‌شوند، شایع‌ترین علتِ یک ابطال، اتصال یا قطعِ یک سرور در میانه‌ی نشست است، که می‌تواند بدون هیچ اقدامی از سوی تو رخ دهد: پروسه‌ی یک سرورِ stdio خارج می‌شود، یک نشستِ HTTP منقضی می‌شود، یا یک سرور بعد از یک خطای گذرا خودکار دوباره وصل می‌شود. یک سرورِ متصل هم می‌تواند یک به‌روزرسانیِ پویای ابزار ارسال کند که فهرستِ ابزارش را تغییر دهد.

ویرایشِ پیکربندیِ MCP به‌خودیِ‌خود کش را تغییر نمی‌دهد. پیکربندیِ جدید فقط بعد از یک راه‌اندازیِ مجدد اعمال می‌شود، که زمانی است که سرور وصل یا قطع می‌شود.

فعال یا غیرفعال‌کردنِ یک پلاگین

پلاگین‌ها چند نوع کامپوننت را بسته‌بندی می‌کنند، و هزینه‌ی یک تغییر به این بستگی دارد که پلاگین کدام کامپوننت‌ها را فراهم می‌کند. Skillها، commandها، agentها، hookها، سرورهای LSP، monitorها و themeها هرگز کش را باطل نمی‌کنند: هرچه به درخواست اضافه کنند بعد از مکالمه‌ی موجود اضافه می‌شود، پس درخواستِ بعدی بهای محتوای جدید را می‌پردازد اما همه‌چیزِ قبل از آن را همچنان از کش می‌خواند.

استثنا پلاگینی است که سرورهای MCP فراهم می‌کند. فعال یا غیرفعال‌کردنِ یکی از همان قواعدِ اتصال یا قطعِ یک سرورِ MCP پیروی می‌کند: کش وقتی ابزارهای سرور به‌تعویق‌افتاده باشند زنده می‌ماند، و درخواستِ بعدی وقتی در prefix بارگذاری شوند کلِ مکالمه را دوباره می‌خواند.

تغییراتِ پلاگین وقتی /reload-plugins را اجرا کنی یا نشستی تازه شروع کنی اعمال می‌شوند. هزینه — چه اعلان‌های اضافه‌شده و چه یک خوانشِ کاملِ مجدد — در اولین نوبتِ بعد از reload نمایان می‌شود، نه وقتی /plugin install، /plugin enable، یا /plugin disable را اجرا می‌کنی. {/* min-version: 2.1.163 */}از نسخه‌ی v2.1.163، وقتی یک reload خوانشِ کاملِ مجدد را راه‌اندازی کند، /reload-plugins یک هشدار نشان می‌دهد و reload را اعمال نمی‌کند. --force را پاس بده تا به‌هرحال اعمال شود.

غیرفعال‌کردنِ پلاگینی که زودتر در همان نشست فعال کرده بودی، شکلِ قبلیِ درخواست را بازمی‌گرداند. اگر آن prefix هنوز در طولِ عمرِ کشَش باشد، درخواستِ بعدی به‌جای بازسازی، ورودیِ کشِ قدیمی‌تر را می‌خواند.

انکارِ کاملِ یک ابزار

افزودنِ یک نامِ خامِ ابزار مثلِ Bash یا WebFetch به‌عنوان یک قاعده‌ی انکار (deny rule) آن ابزار را به‌کلی از کانتکستِ Claude حذف می‌کند. تعریفِ ابزارهای داخلی در لایه‌ی system prompt بارگذاری می‌شود، پس افزودن یا حذفِ یکی از این قواعد در میانه‌ی نشست کش را باطل می‌کند. تغییر در نوبتِ بعدی اعمال می‌شود، چه آن را از طریقِ /permissions اضافه کنی چه با ویرایشِ مستقیمِ یک فایلِ تنظیمات.

فقط قاعده‌ی انکاری که در جایگاهِ نامِ ابزار تطبیق یابد این اثر را دارد: یک نامِ خامِ ابزار، شکلِ معادلِ Bash(*)، یا یک glob روی نامِ ابزار مثلِ "*". یک glob که فقط ابزارهای MCP را تطبیق دهد، مثلِ "mcp__*"، آن ابزارها را به همان روش حذف می‌کند اما وقتی ابزارهای تطبیق‌یافته به‌تعویق‌افتاده باشند — که پیش‌فرض است — کش را دست‌نخورده می‌گذارد، چون تعریف‌های به‌تعویق‌افتاده هرگز در prefixِ کش‌شده نبوده‌اند. قواعدِ انکارِ scope‌دار مثلِ Bash(rm *)، و همه‌ی قواعدِ allow و ask، تغییری در ابزارهایی که Claude می‌بیند نمی‌دهند. Claude Code آن‌ها را وقتی Claude تلاش به فراخوانی می‌کند بررسی می‌کند و prefix را دست‌نخورده می‌گذارد.

Compact‌کردنِ مکالمه

Compaction تاریخچه‌ی پیام‌هایت را با یک خلاصه جایگزین می‌کند. این بنا بر طراحی لایه‌ی مکالمه را باطل می‌کند، چون درخواستِ بعدی تاریخچه‌ای جدید و کوتاه‌تر دارد که با تاریخچه‌ی قدیم prefixِ مشترکی ندارد. Claude Code لایه‌ی system prompt را دوباره استفاده می‌کند و کانتکستِ پروژه را از دیسک بازخوانی می‌کند، که فقط اگر CLAUDE.md و حافظه از شروعِ نشست تغییر نکرده باشند اصابتِ کش دارد.

برای تولیدِ خلاصه، Claude Code یک درخواستِ یک‌باره با همان system prompt، ابزارها و تاریخچه‌ی مکالمه‌ات می‌فرستد، به‌علاوه‌ی یک دستورِ خلاصه‌سازی که به‌عنوانِ پیامِ نهاییِ کاربر اضافه می‌شود. چون prefixِ تو را به اشتراک می‌گذارد، آن درخواست به‌جای پردازشِ دوباره‌ی کلِ تاریخچه، کشِ موجود را می‌خواند. بیشترِ زمانِ compaction صرفِ تولیدِ خلاصه می‌شود، نه یک از‌دست‌رفتنِ کش. نوبتی که در پی می‌آید کشِ مکالمه را فقط برای خلاصه‌ی بسیار کوتاه‌تر بازمی‌سازد، پس نوبتِ پس از compaction بخشِ کند نیست.

نکته

Compaction وقتی به سودِ توست که کانتکستی که دور می‌ریزی محتوایی است که دیگر به آن نیاز نداری. برای انتخابِ زمانِ سربارش، /compact را در یک وقفه‌ی طبیعیِ کارت اجرا کن، مثلِ بینِ کارها، به‌جای اینکه منتظرِ راه‌اندازیِ auto-compaction در میانه‌ی کار بمانی. اگر مسیری را پیموده‌ای که می‌خواهی به‌کلی رهایش کنی، به‌جایش با /rewind به نوبتی پیشین برگرد. Rewind به prefixی که از قبل کش شده برمی‌گردد، به‌جای ساختنِ یکی تازه آن‌طور که compaction می‌کند.

ارتقای Claude Code

یک نسخه‌ی جدیدِ Claude Code معمولاً system prompt یا تعریفِ ابزارها را به‌روز می‌کند، پس اولین درخواستِ بعد از یک ارتقا کش را از بالا بازمی‌سازد. Auto-update نسخه‌های جدید را در پس‌زمینه دانلود می‌کند اما آن‌ها را در راه‌اندازیِ بعدی اعمال می‌کند، هرگز در میانه‌ی نشست، پس این را به‌صورتِ یک نوبتِ اولِ بدونِ کش بعد از راه‌اندازیِ مجدد می‌بینی نه یک غافل‌گیری در میانه‌ی نشست. DISABLE_AUTOUPDATER=1 را تنظیم کن تا کنترل کنی ارتقاها کِی اعمال شوند.

یادداشت

ازسرگیریِ یک نشست بعد از یک ارتقا کلِ تاریخچه‌ی مکالمه را بدون هیچ اصابتِ کشی دوباره پردازش می‌کند، چون تاریخچه حالا پشتِ یک system promptِ متفاوت می‌نشیند. هزینه با طولِ مکالمه‌ی ازسرگرفته‌شده مقیاس می‌گیرد، پس نوبتِ اولِ بازگشت به یک نشستِ طولانی می‌تواند گران‌ترین درخواستی باشد که می‌فرستی.

اکشن‌هایی که کش را نگه می‌دارند

این اکشن‌ها یا به انتهای مکالمه اضافه می‌کنند یا اصلاً درخواست را لمس نمی‌کنند. بعضی‌شان، مثلِ ویرایشِ CLAUDE.md یا تغییرِ output style، همچنین دلیلِ این هستند که تغییرِ یک تنظیم تا یک راه‌اندازیِ مجدد منتظر می‌ماند تا اعمال شود.

• ویرایشِ فایل‌ها در مخزنت
• ویرایشِ CLAUDE.md در میانه‌ی نشست
• تغییرِ output style
• تغییرِ permission mode
• فراخوانیِ skillها و commandها
• اجرای /recap
• Rewind‌کردنِ مکالمه
• ساختنِ یک ساب‌ایجنت

ویرایشِ فایل‌ها در مخزنت

محتوای فایل فقط وقتی واردِ کانتکست می‌شود که Claude آن را بخواند، و خوانش‌ها به مکالمه اضافه می‌شوند. ویرایشِ فایلی که Claude قبلاً خوانده، خوانشِ پیشین در تاریخچه را به‌صورتِ عقب‌گرد تغییر نمی‌دهد. در عوض، Claude Code یک <system-reminder> اضافه می‌کند که تغییرِ فایل را اطلاع می‌دهد، و Claude در صورتِ نیاز دوباره آن را می‌خواند.

ویرایشِ CLAUDE.md در میانه‌ی نشست

فایل‌های CLAUDE.md در ریشه‌ی پروژه و در سطحِ کاربر یک‌بار در شروعِ نشست خوانده و در حافظه نگه داشته می‌شوند. ویرایش‌شان در میانه‌ی نشست کش را باطل نمی‌کند، اما ویرایش هم اعمال نمی‌شود. Claude با همان نسخه‌ای که در شروعِ نشست بارگذاری شد کار می‌کند. محتوای جدید در /clear، /compact، یا راه‌اندازیِ مجددِ بعدی بارگذاری می‌شود.

فایل‌های تودرتوی CLAUDE.md در زیرپوشه‌ها و قواعد با frontmatterِ paths: دیرتر بارگذاری می‌شوند، وقتی Claude اولین بار فایلی منطبق را بخواند. ویرایشِ یکی از آن‌ها قبل از بارگذاری‌اش اثر می‌گذارد. بعد از بارگذاری، محتوا بخشی از تاریخچه‌ی مکالمه است، پس یک ویرایشِ میانه‌ی نشست آن را به‌صورتِ عقب‌گرد تغییر نمی‌دهد.

تغییرِ output style

Output style بخشی از system prompt است، که Claude Code یک‌بار در شروعِ نشست می‌خواند. تغییرش از طریقِ /config یا تنظیمِ outputStyle در میانه‌ی نشست کش را باطل نمی‌کند، اما تغییر هم اعمال نمی‌شود. Claude با همان style که در شروعِ نشست بارگذاری شد به کار ادامه می‌دهد. style جدید در /clear یا راه‌اندازیِ مجددِ بعدی بارگذاری می‌شود.

تغییرِ permission mode

تعویض بینِ permission modeها، مثلاً از default به accept edits، system prompt یا تعریفِ ابزارها را تغییر نمی‌دهد، پس تغییرِ mode از نظرِ کش امن است. استثنا plan mode با تنظیمِ مدلِ opusplan است، که با ورود یا خروج از plan mode مدل را بینِ Opus و Sonnet تعویض می‌کند. این، تغییرِ mode را به یک تعویضِ مدل تبدیل می‌کند.

فراخوانیِ skillها و commandها

Skillها و commandها دستورهایشان را به‌عنوانِ پیام‌های کاربر در نقطه‌ی فراخوانی تزریق می‌کنند. هیچ‌چیزِ پیشین در مکالمه تغییر نمی‌کند.

اجرای /recap

/recap یک خلاصه برای نمایش در ترمینالت تولید می‌کند. برخلافِ /compact، خلاصه را به‌جای جایگزینیِ تاریخچه‌ی پیام‌هایت به‌عنوانِ خروجیِ command اضافه می‌کند، پس prefixِ کش‌شده دست‌نخورده می‌ماند.

Rewind‌کردنِ مکالمه

/rewind مکالمه‌ات را به نوبتی پیشین کوتاه می‌کند. تاریخچه‌ی باقی‌مانده همان محتوایی است که کش در آن نقطه از آن ساخته شده بود، و لایه‌های system prompt و کانتکستِ پروژه تغییر نکرده‌اند، پس درخواستِ بعدی به ورودیِ کشِ پیشین اصابت می‌کند. هر نوبت از آن زمان به بعد از آن prefix خوانده، که ورودی را حتی اگر نوبتِ اصلی قدیمی‌تر از TTL بوده گرم نگه داشته است.

بازگردانیِ checkpointهای فایل در کنارِ مکالمه اثرِ جداگانه‌ای روی کش ندارد. محتوای فایل فقط وقتی واردِ کانتکست می‌شود که Claude آن را بخواند، درست مثلِ ویرایشِ فایل‌ها در مخزنت.

طولِ عمرِ کش

prefixهای کش‌شده بعد از مدتی بی‌فعالیتی منقضی می‌شوند. هر درخواست که به کش اصابت کند تایمر را بازنشانی می‌کند، پس کش تا وقتی به کار ادامه دهی گرم می‌ماند. بعد از یک شکافِ به‌اندازه‌ی کافی طولانی، درخواستِ بعدی کلِ ورودی را دوباره محاسبه و کش را دوباره برقرار می‌کند، و به همین خاطر نوبتِ اولِ بازگشت بعد از دور‌شدن می‌تواند به‌طورِ محسوسی کندتر باشد.

زمانِ زنده‌ماندن (TTL) کنترل می‌کند که کش چه‌قدر شکاف را دوام می‌آورد. API دو تا ارائه می‌دهد: یک TTL پنج‌دقیقه‌ای، و یک TTL یک‌ساعته که کش را در طولِ وقفه‌های طولانی‌تر گرم نگه می‌دارد اما نوشتنِ کش را با نرخی بالاتر محاسبه می‌کند. Claude Code TTL را بر اساسِ نحوه‌ی احرازِ هویتت برایت انتخاب می‌کند، و می‌توانی با متغیرهای محیطی بازنویسی‌اش کنی.

روی اشتراکِ Claude

روی اشتراکِ Claude، Claude Code TTL یک‌ساعته را خودکار درخواست می‌کند. استفاده در پلنت گنجانده شده و به‌ازای هر توکن محاسبه نمی‌شود، پس TTL طولانی‌تر برایت هیچ هزینه‌ی اضافه‌ای ندارد و فقط روی مدتِ گرم‌ماندنِ کشَت اثر می‌گذارد.

اگر از سقفِ استفاده‌ی پلنت گذشته‌ای و Claude Code از اعتبارهای استفاده خرج می‌کند، بابتِ آن استفاده محاسبه می‌شوی، پس Claude Code خودکار TTL را به پنج دقیقه پایین می‌آورد.

روی API key یا ارائه‌دهنده‌ی شخصِ ثالث

روی یک API key، Bedrock، Vertex، Foundry، یا Claude Platform on AWS، نرخ‌های به‌ازای توکن را می‌پردازی، پس TTL به‌صورتِ پیش‌فرض روی پنج دقیقه‌ی ارزان‌تر می‌ماند. برای انتخابِ TTL یک‌ساعته، ENABLE_PROMPT_CACHING_1H=1 را تنظیم کن.

روی Bedrock، پشتیبانی از prompt caching، حداقلِ طولِ prefixِ کش‌شدنی، و در دسترس‌بودنِ TTL یک‌ساعته همگی بسته به مدل فرق می‌کنند. اگر شمارشِ توکن‌های کش روی صفر بماند، مدل‌ها، مناطق و محدودیت‌های پشتیبانی‌شده را در مستنداتِ Bedrock بررسی کن.

بازنویسیِ TTL

FORCE_PROMPT_CACHING_5M=1 را تنظیم کن تا صرف‌نظر از احرازِ هویت، TTL پنج‌دقیقه‌ای اعمال شود. این وقتی مفید است که در حالِ عیب‌یابیِ رفتارِ کش هستی، دو TTL را مقایسه می‌کنی، یا یک ENABLE_PROMPT_CACHING_1H تنظیم‌شده در managed settings را بازنویسی می‌کنی.

دامنه‌ی کش

در Claude Code، کش عملاً به یک ماشین و یک پوشه محدود است. system prompt پوشه‌ی کاری، پلتفرم، shell، نسخه‌ی OS، و مسیرهای حافظه‌ی خودکار را در خود جای می‌دهد، پس دو نشست در پوشه‌های متفاوت prefixهای متفاوت می‌سازند و به کشِ یکدیگر اصابت نمی‌کنند. این شاملِ worktreeهای همان مخزن هم می‌شود، چون هر worktree پوشه‌ی کاریِ خودش را دارد.

نشست‌هایی که به‌صورتِ موازی در همان پوشه اجرا می‌کنی prefixهای منطبق می‌سازند و کشِ یکدیگر را می‌خوانند. نشست‌های متوالی فقط وقتی prefix را به اشتراک می‌گذارند که snapshotِ git status در شروع منطبق باشد، چون system prompt شاخه و کامیت‌های اخیر را هم ثبت می‌کند.

کشِ زیربناییِ API گسترده‌تر است. کش‌ها بینِ سازمان‌ها ایزوله‌اند، و روی بعضی ارائه‌دهنده‌ها بینِ workspaceها درونِ یک سازمان هم ایزوله‌اند. درونِ آن مرزها، هر دو درخواست با همان مدل و prefix همان کش را می‌خوانند. برای فراخواننده‌های Agent SDK که ناوگانی از پروسه‌های خودکار اجرا می‌کنند، بهبودِ prompt caching در میانِ کاربران و ماشین‌ها را ببین تا بخش‌های مخصوصِ هر ماشینِ system prompt را سرکوب کنی و کش را در میانِ ماشین‌ها به اشتراک بگذاری.

بررسیِ کاراییِ کش

کاراییِ کش به‌صورتِ دو شمارشِ توکن نمایان می‌شود که API روی هر پاسخ گزارش می‌دهد. مستقیم‌ترین راه برای پایشِ زنده‌ی آن‌ها یک اسکریپتِ statusline است که شیءِ current_usage را می‌خواند:

فیلد	معنا
cache_creation_input_tokens	توکن‌هایی که در این نوبت به کش نوشته شدند، با نرخِ نوشتنِ کش محاسبه می‌شوند
cache_read_input_tokens	توکن‌هایی که در این نوبت از کش سرویس داده شدند، تقریباً با ۱۰٪ نرخِ ورودیِ استاندارد محاسبه می‌شوند

نسبتِ بالای خواندن به ساختن یعنی کش خوب کار می‌کند. اگر ساختن نوبت‌به‌نوبت بالا بماند، چیزی در prefixَت در حالِ تغییر است. بخشِ اکشن‌هایی که کش را باطل می‌کنند علت‌های معمول را فهرست می‌کند.

برای دیدِ سراسری در یک سازمان، صادرکننده‌ی OpenTelemetry توکن‌های خواندن و ساختنِ کش را به‌ازای هر کاربر و نشست گزارش می‌دهد. برای مرجعِ متریک و خصوصیاتِ رویداد، Monitor usage را ببین.

ساب‌ایجنت‌ها و کش

یک ساب‌ایجنت مکالمه‌ی خودش را با system prompt و مجموعه‌ابزارِ خودش، جدا از والد، شروع می‌کند. کشِ خودش را می‌سازد، با هیچ اصابتِ کشی در اولین فراخوانی شروع می‌کند و در طولِ نوبت‌های خودش گرم می‌شود. ساب‌ایجنت‌ها حتی روی اشتراک هم از TTL پنج‌دقیقه‌ای استفاده می‌کنند، چون TTL یک‌ساعته‌ی خودکار به مکالمه‌ی اصلی اعمال می‌شود.

کشِ والد بی‌تأثیر می‌ماند. از سمتِ والد، فراخوانی و نتیجه‌ی ساب‌ایجنت به مکالمه اضافه می‌شوند و prefixِ والد را دست‌نخورده می‌گذارند.

یک fork، در مقابل، system prompt، ابزارها، و تاریخچه‌ی مکالمه‌ی والد را عیناً به ارث می‌برد، پس اولین درخواستش کشِ والد را می‌خواند. فراخوانیِ خلاصه‌سازیِ compaction که در Compact‌کردنِ مکالمه شرح داده شد از همین رویکردِ اشتراکِ prefix استفاده می‌کند.

غیرفعال‌کردنِ prompt caching

غیرفعال‌کردنِ کش گاهی هنگامِ عیب‌یابیِ رفتارِ کش با یک مدل یا ارائه‌دهنده‌ی خاص مفید است. برای خاموش‌کردنش، یکی از این متغیرهای محیطی را روی 1 تنظیم کن:

متغیر	اثر
DISABLE_PROMPT_CACHING	غیرفعال برای همه‌ی مدل‌ها
DISABLE_PROMPT_CACHING_HAIKU	غیرفعال فقط برای Haiku
DISABLE_PROMPT_CACHING_SONNET	غیرفعال فقط برای Sonnet
DISABLE_PROMPT_CACHING_OPUS	غیرفعال فقط برای Opus
DISABLE_PROMPT_CACHING_FABLE	غیرفعال فقط برای Fable

برای تنظیمِ سیاستِ کش در یک سازمان، هر یک از این‌ها یا متغیرهای TTL را در بلاکِ env در managed settings قرار بده. برای استفاده‌ی عادی، کش را فعال بگذار.

منابعِ مرتبط

• درس‌هایی از ساختِ Claude Code: prompt caching همه‌چیز است: منطقِ طراحیِ plan mode، بارگذاریِ به‌تعویق‌افتاده‌ی ابزار، و compaction
• کاوش در پنجره‌ی کانتکست: چه چیزی واردِ کانتکست می‌شود و کِی
• کاهشِ استفاده‌ی توکن: راهبردهای فراتر از کش برای مدیریتِ اندازه‌ی کانتکست
• ردیابی و کاهشِ هزینه‌ها: ردیابیِ توکنِ کش و پیکربندیِ TTL برای فراخواننده‌های Agent SDK
• Prompt caching: سازوکارِ زیربناییِ API، نقاطِ شکست، و هزینه‌گذاری