چرا ایجنت‌های کدنویسی دستورات شما را نادیده می‌گیرند؟

چرا ایجنت‌های کدنویسی دستورات شما را نادیده می‌گیرند

ایجنت‌های کدنویسی به چهار دلیل دستورات شما را نادیده می‌گیرند و هیچ‌کدام از این دلایل به این خاطر نیست که شما بیش از حد مؤدب بوده‌اید. قانون مورد نظر هرگز در context window قرار نگرفته است. قانون بیش از حد مبهم بوده و امکان بررسی یک اقدام بر اساس آن وجود نداشته است. مورد دیگری در context با آن در تضاد بوده که معمولاً کدی است که ایجنت به‌تازگی خوانده است. یا اینکه قانون همچنان بارگذاری شده اما در فاصله‌ای دور از نوبت فعلی قرار دارد و ایجنت بر اساس آنچه در نزدیکی‌اش است عمل می‌کند.

هر علت، راه‌حل خاص خود را دارد، بنابراین اولین وظیفه، تشخیص این دلایل از یکدیگر است. استفاده از حروف بزرگ و کلمه IMPORTANT تشخیص درستی نیست. مکانیسم‌های زیر از Claude Code به‌عنوان نمونه استفاده می‌کنند، زیرا رفتار بارگذاری و فشرده‌سازی آن تا اوت 2026 به‌طور دقیق مستند شده است. سایر ابزارها در جزئیات متفاوت هستند اما در کلیات به همین صورت عمل می‌کنند.

ابتدا دو اصطلاح را تعریف می‌کنیم. context window بلوکی از متن است که مدل در یک نوبت مشخص می‌بیند: system prompt، فایل‌های دستورالعمل شما، گفتگو و هر فایلی که ایجنت خوانده است. harness برنامه‌ای است که پیرامون مدل قرار دارد؛ همان چیزی که فایل‌ها را از دیسک می‌خواند و آن بلوک را سرهم می‌کند. تقریباً هر شکایتی در این مطلب، در واقع شکایتی از harness است، نه مدل.

فایل دستورالعمل شما یک پیام است، نه یک تنظیمات

یک فایل دستورالعمل، پیکربندی (configuration) نیست. هیچ بخشی از runtime، فایل CLAUDE.md را نمی‌خواند و آن را اعمال نمی‌کند. ابزار اجراکننده (harness)، فایل را از روی دیسک می‌خواند و متن آن را در گفتگو جای‌گذاری می‌کند. در Claude Code، این محتوا به عنوان یک پیام کاربر که پس از system prompt قرار می‌گیرد، ارسال می‌شود؛ این یعنی مدل، قوانین شما را همان‌طور می‌بیند که هر متن دیگری را که تایپ کرده‌اید، مشاهده می‌کند.

این موضوع یک نتیجهٔ ناخوشایند دارد. قوانین شما با هر متن دیگری در پنجره، در شرایطی برابر رقابت می‌کنند. یک قانون، صرفاً یک ادعاست. فایلی که agent به‌تازگی باز کرده است، یک مدرک است. وقتی این دو با هم اختلاف داشته باشند، مدرک اغلب پیروز می‌شود و هیچ خطایی هم رخ نمی‌دهد، زیرا از دیدگاه مدل، هیچ اتفاق اشتباهی نیفتاده است.

مستندات رسمی این موضوع را به‌صراحت بیان می‌کنند: فایل‌های دستورالعمل به عنوان زمینه (context) در نظر گرفته می‌شوند، نه پیکربندیِ اعمال‌شده. برای مسدود کردن یک اقدام، صرف‌نظر از اینکه مدل چه تصمیمی می‌گیرد، شما به یک hook نیاز دارید، نه یک جمله. این اصل را به خاطر بسپارید. بیشتر اصلاحاتی که در انتهای این پست آمده‌اند، در واقع همین اصل هستند که در یک مورد خاص اعمال شده‌اند.

کدام فایل‌های دستورالعمل بارگذاری می‌شوند و چه زمانی

ابزار Claude Code مسیر درختی را از دایرکتوری که آن را در آن اجرا کرده‌اید، به سمت بالا طی می‌کند. تمام فایل‌های CLAUDE.md و CLAUDE.local.md از ریشه سیستم‌فایل تا دایرکتوری کاری شما، هنگام راه‌اندازی به‌طور کامل بارگذاری می‌شوند. این فایل‌ها به همان ترتیب به یکدیگر متصل (concatenate) می‌شوند، بنابراین فایلی که به محل اجرای شما نزدیک‌تر است، در آخرین مرحله خوانده می‌شود و در یک دایرکتوری واحد، فایل .local پس از فایل اصلی ضمیمه می‌گردد.

فایل‌های موجود در زیرشاخه‌های پایین‌تر از دایرکتوری کاری شما رفتار متفاوتی دارند. این فایل‌ها هنگام راه‌اندازی بارگذاری نمی‌شوند، بلکه زمانی بارگذاری می‌شوند که ایجنت فایلی را در آن دایرکتوری بخواند. همین موضوع در مورد قوانین محدود به مسیر در .claude/rules/ که دارای فیلد frontmatter با عنوان paths: هستند نیز صدق می‌کند: این قوانین هنگام خوانده شدن یک فایل منطبق وارد کانتکست می‌شوند، نه در هر نوبت از گفتگو.

همین یک تفاوت، بخش بزرگی از خطاهای گزارش‌شده را توضیح می‌دهد. شما قانونی را در packages/api/CLAUDE.md قرار می‌دهید، سوالی درباره API می‌پرسید و ایجنت بدون باز کردن هیچ فایلی در مسیر packages/api/ پاسخ می‌دهد. قانون نادیده گرفته نشده است؛ بلکه اصلاً در کانتکست حضور نداشته است. اگر مخزن شما دستورالعمل‌ها را در فایل‌های دستورالعمل هر پکیج در یک monorepo تقسیم کرده است، این اولین موردی است که باید همیشه بررسی کنید.

یک تله دیگر در بارگذاری وجود دارد که رایج‌ترین نسخه از «ایجنت دستورات مرا نادیده گرفت» است: Claude Code فایل CLAUDE.md را می‌خواند، نه AGENTS.md. مخزنی که از AGENTS.md استفاده می‌کند و فاقد CLAUDE.md است، هیچ چیزی برای بارگذاری به Claude Code نمی‌دهد. پل ارتباطی پشتیبانی‌شده، یک فایل CLAUDE.md است که خط اول آن @AGENTS.md باشد؛ این خط فایل مذکور را هنگام راه‌اندازی وارد می‌کند و یادداشت‌های اختصاصی Claude می‌توانند در زیر آن قرار گیرند. اگر محتوای اضافه‌ای برای افزودن ندارید، استفاده از symlink نیز کارساز است. تصمیم‌گیری درباره اینکه چه چیزی باید در وهله اول در آن فایل قرار بگیرد، موضوع جداگانه‌ای است که در تفکیک دستورالعمل‌های ایجنت از مستندات انسانی به آن پرداخته شده است.

پیش از بازنویسی فایل، از بارگذاری آن اطمینان حاصل کنید

تا زمانی که از مشاهده فایل توسط agent مطمئن نشده‌اید، تغییری در متن ایجاد نکنید. دو روش برای بررسی وجود دارد که روش ساده‌تر در اولویت است.

دستور /context را در نشست اجرا کنید. این دستور پنجره فعلی را بر اساس دسته‌بندی نمایش می‌دهد و لیست Memory files نام تمام فایل‌های دستورالعملی که واقعاً بارگذاری شده‌اند را ذکر می‌کند. فایلی که در این لیست نباشد، در گفتگو وجود ندارد؛ بنابراین هر چیزی که در آن بنویسید بی‌اثر خواهد بود. دستور /memory مسیر فایل‌ها را لیست کرده و آن‌ها را برای ویرایش باز می‌کند، حتی فایل‌هایی که هنوز وجود ندارند.

برای بررسی دقیق‌تر، بارگذاری‌ها را لاگ کنید. رویداد hook در InstructionsLoaded هر بار که یک CLAUDE.md یا یک فایل قوانین وارد context می‌شود، فعال می‌گردد و 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"
          }
        ]
      }
    ]
  }
}

این hook داده‌های خود را به صورت JSON در ورودی استاندارد (stdin) دریافت می‌کند، بنابراین cat کل رکورد را به فایل ضمیمه می‌کند. در حین کار، آن را با tail -f /tmp/instructions-loaded.log مانیتور کنید. وضعیت خروج (exit status) این رویداد نادیده گرفته می‌شود، بنابراین hook فقط می‌تواند مشاهده کند و هرگز قادر به مسدودسازی نیست. اگر فایل تو در توی شما در طول نشستی که انتظار بارگذاری آن را داشتید در لاگ ظاهر نشد، بازنویسی را متوقف کنید. مشکل از محل قرارگیری فایل است.

تأثیر نشست‌های طولانی بر قوانین شما

در اینجا دو اثر مجزا اعمال می‌شود که نیازمند واکنش‌های متفاوتی هستند.

فاصله. قانونی که در نوبت 1 بیان شده، در نوبت 90 همچنان در پنجره قرار دارد، اما اکنون با 90 نوبت متن که جدیدتر و مرتبط‌تر با کاری است که در حال حاضر انجام می‌دهید، رقابت می‌کند. شما نمی‌توانید این موضوع را با پیکربندی برطرف کنید، اما می‌توانید آن را اندازه‌گیری کنید. همان وظیفه را در یک نشست تازه اجرا کنید. اگر قانون در آنجا برقرار است اما در عمق یک نشست طولانی شکست می‌خورد، پاسخ شما «فاصله» است.

فشرده‌سازی. هنگامی که پنجره پر می‌شود، سیستم گفتگو را تا آن لحظه خلاصه کرده و از آن خلاصه ادامه می‌دهد. آنچه باقی می‌ماند، مواردی است که خلاصه‌ساز آن‌ها را مهم تشخیص داده است، که با آنچه شما مهم می‌دانید متفاوت است. 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 خط ادعا با احتمال تناقض بیشتر است و در هر نوبت از پنجره متنی شما کسر می‌شود که مستقیماً در میزان مصرف توکن شما نمایان می‌شود. ساختاردهی به فایل به گونه‌ای که هر قانون زیر یک عنوان قابل اسکن قرار گیرد، در نوشتن فایل دستورالعملی که عامل بتواند بر اساس آن عمل کند پوشش داده شده است. بهتر از آن، بخش‌هایی که به جای دستور دادن، توصیف می‌کنند را حذف کنید: تور دایرکتوری برای اینکه هندلرها و مدل‌ها کجا قرار دارند، ساختاری است که عامل می‌تواند در صورت نیاز از نقشه تجزیه شده مخزن جستجو کند، به جای اینکه آن را در هر نوبت در پنجره متنی حمل کند.

نحوه عیب‌یابی در ده دقیقه

این دستورالعمل‌ها را به ترتیب اجرا کنید. پریدن به مرحله آخر باعث می‌شود با فایلی طولانی از قوانین متناقض مواجه شوید که همچنان کار نمی‌کنند.

1. بارگذاری را تأیید کنید. دستور /context را اجرا کرده و لیست فایل‌های Memory را بخوانید. اگر فایل در آنجا نیست، مسیر را اصلاح کنید و متوقف شوید. هیچ‌کدام از مراحل بعدی در این حالت کاربرد ندارند.
2. در یک نشست جدید بازتولید کنید. یک نشست جدید شروع کنید و کوچک‌ترین وظیفه‌ای که باید قانون را فعال کند، به آن بدهید. اگر در اینجا کار می‌کند اما در یک نشست طولانی شکست می‌خورد، مشکل از فاصله (distance) یا فشرده‌سازی (compaction) است. اگر در اینجا هم شکست می‌خورد، خودِ قانون مشکل دارد.
3. رقابت را حذف کنید. همان تغییر را در دایرکتوری درخواست کنید که کد موجود در آن، از قبل از قانون پیروی می‌کند. اگر انطباق (compliance) بازگشت، کد اطراف، دستور شما را نادیده می‌گرفته است.
4. به دنبال تضاد بگردید. دو فایل که برای یک رفتار واحد، دستورالعمل‌های متفاوتی می‌دهند، یک خطای مستند است: مدل ممکن است یکی را به دلخواه انتخاب کند و به شما هم اطلاع نخواهد داد.
5. آن را قابل بررسی کنید و دوباره تست کنید. قانون را با یک مسیر مشخص و یک شرط بازنویسی کنید. جهش بزرگ در میزان انطباق به این معناست که نحوه نگارش، عامل مشکل بوده است.

مرحله 4 تنها یک دستور است. تمام منابع دستورالعمل را برای موضوع مورد نظر جستجو کنید، نه فقط فایلی که در حال ویرایش آن بودید:

grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

وجود یک مورد مشابه در دو فایل که مطالب متفاوتی می‌گویند، همان باگ شماست. یکی را حذف کنید. سعی نکنید با استفاده از کلمات قوی‌تر به آن‌ها اولویت بدهید، زیرا هیچ موتور رتبه‌بندی برای اعمال این اولویت‌ها وجود ندارد.

اصلاحات، به ترتیب میزان تأثیرگذاری

هر گام در زیر، نسبت به گام پیشین خود تأثیرگذاری بیشتری دارد و راه‌اندازی آن هزینه‌برتر است. زمانی که بازنویسی یک قانون کم‌هزینه است، از بالا شروع کنید. به محض اینکه یک قانون اهمیت کافی پیدا کرد و نادیده گرفتن گاه‌به‌گاه آن غیرقابل‌قبول شد، به سمت پایین حرکت کنید.

1. قانون را مشخص و عینی کنید. یک مسیر، یک دستور یا یک شرط را نام ببرید. همان‌طور که پیش‌تر نشان داده شد، شواهد نقض‌کننده را که عامل (agent) در مخزن پیدا می‌کند، اضافه کنید. این کار رایگان است و بخش قابل‌توجهی از موارد را برطرف می‌کند.
2. قانون را به موضوع تحت نظارتش نزدیک‌تر کنید. یک CLAUDE.md تو در تو، قانونی با دامنه محدود در .claude/rules/، یا یک کامنت در بالای خود فایل. در این صورت، قانون همزمان با کدی که بر آن اعمال می‌شود، خوانده می‌شود. این بده‌بستان را بپذیرید: هر چیزی که به این شکل بارگذاری شود، در فشرده‌سازی بعدی حذف شده و در خواندن منطبق بعدی بازمی‌گردد.
3. اجرای قانون را به یک hook منتقل کنید. متن (prose) درخواست می‌کند، اما یک hook تصمیم می‌گیرد. hookها به عنوان کد در رویدادهای ثابت چرخه حیات اجرا می‌شوند و فارغ از نتیجه‌گیری مدل، اعمال می‌گردند.
4. قانون را به یک ابزار قطعی (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 در تنظیمات شما همان کار را بدون نیاز به نگهداری اسکریپت انجام می‌دهد و حالت‌های دسترسی (permission modes) بدون پرسش از شما، تعیین می‌کنند چه چیزی اجرا شود. اگر یک دستور واقعاً باید در سطح system prompt باشد و نه در پیام کاربر، --append-system-prompt آن را در آنجا قرار می‌دهد؛ هرچند باید در هر فراخوانی ارسال شود که این برای اسکریپت‌ها مناسب‌تر از کار تعاملی است.

آنچه با دستورالعمل قابل اصلاح نیست

شفاف باشید که کدام بخش از این موارد در حیطه مسئولیت شماست. جای‌گذاری، جمله‌بندی، تداخل بین فایل‌ها و حجم فایل، مشکلاتی هستند که نویسنده باید آن‌ها را رفع کند. مابقی موارد، رفتار مدل است و با تغییر جمله‌بندی اصلاح نمی‌شوند.

توافق به معنای تبعیت نیست. یک عامل (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) و حافظه خودکار پس از compaction دوباره از دیسک تزریق می‌شوند. قوانین دارای frontmatter در paths: و فایل‌های CLAUDE.md تو در تو در زیرشاخه‌ها تا زمانی که دوباره یک فایل منطبق خوانده نشود، از دست می‌روند. هر چیزی که فقط در چت تایپ کرده‌اید، تنها در صورتی باقی می‌ماند که خلاصه‌ساز (summariser) آن را حفظ کرده باشد. اگر قانونی باید در کل نشست معتبر بماند، آن را بدون frontmatter در paths: در فایل ریشه پروژه قرار دهید.

چه زمانی یک قانون باید به جای متن، به یک hook تبدیل شود؟

زمانی که بررسی آن قطعی (deterministic) باشد و هزینه نادیده گرفته شدن آن بیشتر از هزینه نوشتن یک اسکریپت کوچک باشد. محدودیت‌های مسیر فایل، دستورات الزامی پیش از commit و فراخوانی‌های ممنوعه ابزار، همگی واجد شرایط هستند. یک hook در PreToolUse که با وضعیت 2 خارج می‌شود، فراخوانی ابزار را کاملاً مسدود کرده و متن stderr شما را به عنوان دلیل به مدل بازمی‌گرداند، بنابراین فارغ از اینکه قانون در کجای متن زمینه باشد، رعایت می‌شود. هر چیزی که یک formatter یا linter می‌تواند درباره آن تصمیم بگیرد، باید توسط همان ابزار مدیریت شود و به‌طور کامل از فایل دستورالعمل حذف گردد.