کوڈنگ ایجنٹس آپ کی ہدایات کیوں نظرانداز کرتے ہیں

کوڈنگ ایجنٹس آپ کی ہدایات کو نظرانداز کیوں کرتے ہیں

کوڈنگ ایجنٹس آپ کی ہدایات کو 4 وجوہات کی بنا پر نظرانداز کرتے ہیں، اور ان میں سے کوئی وجہ یہ نہیں کہ آپ بہت مؤدبانہ تھے۔ اصول کبھی context window میں شامل ہی نہیں ہوا۔ اصول اتنا مبہم تھا کہ کسی action کے مقابلے میں اس کی جانچ نہیں کی جا سکتی تھی۔ context میں موجود کسی دوسری چیز نے اس کی تردید کی، عموماً وہ code جسے agent نے ابھی پڑھا تھا۔ یا اصول ابھی بھی loaded ہے، لیکن موجودہ turn سے بہت پیچھے ہے، اور agent قریب موجود مواد کی بنیاد پر کام کر رہا ہے۔

ہر وجہ کا اپنا حل ہے، اس لیے پہلا کام یہ ہے کہ انہیں ایک دوسرے سے الگ پہچانا جائے۔ بڑے حروف اور IMPORTANT کا لفظ کوئی تشخیص نہیں ہیں۔ ذیل میں mechanics کی وضاحت کے لیے Claude Code کو عملی مثال کے طور پر استعمال کیا گیا ہے، کیونکہ August 2026 تک اس کے loading اور compaction behaviour کی تفصیلی documentation دستیاب ہے۔ دیگر tools کی تفصیلات مختلف ہو سکتی ہیں، لیکن مجموعی طور پر ان کا طریقۂ کار یہی رہتا ہے۔

پہلے 2 اصطلاحات۔ context window اس text block کو کہتے ہیں جسے model کسی مخصوص turn میں دیکھتا ہے: system prompt، آپ کی instruction files، conversation، اور ہر وہ file جسے agent نے پڑھا ہو۔ harness model کے گرد موجود program ہے؛ یہی وہ چیز ہے جو disk سے files پڑھ کر اس block کو assemble کرتی ہے۔ اس post میں کی گئی تقریباً ہر شکایت دراصل model کے بجائے harness کے بارے میں شکایت ہے۔

آپ کی instruction file پیغام ہے، setting نہیں

instruction file configuration نہیں ہوتی۔ runtime میں کچھ بھی CLAUDE.md کو پڑھ کر اس پر عمل درآمد نہیں کرتا۔ harness اس file کو disk سے پڑھتا ہے اور اس کا متن conversation میں شامل کر دیتا ہے۔ Claude Code میں یہ مواد system prompt کے بعد user message کے طور پر پہنچتا ہے۔ اس کا مطلب ہے کہ model آپ کے rules کو اسی طرح دیکھتا ہے جیسے آپ کا لکھا ہوا کوئی اور متن۔

اس کا ایک پریشان کن نتیجہ نکلتا ہے۔ آپ کے rules window میں موجود متن کے ہر دوسرے حصے سے مقابلہ کرتے ہیں، اور سب کو یکساں اہمیت حاصل ہوتی ہے۔ rule ایک دعویٰ ہے۔ agent نے ابھی جو file کھولی ہے، وہ evidence ہے۔ دونوں میں اختلاف ہو تو اکثر evidence غالب آتی ہے، اور کوئی error بھی ظاہر نہیں ہوتا، کیونکہ model کے نقطۂ نظر سے کچھ غلط نہیں ہوا۔

official documentation یہ بات واضح طور پر بیان کرتی ہے: instruction files کو enforced configuration نہیں بلکہ context سمجھا جاتا ہے۔ اگر آپ model کے فیصلے سے قطع نظر کسی action کو روکنا چاہتے ہیں تو sentence نہیں، hook درکار ہے۔ اس نکتے کو یاد رکھیں۔ اس post کے آخر میں موجود زیادہ تر fixes اسی نکتے کو مخصوص case پر لاگو کرتی ہیں۔

کون سی instruction files load ہوتی ہیں، اور کب

Claude Code اس directory tree میں اوپر کی طرف جاتا ہے جو اس directory سے شروع ہوتی ہے جہاں سے آپ نے اسے چلایا تھا۔ filesystem root سے آپ کی working directory تک موجود ہر CLAUDE.md اور CLAUDE.local.md launch کے وقت مکمل طور پر load ہوتی ہے۔ انہیں اسی ترتیب سے یکجا کیا جاتا ہے، اس لیے جہاں سے آپ نے Claude Code چلایا تھا اس کے قریب ترین file آخر میں پڑھی جاتی ہے۔ ایک ہی directory میں .local file کو main file کے بعد شامل کیا جاتا ہے۔

آپ کی working directory سے نیچے موجود subdirectories کی files مختلف طریقے سے کام کرتی ہیں۔ وہ launch کے وقت load نہیں ہوتیں۔ Agent جب اس directory میں موجود کوئی file پڑھتا ہے، تب وہ load ہوتی ہیں۔ .claude/rules/ میں path scoped rules بھی اسی طرح کام کرتے ہیں، اگر ان میں paths: frontmatter field موجود ہو۔ یہ rules ہر turn پر نہیں بلکہ matching file پڑھے جانے کے وقت context میں شامل ہوتے ہیں۔

یہی فرق رپورٹ ہونے والی ناکامیوں کے ایک بڑے حصے کی وجہ واضح کرتا ہے۔ آپ packages/api/CLAUDE.md میں ایک rule رکھتے ہیں، API کے بارے میں سوال کرتے ہیں، اور agent packages/api/ کے اندر کوئی file کھولے بغیر جواب دے دیتا ہے۔ Rule کو نظرانداز نہیں کیا گیا تھا۔ وہ کبھی context میں موجود ہی نہیں تھا۔ اگر آپ کی repository monorepo میں ہر package کے لیے الگ instruction files کے ذریعے guidance تقسیم کرتی ہے، تو ہر بار سب سے پہلے یہی چیز چیک کریں۔

Loading کا ایک اور مسئلہ ہے، اور یہی "agent نے میری instructions نظرانداز کر دیں" کی سب سے عام شکل ہے: Claude Code AGENTS.md نہیں بلکہ CLAUDE.md پڑھتا ہے۔ جس repository نے AGENTS.md کو standard بنایا ہو اور اس میں CLAUDE.md موجود نہ ہو، وہاں Claude Code کے لیے load کرنے کو کچھ نہیں ہوتا۔ اس کے لیے supported bridge ایک CLAUDE.md ہے، جس کی پہلی line @AGENTS.md ہوتی ہے۔ یہ launch کے وقت file import کرتی ہے، جبکہ اس کے نیچے Claude سے متعلق اضافی notes شامل کی جا سکتی ہیں۔ اگر شامل کرنے کے لیے اضافی مواد نہ ہو تو symlink بھی کام کرتی ہے۔ ابتدا ہی میں یہ طے کرنا کہ اس file میں کیا شامل ہونا چاہیے، ایک الگ سوال ہے۔ اس کی وضاحت agent instructions کو human documentation سے الگ کرنے میں کی گئی ہے۔

فائل کو دوبارہ لکھنے سے پہلے تصدیق کریں کہ وہ load ہو چکی ہے

الفاظ میں کوئی تبدیلی اس وقت تک نہ کریں جب تک آپ کے پاس یہ ثبوت نہ ہو کہ agent فائل دیکھ سکتا ہے۔ اس کے لیے 2 checks ہیں، اور پہلے کم لاگت والا check کریں۔

session کے اندر /context چلائیں۔ یہ موجودہ window کو category کے لحاظ سے تقسیم کرکے دکھاتا ہے، اور Memory files کی فہرست میں ان تمام instruction files کے نام ہوتے ہیں جو حقیقتاً load ہوئی ہیں۔ جو فائل اس فہرست میں موجود نہ ہو، وہ conversation کا حصہ نہیں ہے؛ اس لیے اس کے اندر آپ جو کچھ بھی لکھیں گے، اس کا کوئی اثر نہیں ہوگا۔ /memory فائل کے locations دکھاتا ہے اور انہیں editing کے لیے کھولتا ہے، جن میں وہ فائلیں بھی شامل ہیں جو ابھی موجود نہیں ہیں۔

زیادہ قطعی نتیجے کے لیے loads کا log بنائیں۔ InstructionsLoaded hook event ہر بار فعال ہوتا ہے جب کوئی CLAUDE.md یا rules file context میں شامل ہوتی ہے، اور اس کا matcher بتاتا ہے کہ load کیوں ہوئی: 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 اپنا payload standard input پر JSON کے طور پر وصول کرتا ہے، اس لیے cat پورا record شامل کر دیتا ہے۔ کام کے دوران اسے tail -f /tmp/instructions-loaded.log سے monitor کریں۔ اس event کا exit status نظرانداز کیا جاتا ہے، اس لیے hook صرف مشاہدہ کر سکتا ہے، عمل کو روک نہیں سکتا۔ اگر ایسی session کے دوران، جس میں آپ nested file کے load ہونے کی توقع رکھتے تھے، وہ فائل اس log میں کبھی ظاہر نہ ہو تو الفاظ کی نئی ترتیب دینا روک دیں۔ مسئلہ file placement کا ہے۔

طویل session آپ کے rules پر کیا اثر ڈالتی ہے

یہاں دو الگ اثرات لاگو ہوتے ہیں، اور ان کے لیے مختلف اقدامات درکار ہوتے ہیں۔

فاصلہ۔ turn 1 پر بیان کیا گیا rule، turn 90 پر بھی context window میں موجود ہوتا ہے، لیکن اب وہ حالیہ اور آپ کے موجودہ کام سے زیادہ متعلقہ 90 turns کے متن سے مقابلہ کر رہا ہوتا ہے۔ آپ اسے configuration کے ذریعے ختم نہیں کر سکتے، لیکن اس کی پیمائش کر سکتے ہیں۔ یہی task ایک نئی session میں چلائیں۔ اگر rule وہاں برقرار رہتا ہے اور طویل session کے دوران ناکام ہو جاتا ہے تو اس کا سبب فاصلہ ہے۔

Compaction۔ جب window بھر جاتی ہے تو harness اب تک کی conversation کا خلاصہ بناتا ہے اور اسی summary سے عمل جاری رکھتا ہے۔ جو کچھ برقرار رہتا ہے، اس کا فیصلہ summariser کرتا ہے کہ کیا اہم ہے؛ یہ ضروری نہیں کہ وہی چیز اہم ہو جسے آپ اہم سمجھتے ہیں۔ Claude Code ہر mechanism کے نتائج کی دستاویز فراہم کرتا ہے، اور ان میں نمایاں فرق ہے۔ Project root CLAUDE.md اور unscoped rules، compaction کے بعد disk سے دوبارہ inject کیے جاتے ہیں۔ Auto memory بھی disk سے دوبارہ inject ہوتی ہے۔ paths: frontmatter والے rules اس وقت تک ضائع رہتے ہیں جب تک matching file دوبارہ نہ پڑھی جائے۔ ذیلی directories میں موجود nested CLAUDE.md files اس وقت تک ضائع رہتی ہیں جب تک اسی subdirectory کی کوئی file دوبارہ نہ پڑھی جائے۔

اپنی instructions کو اس table کے مطابق درجہ دیں، تو fragility کی ترتیب واضح ہو جاتی ہے۔ جو rule آپ نے صرف chat میں type کیا ہو، وہ session میں سب سے زیادہ fragile ہوتا ہے: وہ صرف اسی صورت برقرار رہتا ہے جب summary میں اتفاقاً شامل کر لیا جائے۔ packages/api/CLAUDE.md میں موجود rule اس کے بعد آتا ہے، کیونکہ اسے ایک بار load کیا گیا، پھر summary میں غائب ہو گیا، اور وہ صرف اسی directory میں اگلی read کے وقت واپس آتا ہے۔ Project root file میں موجود rule سب سے زیادہ پائیدار ہوتا ہے، کیونکہ اسے ہر بار disk سے دوبارہ پڑھا جاتا ہے۔

لہذا اگر کسی instruction کو پوری session کے دوران برقرار رہنا ضروری ہو تو اسے project root file میں رکھیں اور اس میں paths: frontmatter شامل نہ کریں۔ باقی ہر چیز ایک ایسا tradeoff ہے جس کا انتخاب آپ کو جان بوجھ کر کرنا چاہیے۔ context window میں برقرار رہنے والی چیزوں کا انتظام میں /compact کو focus argument کے ساتھ اور /clear کو غیر متعلقہ tasks کے درمیان بیان کیا گیا ہے۔ دونوں عوامل اس بات کو بدلتے ہیں کہ summariser کو آپ کے rules کے بارے میں فیصلہ کرنے کا موقع کتنی بار ملتا ہے۔

اردگرد موجود کوڈ اصول سے زیادہ مؤثر کیوں ہوتا ہے

یہ وہ ناکامی ہے جسے لوگ سب سے زیادہ بیان کرتے ہیں، لیکن سب سے کم تشخیص کرتے ہیں۔ آپ کی فائل میں لکھا ہے کہ database access repository layer کے ذریعے ہونی چاہیے۔ agent ایسا handler لکھ دیتا ہے جو ORM (object relational mapper) کو براہِ راست کال کرتا ہے۔ agent نے style کی بنیاد پر آپ کی ہدایت نظرانداز نہیں کی۔ شواہد کی تعداد زیادہ تھی۔

اصول ایک ترجیح بیان کرتا ہے۔ کوڈ ایک ترجیح کا عملی نمونہ دکھاتا ہے۔ جب agent اس module میں ترمیم سے پہلے 3 فائلیں کھولتا ہے اور تینوں ORM کو براہِ راست کال کرتی ہیں، تو context کے ایک طرف ایک تجریدی جملہ ہوتا ہے، جبکہ دوسری طرف 3 ٹھوس، حالیہ اور اسی task سے متعلق مثالیں ہوتی ہیں۔ مقامی pattern کو نقل کرنا عموماً درست عمل ہوتا ہے۔ یہاں یہ صرف اس لیے غلط ہے کہ آپ ایک ایسی بات جانتے ہیں جو context میں موجود نہیں: یہ فائلیں legacy ہیں۔

اس لیے یہ بات rule میں لکھیں۔ ایسے rules جو اپنے خلاف موجود شواہد کا ذکر کرتے ہیں، حقیقی repository میں بھی مؤثر رہتے ہیں۔ جو rules صرف ایک واضح ترجیح بیان کرتے ہیں، وہ ایسا نہیں کر پاتے۔

نیا database access app/repositories/ کے ذریعے ہونا چاہیے۔ app/legacy/ کے تحت موجود فائلیں اب بھی ORM کو براہِ راست کال کرتی ہیں۔ یہ پرانا code ہے، pattern نہیں۔ اسے نقل نہ کریں۔

اصل کام دوسرا جملہ کرتا ہے۔ یہ agent کو پہلے ہی بتا دیتا ہے کہ اسے کیا ملنے والا ہے اور اسے کیسے سمجھنا ہے۔ یہی اصلاح ہر ایسے rule پر لاگو ہوتی ہے جس کی repository واضح طور پر تردید کرتی ہو: ایسا commit style جس کی آپ کی history پیروی نہیں کرتی، ایسا test layout جسے آپ کی نصف test suite نظرانداز کرتی ہے، یا ایسا import convention جو صرف نئے code میں موجود ہے۔ جہاں بھی code اور file میں اختلاف ہو، اس اختلاف کو file میں واضح طور پر لکھیں۔

ایک مبہم اصول کی جانچ نہیں ہو سکتی، اس لیے اس پر عمل بھی نہیں کیا جا سکتا

"صاف code لکھیں۔" "غیر ضروری engineering نہ کریں۔" "اسے سادہ رکھیں۔" "migrations کے معاملے میں محتاط رہیں۔" ان میں سے کسی بھی اصول کو کسی مخصوص action کے مقابلے میں agent یا آپ test نہیں کر سکتے۔ اگر agent کو ایسا اصول دیا جائے جسے وہ اپنے output کے مقابلے میں check نہ کر سکے، تو وہ اندازہ لگا رہا ہے، اور آپ اس اندازے کی درجہ بندی احساس کی بنیاد پر کر رہے ہیں۔

اپنی file کی ہر line پر یہ test لاگو کریں۔ وہ shell command لکھیں جو اصول ٹوٹنے پر non-zero exit کرے۔ اگر آپ وہ command نہیں لکھ سکتے، تو اصول checkable نہیں ہے۔ ان جوڑوں کا موازنہ کریں:

• Checkable نہیں: "Functions کو چھوٹا رکھیں۔" Checkable: "60 lines سے زیادہ طویل function کے اوپر ایک comment ہونا چاہیے جس میں بتایا گیا ہو کہ یہ function اتنا طویل کیوں ہے۔"
• Checkable نہیں: "اپنی تبدیلیوں کو test کریں۔" Checkable: "task مکمل قرار دینے سے پہلے npm test چلائیں اور failure count شامل کریں۔"
• Checkable نہیں: "Files کو منظم رکھیں۔" Checkable: "HTTP handlers src/api/handlers/ میں موجود ہوں۔ اس directory میں کوئی اور چیز نہ ہو۔"
• Checkable نہیں: "Code کو درست طور پر format کریں۔" Checkable: ".ts files میں 2 space indentation استعمال کریں۔"

"غیر ضروری engineering نہ کریں" وہ اصول ہے جسے لوگ سب سے پہلے ترک کرتے ہیں، کیونکہ اس کی اصلاح مختصر sentence نہیں بلکہ طویل sentence ہوتی ہے: یہ واضح کرنا کہ کام کرنے والی کم سے کم تبدیلی سے حقیقتاً کیا مراد ہے agent کو ایسے criteria فراہم کرتا ہے جن کے مقابلے میں وہ اپنے diff کی جانچ کر سکتا ہے۔

Size بھی یہی مسئلہ ہے، صرف مختلف شکل میں۔ Claude Code کی guidance ہر instruction file کے لیے 200 lines سے کم رہنے کو ہدف بناتی ہے اور براہ راست بتاتی ہے کہ طویل files adherence کم کرتی ہیں۔ 700 lines کی file زیادہ مضبوط instruction نہیں ہوتی۔ یہ دعووں کی 700 lines ہوتی ہیں، جن میں ایک دوسرے سے متصادم ہونے کے زیادہ امکانات ہوتے ہیں، اور ہر turn میں ان کا شمار آپ کے window کے خلاف ہوتا ہے، جو آپ کے token usage میں براہ راست ظاہر ہوتا ہے۔ File کو اس طرح structure کرنا کہ ہر rule ایسے heading کے تحت ہو جسے reader scan کر سکے، ایسی instruction file لکھنے کے موضوع میں شامل ہے جس پر agent عمل کر سکے۔ اس سے بھی بہتر یہ ہے کہ ان حصوں کو ہٹا دیں جو instruction دینے کے بجائے صرف وضاحت کرتے ہیں: handlers اور models کہاں موجود ہیں، اس کی directory tour ایسا structure ہے جسے agent ضرورت کے وقت repository کے parsed map سے lookup کر سکتا ہے، بجائے اس کے کہ اسے ہر turn میں window کے اندر رکھا جائے۔

دس منٹ میں اس کی تشخیص کیسے کریں

یہ کمانڈز اسی ترتیب سے چلائیں۔ آخری مرحلے پر فوراً جانے سے عموماً قواعد کی ایک لمبی فائل بن جاتی ہے، مگر مسئلہ پھر بھی حل نہیں ہوتا۔

1. تصدیق کریں کہ یہ load ہوئی ہے۔ /context چلائیں اور Memory files کی فہرست پڑھیں۔ اگر فائل موجود نہ ہو تو location درست کریں اور رک جائیں۔ اس فہرست کی کوئی دوسری ہدایت ابھی لاگو نہیں ہوتی۔
2. نئے session میں دوبارہ مسئلہ پیدا کریں۔ نیا session شروع کریں اور کم سے کم ایسا task دیں جس سے rule لاگو ہونا چاہیے۔ اگر مختصر session میں rule کام کرتی ہے مگر طویل session میں ناکام ہوتی ہے تو مسئلہ context distance یا compaction میں ہے۔ اگر یہاں بھی ناکام ہو تو خود rule میں مسئلہ ہے۔
3. متبادل ہدایات ہٹا دیں۔ اسی تبدیلی کی درخواست ایسی directory میں کریں جہاں موجودہ code پہلے ہی اس rule کی پیروی کرتا ہو۔ اگر compliance واپس آ جائے تو اردگرد کا code آپ کے جملے پر غالب آ رہا تھا۔
4. تضاد تلاش کریں۔ ایک ہی behaviour کے بارے میں مختلف guidance دینے والی دو files ایک documented failure ہیں۔ Model کسی ایک کو من مانے طور پر منتخب کر سکتا ہے، اور آپ کو یہ نہیں بتائے گا کہ اس نے ایسا کیا۔
5. اسے قابلِ جانچ بنائیں اور دوبارہ test کریں۔ Rule کو ایک concrete path اور condition کے ساتھ دوبارہ لکھیں۔ Compliance میں نمایاں اضافہ اس بات کی نشاندہی کرتا ہے کہ مسئلہ phrasing میں تھا۔

Step 4 کے لیے ایک ہی command درکار ہے۔ صرف اس file میں نہیں بلکہ ہر instruction source میں topic تلاش کریں جسے آپ edit کر رہے تھے:

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

دو files میں مختلف ہدایات ملنا آپ کا bug ہے۔ ایک file حذف کریں۔ انہیں زیادہ سخت wording سے ترتیب دینے کی کوشش نہ کریں، کیونکہ ان کی ترجیح طے کرنے والا کوئی ranking engine موجود نہیں جس سے رجوع کیا جا سکے۔

جن اقدامات کا اثر زیادہ ہے، وہ ترتیب سے

ذیل کا ہر قدم اس سے اوپر والے قدم کے مقابلے میں زیادہ مؤثر ہے اور اسے ترتیب دینے میں زیادہ لاگت آتی ہے۔ جب کسی rule کو دوبارہ لکھنا آسان ہو تو اوپر سے آغاز کریں۔ جیسے ہی rule اتنا اہم ہو جائے کہ کبھی کبھار ہونے والی خلاف ورزیاں قابل قبول نہ رہیں، نچلے قدم پر چلے جائیں۔

1. Rule کو واضح بنائیں۔ کسی path، command یا condition کا نام دیں۔ وہ counter-evidence بھی شامل کریں جو agent کو repository میں ملے گا، جیسا کہ پہلے دکھایا گیا ہے۔ اس پر کوئی لاگت نہیں آتی اور یہ حیرت انگیز حد تک بہت سے cases حل کر دیتا ہے۔
2. Rule کو اس چیز کے قریب لے جائیں جس پر وہ لاگو ہوتا ہے۔ مثلاً nested CLAUDE.md، .claude/rules/ میں scoped path rule، یا خود file کے اوپر موجود comment۔ اس طرح rule اسی read میں آ جاتا ہے جس میں متعلقہ code پڑھا جاتا ہے۔ اس tradeoff کو قبول کریں: اس طریقے سے load ہونے والی ہر چیز اگلی compaction پر context سے نکل جاتی ہے اور اگلی matching read پر دوبارہ شامل ہوتی ہے۔
3. Enforcement کو hook میں منتقل کریں۔ Prose صرف ہدایت دیتی ہے۔ Hook فیصلہ کرتا ہے۔ Hooks مقررہ lifecycle events پر code کے طور پر چلتے ہیں اور model کے نتیجے سے قطع نظر rule نافذ کرتے ہیں۔
4. Rule کو deterministic tool کے حوالے کریں اور prose حذف کر دیں۔ Formatting، import order، line length، ممنوع imports اور commit message کی ساخت۔ ruff format، prettier --write، eslint، یا pre-commit hook استعمال کریں۔ Formatter ہر بار درست ہوتا ہے اور zero tokens استعمال کرتا ہے۔ جملہ زیادہ تر اوقات درست ہوتا ہے، لیکن ہر turn پر tokens استعمال کرتا ہے۔

مرحلہ 3 مکمل طور پر۔ فرض کریں کہ agent کو migration files میں کبھی ترمیم نہیں کرنی چاہیے۔ اسے .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 چلائیں، پھر نیا session شروع کریں اور agent سے migrations/ کے تحت موجود file میں ترمیم کرنے کو کہیں۔ ترمیم مسترد ہو جائے گی اور آپ کا message وجہ کے طور پر واپس آئے گا۔ PreToolUse پر exit status 2 tool call کو چلنے سے پہلے روک دیتا ہے، اور آپ کا stderr متن model کو blocking message کے طور پر دیا جاتا ہے۔ ${CLAUDE_PROJECT_DIR} project root پر resolve ہوتا ہے، اس لیے hook اس directory سے قطع نظر کام کرتا ہے جس میں agent موجود ہو۔ Agent کو rule سے اتفاق کرنے، اسے یاد رکھنے، یا اسے اب بھی context میں رکھنے کی ضرورت نہیں ہوتی۔ ترمیم نہیں ہوتی۔

کسی ایسی flat prohibition کے لیے جس میں کوئی logic نہ ہو، اپنی settings میں permissions.deny بغیر کسی maintain کیے جانے والے script کے یہی کام کرتا ہے، اور permission modes طے کرتے ہیں کہ آپ سے پہلے پوچھے بغیر کیا چلایا جائے۔ اگر کسی instruction کو واقعی user message کے بجائے system prompt level پر موجود ہونا ضروری ہو تو --append-system-prompt اسے وہاں رکھتا ہے، تاہم اسے ہر invocation کے ساتھ pass کرنا لازمی ہے؛ اس لیے یہ interactive کام کے مقابلے میں scripts کے لیے زیادہ موزوں ہے۔

جن چیزوں کی ہدایت نہیں دی جا سکتی

واضح طور پر طے کریں کہ اس کا کون سا حصہ آپ کی ذمہ داری ہے۔ جگہ کا تعین، عبارت، فائلوں کے درمیان تضادات، اور فائل کا سائز مصنف کے مسائل ہیں، اور ان کے حل بھی مصنف ہی کو کرنے ہیں۔ باقی چیز model کا رویہ ہے، اور بہتر wording اسے ختم نہیں کرے گی۔

اتفاق compliance نہیں ہے۔ کوئی agent کسی rule کو تسلیم کرے گا، اسے درست طور پر دہرا دے گا، اور دو tool calls بعد اسے توڑ دے گا۔ یہ acknowledgement کچھ خرچ نہیں کرتی اور نہ ہی کسی چیز کی پیش گوئی کرتی ہے۔ اسے fix نہ سمجھیں اور test میں شمار نہ کریں۔

کچھ عادات مستقل رہتی ہیں۔ Comments شامل کرنا، defensive error handling شامل کرنا، اختتامی summary لکھنا، اور واضح اگلی command چلانا۔ جس rule میں ان کی ممانعت ہو، وہاں یہ عادات صفر کے بجائے کم شرح سے دوبارہ ظاہر ہوتی ہیں۔ آپ اپنی شرح ناپ سکتے ہیں: یہی task fresh sessions میں 10 بار چلائیں اور violations گنیں۔ جہاں یہ تعداد صفر ہونی چاہیے، وہاں rule کو prompt سے نکالنا ہوگا۔ کام کا کچھ حصہ باقی ہونے کے باوجود اسے مکمل قرار دینا بھی اسی عادت کی ایک شکل ہے، اور اس کا حل زبانی ہدایت کے بجائے ساختی ہونا چاہیے: unlazy skill اس جملے کی جگہ Depth Tree استعمال کرتا ہے، اور gate files مقرر کرتا ہے جنہیں agent کے مکمل ہونے کا دعویٰ کرنے سے پہلے clear کرنا ضروری ہوتا ہے۔

آپ کا اپنا session بھی مثال بن جاتا ہے۔ اگر agent نے turn 12 پر rule توڑا اور آپ نے اسے نظرانداز کر دیا، تو یہ violation اب context میں demonstration کے طور پر موجود ہے، اور rule کی نسبت کہیں زیادہ حالیہ ہے۔ Violation نظر آتے ہی اسے درست کریں۔ غیر درست شدہ violation session کے باقی حصے کو سکھاتا ہے۔

Instruction file security boundary نہیں ہے۔ یہ رویے کو shape کرتی ہے، اسے enforce نہیں کرتی۔ جہاں miss مہنگی پڑ سکتی ہو، جیسے credentials یا destructive commands، وہاں permissions یا hook استعمال کریں۔ Agent سے secrets دور رکھنا یہی اصول data پر لاگو کرتا ہے: agent کو کسی file کو نہ پڑھنے کی ہدایت نہ دیں، بلکہ file کو اس کے لیے unreadable بنائیں۔

مختصر بات یہ ہے: ثابت کریں کہ file load ہوئی ہے، rule کو checkable بنائیں، اسے اس چیز کے قریب رکھیں جس پر وہ لاگو ہوتا ہے، اور جب miss rate اب بھی اہم ہو تو اسے prose سے نکال دیں۔ جس rule کو agent نظرانداز نہیں کر سکتا، وہ rule کبھی agent سے مانگا ہی نہیں گیا تھا۔

FAQ

Claude Code میری CLAUDE.md کو نظرانداز کیوں کرتا ہے؟

یہ فرض کرنے سے پہلے تصدیق کریں کہ وہ لوڈ ہوئی تھی۔ /context چلائیں اور Memory files کی فہرست دیکھیں؛ جس فائل کا نام وہاں موجود نہ ہو، وہ گفتگو میں شامل نہیں ہے۔ Instruction files، system prompt کے بعد user message کے طور پر بھیجی جاتی ہیں اور نافذ configuration کے بجائے context سمجھی جاتی ہیں، اس لیے مکمل پابندی کی ضمانت نہیں ہوتی۔ حقیقی صورتوں میں عموماً چار میں سے ایک وجہ ہوتی ہے: فائل ایسی subdirectory میں ہے جہاں agent نے کبھی نہیں پڑھا، دو فائلوں میں اختلاف ہے اور model نے ایک کو من مانے طور پر منتخب کیا، rule اتنا مبہم ہے کہ کسی action کے مقابلے میں اس کی جانچ نہیں ہو سکتی، یا اردگرد کا code rule کے برخلاف عمل دکھا رہا ہے۔

session کے دوران instruction file میں ترمیم کرنے سے کیا فرق پڑتا ہے؟

گفتگو میں پہلے سے موجود copy پر کوئی فرق نہیں پڑتا۔ آپ کی working directory سے اوپر موجود فائلیں launch کے وقت مکمل طور پر لوڈ ہوتی ہیں، اس لیے model کے پاس موجود متن launch کے وقت والا متن ہوتا ہے۔ ترمیم شامل کرنے کے لیے نئی session شروع کریں، یا agent سے کہیں کہ وہ اپنی معمول کی file tools کے ذریعے فائل پڑھے؛ اس طرح موجودہ version ایک نئے message کے طور پر گفتگو میں شامل ہو جائے گا۔ compaction کے بعد project root file کو disk سے دوبارہ پڑھا جاتا ہے، اس لیے نیا version اس مرحلے پر بھی شامل ہو جاتا ہے۔

root CLAUDE.md اور nested فائل میں اختلاف ہو تو کون سی فائل مؤثر ہوتی ہے؟

قابلِ اعتماد طور پر کوئی بھی نہیں۔ دریافت شدہ فائلیں ایک دوسرے کو override کرنے کے بجائے context میں concatenate کی جاتی ہیں۔ ان کی ترتیب filesystem root سے آپ کی working directory تک ہوتی ہے، اس لیے قریب ترین فائل صرف آخر میں پڑھی جاتی ہے۔ تضادات حل کرنے والا کوئی precedence engine موجود نہیں، اور Claude Code کی documentation کے مطابق متضاد rules من مانے طور پر resolve ہو سکتے ہیں۔ Nested فائلوں کو ایسی additions کے طور پر لکھیں جن میں وہ path واضح ہو جس پر وہ لاگو ہوتی ہیں، اور contradiction کو برتری دلانے کی کوشش کرنے کے بجائے حذف کریں۔

کیا میری instructions /compact کے بعد برقرار رہتی ہیں؟

یہ اس بات پر منحصر ہے کہ وہ کیسے لوڈ ہوئی تھیں۔ Project root CLAUDE.md، غیر محدود rules اور auto memory، compaction کے بعد disk سے دوبارہ inject کیے جاتے ہیں۔ paths: frontmatter والی rules اور subdirectories میں موجود nested CLAUDE.md فائلیں اس وقت تک ضائع رہتی ہیں جب تک matching file دوبارہ نہ پڑھی جائے۔ جو چیز آپ نے صرف chat میں لکھی ہو، وہ صرف اسی صورت برقرار رہتی ہے جب summariser نے اسے محفوظ رکھا ہو۔ اگر کوئی rule پوری session کے دوران برقرار رہنا ضروری ہے تو اسے project root file میں، paths: frontmatter کے بغیر، رکھیں۔

rule کو prose کے بجائے hook کب بنانا چاہیے؟

جب check deterministic ہو اور miss ہونے کی لاگت ایک چھوٹی script لکھنے کی لاگت سے زیادہ ہو۔ File path restrictions، commit سے پہلے مطلوبہ commands، اور ممنوع tool calls اس معیار پر پورے اترتے ہیں۔ ایسا PreToolUse hook جو status 2 کے ساتھ exit کرے، tool call کو براہِ راست روک دیتا ہے اور آپ کے stderr text کو وجہ کے طور پر model کو واپس دیتا ہے۔ اس لیے rule context میں موجود نہ ہونے کے باوجود بھی نافذ رہتا ہے۔ جس چیز کا فیصلہ formatter یا linter کر سکتا ہو، اس کی ذمہ داری اسی tool کو دیں اور اسے instruction file سے مکمل طور پر حذف کر دیں۔