تکلیف: AI کوڈنگ ایک ہی جگہ بار بار کیوں ٹوٹتی ہے

Cursor، Windsurf یا Claude Code سے پروجیکٹ لکھوانے والے تقریباً ہر کسی ن� یہی درد سہا ہے: AI پورا بلاک کوڈ دیتا ہے، آپ کاپی پیسٹ کر کے چلاتے ہیں — بلڈ فال، ٹیسٹ ریڈ، ڈیپنڈنسی غلط جگہ انسٹال۔ مسئلہ AI کی ذہانت نہیں، بلکہ یہ ہے کہ اسے آپ کے پروجیکٹ کے «خفیہ قوانین» معلوم ہی نہیں۔

AGENTS.md پروجیکٹ کی روٹ ڈائریکٹری میں رکھی جانے والی ایک مارک ڈاؤن فائل ہے، خاص طور پر AI کے لیے لکھی گئی، جو بتاتی ہے کہ بلڈ کیسے کرنا ہے، ٹیسٹ کیسے چلانا ہے، کون سے معیارات پر عمل کرنا ہے۔ README.md انسانوں کے لیے ہے، اس میں پروجیکٹ کا تعارف، شراکت کی ہدایات، برانڈ کی کہانی بھری ہوتی ہے۔ AI جب یہ سب پڑھتا ہے تو ایسے ہوتا ہے جیسے نئے ملازم کو پہلے دن کمپنی کی تشہیری بروشر تھما کر فوراً کوڈ لکھنے کو کہا جائے — وہ جانتا ہے کمپنی کیا کرتی ہے، لیکن بلڈ کمانڈ، ٹیسٹ کا طریقہ، ESLint کے قوانین سے بالکل بے خبر۔ نتیجہ یہ ہوتا ہے کہ ہر چیٹ میں بار بار اصلاح کرنی پڑتی ہے: «pnpm استعمال کرو npm نہیں»، «ٹیسٹ packages/web کے نیچے ہے»، «lint چلانا مت بھولنا»۔ یہی اصلاح سو بار دہرائیں، پروجیکٹ پھر بھی بگڑا رہتا ہے۔

فری لانسنگ کا نقصان اور بھی سیدھا ہے: آپ نے Next.js + Prisma کا آرڈر لیا، Cursor سے تیز کام کروانا ہے، لیکن AI نے npm install سے ڈیپنڈنسی لگا دی، pnpm کی workspace سیٹنگ برباد ہو گئی؛ اسے آپ کا ڈیٹا بیس schema کس ڈائریکٹری میں ہے معلوم نہیں، بنایا ہوا migration فائل فوراً ایرر دے رہا ہے۔ کلائنٹ ڈلیوری پر دباؤ ڈال رہا ہے، آپ AI کے بنائے کوڈ کو ڈیبگ کرتے ہوئے تین گھنٹے کھو دیتے ہیں — یہ پیسے بہت بے چین کما رہے ہیں۔

AI کو پروجیکٹ کے خفیہ قوانین معلوم نہ ہونے کے 3 عام حادثے: ① پیکج مینیجر غلط (پروجیکٹ pnpm استعمال کرتا ہے، AI ڈیفالٹ طور پر npm install چلاتا ہے)، ڈیپنڈنسی غلط جگہ لگتی ہے، workspace سیٹنگ فال ہو جاتی ہے؛ ② ٹیسٹ اندراج نہیں ملتا (ٹیسٹ packages/web میں ہے، AI روٹ سے pnpm test چلاتا ہے، «ٹیسٹ فائل نہیں ملی» کا ایرر آتا ہے)؛ ③ کوڈ اسٹائل ناموافق (پروجیکٹ ESLint + Prettier استعمال کرتا ہے، AI کے بنائے کوڈ کی انڈنٹیشن اور کوٹیشن بالکل غلط، CI فوراً فال ہو جاتا ہے)۔

موقع: AGENTS.md «انسانی دستاویز» اور «مشینی دستاویز» کو مکمل طور پر الگ کرتا ہے

GitHub پر اوپن سورس پروجیکٹ AGENTS.md (ریپوزٹری: github.com/agentsmd/agents.md، 26 اگست 2026 تک تقریباً 24 ہزار اسٹارز) بالکل اسی مسئلے کا حل ہے۔ اس کا بنیادی خیال انتہائی سادہ ہے: پروجیکٹ کی روٹ میں ایک مارک ڈاؤن فائل رکھو، جو خاص طور پر AI کو بتائے کہ بلڈ کیسے کرنا ہے، ٹیسٹ کیسے چلانا ہے، کوڈ اسٹائل کیا ہونا چاہیے۔

یہ README کا متبادل نہیں، بلکہ ضمیمہ ہے۔ README انسانی شراکت داروں کے لیے ہے، AGENTS.md AI ایجنٹس کے لیے۔ دونوں کے فرائض واضح ہیں، ایک دوسرے میں مداخلت نہیں۔

ماخذ کے مطابق، AGENTS.md کو ہزاروں اوپن سورس پروجیکٹس اپنا چکے ہیں (تصدیق شدہ)، اور یہ VS Code، Cursor، Windsurf، Aider، GitHub Copilot جیسے تمام بڑے AI کوڈنگ ٹولز کے ساتھ کام کرتا ہے (تصدیق شدہ نتیجہ)؛ مزید برآں کمیونٹی فیڈبیک کے مطابق OpenAI Codex اور Google Jules بھی اسے سپورٹ کرتے ہیں (⚠️ غیر تصدیق شدہ)۔ آپ ابھی نہیں سیکھیں گے تو AI آپ سے بول چال کی زبان میں بات کرے گا۔

راستہ نمبر ایک: کم از کم قابل استعمال AGENTS.md خود لکھیں

لاگت بہت کم ہے۔ نئی فائل بنائیں، تین سیکشن لکھ دیں، بس۔

پیشگی سمجھ: نیچے کی مثالوں میں pnpm استعمال ہو رہا ہے (npm سے زیادہ ڈسک بچاتا ہے، monorepo workspace سپورٹ کرتا ہے)، turbo monorepo ٹاسک آرکیسٹریشن ٹول ہے، --filter پیرامیٹر صرف کسی مخصوص سب پیکج پر عمل کرتا ہے، پورے ریپوزٹری کو متاثر نہیں کرتا۔

پہلا سیکشن «Dev environment tips»: AI کو بتائیں کہ پروجیکٹ کون سا پیکج مینیجر استعمال کرتا ہے، سب پیکج میں کیسے جائیں، نیا ماڈیول کیسے بنائیں۔ مثال کے طور پر آفیشل ٹیمپلیٹ میں:

• pnpm dlx turbo run where <project_name> — سیدھا مخصوص سب پیکج ڈائریکٹری میں پہنچ جائیں، ls کر کے ایک ایک فولڈر دیکھنے کی ضرورت نہیں
• pnpm install --filter <project_name> — صرف ایک سب پیکج کی ڈیپنڈنسی لگائے، پورے monorepo کو ہاتھ نہ لگائے
• pnpm create vite@latest <project_name> -- --template react-ts — TypeScript چیکنگ کے ساتھ نیا React + Vite سب پیکج بنائے

یہ کمانڈز AI خود نہیں جوڑ سکتا، لیکن آپ لکھ دیں تو فوراً مان لے گا۔

دوسرا سیکشن «Testing instructions»: AI کو بتائیں ٹیسٹ کیسے چلانا ہے، CI پلان کہاں ہے، کمٹ کرنے سے پہلے کون سی چیکنگ لازمی ہے۔ آفیشل مثال میں شامل ہے:

• pnpm turbo run test --filter <project_name> — مخصوص سب پیکج کی تمام چیکنگ چلائے
• pnpm vitest run -t "<test name>" — صرف نام سے ملنے والا ایک ٹیسٹ چلائے
• «Fix any test or type errors until the whole suite is green» — پوری سیوٹ سبز نہ ہو تو رکنا نہیں
• «Add or update tests for the code you change, even if nobody asked» — یہ آخری جملہ کلیدی ہے، نہ لکھیں تو AI اکثر ٹیسٹ لکھنے میں کنجی کھینچتا ہے

تیسرا سیکشن «PR instructions»: کمٹ ٹائٹل کا فارمیٹ طے کرے، lint اور test چلانا لازمی بنائے۔ آفیشل مثال ہے Title format: [<project_name>] <Title>، اور «Always run pnpm lint and pnpm test before committing»۔

یہ تین سیکشن مل کر 50 لائنوں سے کم ہیں، لیکن AI کے بنائے کوڈ کی فرسٹ ٹائم پاس ریٹ واضح طور پر بڑھ جاتی ہے (کمیونٹی فیڈبیک کے مطابق، تصدیق باقی ہے)۔

راستہ نمبر دو: بڑے monorepo میں نیسٹڈ استعمال

اگر آپ نے انٹرپرائز لیول پروجیکٹ اٹھایا ہے اور کوڈ بیس monorepo سٹرکچر میں ہے (متعدد متعلقہ پروجیکٹس ایک ہی Git ریپوزٹری میں، مثلاً فرنٹ اینڈ، بیک اینڈ، شیئرڈ کوڈ ہر ایک الگ سب ڈائریکٹری میں)، تو ایک ہی AGENTS.md کافی نہیں۔ AGENTS.md نیسٹنگ سپورٹ کرتا ہے: ہر سب ڈائریکٹری میں الگ AGENTS.md رکھیں، AI خود بخود «سب سے قریب والی» فائل پڑھ لے گا۔

عملی طریقہ: روٹ ڈائریکٹری کی AGENTS.md میں عالمی ضوابط لکھیں (پیکج مینیجر، CI فلو، سیکیورٹی ہدایات)، پھر packages/web/، packages/api/، packages/shared/ میں الگ الگ فائلیں رکھیں، ہر ایک میں اسی سب پیکج کی مخصوص بلڈ کمانڈ، ٹیسٹ اندراج، خاص ڈیپنڈنسی لکھیں۔ مثلاً فرنٹ اینڈ پیکج میں لکھیں «کمپوننٹ لائبریری shadcn، اسٹائلنگ Tailwind، آئیکنز lucide-react»؛ بیک اینڈ پیکج میں لکھیں «ڈیٹا بیس migration Prisma سے، API روٹس src/routes کے نیچے، تصدیق JWT سے»۔

AI جب سب ڈائریکٹری میں کام کرتا ہے تو خود بخود قریب ترین AGENTS.md لوڈ کر لیتا ہے، روٹ والی فائل سے زیادہ ترجیح دیتا ہے۔ اس کا مطلب ہے کہ ایک ہی پروجیکٹ میں فرنٹ اینڈ AI اسسٹنٹ اور بیک اینڈ AI اسسٹنٹ کو مکمل طور پر مختلف ہدایات ملیں، ایک دوسرے میں مداخلت نہیں ہوگی۔

راستہ نمبر تین: اسے فری لانسنگ کا فرق کرنے والا فروختی نقطہ بنائیں

AI فری لانسنگ مارکیٹ اب خونی مقابلے میں بدل چکی ہے — ہر کوئی Cursor استعمال کرتا ہے، لیکن ڈلیوری کا معیار ناہموار ہے۔ اگر آپ بولی کی دستاویز میں ایک جملہ لکھ دیں «اس پروجیکٹ میں AGENTS.md معیاری دستاویز لگائی گئی ہے، AI سے مدد لے کر تیار کردہ کوڈ پروجیکٹ کے معیارات پر عمل کرتا ہے»، تو جیتنے کا امکان ان لوگوں سے واضح طور پر زیادہ ہو جائے گا جو صرف یہ کہتے ہیں «میں AI سے کوڈ لکھواتا ہوں»۔

عملی حکمت عملی: آرڈر ملنے کے بعد پہلے 30 منٹ کلائنٹ کے پروجیکٹ کی سٹرکچر سمجھنے میں لگائیں، پھر کسٹم AGENTS.md لکھیں۔ یہ دستاویز خود بھی ڈلیوری کا حصہ ہے — کلائنٹ کو ملے گی تو وہ آگے خود بھی AI سے کوڈ کی دیکھ بھال آسانی سے کر سکے گا۔

AGENTS.md کنفیگریشن سروس کو الگ قیمت دیں (حوالہ قیمت، مقامی مارکیٹ کے مطابق ایڈجسٹ کریں): بنیادی ورژن $70 (سنگل فائل کنفیگریشن + README وضاحت)، انٹرپرائز ورژن $420 (monorepo نیسٹنگ + سیکیورٹی ضوابط + ٹیم ٹریننگ)۔ ڈلیوری کی فہرست: ① کسٹم AGENTS.md فائل ② 30 دن کی واٹس ایپ مدد ③ 10 منٹ کی اسکرین ریکارڈنگ ٹریننگ۔ کس کے لیے موزوں: کلائنٹ کے پاس پہلے سے Cursor/Windsurf سبسکرپشن ہے لیکن نتائج نہیں آ رہے۔ کس کے لیے نہیں: کلائنٹ ابھی بھی صرف دستی ڈویلپمنٹ کر رہا ہے، AI ٹولز اپنایا ہی نہیں۔

کیس اسٹڈی: AGENTS.md کی مطابقت کی حفاظتی دیوار

AGENTS.md MIT لائسنس کے تحت ہے (تصدیق شدہ)، کمیونٹی کی طرف سے دیکھ بھال ہوتی ہے (گورننس سٹرکچر کی تصدیق باقی)، آفیشل ویب سائٹ agents.md ہے۔

مطابقت اس کی سب سے بڑی حفاظتی دیوار ہے: تصدیق شدہ نتیجہ کے مطابق VS Code، Cursor، Windsurf، Aider، GitHub Copilot سب AGENTS.md پڑھنے کی سپورٹ رکھتے ہیں؛ کمیونٹی فیڈبیک کے مطابق OpenAI Codex، Claude Code، Gemini CLI، Google Jules جیسے ٹولز بھی سپورٹ فراہم کرتے ہیں (⚠️ غیر تصدیق شدہ)۔ اس کا مطلب ہے کہ آپ ایک فائل لکھیں، تمام بڑے AI اسسٹنٹ کام کریں — ہر ٹول کے لیے الگ کنفیگریشن لکھنے کی ضرورت نہیں۔

دوسرے حل سے موازنہ کریں: Cursor کی .cursorrules صرف Cursor پر کام کرتی ہے، Windsurf پر جانے سے برباد؛ Claude Code کی CLAUDE.md صرف Claude کے لیے؛ GitHub Copilot کا ہدایات کا نظام بالکل الگ۔ AGENTS.md کی «ایک بار لکھو، ہر جگہ چلاؤ» والی خصوصیت ہی اس کی تیزی سے مقبولیت کی بنیادی وجہ ہے۔

ٹول کی منتقلی کی لاگت صفر۔ آج Cursor استعمال کریں، کل Windsurf پر جائیں، AGENTS.md فوراً دوبارہ قابل استعمال، قوانین دوبارہ لکھنے کی ضرورت نہیں۔

ایکشن کال: آج رات اپنے پروجیکٹ میں مشینی ہدایات نامہ شامل کریں

5 منٹ کی ایکشن لسٹ: ① پروجیکٹ کی روٹ