تصور کنید ساعتها وقت صرف تنظیم دقیق دستورالعملهای پروژه کردهاید، اما عامل هوش مصنوعی شما بهسادگی نیمی از آنها را نادیده میگیرد بدون اینکه حتی یک پیام خطا نمایش دهد. این دقیقاً همان تلهای است که اکنون توسعهدهندگان در استفاده از Claude Code با آن مواجهاند.
این ابزار اکنون دو نوع فایل دستورالعمل را میشناسد، اما بهجای ادغام آنها، یکی را انتخاب و دیگری را حذف میکند. به این معنا که عامل (Agent) — شبیه دستیاری که فقط یک دفترچه یادداشت را در لحظه میخواند و هر چه در دفتر دوم باشد را دور میاندازد — ممکن است دستورات حیاتی شما را نادیده بگیرد. این چالش با بحران ناهماهنگی فایلهای تنظیمات در Shopify شباهت زیادی دارد، جایی که تداخل در دستورالعملها منجر به شکست عملیاتی عاملهای هوش مصنوعی شد.
همانطور که در تحلیل قبلی ما دربارهی امنیت مدلهای بازمتن اشاره کردیم، کنترل دقیق روی ورودیها و تنظیمات، کلید دستیابی به نتایج قابلاتکا است. در مورد Claude Code، این کنترل به دلیل یک نقص در اولویتبندی فایلها به خطر افتاده است.
طبق گزارشهای منتشر شده، این رفتار در بهروزرسانی ۱۸ سپتامبر ۲۰۲۴ معرفی شد و یک «تله اولویت» برای برنامهنویسان ایجاد کرد. در حالی که پیشتر بررسی کردیم که چگونه Claude Opus 5.5 میتواند وظایف پیچیده و قطعی (Deterministic) را از طریق کد خالص مدیریت کند، توانایی هدایت این قدرت کاملاً به این بستگی دارد که عامل در واقع کدام فایل پیکربندی را بارگذاری میکند. این تحول در مدیریت وظایف، بخشی از مسیر تغییر ساختار اجرایی Claude Code از حالت چت به ارکستراسیون است تا مدیریت پروژههای پیچیده تسهیل شود. بسیاری از آموزشها به شما میگویند چه چیزی را در این فایلها قرار دهید، اما تقریباً هیچکدام توضیح نمیدهند که وقتی دو فایل بهطور همزمان وجود داشته باشند چه اتفاقی میافتد یا شواهدی ارائه نمیدهند که آیا محتوا واقعاً اثر میکند یا خیر.
تله اولویتبندی
Claude Code برای حافظه پروژه دو فایل اصلی را شناسایی میکند:
- CLAUDE.md: فایل حافظه بومی مخصوص Claude Code.
- AGENTS.md: یک قرارداد مشترک بین ابزارهای مختلف که توسط بنیاد لینوکس به عنوان استاندارد پذیرفته شده است.
بر اساس تغییرات ۱۸ سپتامبر، Claude Code فایل AGENTS.md را میخواند، اما این کار را از طریق یک مکانیزم «جایگزین» (Fallback) انجام میدهد و نه از طریق «اتحاد» (Union). یعنی اگر هر دو فایل موجود باشند، مدل آنها را با هم ترکیب نمیکند، آنها را در هم نمیآمیزد و «بهترینهای هر دو» را انتخاب نمیکند؛ بلکه یکی برنده میشود و دیگری کاملاً نادیده گرفته میشود.
منطق اولویتبندی به این ترتیب است:
۱. شروع جلسه توسط Claude Code.
۲. بررسی وجود CLAUDE.md. اگر موجود باشد، فقط این فایل خوانده میشود.
۳. اگر فایل اول نباشد، بررسی AGENTS.md. اگر موجود باشد، فقط این فایل خوانده میشود.
۴. اگر هیچکدام نباشند، هیچ دستوری بارگذاری نمیشود.
این وضعیت یک حالت شکست خطرناک ایجاد میکند. اگر شما یک فایل CLAUDE.md بهینه داشته باشید و سپس برای سازگاری با ابزارهای دیگر (مانند Codex) یک فایل AGENTS.md اضافه کنید تا دستورالعملها به اشتراک گذاشته شوند، تمام تغییرات شما در فایل دوم برای Claude Code بیاثر خواهد بود. بدتر از آن، اگر محتوا را برای یکپارچهسازی از فایل اول به دوم منتقل کنید، مدل تمام دستورات را فراموش میکند، بدون اینکه هشداری بدهد. هیچ پیام خطا یا اخطاری صادر نمیشود؛ عامل فقط شروع به فراموش کردن قراردادهای شما میکند.
گیت تلهمتری و دسترسی
یک نکته فنی حساس در گزارش وبسایت blog.szypowi.cz به چشم میخورد. در نسخه ۲.۱.۲۷۷، پشتیبانی از AGENTS.md توسط یک پلاگین داخلی به نام agents-md مدیریت میشود.
شواهد نشان میدهد که برای برخی کاربران، این بارگذار تنها زمانی کار میکند که تلهمتری (Telemetry) فعال باشد. کاربرانی که تلهمتری را در محیط شل (Shell) خود غیرفعال کردهاند، گزارش دادهاند که حتی در پروژههایی که CLAUDE.md نداشتند، فایل AGENTS.md هرگز بارگذاری نشد. این موضوع لایه دیگری از نامرئی بودن را به فرآیند پیکربندی اضافه میکند و در واقع باگی است که باعث نادیده گرفتن تنظیمات محلی در صورت غیرفعال بودن تلمتری میشود.
چه دستوراتی واقعاً اثرگذارند؟
همه دستورات ارزش یکسانی ندارند. یک مطالعه کنترلشده (arXiv 2602.11988) بررسی کرد که کدام محتواها بهطور ملموس رفتار عامل را تغییر میدهند. یافتهها برخلاف توصیههای رایج در آموزشهاست: فایلهای طولانی و کلی تأثیر پایداری ندارند و برخی دستههای رایج از محتوا هیچ سودی ندارند یا حتی با رقیق کردن دستورات مهم، اثر منفی میگذارند.
برای بهینهسازی فایلها، این مطالعه چارچوب «نگه داشتن در برابر حذف» را پیشنهاد میکند:
موارد لازم (نگه دارید):
- دستورات دقیق: دستورات Build، Test و Lint (مثلاً رشته متنی دقیق برای اجرا، نه توصیف فرآیند).
- راهنمای استایل: مقالات و ترجیحات خاص در کدنویسی.
- محدودیتهای خاص پروژه: محدودیتهای سخت مانند «به پوشه legacy/ دست نزن» یا «قبل از تستها، Migrationها را اجرا کن».
- محدودیتهای غیربدیهی: متغیرهای محیطی مورد نیاز، پورتهای خاص یا سرویسهای ضروری.
- آدرس فایلها: مسیرهای مستقیم، مثل «تایپهای API در src/types/api.ts هستند».
موارد زائد (حذف کنید):
- بهترین شیوههای کلی: جملاتی مثل «کد تمیز بنویس» یا «گامبهگام فکر کن».
- دانش استنتاجی: تکرار چیزهایی که مدل میتواند با تحلیل کد بفهمد.
- توضیحات طولانی پسزمینه: مقالات مفصل درباره معماری کلی پروژه.
منطق ساده است: هر توکنی که صرف محتوای قابل استنتاج شود، از فضای پنجره زمینه (Context Window) — شبیه میز کاری که فضای محدودی برای کاغذها دارد — میکاهد و جای دستورات حیاتی را میگیرد. یک خط ساده مانند «هرگز npm test را بدون بالا آوردن داکر استک اجرا نکن» بسیار ارزشمندتر از سه پاراگراف درباره فلسفه پیامهای کامیت شماست.
مدیریت محدودیت زمینه
زمینه یک منبع محدود است. گزارشها حاکی از آن است که سقف اندازه این فایلهای دستورالعمل حدود ۳۲ کیلوبایت است. اگرچه این عدد در نسخههای مختلف تغییر میکند، اما پیامد آن ثابت است: فایلهای بسیار طولانی با ریسک «برش خاموش» (Silent Truncation) مواجهاند.
وقتی فایلی برش میخورد، مدل انتهای سند را بدون اطلاع کاربر از دست میدهد. این موضوع نیاز به اولویتبندی محدودیتهای سخت بر فلسفههای کدنویسی را دوچندان میکند. همیشه پیش از تکیه بر اندازه خاصی از فایل، محدودیت فعلی را با آخرین مستندات Anthropic بررسی کنید.
پروتکل تأیید ۲۰ دقیقهای
از آنجایی که این شکستها بهصورت خاموش رخ میدهند، نمیتوانید با نگاه کردن به پیکربندی به آن اعتماد کنید. رویکرد توصیه شده، یک تست A/B سریع است تا یک سؤال پیکربندی نامرئی به یک نتیجه مرئی تبدیل شود:
۱. انتخاب یک تسک نماینده: یک رفع باگ واقعی، یک ویژگی کوچک یا یک بازسازی (Refactor) را انتخاب کنید که واقعاً در این هفته به آن نیاز دارید. از پرامپتهای ساده و مصنوعی دوری کنید.
۲. اجرای پایه (Baseline): تسک را با تنظیمات فعلی اجرا کنید. نتیجه را یادداشت کنید: آیا قراردادها را رعایت کرد؟ چند دور اصلاح نیاز بود؟
۳. تعویض فایلها: اگر هر دو فایل CLAUDE.md و AGENTS.md را دارید، یکی را تغییر نام دهید (مثلاً به CLAUDE.bak) و همان تسک را دوباره اجرا کنید. اگر فقط یک فایل دارید، آن را به حداقل (فقط دستورات و محدودیتهای سخت) برسانید و دوباره اجرا کنید.
۴. مقایسه: اگر نتایج با تنظیمات کوچکتر یکسان بود، یعنی محتوای اضافی فقط هزینه زمینه (Context) داشته بدون اینکه سودی برساند. اگر نتایج افت کرد، متوجه میشوید کدام محتوا واقعاً جایگاه خود را در فایل به دست آورده است.
محدودیتها و زمینه صادقانه
بسیار مهم است که محدودیتهای این راهنما را بیان کنیم:
- مطالعه (arXiv 2602.11988) تنها یک مقاله روی یک مجموعه از مدلهاست؛ نتایج آن را به عنوان جهتنما در نظر بگیرید، نه به عنوان حقیقتی قطعی.
- رفتار اولویتبندی منعکسکننده Claude Code تا تغییرات ۱۸ سپتامبر است. ابزارهای عاملها سریع پیش میروند؛ حتماً یادداشتهای انتشار فعلی را بررسی کنید.
- عدد ۳۲ کیلوبایت تقریبی و وابسته به نسخه است.
- پروتکل A/B ذاتاً تجربی است؛ یک تسک واحد دقت آماری را ثابت نمیکند، اما از حدس زدن بهتر است.
این تغییر در نحوه مدیریت حافظه پروژه توسط Anthropic، تنش فزایندهای را در اکوسیستم عوامل هوش مصنوعی نشان میدهد. همانطور که به سمت استانداردهای مشترک مانند AGENTS.md حرکت میکنیم، نبود یک منطق ادغام یکپارچه باعث ایجاد «پیکربندیهای سایه» میشود که میتواند بهرهوری توسعهدهنده را کاهش دهد.
برای متخصصان، داشتن یک «منبع واحد حقیقت» (Single Source of Truth) تنها راه امن است. اگر تیم شما از ابزارهای متعددی استفاده میکند، محتوای مشترک را در AGENTS.md قرار دهید و CLAUDE.md را یا حذف کنید یا فقط شامل موارد خاص Claude نگه دارید — هرگز از کپی جزئی استفاده نکنید، زیرا یک کپی جزئی بهطور خاموش روی فایل کامل سایه میاندازد و آن را نادیده میگیرد.
گام بعدی شما
- تست A/B سریع: یک تسک واقعی (نه یک پرامپت ساده) را با تنظیمات فعلی اجرا کنید و نتیجه را یادداشت کنید.
- تغییر نام فایلها: اگر هر دو فایل را دارید، یکی را تغییر نام دهید (مثلاً به
CLAUDE.bak) و تسک را دوباره اجرا کنید تا ببینید کدام فایل اثرگذارتر است. - پاکسازی محتوا: تمام جملات کلی و فلسفی را حذف کرده و فقط دستورات اجرایی و محدودیتهای سخت را باقی بگذارید.
اما داستان سختافزاری این تحول حتی شگفتانگیزتر است — به تحلیل ما دربارهی تراشههای Blackwell مراجعه کنید.
گفتگو