SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor · اپ ڈیٹ شدہ 2026-10-26

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

اگر instruction file میں stop لکھنے کے باوجود agent کام جاری رکھے تو اصل وجہ جانیں: context، مبہم اصول، متضاد code یا compaction، اور دوبارہ لکھنے سے پہلے diagnosis چلائیں۔

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

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

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

پہلے دو اصطلاحات سمجھ لیں۔ context window اس text block کو کہتے ہیں جسے model کسی مخصوص turn پر دیکھتا ہے: system prompt، آپ کی instruction files، conversation، اور agent کی پڑھی ہوئی ہر file۔ harness model کے گرد موجود program کو کہتے ہیں، یعنی وہ program جو disk سے files پڑھ کر یہ block تیار کرتا ہے۔ اس 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 میں اوپر کی طرف جاتا ہے جہاں سے آپ نے اسے شروع کیا تھا۔ filesystem root سے آپ کی working directory تک موجود ہر CLAUDE.md اور CLAUDE.local.md launch کے وقت مکمل load ہوتا ہے۔ انہیں اسی ترتیب سے جوڑا جاتا ہے۔ اس لیے launch کی جگہ کے سب سے قریب موجود file آخر میں پڑھی جاتی ہے، اور ایک ہی directory میں .local file کو main file کے بعد شامل کیا جاتا ہے۔

آپ کی working directory کے نیچے موجود subdirectories کی files مختلف طریقے سے کام کرتی ہیں۔ وہ launch کے وقت load نہیں ہوتیں۔ Agent جب اس directory میں موجود کوئی file پڑھتا ہے تو وہ files load ہوتی ہیں۔ .claude/rules/ میں موجود path-scoped rules کے ساتھ paths: frontmatter field ہو تو ان پر بھی یہی اصول لاگو ہوتا ہے۔ وہ ہر turn پر نہیں بلکہ matching file پڑھے جانے کے وقت context میں شامل ہوتے ہیں۔ v2.1.309 سے اس طرح load ہونے والی files پر فی file size limit بھی ہے: 200K context window میں 40,000 characters۔ طویل file کی صورت میں agent کو صرف اس کا ابتدائی حصہ ملتا ہے۔ اس لیے بڑی nested file کے آخر میں موجود rules ممکن ہے context تک نہ پہنچیں۔

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

AGENTS.md کو معیار بنانے والی repositories کو loading کا ایک اور مسئلہ درپیش ہوتا ہے۔ v2.1.277 سے Claude Code بطور default AGENTS.md کو project instructions کے طور پر پڑھتا ہے، لیکن صرف اس وقت جب آپ کی working directory یا اس سے اوپر کسی directory میں CLAUDE.md، .claude/CLAUDE.md یا CLAUDE.local.md موجود نہ ہو۔ آپ کی ذاتی ~/.claude/CLAUDE.md اس شمار میں شامل نہیں ہوتی۔ ان میں سے کوئی ایک بھی شامل کر دیں، حتیٰ کہ ذاتی notes کے لیے CLAUDE.local.md بھی، تو Claude Code اس کے بجائے آپ کی CLAUDE.md files پڑھتا ہے اور AGENTS.md کو مکمل طور پر چھوڑ دیتا ہے۔ دونوں load کرنے کے لیے /config میں Project instructions کو claude-md-and-agents-md پر set کریں۔ v2.1.277 سے پہلے کے versions میں، یا جب آپ CLAUDE.md برقرار رکھنا چاہیں، تو bridge کے طور پر CLAUDE.md استعمال کریں۔ اس کی پہلی line @AGENTS.md ہوتی ہے، جو launch کے وقت file import کرتی ہے؛ اس کے نیچے Claude سے متعلق اضافی notes شامل کی جا سکتی ہیں۔ اگر آپ کو کچھ اضافی شامل نہیں کرنا تو symlink بھی کام کرتا ہے۔ ابتدا ہی میں یہ طے کرنا کہ اس file میں کیا شامل ہونا چاہیے، الگ سوال ہے۔ اس کی وضاحت agent instructions کو human documentation سے الگ کرنے میں کی گئی ہے۔

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

الفاظ میں تبدیلی سے پہلے یہ ثابت کریں کہ agent فائل دیکھ سکتا ہے۔ اس کے لیے دو checks ہیں، اور پہلے کم خرچ check کریں۔

Session کے اندر /context چلائیں۔ یہ موجودہ window کو category کے لحاظ سے دکھاتا ہے، اور Memory files کی فہرست ان تمام instruction files کے نام دکھاتی ہے جو launch کے وقت load ہوئیں۔ جو فائل اس فہرست میں موجود نہ ہو، وہ launch کے وقت load نہیں ہوئی؛ اس لیے جب تک کوئی چیز اسے load نہ کرے، اس کے اندر لکھی گئی کوئی بھی بات مؤثر نہیں ہو سکتی۔ Subdirectory میں موجود nested file اس فہرست میں کبھی ظاہر نہیں ہوتی، کیونکہ وہ on demand load ہوتی ہے۔ جب وہ load ہوتی ہے تو terminal میں اس کے path کے ساتھ Loaded line ظاہر ہوتی ہے۔ /memory فائلوں کے locations دکھاتا ہے اور انہیں editing کے لیے کھولتا ہے، ان فائلوں کو بھی جو ابھی موجود نہیں ہیں۔

مزید یقینی جواب کے لیے loads کو log کریں۔ InstructionsLoaded hook event ہر بار fire ہوتا ہے جب کوئی 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 append کرتا ہے۔ کام کے دوران اسے tail -f /tmp/instructions-loaded.log کے ذریعے monitor کریں۔ اس event کا exit status نظرانداز کیا جاتا ہے، اس لیے hook صرف مشاہدہ کر سکتا ہے، عمل روک نہیں سکتا۔ اگر کسی session میں، جہاں nested file کے load ہونے کی توقع تھی، وہ log میں کبھی ظاہر نہ ہو تو الفاظ دوبارہ لکھنا روک دیں۔ مسئلہ placement کا ہے۔ ایک استثنا یہ ہے کہ Claude Code کی جانب سے براہ راست پڑھی جانے والی AGENTS.md اس event کو fire نہیں کرتی، اس لیے اس کا path /memory میں تلاش کریں۔ CLAUDE.md سے import کی گئی AGENTS.md معمول کے مطابق یہ event fire کرتی ہے۔

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

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

فاصلہ۔ جب تک compaction نہیں چلتی، turn 1 میں بیان کیا گیا rule، turn 90 میں بھی context window کے اندر موجود رہتا ہے۔ لیکن اب اسے 90 turns کے ایسے متن سے مقابلہ کرنا پڑتا ہے جو زیادہ نیا ہے اور آپ کے موجودہ کام سے زیادہ مخصوص ہے۔ جب compaction چل چکی ہو، تو ممکن ہے کہ وہ rule جو آپ نے صرف chat میں لکھا تھا، window میں موجود ہی نہ ہو۔ Claude Code کی اپنی documentation خبردار کرتی ہے کہ conversation کے ابتدائی حصے کی instructions ضائع ہو سکتی ہیں۔ یہ ذیل میں بیان کیا گیا دوسرا اثر ہے۔ آپ distance کو configuration کے ذریعے ختم نہیں کر سکتے، لیکن اسے ناپ سکتے ہیں۔ یہی task ایک fresh session میں چلائیں۔ اگر وہاں rule برقرار رہے اور طویل session کے دوران ناکام ہو جائے تو وجہ distance یا compaction ہے۔

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

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

لہذا اگر کوئی instruction پورے session میں برقرار رہنی چاہیے تو اسے project root file میں، بغیر paths: frontmatter کے، رکھیں۔ باقی تمام چیزیں ایسے tradeoffs ہیں جن کا فیصلہ آپ کو جان بوجھ کر کرنا چاہیے۔ 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. تصدیق کریں کہ یہ لوڈ ہوئی ہے۔ /context چلائیں اور Memory files کی فہرست پڑھیں، یا nested file کے لیے terminal میں اس کی Loaded لائن تلاش کریں۔ اگر فائل موجود نہیں ہے تو location درست کریں اور رک جائیں۔ اس فہرست میں شامل کوئی اور قدم ابھی لاگو نہیں ہوتا۔
  2. نئے session میں دوبارہ مسئلہ پیدا کریں۔ نیا session شروع کریں اور سب سے چھوٹا ایسا task دیں جس سے rule لاگو ہونا چاہیے۔ اگر یہاں rule کام کرے لیکن طویل session میں ناکام ہو، تو مسئلہ distance یا compaction میں ہے۔ اگر یہاں بھی ناکام ہو، تو مسئلہ خود rule میں ہے۔
  3. متبادل اثر ختم کریں۔ اسی تبدیلی کی درخواست ایسی directory میں کریں جس کا موجودہ code پہلے ہی rule کی پیروی کرتا ہو۔ اگر compliance واپس آ جائے تو اردگرد کا code آپ کے جملے پر غالب آ رہا تھا۔
  4. تضاد تلاش کریں۔ ایک ہی behaviour کے بارے میں مختلف guidance دینے والی دو files ایک documented failure ہیں: model کسی ایک کو من مانے طور پر منتخب کر سکتا ہے، اور یہ نہیں بتائے گا کہ اس نے ایسا کیا۔
  5. اسے قابلِ جانچ بنائیں اور دوبارہ آزمائیں۔ rule کو ایک واضح path اور condition کے ساتھ دوبارہ لکھیں۔ compliance میں نمایاں اضافہ ہو تو اس کا سبب phrasing تھا۔

Step 4 کے لیے صرف ایک command درکار ہے۔ موضوع کے لیے ہر instruction source میں grep کریں، صرف اس file میں نہیں جس میں آپ editing کر رہے تھے:

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

دو files میں مختلف ہدایات ملنا آپ کا bug ہے۔ ایک کو delete کریں۔ انہیں زیادہ سخت wording کے ذریعے ترجیح دینے کی کوشش نہ کریں، کیونکہ اس کا فیصلہ کرنے والا کوئی ranking engine موجود نہیں ہے۔ Claude Code v2.1.283 یا اس کے بعد کے version میں /doctor prompt-audit آپ کی instruction files، rules اور skills میں اس search کا وسیع تر version چلاتا ہے، اور proposed edits کے ساتھ contradictions رپورٹ کرتا ہے۔ یہ کچھ بھی تبدیل نہیں کرتا جب تک آپ اس کی اجازت نہ دیں۔

زیادہ مؤثر اصلاحات، ترتیب کے ساتھ

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

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

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

ایسی سادہ ممانعت کے لیے جس میں کوئی logic نہ ہو، آپ کی settings میں permissions.deny بغیر کسی maintain کیے جانے والے script کے یہی کام کرتا ہے، اور permission modes طے کرتے ہیں کہ آپ سے پوچھے بغیر کیا چلایا جائے۔ اگر کوئی instruction لازماً user message کے بجائے system prompt کی سطح پر ہونی چاہیے، تو --append-system-prompt اسے وہاں رکھتا ہے۔ تاہم یہ launch flag ہے جسے ہر نئے session کے ساتھ دوبارہ 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 کو نظرانداز کیوں کرتا ہے؟

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

session کے دوران instruction file میں ترمیم کرنے سے کیا کچھ تبدیل ہوتا ہے؟

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

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

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

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

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

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

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

کیا یہ مضمون مفید تھا؟