چرا ایجنتهای برنامهنویسی دستورات شما را نادیده میگیرند؟
اگر ایجنت دستورات شما را اجرا نمیکند، مشکل از لحن شما نیست. در این مقاله دلایل فنی نادیده گرفتن قوانین و روش تشخیص خطا در Claude Code تا اکتبر 2026 را بررسی میکنیم.
چرا ایجنتهای برنامهنویسی دستورات شما را نادیده میگیرند
ایجنتهای برنامهنویسی به چهار دلیل دستورات شما را نادیده میگیرند و هیچکدام از این دلایل به مودب بودن بیش از حد شما مربوط نمیشود. قانون مورد نظر هرگز در پنجره کانتکست (context window) قرار نگرفته است. قانون بیش از حد مبهم بوده و امکان بررسی عملکرد بر اساس آن وجود نداشته است. مورد دیگری در کانتکست با آن در تضاد بوده که معمولاً کدی است که ایجنت بهتازگی خوانده است. یا اینکه قانون همچنان بارگذاری شده اما در فاصلهای دور از نوبت فعلی قرار دارد و ایجنت بر اساس اطلاعات نزدیکتر عمل میکند.
هر علت راهحل خاص خود را دارد، بنابراین اولین وظیفه شما تشخیص تفاوت آنهاست. استفاده از حروف بزرگ و کلمه IMPORTANT تشخیص درستی نیست. مکانیسمهای زیر از Claude Code به عنوان نمونه استفاده میکنند، زیرا رفتار بارگذاری و فشردهسازی آن تا اکتبر 2026 بهطور دقیق مستند شده است. سایر ابزارها در جزئیات متفاوت هستند اما در کلیات به همین صورت عمل میکنند.
ابتدا دو اصطلاح را تعریف میکنیم. پنجره کانتکست بلوکی از متن است که مدل در هر نوبت مشاهده میکند: پرامپت سیستم، فایلهای دستورالعمل شما، گفتگو و هر فایلی که ایجنت خوانده است. هارنس (harness) برنامهای است که مدل را احاطه کرده و وظیفه خواندن فایلها از دیسک و جمعآوری آن بلوک را بر عهده دارد. تقریباً هر شکایتی در این مطلب، در واقع شکایتی از هارنس است، نه مدل.
فایل دستورالعمل شما یک پیام است، نه یک تنظیمات
یک فایل دستورالعمل، پیکربندی (configuration) نیست. هیچ بخشی از runtime، فایل CLAUDE.md را نمیخواند و آن را اعمال نمیکند. ابزار اجراکننده (harness)، فایل را از روی دیسک میخواند و متن آن را در گفتگو جایگذاری میکند. در Claude Code، این محتوا به عنوان یک پیام کاربر که پس از system prompt قرار میگیرد، ارسال میشود؛ این یعنی مدل، قوانین شما را همانطور میبیند که هر متن دیگری را که تایپ کردهاید، مشاهده میکند.
این موضوع یک نتیجهٔ ناخوشایند دارد. قوانین شما با هر متن دیگری در پنجره، در شرایطی برابر رقابت میکنند. یک قانون، صرفاً یک ادعاست. فایلی که agent بهتازگی باز کرده است، یک مدرک است. وقتی این دو با هم اختلاف داشته باشند، مدرک اغلب پیروز میشود و هیچ خطایی هم رخ نمیدهد، زیرا از دیدگاه مدل، هیچ اتفاق اشتباهی نیفتاده است.
مستندات رسمی این موضوع را بهصراحت بیان میکنند: فایلهای دستورالعمل به عنوان زمینه (context) در نظر گرفته میشوند، نه پیکربندیِ اعمالشده. برای مسدود کردن یک اقدام، صرفنظر از اینکه مدل چه تصمیمی میگیرد، شما به یک hook نیاز دارید، نه یک جمله. این اصل را به خاطر بسپارید. بیشتر اصلاحاتی که در انتهای این پست آمدهاند، در واقع همین اصل هستند که در یک مورد خاص اعمال شدهاند.
کدام فایلهای دستورالعمل بارگذاری میشوند و چه زمانی
Claude Code مسیر دایرکتوری را از جایی که آن را اجرا کردهاید به سمت بالا طی میکند. هر CLAUDE.md و CLAUDE.local.md از ریشه فایلسیستم تا دایرکتوری کاری شما، در زمان راهاندازی بهطور کامل بارگذاری میشوند. این فایلها به همان ترتیب به یکدیگر متصل (concatenate) میشوند، بنابراین فایلی که به محل اجرای شما نزدیکتر است، در انتها خوانده میشود و در یک دایرکتوری واحد، فایل .local پس از فایل اصلی ضمیمه میگردد.
فایلهای موجود در زیردایرکتوریهای پایینتر از دایرکتوری کاری شما رفتار متفاوتی دارند. این فایلها در زمان راهاندازی بارگذاری نمیشوند، بلکه زمانی بارگذاری میشوند که عامل (agent) فایلی را در آن دایرکتوری بخواند. همین موضوع در مورد قوانین محدود به مسیر در .claude/rules/ که دارای فیلد frontmatter از نوع paths: هستند نیز صادق است: این قوانین زمانی وارد context میشوند که یک فایل منطبق خوانده شود، نه در هر نوبت. از نسخه v2.1.309 به بعد، فایلهایی که به این روش بارگذاری میشوند، دارای محدودیت اندازه به ازای هر فایل هستند (40,000 کاراکتر در یک پنجره context با ظرفیت 200K) و عامل فقط ابتدای فایلهای طولانیتر را دریافت میکند؛ بنابراین قوانینی که در انتهای یک فایل تو در توی بزرگ قرار دارند، ممکن است هرگز به context نرسند.
همین یک تفاوت، بخش بزرگی از خطاهای گزارششده را توضیح میدهد. شما قانونی را در packages/api/CLAUDE.md قرار میدهید، سوالی درباره API میپرسید و عامل بدون باز کردن هیچ فایلی در packages/api/ پاسخ میدهد. قانون نادیده گرفته نشده است، بلکه هرگز وجود نداشته است. اگر مخزن شما دستورالعملها را در فایلهای دستورالعمل به ازای هر پکیج در یک monorepo تقسیم کرده است، این اولین چیزی است که باید هر بار بررسی کنید.
یک تله بارگذاری دیگر مخازنی را تحت تأثیر قرار میدهد که از AGENTS.md استفاده میکنند. از نسخه v2.1.277 به بعد، Claude Code بهطور پیشفرض AGENTS.md را به عنوان دستورالعملهای پروژه شما میخواند، اما فقط زمانی که هیچ CLAUDE.md، .claude/CLAUDE.md یا CLAUDE.local.md در دایرکتوری کاری شما یا هر دایرکتوری بالادستی وجود نداشته باشد (فایل ~/.claude/CLAUDE.md شخصی شما در این محاسبه لحاظ نمیشود). با افزودن هر یک از این موارد، حتی یک CLAUDE.local.md برای یادداشتهای شخصی، Claude Code به جای آن فایلهای CLAUDE.md شما را میخواند و AGENTS.md را بهطور کامل نادیده میگیرد. برای بارگذاری هر دو، Project instructions را در /config روی claude-md-and-agents-md تنظیم کنید. در نسخههای پیش از v2.1.277، یا زمانی که میخواهید یک CLAUDE.md را حفظ کنید، راه حل یک CLAUDE.md است که خط اول آن @AGENTS.md باشد؛ این کار فایل را در زمان راهاندازی وارد میکند و هر یادداشت خاص مربوط به Claude میتواند در زیر آن قرار گیرد. استفاده از symlink نیز زمانی که چیز اضافهای برای افزودن ندارید، کارساز است. تصمیمگیری در مورد اینکه چه چیزی در وهله اول متعلق به آن فایل است، موضوع جداگانهای است که در تفکیک دستورالعملهای عامل از مستندات انسانی به آن پرداخته شده است.
تأیید بارگذاری فایل پیش از بازنویسی آن
تا زمانی که از مشاهده فایل توسط ایجنت اطمینان حاصل نکردهاید، متن آن را تغییر ندهید. دو روش برای بررسی وجود دارد که روش سادهتر در اولویت است.
دستور /context را در نشست اجرا کنید. این دستور پنجره فعلی را بر اساس دستهبندی نمایش میدهد و لیست Memory files نام تمام فایلهای دستورالعملی که در زمان راهاندازی بارگذاری شدهاند را ذکر میکند. فایلی که در آن لیست نباشد، در زمان راهاندازی بارگذاری نشده است؛ بنابراین تا زمانی که فایلی آن را فراخوانی نکند، هر تغییری در آن بیاثر خواهد بود. فایلهای تو در تو در زیرپوشهها هرگز در آن لیست ظاهر نمیشوند، زیرا در صورت نیاز بارگذاری میشوند؛ هنگامی که بارگذاری انجام شود، یک خط Loaded به همراه مسیر فایل در ترمینال ظاهر میشود. دستور /memory مکان فایلها را لیست کرده و آنها را برای ویرایش باز میکند، حتی فایلهایی که هنوز وجود ندارند.
برای بررسی دقیقتر، بارگذاریها را لاگ کنید. رویداد هوک InstructionsLoaded هر بار که یک CLAUDE.md یا فایل قوانین وارد کانتکست میشود فعال میگردد و تطبیقدهنده (matcher) آن دلیل بارگذاری را مشخص میکند: session_start، nested_traversal، path_glob_match، include یا compact. این کد را در .claude/settings.json قرار دهید:
{
"hooks": {
"InstructionsLoaded": [
{
"matcher": "nested_traversal",
"hooks": [
{
"type": "command",
"command": "cat >> /tmp/instructions-loaded.log"
}
]
}
]
}
}هوک، محموله (payload) خود را به صورت JSON در ورودی استاندارد دریافت میکند، بنابراین cat کل رکورد را ضمیمه میکند. هنگام کار، آن را با tail -f /tmp/instructions-loaded.log مانیتور کنید. وضعیت خروج این رویداد نادیده گرفته میشود، بنابراین هوک فقط میتواند مشاهده کند و هرگز قادر به مسدودسازی نیست. اگر فایل تو در توی شما در طول نشستی که انتظار بارگذاری آن را داشتید در لاگ ظاهر نشد، بازنویسی را متوقف کنید. مشکل در محل قرارگیری فایل است. یک استثنا وجود دارد: یک AGENTS.md که Claude Code مستقیماً میخواند، این رویداد را فعال نمیکند؛ بنابراین مسیر آن را در /memory جستجو کنید. یک AGENTS.md که از یک CLAUDE.md وارد (import) شده باشد، طبق روال معمول این رویداد را فعال میکند.
تأثیر نشستهای طولانی بر قوانین شما
در اینجا دو اثر مجزا اعمال میشود که نیازمند واکنشهای متفاوتی هستند.
فاصله. تا زمانی که یک فشردهسازی (compaction) اجرا نشود، قانونی که در نوبت 1 بیان شده، در نوبت 90 همچنان در پنجره (window) حضور دارد، اما اکنون با 90 نوبت متن جدیدتر که به آنچه در حال حاضر انجام میدهید مرتبطتر است، رقابت میکند. پس از اجرای فشردهسازی، قانونی که فقط در چت تایپ کردهاید ممکن است اصلاً در پنجره باقی نماند: مستندات خود Claude Code هشدار میدهد که دستورالعملهای ابتدای گفتگو ممکن است گم شوند، که این همان اثر دوم در زیر است. شما نمیتوانید فاصله را با پیکربندی حذف کنید، اما میتوانید آن را اندازهگیری کنید. همان وظیفه را در یک نشست تازه اجرا کنید. اگر قانون در آنجا رعایت شد اما در عمق یک نشست طولانی شکست خورد، پاسخ شما فاصله یا فشردهسازی است.
فشردهسازی. هنگامی که پنجره پر میشود، سیستم، گفتگو را تا آن لحظه خلاصه کرده و از آن خلاصه ادامه میدهد. آنچه باقی میماند چیزی است که خلاصهساز آن را مهم تشخیص داده است، که لزوماً با آنچه شما مهم میدانید یکی نیست. Claude Code خروجی را به تفکیک مکانیزم مستند کرده است و تفاوتها بسیار زیاد هستند. ریشه پروژه CLAUDE.md و قوانین بدون محدوده (unscoped)، پس از هر فشردهسازی از روی دیسک دوباره تزریق میشوند. حافظه خودکار (Auto memory) نیز از روی دیسک دوباره تزریق میشود. قوانینی که دارای پیشگفتار (frontmatter) paths: هستند، تا زمانی که یک فایل منطبق دوباره خوانده نشود، از دست میروند. فایلهای CLAUDE.md تو در تو در زیرپوشهها نیز تا زمانی که فایلی در آن زیرپوشه دوباره خوانده نشود، از دست میروند.
دستورالعملهای خود را بر اساس آن جدول رتبهبندی کنید تا ترتیب شکنندگی مشخص شود. قانونی که فقط در چت تایپ کردهاید، شکنندهترین مورد در نشست است: تنها در صورتی باقی میماند که خلاصهساز بهطور اتفاقی آن را حفظ کرده باشد. قانون موجود در packages/api/CLAUDE.md در رتبه بعدی قرار دارد، زیرا یک بار بارگذاری شده، در خلاصه حذف شده و تنها با خواندن مجدد در آن دایرکتوری بازمیگردد. قانون موجود در فایل ریشه پروژه، بادوامترین است، زیرا هر بار از روی دیسک بازخوانی میشود.
بنابراین اگر یک دستورالعمل باید برای کل نشست معتبر بماند، باید در فایل ریشه پروژه و بدون پیشگفتار paths: قرار گیرد. هر چیز دیگری یک مصالحه است که باید آگاهانه انجام دهید. مدیریت آنچه در پنجره زمینه باقی میماند به /compact با آرگومان focus و /clear بین وظایف نامرتبط میپردازد که هر دو نحوه تصمیمگیری خلاصهساز درباره قوانین شما را تغییر میدهند.
چرا کد موجود، قانون را نقض میکند
این همان شکستی است که افراد بیش از همه توصیف میکنند و کمتر از همه عیبیابی میکنند. فایل شما میگوید دسترسی به دیتابیس باید از طریق لایه repository انجام شود. اما agent یک handler مینویسد که مستقیماً ORM (نگاشتگر شیء-رابطهای) را فراخوانی میکند. نادیده گرفته شدن شما به دلیل سبک کدنویسی نبوده است؛ بلکه شواهد، نظر شما را شکست دادهاند.
یک قانون، بیانگر یک ترجیح است. اما کد، یک واقعیت را نشان میدهد. وقتی agent سه فایلی را که قصد ویرایش آنها را دارد باز میکند و هر سه مستقیماً ORM را فراخوانی میکنند، زمینه (context) شامل یک جمله انتزاعی در یک طرف و سه مثال ملموس، جدید و مرتبط با وظیفه در طرف دیگر است. کپی کردن الگوی محلی معمولاً رفتار درستی است. این کار فقط در اینجا اشتباه است، چون شما چیزی را میدانید که زمینه از آن بیخبر است: آن فایلها legacy هستند.
پس این موضوع را در قانون بنویسید. قوانینی که شواهد نقض خود را نام میبرند، در مواجهه با یک مخزن واقعی دوام میآورند. قوانینی که فقط یک ترجیح ساده را بیان میکنند، دوام نمیآورند.
دسترسی جدید به دیتابیس باید از طریقapp/repositories/انجام شود. فایلهای موجود درapp/legacy/همچنان مستقیماً ORM را فراخوانی میکنند. اینها کدهای قدیمی هستند، نه الگو. از آنها کپیبرداری نکنید.
جمله دوم کار اصلی را انجام میدهد. این جمله به agent میگوید که قرار است با چه چیزی مواجه شود و پیش از آنکه آن را پیدا کند، چگونه باید آن را تفسیر کند. همین اصلاح برای هر قانونی که مخزن شما بهطور مشهود با آن در تضاد است، کاربرد دارد: سبکی در commit که تاریخچه شما از آن پیروی نمیکند، ساختار تستی که نیمی از suite شما آن را نادیده میگیرد، یا قرارداد import که فقط در کدهای جدید رعایت میشود. هر جا که کد با فایل قوانین اختلاف دارد، آن اختلاف را در فایل نام ببرید.
یک قانون مبهم قابل بررسی نیست، بنابراین نمیتوان از آن پیروی کرد
«کد تمیز بنویسید.» «مهندسی بیش از حد نکنید.» «ساده نگه دارید.» «در مهاجرتها دقت کنید.» هیچکدام از این موارد را نمیتوان در برابر یک اقدام مشخص، چه توسط عامل (agent) و چه توسط شما، آزمایش کرد. عاملی که قانونی به او داده شده که نمیتواند خروجی خود را با آن بسنجد، در حال حدس زدن است و شما نیز حدس او را بر اساس احساس خود نمره میدهید.
این آزمونی است که باید برای هر خط در فایل خود اعمال کنید. دستور shellای را بنویسید که در صورت نقض قانون، با کد خروجی غیر صفر (non-zero) متوقف شود. اگر نمیتوانید آن دستور را بنویسید، آن قانون قابل بررسی نیست. این جفتها را مقایسه کنید:
- غیرقابل بررسی: «توابع را کوچک نگه دارید.» قابل بررسی: «هر تابعی که بیش از 60 خط باشد، باید در بالای آن توضیحی مبنی بر دلیل این کار وجود داشته باشد.»
- غیرقابل بررسی: «تغییرات خود را تست کنید.» قابل بررسی: «دستور
npm testرا اجرا کنید و تعداد شکستها را پیش از اعلام پایان کار، درج کنید.» - غیرقابل بررسی: «فایلها را سازماندهی کنید.» قابل بررسی: «هندلرهای HTTP در
src/api/handlers/قرار دارند. هیچ چیز دیگری نباید در آن دایرکتوری باشد.» - غیرقابل بررسی: «کد را به درستی فرمت کنید.» قابل بررسی: «از تورفتگی 2 فضایی در فایلهای
.tsاستفاده کنید.»
«مهندسی بیش از حد نکنید» اولین قانونی است که افراد از آن دست میکشند، زیرا راه حل آن یک جمله کوتاهتر نیست، بلکه جملهای طولانیتر است: توضیح دقیق اینکه کوچکترین تغییرِ کارآمد واقعاً به چه معناست معیارهایی را به عامل میدهد که میتواند diff خود را با آن بسنجد.
اندازه نیز همان مشکل است که با ظاهری متفاوت بروز میکند. راهنمای Claude Code برای هر فایل دستورالعمل، کمتر از 200 خط را هدف قرار میدهد و مستقیماً بیان میکند که فایلهای طولانیتر، پایبندی به دستورات را کاهش میدهند. یک فایل 700 خطی، دستورالعمل محکمتری نیست. این فایل شامل 700 خط ادعا با احتمال تناقض بیشتر است و در هر نوبت از پنجره متنی شما کسر میشود که مستقیماً در میزان مصرف توکن شما نمایان میشود. ساختاردهی به فایل به گونهای که هر قانون زیر یک عنوان قابل اسکن قرار گیرد، در نوشتن فایل دستورالعملی که عامل بتواند بر اساس آن عمل کند پوشش داده شده است. بهتر از آن، بخشهایی که به جای دستور دادن، توصیف میکنند را حذف کنید: تور دایرکتوری برای اینکه هندلرها و مدلها کجا قرار دارند، ساختاری است که عامل میتواند در صورت نیاز از نقشه تجزیه شده مخزن جستجو کند، به جای اینکه آن را در هر نوبت در پنجره متنی حمل کند.
نحوه عیبیابی در ده دقیقه
این مراحل را به ترتیب اجرا کنید. پریدن به مرحله آخر باعث میشود با لیستی طولانی از قوانینِ با صدای بلند مواجه شوید که همچنان کار نمیکنند.
- بارگذاری را تأیید کنید. دستور
/contextرا اجرا کنید و لیست فایلهای Memory را بخوانید، یا برای یک فایل تو در تو، به دنبال خطLoadedآن در ترمینال باشید. اگر فایل در آنجا نیست، مسیر را اصلاح کنید و متوقف شوید. هیچکدام از مراحل بعدی این لیست هنوز کاربردی ندارند. - در یک نشست جدید بازتولید کنید. یک نشست جدید شروع کنید و کوچکترین وظیفهای که باید قانون را فعال کند، به آن بدهید. اگر در اینجا موفق بود اما در یک نشست طولانی شکست خورد، مشکل از فاصله یا فشردهسازی است. اگر در اینجا هم شکست خورد، خودِ قانون مشکل دارد.
- رقابت را حذف کنید. همان تغییر را در دایرکتوری درخواست کنید که کد موجود در آن از قبل از قانون پیروی میکند. اگر انطباق بازگشت، کدِ اطراف، دستور شما را نادیده میگرفته است.
- به دنبال تداخل بگردید. دو فایل که برای یک رفتار مشابه، راهنماییهای متفاوتی ارائه میدهند، یک خطای مستند است: مدل ممکن است یکی را به دلخواه انتخاب کند و به شما هم اطلاع نخواهد داد.
- آن را قابل بررسی کنید و دوباره تست کنید. قانون را با یک مسیر مشخص و یک شرط بازنویسی کنید. جهش بزرگ در انطباق نشان میدهد که علت مشکل، نحوه جملهبندی شما بوده است.
مرحله 4 تنها یک دستور است. تمام منابع دستورالعمل را برای آن موضوع جستجو کنید، نه فقط فایلی که در حال ویرایش آن بودید:
grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/nullیک نتیجه مثبت در دو فایل که چیزهای متفاوتی میگویند، همان باگ شماست. یکی را حذف کنید. سعی نکنید با استفاده از کلمات قویتر به آنها رتبه بدهید، زیرا هیچ موتور رتبهبندی برای رسیدگی به این موضوع وجود ندارد. در نسخه Claude Code v2.1.283 یا بالاتر، /doctor prompt-audit نسخه گستردهتری از این جستجو را در فایلهای دستورالعمل، قوانین و مهارتهای شما اجرا میکند و تناقضات را به همراه ویرایشهای پیشنهادی گزارش میدهد، بدون اینکه تا زمانی که شما نخواهید، تغییری ایجاد کند.
اصلاحات، به ترتیب میزان تأثیرگذاری
هر گام در زیر، تأثیرگذاری بیشتری نسبت به گام پیشین دارد و راهاندازی آن هزینهبرتر است. زمانی که بازنویسی یک قانون کمهزینه است، از بالا شروع کنید. به محض اینکه یک قانون اهمیت پیدا کرد و خطاهای گاهبهگاه دیگر قابلقبول نبود، به سمت پایین حرکت کنید.
- قانون را مشخص و عینی کنید. یک مسیر، یک دستور یا یک شرط را نام ببرید. شواهد نقضی که عامل (agent) در مخزن پیدا میکند را اضافه کنید، همانطور که پیشتر نشان داده شد. این کار رایگان است و بخش قابلتوجهی از موارد را اصلاح میکند.
- آن را به چیزی که کنترل میکند نزدیکتر کنید. یک
CLAUDE.mdتو در تو، قانونی با دامنه محدود در.claude/rules/، یا یک کامنت در بالای خودِ فایل. در این صورت، قانون در همان خوانش اول، همراه با کدی که بر آن اعمال میشود، در دسترس قرار میگیرد. این بدهبستان را بپذیرید: هر چیزی که به این شکل بارگذاری شود، در فشردهسازی بعدی حذف شده و در خوانش منطبق بعدی بازمیگردد. - اجرای قانون را به یک hook منتقل کنید. متنِ نوشتاری درخواست میکند، اما یک hook تصمیم میگیرد. hookها به عنوان کد در رویدادهای ثابت چرخه حیات اجرا میشوند و صرفنظر از نتیجهگیری مدل، اعمال میگردند.
- قانون را به یک ابزار قطعی (deterministic) بسپارید و متن نوشتاری را حذف کنید. قالببندی، ترتیب importها، طول خط، importهای ممنوع، ساختار پیام commit.
ruff format،prettier --write،eslint، یک hook از نوعpre-commit. فرمتکننده همیشه درست عمل میکند و هزینه توکن آن صفر است. جمله نوشتاری در بیشتر مواقع درست است اما در هر نوبت هزینه توکن دارد.
گام 3 به طور کامل. فرض کنید فایلهای migration هرگز نباید توسط عامل ویرایش شوند. این را در .claude/settings.json قرار دهید:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
}
]
}
]
}
}و این را در .claude/hooks/guard-migrations.sh:
#!/usr/bin/env bash
set -euo pipefail
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*/migrations/*)
echo "Files under migrations/ are written by hand. Stop and ask first." >&2
exit 2
;;
esac
exit 0دستور chmod +x .claude/hooks/guard-migrations.sh را اجرا کنید، سپس یک نشست جدید شروع کرده و از عامل بخواهید فایلی را در مسیر migrations/ ویرایش کند. ویرایش رد میشود و پیام شما به عنوان دلیل بازگردانده میشود. وضعیت خروج 2 در PreToolUse، فراخوانی ابزار را پیش از اجرا مسدود میکند و متن stderr شما به عنوان پیام مسدودکننده به مدل تحویل داده میشود. ${CLAUDE_PROJECT_DIR} به ریشه پروژه اشاره میکند، بنابراین hook فارغ از اینکه عامل در چه دایرکتوری قرار دارد، کار میکند. عامل نیازی ندارد با قانون موافق باشد، آن را به خاطر بسپارد یا همچنان آن را در context داشته باشد. ویرایش انجام نمیشود.
برای یک ممنوعیت کلی بدون هیچ منطق خاصی، permissions.deny در تنظیمات شما همان کار را بدون نیاز به نگهداری اسکریپت انجام میدهد و حالتهای دسترسی تعیین میکنند چه چیزی بدون پرسش از شما اجرا شود. اگر یک دستور واقعاً باید در سطح system prompt قرار بگیرد و نه در پیام کاربر، --append-system-prompt آن را در آنجا قرار میدهد؛ هرچند این یک پرچم (flag) راهاندازی است که هر نشست جدیدی نیاز به ارسال مجدد آن دارد، که برای اسکریپتها مناسبتر از کار تعاملی است.
آنچه با دستورالعمل قابل اصلاح نیست
شفاف باشید که کدام بخش از این موارد در حیطه مسئولیت شماست. جایگذاری، جملهبندی، تداخل بین فایلها و حجم فایل، مشکلاتی هستند که نویسنده باید آنها را رفع کند. مابقی موارد، رفتار مدل است و با تغییر جملهبندی اصلاح نمیشوند.
توافق به معنای تبعیت نیست. یک عامل (agent) ممکن است قانونی را تأیید کند، آن را بهدرستی برای شما بازگو کند و دو فراخوانی ابزار بعد، آن را نقض نماید. تأیید کردن هیچ هزینهای ندارد و هیچچیز را پیشبینی نمیکند. آن را به عنوان یک اصلاح در نظر نگیرید و به عنوان یک تست روی آن حساب نکنید.
برخی عادتها پایدار هستند. افزودن کامنت، افزودن مدیریت خطای تدافعی، نوشتن خلاصه پایانی، اجرای دستور بعدی که بدیهی است. این موارد حتی تحت قانونی که آنها را منع میکند، بازمیگردند؛ هرچند با نرخ کمتر، اما نه صفر. شما میتوانید نرخ خطای خود را اندازهگیری کنید: یک کار مشابه را 10 بار در نشستهای جدید اجرا کنید و تعداد تخلفات را بشمارید. در مواردی که این عدد باید صفر باشد، آن قانون باید از پرامپت حذف شود. اعلام پایان کار در حالی که بخشی از آن هنوز انجام نشده، از همین جنس عادتهاست و اصلاح آن ساختاری است، نه کلامی: مهارت غیرتنبلی، جملات را با یک درخت عمق (Depth Tree) جایگزین میکند و فایلهای دروازهای (gate files) ایجاد میکند که عامل باید پیش از ادعای پایان کار، آنها را پاکسازی کند.
نشست (session) شما به یک نمونه تبدیل میشود. اگر عامل در مرحله 12 قانون را شکست و شما از آن گذشتید، آن تخلف اکنون به عنوان یک الگو در کانتکست باقی میماند و بسیار جدیدتر از خودِ قانون است. تخلف را در همان لحظهای که مشاهده کردید، اصلاح کنید. یک تخلف اصلاحنشده، به ادامه نشست آموزش میدهد.
فایل دستورالعمل یک مرز امنیتی نیست. این فایل رفتار را شکل میدهد اما آن را تحمیل نمیکند. هر چیزی که خطا در آن هزینهبر باشد، مانند اعتبارنامهها یا دستورات مخرب، باید در سطح مجوزها یا هوکها (hooks) مدیریت شود. دور نگه داشتن اسرار از دسترس عامل همین اصل را در مورد دادهها اعمال میکند: از عامل نخواهید که فایلی را نخواند، بلکه کاری کنید که فایل برای او قابل خواندن نباشد.
خلاصه مطلب: بارگذاری فایل را اثبات کنید، قانون را قابل بررسی کنید، آن را در کنار چیزی که بر آن نظارت دارد قرار دهید و زمانی که نرخ خطا همچنان اهمیت دارد، آن را از متن خارج کنید. قانونی که عامل نتواند آن را نادیده بگیرد، قانونی است که هرگز از عامل درخواست نشده است.
FAQ
چرا Claude Code فایل CLAUDE.md مرا نادیده میگیرد؟
پیش از آنکه فرض کنید فایل نادیده گرفته شده است، بررسی کنید که آیا اصلاً بارگذاری شده است یا خیر. دستور /context را اجرا کنید و لیست Memory files را ببینید؛ فایلی که در آنجا نام برده نشده، در زمان راهاندازی بارگذاری نشده است. فایلهای دستورالعمل بهعنوان یک پیام کاربری پس از system prompt ارسال میشوند و بهجای پیکربندی اجباری، بهعنوان متن زمینه (context) در نظر گرفته میشوند، بنابراین هیچ تضمین قطعی برای رعایت آنها وجود ندارد. اکثر موارد واقعی به یکی از چهار دلیل زیر رخ میدهند: فایل در زیردایرکتوریای قرار دارد که عامل (agent) هرگز آن را نخوانده است، دو فایل با هم تضاد دارند و مدل بهطور تصادفی یکی را انتخاب کرده است، قانون آنقدر مبهم است که نمیتوان عملی را با آن سنجید، یا کدهای موجود در اطراف، خلاف آنچه قانون میگوید را نشان میدهند.
آیا ویرایش فایل دستورالعمل در میانه نشست (session) تغییری ایجاد میکند؟
برای نسخهای که در حال حاضر در گفتگو وجود دارد، خیر. فایلهای موجود در دایرکتوریهای بالاتر از دایرکتوری کاری شما در زمان راهاندازی بهطور کامل بارگذاری میشوند، بنابراین متنی که مدل در اختیار دارد، همان متن زمان راهاندازی است. برای اعمال ویرایش، یک نشست جدید شروع کنید یا از عامل بخواهید فایل را با ابزارهای فایل معمولی خود بخواند؛ این کار نسخه فعلی را بهعنوان یک پیام تازه وارد گفتگو میکند. پس از یک فشردهسازی (compaction)، فایل ریشه پروژه دوباره از دیسک خوانده میشود، بنابراین نسخه جدید در آن نقطه نیز وارد میشود.
وقتی یک CLAUDE.md در ریشه و یک فایل تو در تو با هم اختلاف دارند، کدام پیروز است؟
هیچکدام بهطور قابلاطمینان. فایلهای کشفشده بهجای جایگزینی یکدیگر، به متن زمینه الحاق میشوند و از ریشه سیستم فایل تا دایرکتوری کاری شما مرتب میشوند، بنابراین نزدیکترین فایل صرفاً در آخرین مرحله خوانده میشود. هیچ موتور اولویتی برای حل تناقضات وجود ندارد و مستندات Claude Code بیان میکند که قوانین متناقض ممکن است بهطور تصادفی حل شوند. فایلهای تو در تو را بهعنوان افزودنیهایی بنویسید که مسیری که تحت کنترل دارند را مشخص میکنند و بهجای تلاش برای برتری دادن به یکی، تناقض را حذف کنید.
آیا دستورالعملهای من پس از /compact باقی میمانند؟
بستگی به نحوه بارگذاری آنها دارد. فایل CLAUDE.md در ریشه پروژه، قوانین بدون محدوده (unscoped) و حافظه خودکار پس از فشردهسازی دوباره از دیسک تزریق میشوند. قوانین دارای frontmatter از نوع paths: و فایلهای CLAUDE.md تو در تو در زیردایرکتوریها تا زمانی که دوباره یک فایل منطبق خوانده نشود، از دست میروند. هر چیزی که فقط در چت تایپ کردهاید، تنها در صورتی باقی میماند که خلاصهساز (summariser) بهطور اتفاقی آن را حفظ کرده باشد. اگر قانونی باید در طول کل نشست معتبر بماند، آن را در فایل ریشه پروژه بدون frontmatter از نوع paths: قرار دهید.
چه زمانی یک قانون باید به جای متن، به یک hook تبدیل شود؟
زمانی که بررسی آن قطعی (deterministic) باشد و هزینه نادیده گرفته شدن آن بیشتر از هزینه نوشتن یک اسکریپت کوچک باشد. محدودیتهای مسیر فایل، دستورات الزامی پیش از commit و فراخوانیهای ممنوعه ابزار، همگی شامل این مورد میشوند. یک hook از نوع PreToolUse که با وضعیت 2 خارج میشود، فراخوانی ابزار را بهطور کامل مسدود میکند و متن stderr شما را بهعنوان دلیل به مدل بازمیگرداند، بنابراین این قانون فارغ از اینکه در کجای متن زمینه قرار دارد، اعمال میشود. هر چیزی که یک formatter یا linter میتواند درباره آن تصمیم بگیرد، باید توسط همان ابزار مدیریت شود و بهطور کامل از فایل دستورالعمل حذف گردد.