ایجنٹی فلٹر ڈویلپمنٹ میں ٹیکنالوجی کا استعمال کیسے کریں: ڈویلپرز کے لیے ایک ہینڈ بک

AI کی مدد سے ترقی کے بارے میں سب سے بڑی غلط فہمیوں میں سے ایک یہ ہے کہ AI استعمال کرنے کا مطلب یہ ہے کہ انجینئرنگ کے سالوں کے تجربے کو ترک کر دیا جائے۔ یہ سچ نہیں ہے۔

آپ جو آرکیٹیکچرل پیٹرن آپ نے سیکھے ہیں، آپ نے جو غلطیاں کی ہیں، آپ کی ٹیم جن اصولوں پر عمل کرتی ہے، اور فلٹر انجینئر کے طور پر آپ نے جو معیارات تیار کیے ہیں وہ لے سکتے ہیں اور ایجنٹ کی مہارتوں کے ذریعے اپنے AI کوڈنگ ایجنٹس کو سکھا سکتے ہیں۔ اس کا مطلب ہے کہ آپ کو تجربہ اور AI کے درمیان انتخاب کرنے کی ضرورت نہیں ہے۔ آپ دونوں کو ساتھ لے سکتے ہیں۔

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

ایجنٹ سے پروفائل اسکرین کو پُر کرنے کو کہیں۔ یہ ایسی چیز پیدا کرتا ہے جو کام کرتا ہے۔ لیکن صاف اور دوبارہ قابل استعمال کوڈ بنانے کے بجائے، ProfileCard آپ کا ویجیٹ widgets/ فولڈر میں درج ذیل کو لکھیں: _buildProfileCard() اسکرین فائل کے اندر چھپا ہوا نجی طریقہ۔

تنہائی میں خدشات رکھنے کے بجائے؛ StatefulWidget احتیاط سے ڈیزائن کردہ فائل ڈھانچے میں، متوقع حالت کو فائل کے نیچے شامل کیا جاتا ہے جس میں پہلے سے ہی 10 کلاسز ہیں۔

ڈیٹا ماڈل استعمال کرتا ہے: Map آپ کے بجائے freezed– تشریح شدہ اسباق۔ درآمد بیرل فائل کو چھوڑ دے گا اور براہ راست اندرونی پیکیج کے راستے کو مارے گا۔ تھیم ڈیزائن ٹوکن کو نظر انداز کرتی ہے اور ہارڈ کوڈ شدہ ہیکساڈیسیمل ویلیو کا استعمال کرتی ہے۔ خرابی کو سنبھالنے میں ان پٹ کی خرابی کے درجہ بندی کے بجائے خام تاروں کا استعمال ہوتا ہے۔ جب کوئی ٹیم بلاک استعمال کرتی ہے تو ریاستی انتظام فراہم کنندہ ہوتا ہے۔

اس میں سے کوئی بھی مطلق معنی میں غلط نہیں ہے۔ ایجنٹ نے غلطی نہیں کی کیونکہ وہ ڈارٹ میں اچھا نہیں تھا۔ غلطیاں اس لیے ہوئیں کیونکہ ٹیم نہیں جانتی تھی کہ فلٹر کوڈ کیسے لکھنا ہے۔

یہ وہ مسئلہ ہے جسے حل کرنے کے لیے ایجنٹ کی مہارتیں پیدا کی گئی تھیں۔

ایجنٹ کی مہارتیں سٹرکچرڈ مارک ڈاؤن فائلیں ہیں جو ایک AI ایجنٹ کو نہ صرف "کیا” بلکہ کسی مخصوص کام کا "کیسا” بھی سکھاتی ہیں۔ ایجنٹ کوڈ تیار کرنے سے پہلے ٹیکنالوجی کا انتخاب اس بات کو یقینی بناتا ہے کہ ٹیم کے کنونشنز، آرکیٹیکچرل پیٹرن، فائل آرگنائزیشن کنونشن، نام کے معیارات، اور معیار کی توقعات اپنی جگہ پر ہیں۔ نتیجہ پروجیکٹ سے تعلق رکھنے والا کوڈ ہے۔

فلٹر ٹیم درج ذیل سرکاری تکنیکی ذخیروں کو برقرار رکھتی ہے: github.com/flutter/agent-pluginsڈارٹ ٹیم مندرجہ ذیل تکمیلی سیٹوں کو برقرار رکھتی ہے: github.com/dart-lang/skills. اس میں ریسپانسیو لے آؤٹ، ڈیکلیرٹیو روٹنگ، JSON سیریلائزیشن، یونٹ ٹیسٹنگ، سٹیٹک اینالیسس، پیکیج پر انحصار ریزولوشن، پیٹرن میچنگ، اور بہت کچھ شامل ہے۔

لیکن سب سے زیادہ طاقتور ہنر وہ ہیں جو آپ کی اپنی تحریر، بطور انجینئر آپ کے مخصوص تجربے، آپ کی ٹیم کی مخصوص غلطیاں، اور آپ کے پروجیکٹ کے مخصوص نمونوں کو انکوڈ کرتی ہیں۔ آپ کے اپنے پروڈکشن کے تجربے سے لکھی گئی تکنیکیں 10 عام تکنیکوں کے قابل ہیں کیونکہ وہ ان درست غلطیوں کو روکتی ہیں جو آپ کی ٹیم اصل میں ان کے برقرار رکھنے والے کوڈ بیسز میں کرتی ہے۔

ٹیکنالوجی تمام بڑے AI کوڈنگ ایجنٹس کے ساتھ کام کرتی ہے۔ چاہے آپ کی ٹیم Claude Code، Antigravity، OpenAI Codex، Cursor، GitHub Copilot CLI، یا کوئی اور ہم آہنگ ایجنٹ استعمال کرتی ہو، ٹیکنالوجی عالمگیر معیارات کی پیروی کرتی ہے۔ ایک بار ایک مہارت لکھیں اور یہ کہیں بھی کام کرتا ہے۔

اس ہینڈ بک میں ہر چیز کا احاطہ کیا گیا ہے: ٹیکنالوجیز کیا ہیں، وہ اندرونی طور پر کیسے کام کرتی ہیں، آفیشل فلٹر اور ڈارٹ ٹیکنالوجیز کو کیسے انسٹال کیا جائے، ہر ایک اہم ایجنٹ کے لیے ٹیکنالوجیز کو کیسے ترتیب دیا جائے، موجودہ ٹیکنالوجیز کو گہرائی سے کیسے پڑھیں اور سمجھیں، اور سب سے اہم بات یہ ہے کہ آپ کی اپنی ٹیکنالوجیز کیسے لکھیں جو آپ کے مخصوص کوڈ کو بہتر بناتی ہیں۔

ہم ضروری مہارتوں کا بھی احاطہ کرتے ہیں جو ہر فلٹر ٹیم کے پاس ہونا ضروری ہے، ڈارٹ کی مہارتیں جن سے تمام ڈویلپرز مستفید ہوتے ہیں، اور ایسے جدید نمونوں کا بھی احاطہ کرتے ہیں جو وقت کے ساتھ ساتھ آپ کی مہارتوں کو جوڑ دیتے ہیں۔

سب کے بعد، آپ کو ٹیکنالوجی کا استعمال کرنے کا طریقہ معلوم نہیں ہوگا. آپ اسی نیت سے کوڈ لکھیں گے جس نیت سے آپ صاف فلٹر کوڈ لکھتے ہیں، اور آپ سمجھ جائیں گے کہ ایسا کرنا آپ کی ٹیم کے انجینئرنگ کے معیار میں کیا جانے والا سب سے بڑا فائدہ مند سرمایہ کاری کیوں ہے۔

انڈیکس

شرطیں

اس گائیڈ کے ساتھ آگے بڑھنے سے پہلے، آپ کو درج ذیل کی ضرورت ہوگی:

1. پھڑپھڑانا اور ڈارٹ کی مہارت

آپ کو ملٹی اسکرین فلٹر ایپس بنانے، ریاستی نظم و نسق کے نمونوں کا استعمال کرتے ہوئے، اور کلین آرکیٹیکچر کے بنیادی اصولوں پر عمل کرنے میں ماہر ہونا چاہیے۔ آپ کو سینئر انجینئر بننے کی ضرورت نہیں ہے، لیکن اس گائیڈ میں موجود تکنیکی مثالوں سے اندازہ ہوتا ہے کہ آپ جانتے ہیں کہ تکنیکی مہارتیں کیا ہیں۔ StatefulWidget ریپوزٹری پیٹرن کیسا لگتا ہے، مہر بند کلاسز کیوں اہم ہیں، اور json_serializable بنائیں۔

2. اے آئی کوڈنگ ایجنٹ کارروائی میں

یہ ٹیکنالوجی ایجنٹوں کے ساتھ کام کرتی ہے جس میں کلاڈ کوڈ، اینٹی گریویٹی، اوپن اے آئی کوڈیکس، گٹ ہب کوپائلٹ سی ایل آئی، کرسر، اور بہت کچھ شامل ہے۔ ان میں سے کم از کم ایک انسٹال اور کام کرنا ضروری ہے۔ یہ گائیڈ تمام ایجنٹوں کے لیے مخصوص ترتیبات کا احاطہ کرتا ہے۔

3. Node.js انسٹال کریں۔

کہ skills سرکاری مہارتوں کو انسٹال کرنے کے لیے استعمال ہونے والے CLI ٹولز npm کے ذریعے تقسیم کیے جاتے ہیں۔ چلائیں node -v چیک کریں۔ اگر آپ کے پاس Node.js انسٹال نہیں ہے تو اسے nodejs.org سے ڈاؤن لوڈ کریں۔

4. فلٹر یا ڈارٹ پروجیکٹ جس پر کام کرنا ہے۔

اس گائیڈ میں دی گئی مثالیں اور تکنیکی مشقیں بہترین کام کرتی ہیں جب خلاصہ کی پیروی کرنے کے بجائے حقیقی منصوبوں پر لاگو کیا جائے۔

5. بنیادی مارک ڈاؤن واقفیت

مہارتیں مارک ڈاؤن میں لکھی جاتی ہیں۔ آپ کو یہ جاننا ہوگا کہ عنوان کیا ہے (##)، کوڈ بلاک کی ظاہری شکل (ٹرپل بیک ٹِکس)، اور YAML فرنٹ بلاک کی ظاہری شکل ( --- ڈھیر کے سب سے اوپر بلاکس میں بنڈل)۔

اس کے علاوہ، آپ کو کسی خاص ٹولز کی ضرورت نہیں ہے۔ اسکلز سادہ ٹیکسٹ فائلیں ہیں جو آپ کے پروجیکٹ کے فولڈر میں موجود ہیں۔ ابتدائی CLI کمانڈز کے علاوہ بنانے، مرتب کرنے یا انسٹال کرنے کے لیے کچھ نہیں ہے۔

ایجنٹ کی مہارتیں کیا ہیں؟

ڈارٹ کو جاننے والے ڈویلپر کی خدمات حاصل کرنے اور ایک ایسے ڈویلپر کی خدمات حاصل کرنے کے درمیان فرق کے بارے میں سوچیں جو آپ کے جیسے فلٹر پروجیکٹ پر دو سالوں سے کام کر رہا ہے۔

آپ فلٹر کوڈ لکھ سکتے ہیں جو دونوں کے ساتھ کام کرتا ہے۔ لیکن تجربہ کار لوگ جانتے ہیں کہ کسی دستاویز میں کیا نہیں ہے۔ اس کا مطلب یہ ہے کہ ٹیم نجی تعمیراتی طریقے استعمال نہیں کرتی ہے، کہ وہ ہمیشہ ویجیٹ سیکشنز کو اپنی فائلوں میں نکالتی ہے، کہ وہ لوڈنگ کی حالت کو سنبھالنے کے لیے ایک مخصوص پیٹرن کا استعمال کرتی ہے، کہ بلاک کے واقعات کو ماضی کے تناؤ کے فعل کے ساتھ نام دیا جاتا ہے، اور یہ کہ وہ ماضی کے دور میں کبھی فعل استعمال نہیں کرتے ہیں۔ BuildContext بغیر جانچ کے غیر مطابقت پذیر وقفہ کے اندر mountedٹیم کی طرف سے استعمال کیا جاتا ہے fpdart کے لیے Either پرت کی حدود کو عبور کرنے اور استثناء کو بڑھانے کے بجائے قسم کی وضاحت کرتا ہے۔

ہنر AI ایجنٹوں تک ہنر مند ڈویلپر کا علم لانے کا ایک طریقہ ہے۔ یہ ایک دستاویز ہے جو نہ صرف اس بات کی وضاحت کرتی ہے کہ کیا کرنا ہے، بلکہ اسے کیسے کرنا ہے، کس چیز سے بچنا ہے، اور قواعد کیوں موجود ہیں۔

باضابطہ طور پر، ایجنٹ ٹیکنالوجی AI ایجنٹوں کو کام پر مبنی بلیو پرنٹس کا ایک سیٹ فراہم کرنے کا ایک معیاری طریقہ فراہم کرتی ہے۔ ایجنٹوں کو حقیقی ڈومین کی مہارت اور دہرائے جانے کے قابل ورک فلو فراہم کرکے، آپ غلطیوں کو کافی حد تک کم کر سکتے ہیں اور مستقل نمونوں کو نافذ کر سکتے ہیں۔

کلیدی لفظ کام پر مبنی ہے۔ ٹیکنالوجی ایک سٹائل گائیڈ نہیں ہے. کام کے مخصوص زمرے سے متعلق ہدایات کا مجموعہ۔

عالمگیر معیار

مہارتیں Agentkills.io پر رکھی گئی تصریحات پر عمل کرتی ہیں۔ یہ تصریح فائل فارمیٹ (YAML سابقہ ​​کے ساتھ مارک ڈاؤن)، ڈائریکٹری لوکیشن (.agents/skills/) اور نام دینے کے کنونشنز۔

وضاحتیں آفاقی ہیں، لہذا وہی تکنیکی فائلیں Claude Code، Cursor، Antigravity، Codex، اور دیگر ایجنٹوں کے ساتھ کام کریں گی جو معیار کی پیروی کرتے ہیں۔

یہ پورٹیبلٹی آپ کی ٹیم کے لیے اہم ہے۔ ہر ایجنٹ کے لیے الگ مہارت پیدا کرنے کی ضرورت نہیں ہے۔ جب آپ کوئی ہنر لکھتے ہیں اور اسے کسی ذخیرے میں بھیج دیتے ہیں، تو آپ کی ٹیم کے تمام ایجنٹ فوری طور پر اس سے فائدہ اٹھا سکتے ہیں۔

جہاں ٹیکنالوجی زندہ ہو جاتی ہے۔

ٹیکنالوجی .agents/skills/ پروجیکٹ ورک اسپیس کی ڈائرکٹری۔ یہ وہ معیاری مقام ہے جسے تمام ہم آہنگ ایجنٹ کسی کام کا کام شروع کرتے وقت خود بخود تلاش کرتے ہیں۔

your_flutter_project/
  .agents/
    skills/
      flutter-file-organization.md
      flutter-state-management-bloc.md
      flutter-testing.md
      flutter-theming.md
      flutter-error-handling.md
      flutter-navigation.md
      flutter-feature-architecture.md
      dart-unit-testing.md
      dart-static-analysis.md
      dart-pattern-matching.md
  lib/
  android/
  ios/
  pubspec.yaml

.agents/skills/ یہ ایجنٹ تکنیکی وضاحتوں کے ذریعہ قائم کردہ اصول ہیں۔ جب کوئی ایجنٹ کسی پروجیکٹ پر سیشن شروع کرتا ہے، تو وہ اس ڈائرکٹری کو تلاش کرتا ہے، تکنیکی فائلوں کو انڈیکس کرتا ہے، دستیاب خصوصیات کا تعین کرنے کے لیے میٹا ڈیٹا پڑھتا ہے، اور مکمل تکنیکی مواد صرف اس صورت میں لوڈ کرتا ہے جب آپریشن تکنیکی وضاحت سے میل کھاتا ہے۔

کس طرح مہارتیں سسٹم کے اشارے یا قواعد سے مختلف ہیں۔

ایک بار کا پیغام ایجنٹ کو بتاتا ہے کہ وہ اس سیشن سے کیا چاہتے ہیں۔ AI قوانین کی فائلیں، جیسے .cursorrules یا CLAUDE.md) ایجنٹوں کو پروجیکٹ کے وسیع حقائق سے آگاہ کرتا ہے جو تمام کاموں پر لاگو ہوتے ہیں۔ ہنر ایجنٹوں کو سکھاتا ہے کہ مستقبل کی تمام درخواستوں میں مخصوص قسم کے کاموں کو کس طرح درست طریقے سے انجام دیا جائے، جو صرف متعلقہ ہونے پر ہی لوڈ کیے جاتے ہیں۔

جب آپ Flutter فائلوں کو ترتیب دینے کے لیے تکنیک لکھتے ہیں، تو آپ کو ہر سیشن میں چیٹ میں قواعد کی وضاحت کرنے کی ضرورت نہیں ہوتی ہے۔ جب بھی آپ یا ٹیم کا کوئی رکن کسی ایجنٹ سے فلٹر فائل بنانے، تقسیم کرنے یا ری فیکٹر کرنے کے لیے کہتے ہیں، مہارت خود بخود لوڈ ہو جاتی ہے اور اسی معیار کی رہنمائی فراہم کرتی ہے۔ جب کوئی نیا ڈویلپر آپ کی ٹیم میں شامل ہوتا ہے اور آپ کے AI ایجنٹ کا استعمال شروع کرتا ہے، تو وہ آپ کی ٹیم کے معیارات کو دستی طور پر سیکھے بغیر، آپ کی ٹیم کے پہلے دن سے لکھی گئی تمام ٹیکنالوجیز سے فائدہ اٹھا سکتا ہے۔

مسئلہ: اے آئی ایجنٹ پھڑپھڑانے میں خرابیاں کیوں پیدا کرتے ہیں۔

یہ سمجھنے کے لیے کہ ہمیں ٹیکنالوجی کی ضرورت کیوں ہے، ہمیں ان مخصوص اور قابل پیشن گوئی طریقوں کو سمجھنے کی ضرورت ہے جن کے بغیر AI ایجنٹ فلٹر اور ڈارٹ میں ناکام ہو جاتے ہیں۔ یہ ناکامیاں بے ترتیب نہیں ہیں۔ وہ کچھ بنیادی وجوہات کا پتہ لگاتے ہیں جنہیں حل کرنے کے لیے ٹیکنالوجی کو ڈیزائن کیا گیا ہے۔

تربیتی ڈیٹا کا مسئلہ

اے آئی ایجنٹ کو ٹریننگ ڈیٹا کے ذریعے ڈارٹ اور فلٹر کا علم ہوتا ہے۔ اس کے تربیتی ڈیٹا میں فلٹر کوڈ کی لاکھوں لائنیں ہیں جو عوامی ذخیروں، دستاویزات، سبق آموز اور فورم کے جوابات سے کھینچی گئی ہیں۔ اس میں پرانے پیٹرن (نال پری سیف ڈارٹ)، خراب پیٹرن (اعلی درجے کے ویجٹس) اور وہ پیٹرن شامل ہیں جو انفرادی طور پر درست ہیں لیکن کسی خاص ٹیم کے معیار پر پورا نہیں اترتے۔

جب ایجنٹ بغیر مہارت کے کوڈ تیار کرتا ہے، تو یہ تمام مخلوط تربیتی ڈیٹا کا فائدہ اٹھاتا ہے۔ آپ 2021 ٹیوٹوریل اسٹائل میں کوڈ تیار کر سکتے ہیں: setState کہیں بھی یا ذخیرہ انداز میں استعمال کرتے ہوئے: ChangeNotifier اگر آپ کی ٹیم بلاک یا استعمال کرتی ہے۔ Navigator.push جب ٹیمیں گہرے لنکنگ سپورٹ کے لیے انصاف کے ساتھ GoRouter کا استعمال کرتی ہیں۔

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

پھڑپھڑانے سے متعلق سب سے عام غلطیاں

ایجنٹوں نے پیچیدہ اسکرینوں کو مندرجہ ذیل نجی طریقوں سے بنانے کے لیے کہا: _buildHeader(), _buildStatsList()اور _buildActionBar() اسکرین کلاس کے اندر۔ یہ ایک درست ڈارٹ ہے، لیکن ساختی طور پر نقصان دہ ہے۔ یہ سیکشنز علیحدہ ٹیسٹ ایبل اور دوبارہ قابل استعمال ویجیٹ کلاسز ہونے چاہئیں۔ widgets/ فولڈر

2. StatefulWidget کو ریاست سے الگ کریں۔

بڑی فائلوں کو تقسیم کرتے وقت، ایجنٹ فائلوں کو منتقل کر سکتے ہیں۔ StatefulWidget کلاس کو ایک فائل میں تبدیل کریں۔ State دوسروں کو سبق سکھانا۔ یہ فلٹر کمپلیشن کی بنیادی رکاوٹوں کو توڑ دیتا ہے۔ دونوں فائلیں ہمیشہ ایک ہی فائل میں ہونی چاہئیں۔

3. ریاستی انتظامی انتخاب کو نظر انداز کریں۔

ریاستی انتظامی ترجیحات کو جانے بغیر، ایجنٹ ٹریننگ ڈیٹا میں اکثر پائے جانے والے نمونوں کا انتخاب کرتا ہے۔ ایک سیشن ایک بلاک بناتا ہے۔ اگلا، ایک فراہم کنندہ بنائیں۔ آگے کیا استعمال کرنا ہے۔ setState. یہ سب ایک ہی کوڈ بیس میں ہے۔

4. ان پٹ ماڈل کے بجائے نقشہ استعمال کریں۔

سیریلائزیشن کے قواعد کو جانے بغیر، ایجنٹ ڈیفالٹ کرتا ہے۔ Map. اگر آپ کی ٹیم اسے استعمال کرتی ہے۔ freezed اور json_serializableتمام تیار کردہ ماڈلز کو مکمل طور پر دوبارہ لکھنا پڑے گا۔

5. ہارڈ کوڈ شدہ بصری اقدار۔

ایجنٹ کی ڈیفالٹ قدر ایک لغوی قدر ہے۔ Color(0xFF6750A4), EdgeInsets.all(16)اور BorderRadius.circular(8). اگر آپ کے پروجیکٹ میں تھیم ایکسٹینشنز اور وقفہ کنسٹنٹ کے ساتھ ڈیزائن سسٹم ہے تو ایجنٹ انہیں مکمل طور پر نظر انداز کر دے گا۔

بہت سی ٹیمیں خاص طور پر وضاحتی ناموں کے ساتھ خود دستاویزی کوڈ کے حق میں کوڈ کے تبصروں سے گریز کرتی ہیں۔ ایجنٹ بطور ڈیفالٹ وضاحتی تشریحات شامل کرتے ہیں کیونکہ زیادہ تر تربیتی ڈیٹا میں وضاحتی تشریحات شامل ہوتی ہیں جن کے لیے جائزوں کے درمیان صفائی کی ضرورت ہوتی ہے۔

7. غلط درآمدی راستہ۔

ایجنٹ اندرونی پیکیج کا راستہ استعمال کرتا ہے (package:myapp/src/internal/models/user.dartبیرل فائل (package:myapp/features/profile/profile.dart)، اندرونی APIs کے لیے غیر مرئی پابندیاں تخلیق کرتا ہے جو چھپنے چاہئیں۔

8. مقامی استثنیٰ ہینڈلنگ۔

غلطی کے فن تعمیر کو جانے بغیر، ایجنٹ استعمال کرتا ہے: try-catch خام Exception یہ ٹیم کے ذریعے داخل کردہ غلطی کے درجہ بندی کو نظر انداز کرتا ہے اور کوڈ بیس میں غلطی سے نمٹنے کو متضاد بنا دیتا ہے۔

ٹیکنالوجی کیسے کام کرتی ہے: ترقی پسند انکشاف

ٹیکنالوجی کے پیچھے میکانزم خوبصورت اور موثر ہیں۔ سیاق و سباق کی ونڈو میں تمام کمانڈز کو پہلے سے لوڈ کرنے کے بجائے، ایجنٹ پہلے صرف میٹا ڈیٹا پڑھتا ہے۔ بھاری، تفصیلی ہدایات صرف اس وقت حاصل کریں جب آپ کو درحقیقت ہاتھ میں کام کے لیے ان کی ضرورت ہو۔

فلٹر دستاویزات اس کو "ترقی پسند انکشاف” کے طور پر بیان کرتی ہیں، جیسا کہ فلٹر میں ہی سست لوڈنگ۔

یہ ڈیزائن ایک حقیقی مسئلہ حل کرتا ہے۔ AI ایجنٹ کی سیاق و سباق کی ونڈو لامحدود نہیں ہے۔ اگر ہر ہنر ہر کام کے لیے پورا مواد لوڈ کرتا ہے، تو ایجنٹ غیر متعلقہ معلومات پر اپنا سیاق و سباق کا بجٹ کھا جائیں گے۔ جب آپ کسی ایجنٹ سے یونٹ ٹیسٹ لکھنے کے لیے کہتے ہیں، تو نیویگیشن کی مہارت کو سیاق و سباق کے مطابق ہونے کی ضرورت نہیں ہے۔ روٹنگ ترتیب دیتے وقت جانچ کی تکنیکوں کو سیاق و سباق میں ہونے کی ضرورت نہیں ہے۔

ترقی پسند انکشاف ایجنٹ کی صورتحال کو فوکس میں رکھتا ہے۔ سب سے پہلے، ایجنٹ تمام دستیاب ٹیکنالوجیز سے ہلکے وزن کے میٹا ڈیٹا کو انڈیکس کرتا ہے۔ جب کوئی کام آتا ہے، تو ہم اس کی تفصیل کا استعمال اس بات کی نشاندہی کرنے کے لیے کرتے ہیں کہ کون سی مہارتیں شامل ہیں اور صرف مکمل ہدایات لوڈ کرتے ہیں۔ ایجنٹوں کو ان کے کاموں کے لیے تفصیلی ہدایات فراہم کرتے ہوئے سیاق و سباق کے استعمال کو کم کرتے ہوئے غیر متعلقہ مہارتیں اتاری جاتی ہیں۔

اس ترقی پسند انکشافی ماڈل کا مطلب ہے کہ آپ سیاق و سباق کے زیادہ بہاؤ کی فکر کیے بغیر اپنے پروجیکٹ میں بہت سی ٹیکنالوجیز رکھ سکتے ہیں۔ 20 مہارتوں کا ہونا ایک مہارت رکھنے سے 20 گنا زیادہ مہنگا نہیں ہے۔ کسی خاص کام کے لیے، صرف متعلقہ سب سیٹ لوڈ کیا جاتا ہے۔

مہارت کی فائل کا تجزیہ

تمام ٹیکنالوجیز ایک مخصوص ڈھانچے کی پیروی کرتی ہیں۔ مؤثر تکنیکوں کو استعمال کرنے کے لیے اس ڈھانچے کی گہری سمجھ ایک شرط ہے۔

---
name: skill-name-in-kebab-case
description: A clear, specific description that answers: what does this skill cover,
when should it be applied, and what trigger words indicate this task needs this skill?
This is the ONLY part the agent reads when deciding whether this skill is relevant.
aliases: [alternative-name, another-name]
sources: [chat, code]
---

# Skill Title

Brief introduction of what this skill covers and why it exists.

## First Major Section

Content with specific, actionable rules.

## Second Major Section

More rules, examples, counterexamples.

## Code Examples

Concrete code demonstrating the patterns.

فرنٹ میٹر بلاک کی تفصیلات

---
name: flutter-file-organization
description: Organize and split Flutter/Dart files while preserving StatefulWidget
and State relationships. Use when creating, refactoring, splitting, or reorganizing
Dart files and classes. Applies whenever a new screen, widget, model, or Bloc file
is being created or an existing file is being restructured.
aliases: [flutter-files, dart-organization]
sources: [chat, code]
---

name پورے پروجیکٹ میں اس مہارت کے لیے ایک منفرد شناخت کنندہ۔ یہ کباب اشارے کنونشن کی پیروی کرتا ہے (چھوٹے حروف کو ہائفن سے الگ کیا جاتا ہے) اور عام طور پر پلیٹ فارم یا ڈومین (flutter-, dart-, react-وغیرہ)۔ نام کا استعمال ایجنٹ کے ذریعہ تخمینہ میں مہارت کا حوالہ دیتے وقت اور CLI کے ذریعہ مہارت کا انتظام کرتے وقت استعمال کیا جاتا ہے۔

description یہ پوری فائل میں سب سے اہم فیلڈ ہے۔ یہ واحد فیلڈ ہے جو ایجنٹ ہلکے وزن کے پہلے مرحلے کی اشاریہ سازی کے دوران پڑھتا ہے۔ ایک ناقص تحریری وضاحت کا مطلب ہے کہ ایک مکمل تحریری مہارت کا باڈی لوڈ نہیں ہوگا۔ وضاحت میں تین سوالوں کا جواب ہونا چاہیے۔ اس مہارت کا احاطہ کیا ہے، اسے کب متحرک کیا جانا چاہیے، اور وہ کون سے مخصوص ٹرگر الفاظ یا جملے ہیں جو اس کی مطابقت کی نشاندہی کرتے ہیں؟ غور کریں کہ مثال میں فائل کی اقسام کی ایک جامع فہرست، وضاحت کے ساتھ "تخلیق، ری فیکٹرنگ، تقسیم یا تنظیم نو کے دوران استعمال کیا جاتا ہے” کیسے شامل ہے۔ ہر جملہ ایک ممکنہ محرک ہے جو ایجنٹوں کو اس ہنر سے کام کی تفصیل سے ملنے میں مدد کرتا ہے۔

aliases اس مہارت کے لیے ایک متبادل نام فراہم کرتا ہے جسے ایجنٹ اس کا حوالہ دینے کے لیے استعمال کر سکتے ہیں۔ یہ اختیاری ہے، لیکن مفید ہے اگر مہارت کو مختلف حالات میں کسی اور چیز سے طلب کیا جائے۔

sources اشارہ کرتا ہے کہ یہ مہارت کہاں سے آتی ہے۔ حسب ضرورت ٹیم کی مہارتوں کے لیے، وہ عام طور پر شامل ہیں: [chat]. پیکیج کے مصنف کی طرف سے فراہم کردہ ٹیکنالوجیز کے لیے، اس میں شامل ہو سکتے ہیں: [package].

مہارت جسمانی ساخت

اسکل باڈی مخصوص ساختی اصولوں کے ساتھ خالص مارک ڈاؤن ہے جو اسے ایجنٹ کے استعمال کے لیے سب سے زیادہ مؤثر بناتی ہے۔

# Title Section (h1)
Brief context-setting paragraph. What problem does this skill solve? Why does it exist?
Keep this under three sentences.

## Core Rules (h2 sections)
Numbered or bulleted lists of specific, verifiable rules.
Each rule should be independently actionable.

## Named Sub-Pattern (h2 sections)
More specific guidance for a particular sub-domain of the skill.
Lead with the rule, then show the wrong pattern, then show the right pattern.

## Code Example (h2 sections)
Complete, runnable code that demonstrates the most important patterns.
Always show both wrong and right versions for patterns that agents commonly get wrong.

ایجنٹ مہارت کی ترتیب کو سمجھنے کے لیے موضوع کی ساخت کو تلاش کرتے ہیں۔ واضح ## ایک عنوان جس میں ذیلی عنوان کا احاطہ کیا گیا ہے ایجنٹوں کو بڑی درخواست کے اندر مخصوص حصے تلاش کرنے میں مدد کرتا ہے جو موجودہ ذیلی کام سے متعلق ہیں۔

آفیشل فلٹر اور ڈارٹ ٹیکنالوجیز انسٹال کریں۔

فلٹر اور ڈارٹ ٹیمیں باضابطہ تکنیکی ذخیرے کو برقرار رکھتی ہیں جو ماحولیاتی نظام میں بہترین طریقوں کے بارے میں سالوں کے علم کی نمائندگی کرتی ہیں۔ یہ نقطہ آغاز ہے۔

فلٹر سکلز انسٹال کریں۔

npx skills add flutter/agent-plugins --skill '*' --agent universal --yes

npx skills add پھانسی skills npm کے ذریعے ایک CLI ٹول جس میں مستقل انسٹالیشن کی ضرورت نہیں ہے۔ flutter/agent-plugins GitHub ریپوزٹری کا راستہ جہاں فلٹر ٹیم آفیشل فلٹر ٹیکنالوجی کو برقرار رکھتی ہے۔ --skill '*' یہ ایک وائلڈ کارڈ ہے جو کسی مخصوص ٹیکنالوجی کو منتخب کرنے کے بجائے تمام دستیاب ٹیکنالوجیز کو ذخیرہ میں انسٹال کرتا ہے۔ --agent universal میں اپنی صلاحیتیں رکھیں۔ .agents/skills/ ڈائریکٹری وہ عالمگیر مقام ہے جہاں تمام ہم آہنگ ایجنٹ نظر آتے ہیں۔ --yes آپ انٹرایکٹو کنفرمیشن پرامپٹ کو نظرانداز کرتے ہوئے اس کمانڈ کو اپنے پروجیکٹ سیٹ اپ اسکرپٹ یا میک فائل میں محفوظ طریقے سے رکھ سکتے ہیں۔

اس کمانڈ کو چلانے کے بعد، آپ کا پروجیکٹ ریسپانسیو لے آؤٹ، GoRouter کے ساتھ اعلانیہ روٹنگ، اور JSON سیریلائزیشن میں مہارت حاصل کرے گا۔ json_serializableانٹیگریشن ٹیسٹ سیٹ اپ، ویجیٹ پیش نظارہ سیٹ اپ، ویجیٹ ٹیسٹنگ، BLoC اور کلین آرکیٹیکچر کا استعمال کرتے ہوئے آرکیٹیکچرل بہترین طریقے، بلاک اسٹیٹ مینجمنٹ، بلاک فارمز، اور مزید بہت کچھ شامل ہے۔

ڈارٹ مہارت کی تنصیب

npx skills add dart-lang/skills --skill '*' --agent universal --yes

ڈارٹ ٹیم فلٹر کے ویجیٹ سسٹم سے الگ، ڈارٹ لینگویج پر مرکوز ٹیکنالوجیز کا ایک تکمیلی سیٹ برقرار رکھتی ہے۔ یہ تکنیکیں فلٹر ایپس اور خالص ڈارٹ پروجیکٹس جیسے CLI ٹولز، بیک اینڈ سروسز اور پیکجز دونوں کے لیے مفید ہیں۔

آفیشل ڈارٹ تکنیکوں میں یونٹ ٹیسٹ بنانے، جامد تجزیہ کی ترتیب، پیکیج پر انحصار کا انتظام، پیٹرن میچنگ اور سیل شدہ کلاسز، CLI ایپلیکیشنز کی تعمیر، ٹیسٹ کوریج کو اکٹھا کرنا اور تجزیہ کرنا، LSPs کا استعمال کرتے ہوئے رن ٹائم کی غلطیوں کو ٹھیک کرنا، Mockito کا استعمال کرتے ہوئے مزاق بنانا، FFIs کو بائنڈنگ کرنا، FIgen کے استعمال سے FFIs کو بائنڈنگ کرنا، DARGT سے ڈیٹا اور میموری کی اصلاح کرنا پرانے ٹیسٹ دعوے کے انداز نئے سے۔ package:checks.

دونوں کو ایک ساتھ انسٹال کریں۔

npx skills add flutter/agent-plugins dart-lang/skills --skill '*' --agent universal --yes

دونوں ذخیروں کے ناموں کو ایک ہی کمانڈ میں درج کرنے سے دونوں ذخیرے ایک ساتھ انسٹال ہوں گے اور انحصار کے حل کو ایک بار چلانے کا سبب بنیں گے۔ یہ دو الگ الگ کمانڈز سے قدرے تیز ہے۔ یہ ایک نیا فلٹر پروجیکٹ قائم کرنے کے لیے تجویز کردہ طریقہ ہے۔

pubspec انحصار سے مہارت انسٹال کریں۔

ٹیکنالوجی ماحولیاتی نظام کے سب سے زیادہ طاقتور پہلوؤں میں سے ایک پیکج مصنفین کے لیے اپنی ٹیکنالوجی کو اپنے پیکجوں کے ساتھ بات چیت کرنے کی صلاحیت ہے۔ کہ skills CLI (ایک ڈارٹ پیکیج کے طور پر دستیاب ہے) انحصار درخت میں کسی بھی پیکیج سے ٹیکنالوجیز تلاش اور انسٹال کر سکتا ہے۔

dart pub global activate skills
skills get

dart pub global activate skills انسٹال کریں skills آپ اپنے کمپیوٹر پر عالمی سطح پر Dart CLI ٹولز استعمال کر سکتے ہیں۔ skills get آپ کا پڑھنا pubspec.yaml اور pubspec.lockانحصار کے درخت میں، تمام پیکیجز تلاش کریں جو فراہم کرتے ہیں: skills/ اسے ڈائرکٹری میں محفوظ کریں اور اس مہارت کو اپنے پروجیکٹ میں شامل کریں۔ .agents/skills/ ڈائریکٹری خود بخود.

پیکیج کو اپنے پروجیکٹ میں شامل کریں اور اسے چلائیں۔ skills getایجنٹوں کو فوری طور پر معلوم ہو جائے گا کہ پیکج کے مصنف کی ہدایات پر عمل کرتے ہوئے پیکج کو صحیح طریقے سے کیسے استعمال کرنا ہے۔ یہ ایک بنیادی تبدیلی ہے۔ ایجنٹ کو اندازہ لگانے کے بجائے کہ پیکج کیسے کام کرتا ہے، پیکیج کا مصنف براہ راست ایجنٹ کو استعمال کے صحیح نمونے فراہم کرتا ہے۔

# Update skills whenever your dependencies change
flutter pub get
skills get

چل رہا ہے flutter pub get انحصار کو اپ ڈیٹ کریں۔ چل رہا ہے skills get مماثلت کی مہارتیں اپ ڈیٹ کے فوراً بعد لاگو ہوں گی۔ اسے دو قدموں کی عادت بنانا یقینی بناتا ہے کہ آپ کے ایجنٹوں کے پاس ان کے موجودہ انحصار پر ہمیشہ تازہ ترین مہارتیں موجود ہوں۔

انسٹال ٹیکنالوجی کو چیک کریں۔

ls -la .agents/skills/

ls -la .agents/skills/ تمام انسٹال شدہ تکنیکی فائلوں کی تفصیلات کے ساتھ فہرست بنائیں۔ آپ کو دیکھنا چاہئے .md اس فائل کا نام ہر انسٹال کردہ مہارت کے نام پر رکھا گیا ہے۔ کہ -la جھنڈا چھپی ہوئی فائلوں اور تفصیلی معلومات بشمول فائل کا سائز اور ترمیم کی تاریخ دکھاتا ہے۔

انسٹال ہونے کے بعد، اپنے ایجنٹ کی تکنیکی آگاہی کی جانچ کریں۔

Which of my installed skills can help me with creating a new feature screen?

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

کلاڈ کوڈ کے ساتھ مہارتوں کا استعمال کریں۔

Claude Code Anthropic کا ایجنٹ کوڈنگ اسسٹنٹ ہے جو آپ کے ٹرمینل میں چلتا ہے۔ یہ پیچیدہ، ملٹی سٹیپ فلٹر ڈویلپمنٹ کاموں کے لیے سب سے طاقتور ایجنٹوں میں سے ایک ہے اور تکنیکی معیارات کے لیے بہترین معاونت فراہم کرتا ہے۔

کلاڈ کوڈ کے لیے فلٹر پلگ ان انسٹال کریں۔

کلاڈ کوڈ کے لیے تجویز کردہ طریقہ مکمل فلٹر پلگ ان انسٹال کرنا ہے، جو ٹیکنالوجی کو MCP سرور کنفیگریشن کے ساتھ بنڈل کرتا ہے۔

claude mcp add flutter-mcp -- dart pub global run dart_mcp_server
npx skills add flutter/agent-plugins --skill '*' --agent claude-code --yes
npx skills add dart-lang/skills --skill '*' --agent claude-code --yes

claude mcp add flutter-mcp کلاڈ کوڈ کا استعمال کرتے ہوئے اپنے ڈارٹ ایم سی پی سرور کو رجسٹر کریں۔ MCP سرور کلاڈ کوڈ کو فلٹر دستاویزات، pub.dev پیکیج کی معلومات، اور ویب براؤزنگ کے بغیر ڈارٹ ٹولز تک براہ راست رسائی فراہم کرتا ہے۔ --agent claude-code پر skills add کمانڈ مہارت کو کلاڈ کوڈ کے مخصوص مقام پر رکھتا ہے اگر یہ عالمگیر مقام سے مختلف ہے۔ .agents/skills/ یہ ایک ڈائرکٹری ہے، لیکن کلاڈ کوڈ عالمگیر مقامات سے بھی پڑھتا ہے۔

کلاڈ کوڈ ٹیکنیکل ڈائرکٹری

کلاڈ کا کوڈ اس سے تفصیل پڑھتا ہے: .agents/skills/ (عالمگیر پوزیشن) خود بخود۔ یہ بھی پڑھتا ہے: .claude/skills/ اگر آپ کلاڈ کی مخصوص مہارتوں کو عام مقصد کی مہارتوں سے الگ رکھنا چاہتے ہیں۔

your_project/
  .agents/
    skills/
      flutter-file-organization.md    <- universal, works everywhere
      flutter-bloc-state-management.md
  .claude/
    skills/
      claude-specific-workflow.md     <- Claude Code only
    CLAUDE.md                         <- Claude Code rules file

کلاڈ کوڈ کے اصول اور تکنیک

کلاڈ کا کوڈ ہے۔ CLAUDE.md فائل کو اپنے پروجیکٹ روٹ میں محفوظ کریں (یا .claude/) رولز فائل: پروجیکٹ کے وسیع رہنما خطوط جو ہمیشہ سیاق و سباق میں ہوتے ہیں، چاہے کام کوئی بھی ہو۔

ہنر آہستہ آہستہ لوڈ کیے جاتے ہیں۔ استعمال کریں CLAUDE.md پروجیکٹ کی معلومات (یہ کون سا پیکیج ہے، یہ کون سا SDK ورژن ہے، کون سی اسٹیٹ مینجمنٹ لائبریریاں انسٹال ہیں)۔ کام کے لیے مخصوص مہارت کے لیے اپنی صلاحیتوں کا استعمال کریں (بلاک کو کیسے نافذ کریں، فائلوں کو کیسے ترتیب دیں، یا ٹیسٹ کیسے لکھیں)۔

# CLAUDE.md example

This is a Flutter app called Kopa, a personal budgeting tool.

## Technical Stack
- Flutter 3.47 with Dart 3.10
- State management: flutter_bloc ^9.0.0
- Navigation: go_router ^14.0.0
- Data layer: firebase_ai ^2.0.0 for AI features
- Serialization: freezed + json_serializable
- Testing: bloc_test, mocktail

## Package Name
com.example.kopa

## Minimum SDK
Android API 24, iOS 15

## Project Structure
Feature-first with clean architecture layers.
See the flutter-feature-architecture skill for full structure details.

CLAUDE.md اس میں آپ کے پروجیکٹ کے بارے میں حقائق ہیں جو کبھی بھی کاموں کے درمیان تبدیل نہیں ہوتے ہیں، جیسے کہ ایپ کا نام، استعمال میں پیکیجز، SDK ورژن، اور کم از کم پلیٹ فارم ہدف۔ مہارتوں میں ماہر علم شامل ہے کہ کس طرح مناسب طریقے سے کوڈ شدہ پیکجوں اور ڈھانچے کے ساتھ کام کرنا ہے۔

کلاڈ کوڈ سیشنز میں ٹیکنالوجی کا استعمال

ایک بار جب کوئی ہنر انسٹال ہو جائے تو، کلاڈ کوڈ خود بخود اس مہارت کو استعمال کر لے گا۔ اسے دستی طور پر کال کرنے کی ضرورت نہیں ہے۔ جب آپ پوچھتے ہیں:

Create a UserProfile feature with Bloc state management, 
a repository that fetches from Firestore, and a screen 
that shows loading, data, and error states.

Claude Code پتہ لگاتا ہے کہ اس درخواست میں متعدد تکنیکی ڈومینز (فنکشنل آرکیٹیکچر، بلاک اسٹیٹ مینجمنٹ، فائل آرگنائزیشن، ممکنہ تھیمز، اور ایرر ہینڈلنگ) شامل ہیں، متعلقہ تکنیکی فائلوں کو لوڈ کرتا ہے، اور کوڈ تیار کرتا ہے جو بیک وقت ٹیم کے تمام اصولوں کی پیروی کرتا ہے۔

آپ اسے واضح طور پر اس طرح بھی بیان کر سکتے ہیں:

Using the flutter-bloc-state-management skill, implement 
the CartBloc for the shopping cart feature.

کسی ہنر کو واضح طور پر نام دینا کلاڈ کوڈ کو اس مخصوص مہارت کو لوڈ کرنے کی ہدایت کرتا ہے، چاہے وہ خود بخود اس کی ضرورت کا پتہ لگاتا ہے۔

اینٹی گریویٹی ٹیکنالوجی کا استعمال کریں۔

اینٹی گریویٹی گوگل کا اے آئی کوڈنگ اسسٹنٹ ہے جو فلٹر ایکو سسٹم میں گہرائی سے مربوط ہے اور فلٹر ٹیم کے ساتھ مل کر تیار کیا گیا ہے۔ یہ ایجنٹ ٹکنالوجی کے لیے اعلیٰ سطح کی مدد فراہم کرتا ہے اور یہ سرکاری فلٹر ٹیکنالوجیز کے ساتھ انتہائی جانچ شدہ ایجنٹوں میں سے ایک ہے۔

اینٹی گریوٹی کے لیے فلٹر پلگ ان انسٹال کریں۔

Open Settings in Antigravity by pressing Cmd+, (Mac) or Ctrl+, (Windows/Linux)
Click the Customizations tab
In the Build with Google Plugins section, click Customize
Click Download next to the Dart and Flutter integration

یہ Antigravity کے لیے آفیشل فلٹر پلگ ان انسٹال کرے گا، جو مہارتوں، MCP سرور کنفیگریشن، اور قواعد کو ایک ہی قدم میں بنڈل کرتا ہے۔ یہ تجویز کردہ تنصیب کا راستہ ہے کیونکہ یہ اس بات کو یقینی بناتا ہے کہ تینوں اجزاء (مہارت، MCP، اور قواعد) ایک ساتھ مناسب طریقے سے ترتیب دیے گئے ہیں۔

کشش ثقل کے خلاف غیر فعال ٹیکنالوجی کی تنصیب

اگر آپ دستی تنصیب کو ترجیح دیتے ہیں یا اپنی مرضی کے مطابق ٹیم کی مہارتوں کو شامل کرنے کی ضرورت ہے:

npx skills add flutter/agent-plugins --skill '*' --agent antigravity --yes
npx skills add dart-lang/skills --skill '*' --agent antigravity --yes

--agent antigravity Antigravity عام مقصد کی تکنیکی ڈائریکٹری سے بھی پڑھتا ہے، لیکن Antigravity سے متعلق مخصوص تکنیکی ڈائریکٹریوں کو نشانہ بناتا ہے۔ .agents/skills/ مقام

ٹیکنالوجی کا استعمال کرتے ہوئے اینٹی گریوٹی ورک فلو

اینٹی گریویٹی "ورک فلوز" کو سپورٹ کرتی ہے، جو کہ ایکشن کے پہلے سے طے شدہ سلسلے ہیں جو ٹیکنالوجیز کا حوالہ دے سکتے ہیں۔ آپ مشترکہ ٹیم کے کاموں کے لیے ورک فلو بنا سکتے ہیں۔

# .antigravity/workflows/new-feature.md

## Create New Feature Workflow

Apply skills: flutter-feature-architecture, flutter-bloc-state-management, 
flutter-testing, flutter-file-organization

Steps:
1. Create the feature folder structure.
2. Create the domain model using Freezed.
3. Create the repository interface and implementation.
4. Create the Bloc with its events and states.
5. Create the screen widget.
6. Extract reusable component widgets.
7. Create unit tests for the repository.
8. Create `bloc_test` tests for the Bloc.
9. Create widget tests for the screen.

ہنر سے متعلق ورک فلو اس بات کو یقینی بناتا ہے کہ ایجنٹ ایک کثیر مرحلہ کام کے ہر قدم پر درست اصول لاگو کریں۔ اس واضح حوالہ کے بغیر، ایجنٹ فائل آرگنائزیشن تکنیک کو مرحلہ 1 میں لاگو کر سکتا ہے لیکن ٹیسٹنگ تکنیک کو مرحلہ 7 سے 9 تک لاگو کرنا بھول جاتا ہے۔

OpenAI Codex میں مہارتوں کا استعمال کریں۔

OpenAI Codex ایک ٹرمینل پر مبنی ایجنٹ کوڈنگ اسسٹنٹ ہے جو کلاڈ کوڈ کی طرح ہے۔ یہ ٹرمینل میں چلتا ہے اور آپ کے کوڈ بیس کے خلاف ملٹی سٹیپ آپریشنز کرتا ہے۔

کوڈیکس کے لیے مہارتیں انسٹال کریں۔

npx skills add flutter/agent-plugins --skill '*' --agent codex --yes
npx skills add dart-lang/skills --skill '*' --agent codex --yes

--agent codex کوڈیکس کا مقصد متعلقہ تکنیکی ڈائریکٹریز کے لیے ہے۔ کوڈیکس یونیورسل سے بھی پڑھتا ہے۔ .agents/skills/ کیونکہ یہ ایک ڈائریکٹری ہے۔ --agent universal جھنڈے یکساں طور پر کام کرتے ہیں۔

کوڈیکس رولز فائل

یہ کلاڈ کوڈ کی طرح ہے۔ CLAUDE.mdکوڈیکس اس سے پڑھتا ہے: AGENTS.md یہ فائل پروجیکٹ روٹ میں واقع ہے۔ اسے اپنی مہارت کے ساتھ منظم کریں:

# AGENTS.md

Flutter project: Kopa budgeting app
Stack: flutter_bloc, go_router, firebase_ai, freezed
Architecture: Feature-first with clean architecture
Test framework: bloc_test + mocktail

AGENTS.md ایک پراجیکٹ وسیع سیاق و سباق کی فائل جسے کوڈیکس ہر کام پر پڑھتا ہے۔ اسے مختصر رکھیں۔ 5 سے 15 لائنوں میں سب سے اہم پروجیکٹ حقائق کا احاطہ کریں۔ تفصیلی اصول آرٹ سے تعلق رکھتے ہیں، فن سے نہیں۔ AGENTS.mdاس کی وجہ یہ ہے کہ ٹیکنالوجی آہستہ آہستہ لوڈ ہوتی ہے۔ AGENTS.md ہمیشہ بھری ہوئی

کوڈیکس پلگ ان انسٹالیشن نوٹس

کوڈیکس پلگ ان فی الحال قواعد کی فائلوں کو خود بخود بنڈل کرنے سے قاصر ہے۔ اس کا مطلب ہے فلٹر پلگ ان انسٹال کرنا یہاں سے: flutter/agent-plugins مہارتوں کو انسٹال کرتا ہے، لیکن خود بخود انہیں تخلیق نہیں کرتا ہے۔ AGENTS.md فائل

پلگ ان انسٹال کرنے کے بعد اس فائل کو دستی طور پر بنائیں۔ سرکاری فلٹر دستاویزات تجویز کردہ ٹیمپلیٹس فراہم کرتی ہیں۔ AGENTS.md فلٹر پروجیکٹس کے لیے مواد۔

کرسر کے ساتھ مہارت کا استعمال

کرسر ایک AI-پہلا کوڈ ایڈیٹر ہے جو VS کوڈ پر بنایا گیا ہے۔ یہ ایجنٹ کی فعالیت کو براہ راست ایڈیٹنگ کے تجربے میں ضم کرتا ہے اور اصولوں کے نظام اور عمومی مقاصد کی خصوصیات کے امتزاج کے ذریعے ٹیکنالوجی کی حمایت کرتا ہے۔ .agents/skills/ ڈائریکٹری

کرسر کی مہارت کو انسٹال کریں۔

npx skills add flutter/agent-plugins --skill '*' --agent cursor --yes
npx skills add dart-lang/skills --skill '*' --agent cursor --yes

کرسر مہارت کو پڑھتا ہے۔ .agents/skills/ ایجنٹ کے سیاق و سباق کے حصے کے طور پر۔ کہ --agent cursor جھنڈا اس بات کو یقینی بناتا ہے کہ کرسر کی تلاش کے طریقہ کار کی تکنیک صحیح طریقے سے پوزیشن میں ہے۔

کرسر اصول کا انضمام

کرسر کا مقصد .cursorrules (یا تازہ ترین .cursor/rules/ تازہ ترین ورژن کے لیے ڈائرکٹری) کلاڈ کوڈ کی طرح پروجیکٹ کی وسیع ہدایات CLAUDE.md:

# .cursor/rules/flutter.mdc

---
description: Flutter project rules applied to all Dart files
globs: ["**/*.dart", "pubspec.yaml"]
alwaysApply: true
---

This is a Flutter project using flutter_bloc, go_router, and freezed.
All state management uses the Bloc pattern.
Feature-first folder structure with clean architecture.
See installed skills in .agents/skills/ for detailed conventions.

globs: ["**/*.dart"] ہم اس اصول کو صرف ڈارٹ فائلوں میں ترمیم کرتے وقت لاگو کرتے ہیں، لہذا مارک ڈاؤن ایڈیٹنگ یا YAML کنفیگریشن کے دوران فلٹر رولز لوڈ نہیں ہوتے ہیں۔ alwaysApply: true اس بات کو یقینی بناتا ہے کہ جب مماثل فائل کھلی ہو تو اصول ہمیشہ سیاق و سباق میں ہوتا ہے۔

نیچے تکنیکی ڈائریکٹری کا حوالہ جان بوجھ کر دیا گیا ہے۔ یہ ایجنٹ سے کہتا ہے کہ قواعد کی فائل کو بہت لمبا کرنے کے بجائے نفاذ کی تفصیلات کے لیے ٹیکنالوجی کو دیکھیں۔

کمپوزر کا استعمال کریں اور مہارت کا استعمال کرتے ہوئے کرسر پر چیٹ کریں۔

جب آپ کسی عمل کی وضاحت کرتے ہیں تو کرسر کا کمپوزر (ایک ملٹی فائل ایڈیٹنگ ایجنٹ) خود بخود مہارتیں لوڈ کرتا ہے۔ کرسر چیٹ (ان لائن اسسٹنٹ) میں آپ کو زیادہ واضح ہونے کی ضرورت پڑسکتی ہے۔

@flutter-file-organization Create a new PostCard widget 
extracted from the post list screen

کہ @ کرسر چیٹ میں سابقے، کچھ کنفیگریشنز میں، نصب شدہ ٹیکنالوجیز کو نام کے لحاظ سے حوالہ دے سکتے ہیں۔ دوسرے معاملات میں، ایجنٹ کے لیے متعلقہ مہارتوں کو خود بخود لوڈ کرنے کے لیے صرف کام کو کافی تفصیل سے بیان کرنا کافی ہے۔

دوسرے ایجنٹوں کے ساتھ مہارت کا استعمال کریں۔

GitHub شریک پائلٹ CLI

GitHub Copilot CLI کو عمومی مقصد کی حمایت حاصل ہے۔ .agents/skills/ جب ایجنٹ موڈ میں چل رہا ہو، ڈائریکٹری (gh copilot explain اور gh copilot suggest):

npx skills add flutter/agent-plugins --skill '*' --agent copilot --yes

نوٹ skills GitHub Copilot استعمال کرتے وقت خود کار طریقے سے پتہ نہ لگنے کے بارے میں CLI دستاویزات skills get کیونکہ .github/ ڈائریکٹریز کو عام طور پر مختلف مقاصد کے لیے استعمال کیا جاتا ہے۔ ہمیشہ واضح زبان استعمال کریں۔ --agent copilot Copilot کے لیے ٹیکنالوجیز انسٹال کرتے وقت جھنڈا لگائیں۔

جیمنی سی ایل آئی

گوگل کی جیمنی سی ایل آئی یونیورسل ٹیکنیکل ڈائرکٹری کو سپورٹ کرتی ہے۔

npx skills add flutter/agent-plugins --skill '*' --agent gemini --yes

عالمگیر تنصیب

اگر آپ ایک ہی تنصیب چاہتے ہیں جو بیک وقت تمام ایجنٹوں کے لیے کام کرے:

npx skills add flutter/agent-plugins --skill '*' --agent universal --yes
npx skills add dart-lang/skills --skill '*' --agent universal --yes

کہ universal ایجنٹ کو ٹارگٹ کرنے کی مہارتیں اس پر تعینات کرتی ہیں: .agents/skills/تمام تعمیل کرنے والے ایجنٹ خود بخود دریافت ہو جاتے ہیں۔ یہ ان ٹیموں کے لیے تجویز کردہ ڈیفالٹ ہے جو ایک سے زیادہ ایجنٹوں کا استعمال کرتی ہیں یا ایجنٹ-اگنوسٹک بننا چاہتی ہیں۔

ایجنٹ کی دریافت کی تصدیق کریں۔

اس سے کوئی فرق نہیں پڑتا ہے کہ آپ کون سا ایجنٹ استعمال کرتے ہیں، آپ ایجنٹ سے قدرتی زبان کے سوالات پوچھ کر اپنی مہارت کی دریافتوں کی تصدیق کر سکتے ہیں۔

Summarize the capabilities of the skills you have available for this project.

ایک مناسب طریقے سے تشکیل شدہ ایجنٹ انسٹال شدہ ٹیکنالوجیز کی فہرست اور ان کی تفصیل کے ساتھ اس بات کی تصدیق کرے گا کہ دریافت کام کر رہی ہے۔ اگر ایجنٹ کہتا ہے کہ ان کے پاس مہارت نہیں ہے یا وہ اسے تلاش نہیں کر پا رہے ہیں، تو درج ذیل کو چیک کریں:

1. کہ .agents/skills/ ڈائریکٹری پروجیکٹ روٹ میں موجود ہے۔

2. ڈائریکٹری پر مشتمل ہے: .md درست YAML ہیڈر کے ساتھ فائل

3. ایجنٹ آفاقی تکنیکی خصوصیات کی حمایت کرتا ہے۔

آفیشل فلٹر ٹیکنالوجی: ایک گہرا غوطہ

سرکاری فلٹر ٹیکنالوجی ذخیرہ (flutter/agent-plugins) میں تکنیکوں کا ایک مجموعہ شامل ہے جو عام ترقی کے نمونوں کے بارے میں فلٹر ٹیم کی بہترین سوچ کی نمائندگی کرتا ہے۔ ہر ٹیکنالوجی کا احاطہ کرنے سے آپ کو یہ فیصلہ کرنے میں مدد ملے گی کہ کون سی ٹیکنالوجیز انسٹال کرنی ہیں، کون سی ٹیکنالوجیز کو اپنی مرضی کے مطابق بنانا ہے، اور کون سی ٹیکنالوجیز کو آپ کی اپنی ٹیکنالوجیز کے ساتھ ملنا ہے۔

لہرانا قبول لے آؤٹ

یہ ہنر ایجنٹوں کو سکھاتا ہے کہ وہ لے آؤٹ کیسے بنائے جو موبائل، ٹیبلیٹ اور ڈیسک ٹاپ بریک پوائنٹس پر صحیح طریقے سے لاگو ہوتے ہیں۔ یہ احاطہ کرتا ہے AdaptiveScaffold, LayoutBuilder, MediaQuery, BreakpointsFlutter Adaptive Framework کی طرف سے مختلف اسکرین سائزز کو ہینڈل کرنے کے لیے تجویز کردہ پیٹرن موجود ہیں، اور بہت کچھ۔

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

flutter اعلانیہ روٹنگ

یہ تکنیک GoRouter سیٹ اپ، روٹ ڈیفینیشن پیٹرن، نیسٹڈ نیویگیشن، توثیق کے لیے ری ڈائریکٹ منطق، گہرے روابط کی تشکیل، اور راستوں کے درمیان داخل کردہ پیرامیٹرز کو منتقل کرنے کا صحیح طریقہ سکھاتی ہے۔

اس مہارت کے بغیر، ایجنٹ اکثر استعمال کرتے ہیں: Navigator.push کوڈ بیس کے لیے بھی یہی بات ہے جو GoRouter کو ہر جگہ انصاف کے ساتھ استعمال کرتے ہیں۔ مزید برآں، ڈیپ لنکنگ عام طور پر ناقص ان پٹ پیرامیٹر نکالنے کے پیٹرن کا شکار ہوتی ہے جس کی GoRouter کو ضرورت ہوتی ہے۔

flutter-json-serialization

یہ ہنر سکھاتا ہے: json_serializable اور freezed ورک فلو: تشریح شامل کریں، چلائیں۔ build_runnerنسل fromJson/toJson طریقے، ہینڈلنگ اور کالعدم فیلڈز کا استعمال @JsonKey فیلڈ کے نام کی نقشہ سازی کے لیے۔

اس ٹیکنالوجی کے بغیر، ایجنٹوں کو یا تو سیریلائزیشن کوڈ کو دستی طور پر لکھنا پڑے گا یا Map یہ نازک کوڈ بناتا ہے جو ڈیٹا لیئر میں فیلڈ کے نام تبدیل ہونے پر خاموشی سے ٹوٹ جاتا ہے۔

flutter-add-widget-test

یہ ہنر سکھایا جاتا ہے۔ testWidgets, WidgetTesterپمپ کی حکمت عملی (pump, pumpAndSettle, pumpWidget) ویجیٹ تلاش کریں (find.text, find.byType, find.byKey)، اشارے کی تخروپن، اور سیکھیں کہ اپنے ویجٹس کو کم سے کم لیکن کافی ٹیسٹنگ انفراسٹرکچر میں کیسے لپیٹنا ہے۔

flutter-add-integration-test

یہ ہنر آپ کو سکھاتا ہے کہ ڈیوائس، ویب براؤزر، یا Firebase ٹیسٹ لیب پر اینڈ ٹو اینڈ انٹیگریشن ٹیسٹ کیسے ترتیب دینا اور چلانا ہے۔ ٹیسٹ سیٹ اپ، IntegrationTestWidgetsFlutterBindingان میں ایپ لانچ آرڈر کی وضاحت کرنا، آپ کے ٹیسٹوں میں مکمل طور پر چلنے والی ایپ کے ساتھ تعامل کرنا اور مزید بہت کچھ شامل ہے۔

فلٹر بلاک

یہ تکنیک پورے بلاک ورک فلو کو سکھاتی ہے، واقعات، ریاست اور بلاک کی کلاسوں کی وضاحت کرتی ہے اور بلاک کو فراہم کرتی ہے: BlocProviderایک ساتھ لیا گیا۔ BlocBuilder, BlocListenerاور BlocConsumerاور ٹیسٹ bloc_test.

flutter-apply-architecture-best-practices

یہ ہنر صاف فن تعمیر (ڈیٹا، ڈومین، پریزنٹیشن) کا اطلاق سرکاری فلٹر ٹیم کے تجویز کردہ BLoC پیٹرن کے ساتھ کرتا ہے۔ پرت کی حدود، انحصار کے قواعد، اور اسٹوریج پیٹرن کی وضاحت کریں۔

flutter-extra-widgets-preview

یہ تکنیک فلٹر 3.47 میں متعارف کرائے گئے ویجیٹ پیش نظارہ کے نظام کو سکھاتی ہے، بشمول: @Preview تشریحات ترتیب دینے، بنیادی ڈھانچے کا پیش نظارہ کرنے اور پیچیدہ ویجیٹس کے لیے مفید پیش نظارہ بنانے کا طریقہ سیکھیں۔

آفیشل ڈارٹس تکنیک: ایک گہری غوطہ

ڈارٹ ٹیم کا سرکاری تکنیکی ذخیرہ (dart-lang/skills) خود ڈارٹ زبان کا احاطہ کرتا ہے، نہ کہ فلٹر کے ویجیٹ سسٹم کو۔ یہ تکنیکیں تمام ڈارٹ کوڈ پر لاگو ہوتی ہیں، بشمول فلٹر ایپ لاجک، ڈارٹ سی ایل آئی ٹولز، ڈارٹ بیک اینڈ سروسز، اور ڈارٹ پیکجز۔

ڈارٹ اضافی یونٹ ٹیسٹ

یہ ڈارٹس کی سب سے بنیادی تکنیک ہے اور سب سے زیادہ فوری اثر کے ساتھ۔ اپنے ایجنٹوں کو سکھائیں کہ ڈارٹ کی تمام کلاسوں کے لیے مناسب یونٹ ٹیسٹ کیسے لکھیں، بشمول:

• ترتیب test/ ڈائرکٹری آئینہ دار lib/ ساخت

• تحریر group اور test وضاحتی ناموں کے ساتھ بلاکس

• استعمال کریں setUp اور tearDown ٹیسٹ لائف سائیکل مینجمنٹ کے لیے

• استعمال کریں expect صحیح میچر کے ساتھ

• انحصار کا مذاق اڑانا mocktail

• غیر مطابقت پذیر کوڈ کی جانچ expectLater اور سٹریم میچر

اس ٹکنالوجی کے بغیر، ایجنٹ ایسے ٹیسٹ تیار کریں گے جو غلط چیزوں کی جانچ کرتے ہیں، غلط دعوے کے نمونوں کا استعمال کرتے ہیں، اور ٹیسٹ فائلوں کو اس طرح سے ڈھانچہ بناتے ہیں جو ماخذ کے درخت کی عکس بندی نہ کرے۔ اس کی وجہ سے ایجنٹ ایسے ٹیسٹ تیار کرتا ہے جو: package:test پہلے رن سے ہی اصولوں پر عمل کرنا ضروری ہے۔

# What dart-add-unit-test teaches the agent

## Test file placement
test/features/profile/data/profile_repository_test.dart
mirrors
lib/features/profile/data/profile_repository.dart

## Test naming
```
group('ProfileRepository', () {
  group('getProfile', () {
    test('returns ProfileLoaded when API call succeeds', () async {
      // ...
    });

    test('returns NetworkFailure when connection fails', () async {
      // ...
    });
  });
});
```

## Async testing
```
await expectLater(
  repository.getProfile('user123'),
  completion(isA>()),
);
```

ڈارٹ عملدرآمد جامد تجزیہ

یہ مہارت ایجنٹوں کو سکھاتی ہے کہ ڈارٹ کے جامد تجزیہ کے بنیادی ڈھانچے کے ساتھ کیسے کام کرنا ہے۔ analysis_options.yamlچل رہا ہے dart analyzeدرخواست دے رہا ہے۔ dart fix --applyلنٹ کے قوانین کو سمجھیں، غلط مثبت کو صحیح طریقے سے دبائیں اور سخت قسم کی جانچ کو نافذ کریں۔

# What dart-run-static-analysis covers

## analysis_options.yaml configuration
include: package:flutter_lints/flutter.yaml

analyzer:
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  exclude:
    - '**/*.g.dart'
    - '**/*.freezed.dart'

linter:
  rules:
    avoid_print: true
    prefer_final_fields: true
    require_trailing_commas: true

## Correct suppression (when a lint is a false positive)
// ignore: avoid_print  <- line-level, for one occurrence
// ignore_for_file: type=lint  <- file-level, for generated files

اسے ترتیب دینے کا طریقہ سمجھیں۔ analysis_options.yaml اسے درست کرنا ان کاموں میں سے ایک ہے جو ایجنٹ اکثر رہنمائی کے بغیر غلطیاں کرتے ہیں۔ اس کا مطلب ہے غلط اصولوں کو چالو کرنا، تیار کردہ فائلوں کو خارج کرنا بھول جانا، یا تشخیص کو بہت وسیع پیمانے پر دبانا۔ یہ ٹیکنالوجی پہلی بار اس ترتیب کو حاصل کرتی ہے۔

ڈارٹ کا آلہ

یہ تکنیک آپ کو سکھاتی ہے کہ پیکیج ورژن کے تنازعات کو کیسے حل کیا جائے۔ pubspec.yamlانحصار کو درست طریقے سے استعمال کریں اور براہ راست اور عبوری انحصار کے درمیان فرق کو سمجھیں اور پڑھیں۔ pubspec.lock ورژن کے حل کے مسائل کی تشخیص کریں۔

پیکیج پر انحصار کا انتظام ایک ایسا شعبہ ہے جہاں ایجنٹ اکثر خواب دیکھتے ہیں یا پیکیج ورژن تجویز کرتے ہیں۔ dependency_overrides ایک طرح سے جو حقیقی تنازعہ کو دھندلا دیتا ہے۔ یہ مہارت اس رویے کو درست کرتی ہے۔

ڈارٹ استعمال پیٹرن کے ملاپ

یہ تکنیک ڈارٹ کی سب سے قیمتی تکنیکوں میں سے ایک ہے کیونکہ ڈارٹ 3 میں سیل شدہ کلاسز اور پیٹرن کی مماثلت بالکل نئے کوڈنگ پیراڈائم کی نمائندگی کرتی ہے جو ڈارٹ 3 کی ریلیز سے پہلے تربیت یافتہ ایجنٹوں کے ذریعے مستقل طور پر استعمال نہیں ہوتی ہے۔ یہ سکھاتا ہے:

• مکمل طور پر مہربند کلاس کی تبدیلی

• سوئچ کیس کا ڈسٹرکچرنگ پیٹرن

• تحفظ کی شق when

• تاریخ پیٹرن

• فہرست اور نقشہ سازی کے پیٹرن

• درست استعمال _ (وائلڈ کارڈ) پیٹرن

// What the agent learns to write with dart-use-pattern-matching

// Before: traditional switch on enum (old pattern)
switch (state) {
  case AppState.loading:
    return CircularProgressIndicator();
  case AppState.loaded:
    return ContentWidget(data: data);
  default:
    return ErrorWidget();
}

// After: switch expression with pattern matching (idiomatic Dart 3)
return switch (state) {
  AppStateLoading() => const CircularProgressIndicator(),
  AppStateLoaded(:final data) => ContentWidget(data: data),
  AppStateError(:final message) => ErrorWidget(message: message),
};

تباہی پیٹرن AppStateLoaded(:final data) اگرچہ یہ خالص ڈارٹ 3 اور بہت صاف ہے، ہم اس مہارت کے بغیر شاذ و نادر ہی ایجنٹ بناتے ہیں کیونکہ یہ ایجنٹ کے پچھلے ورژن کے تربیتی ڈیٹا میں نہیں تھا۔

ڈارٹ جمع کرنے کا دائرہ

یہ تکنیک ٹیسٹ کوریج جمع کرتی ہے، LCOV رپورٹس تیار کرتی ہے، HTML رپورٹس تیار کرتی ہے، اور تیار کردہ کوڈ کو فلٹر کرنے کے طریقے فراہم کرتی ہے (*.g.dart, *.freezed.dart) اس بات کو یقینی بنائیں کہ کوریج رپورٹ میں موجود اعداد اصل کوریج کی عکاسی کرتے ہیں، جنریٹڈ کوڈ کے ذریعے نہیں بڑھایا جاتا جس کی معنی خیز جانچ نہیں کی جا سکتی۔

ڈارٹ تخلیق ٹیسٹ فرضی

یہ ہنر سکھاتا ہے: mockito اور build_runner انٹرفیس اور تجریدی کلاسوں سے ٹائپ سیف موک آبجیکٹ بنانے کے لیے ایک ورک فلو۔ تبصرے، عملدرآمد، وغیرہ شامل کرنے کا احاطہ کرتا ہے۔ dart run build_runner buildجانچ کے لیے بنائی گئی فرضی آبجیکٹ کا استعمال کریں۔

ڈارٹ رن ٹائم کی خرابی کو ٹھیک کرتا ہے۔

یہ ایک طریقہ کار کی تکنیک ہے۔ ایجنٹ کو موجودہ اسٹیک ٹریس حاصل کرنے کے لیے لینگویج سرور پروٹوکول (LSP) استعمال کرنے کی ہدایت کرتا ہے، فیلنگ لائن کو تلاش کریں، فکس کا اطلاق کریں، اور ریزولوشن کا تعین کرنے کے لیے ہاٹ ری لوڈ کا استعمال کریں۔ لائیو فلٹر ایپس میں وجہ کا اندازہ لگانے کے بجائے رن ٹائم کی خرابیوں کو ٹھیک کرنے کے لیے یہ درست ورک فلو ہے۔

ڈارٹ جینکٹ

یہ ہنر آپ کو سکھاتا ہے کہ Genkit Dart SDK کا استعمال کرتے ہوئے AI پر مبنی ورک فلو اور ایجنٹ کیسے بنائے جائیں۔ یہ خاص طور پر فلٹر ڈویلپرز کے لیے متعلقہ ہے جو AI فنکشنز بنا رہے ہیں جو فلو ڈیفینیشن، ٹول انوکیشن، ماڈل سلیکشن، اور اسٹریمنگ کا احاطہ کرتے ہیں۔

ڈارٹ-ہجرت-سے-چیک-پیکیج

یہ تکنیک آپ کو سکھاتی ہے کہ پچھلے ورژن سے کیسے ہجرت کی جائے۔ package:matcher دعوے کے انداز کو تازہ ترین میں تبدیل کریں۔ package:checks یہ ایک ایسا انداز ہے جو بہتر غلطی کے پیغامات تیار کرتا ہے اور زیادہ قابل ترتیب ہے۔

// Old style (package:matcher)
expect(result, isA>());
expect(result.getOrElse(() => null)?.name, equals('Ade'));

// New style (package:checks)
check(result).isA>();
check(result.getOrElse(() => null)?.name).equals('Ade');

ڈارٹ میموری

یہ تکنیک آپ کو سکھاتی ہے کہ فلٹر اور ڈارٹ ایپس میں میموری لیک ہونے کو کیسے روکا جائے اور کوڑا اٹھانے کے دباؤ کو کم کیا جائے۔ StreamController ضائع کرنا AnimationController کوڑے کو جمع کرنے سے بچنے کے لیے ڈسپوزل، کلوزر کیپچر پیٹرن، ڈیو ٹولز کا استعمال کرتے ہوئے میموری کے مسائل کی شناخت کیسے کریں، اور بہت کچھ۔

dart-build-cli-app

فلٹر ڈویلپرز کے لیے جو Dart CLI ٹولز، بیک اینڈ اسکرپٹس، یا ڈارٹ میں ڈیپلائمنٹ آٹومیشن لکھتے ہیں، یہ تکنیکیں انٹری پوائنٹ کے ڈھانچے، آرگومنٹ پارسنگ کا احاطہ کرتی ہیں۔ package:argsایگزٹ کوڈز، سب پروسیس ہینڈلنگ، اور کراس پلیٹ فارم اسکرپٹ پیٹرن۔

ڈارٹ منطق پیٹرن

یہ ٹیکنالوجی کاروباری منطق کی تعمیر کے لیے الگورتھم، ڈیٹا ڈھانچے، اور ڈارٹ سے متعلقہ نمونوں کا احاطہ کرتی ہے۔ Iterable صحیح طریقہ کا انتخاب کریں اور درج ذیل میں سے ایک کو منتخب کریں: List, Setاور Map مختلف قسم کے استعمال کے معاملات کے لیے موثر تلاش اور چھانٹی کو نافذ کریں اور ڈارٹ کے مجموعہ لٹریلز کو نتیجہ خیز استعمال کریں۔

flutter-file-organization Skill: مکمل واک تھرو

فائل آرگنائزیشن کی مہارتیں سب سے زیادہ عالمگیر طور پر قابل اطلاق فلٹر کی مہارتیں ہیں اور یہ اس بات کی ایک بہترین تدریسی مثال ہیں کہ مہارتوں کو کس طرح منظم کیا جانا چاہیے۔ اگر آپ اس کتاب کو غور سے پڑھیں تو آپ کو تمام موثر تکنیکوں کے پیچھے اصول معلوم ہوں گے۔

---
name: flutter-file-organization
description: Organize and split Flutter/Dart files while preserving StatefulWidget and State relationships. Use when creating, refactoring, splitting, or reorganizing Dart files and classes.
---

# Flutter File Organization

When creating, splitting, refactoring, or reorganizing Flutter/Dart files, follow these rules.

## Core Rules

1. Inspect the existing file before modifying it.
2. Identify all classes, enums, extensions, mixins, typedefs, and top-level declarations.
3. Identify relationships and dependencies between declarations before splitting them.
4. Keep each independent primary class in its own file.
5. Treat tightly coupled declarations as a single implementation unit and keep them together.
6. Never separate a `StatefulWidget` from its corresponding `State` class.
7. Update all imports and references after moving declarations.
8. Do not introduce unnecessary private helper classes or methods.
9. Preserve existing application behavior. File organization must not change functionality.
10. Run `dart format` on modified Dart files.
11. Run the project's analyzer and relevant tests.

قاعدہ 1 ("موجودہ فائلوں میں ترمیم کرنے سے پہلے ان کو چیک کریں") ایجنٹ کی سب سے عام اور مہنگی غلطیوں میں سے ایک سے بچتا ہے: فائل کے مواد کو پڑھے بغیر ان کے بارے میں قیاس کرنا۔

وہ ایجنٹ جو چیک کو چھوڑ دیتے ہیں وہ ڈیکلریشن کو ڈپلیکیٹ کر سکتے ہیں، انحصار توڑ سکتے ہیں، یا پہلے سے موجود آئٹمز کے ساتھ نام رکھنے میں تنازعات پیدا کر سکتے ہیں۔ چیک کو پہلے واضح اصول کے طور پر سیٹ کرنا یقینی بناتا ہے کہ ایجنٹ ہمیشہ موجودہ حالت کی مکمل تصویر کے ساتھ شروع ہوتا ہے۔

قواعد 2 اور 3 ("تمام طبقوں کی شناخت" اور "تعلقات کی شناخت") پرواز سے پہلے لازمی چیک ہیں۔ اس سے پہلے کہ کوئی ایجنٹ فائل کے ایک بائٹ کو ہینڈل کر سکے، اسے ہر اس چیز کا نقشہ بنانا چاہیے جو موجود ہے اور وہ ٹکڑے ایک دوسرے پر کیسے منحصر ہیں۔

یہ کوڈ ریفیکٹرنگ پر لاگو ہونے کے طور پر "دو بار پیمائش، ایک بار کاٹ" کے برابر ہے اور بگس کی انتہائی مایوس کن کلاس سے بچتا ہے: ری فیکٹرنگ جو کام کر رہی تھی اسے توڑ دیتی ہے۔

قاعدہ 6 ("Stateful Widget کو اس کی ریاستی کلاس سے کبھی الگ نہ کریں") Flutter کے لیے مخصوص تالیف کے علم کو انکوڈ کرتا ہے۔ وہ ڈویلپر جو ڈارٹ کو گہرائی سے جانتے ہیں لیکن فلٹر کو نہیں جانتے ہر کلاس کو اس کی اپنی فائل میں منتقل کرکے فائلوں کو معقول طریقے سے تقسیم کرسکتے ہیں۔ کیونکہ تالیف کی غلطی ہوتی ہے۔ _ProfilePageState حوالہ ProfilePage ویجیٹ کے ذریعے widgetان کی مندرجہ ذیل اقسام ہیں: State یہ کلاس کی سطح پر مقرر کیا جاتا ہے. دونوں طبقے ایک واحد، لازم و ملزوم تالیف یونٹ بناتے ہیں۔ یہ قاعدہ تالیف کی غلطیوں کو روکتا ہے جن سے گریز نہیں کیا جا سکتا چاہے آپ کے پاس کتنا ہی عام ڈارٹ علم ہو۔

رولز 10 اور 11 ("رن ڈارٹ فارم" اور "پراجیکٹ اینالائزر چلائیں") کام کی تکمیل کے لوپ کو بند کرتے ہیں۔ ان اصولوں کے بغیر، ایجنٹ فائل بنانے کے بعد کامیابی کا اعلان کرتا ہے، فارمیٹ میں مماثلت اور تجزیہ کار کی وارننگ چھوڑ دیتا ہے جو بعد میں پکڑا جا سکتا ہے۔ یہ ایجنٹوں کو رپورٹنگ مکمل ہونے سے پہلے فوری طور پر مسائل کو پکڑنے کے لیے دونوں ٹولز چلانے کی اجازت دیتا ہے۔

## Widget Extraction

Do not create private `_build...()` methods as a way of extracting substantial widget UI.

For example, do not do this:

```
Widget _buildUserCard() {
  return Container(
    ...
  );
}
```

Instead separate this into a class that is public and place it inside the widgets folder or the components folder.

ویجیٹ نکالنے والا سیکشن چار چیزیں کرتا ہے جو کسی بھی اچھے تکنیکی اصول کو کرنا چاہیے: یعنی، یہ قواعد کو واضح طور پر بیان کرتا ہے، ممنوعہ نمونوں کو واضح طور پر بیان کرتا ہے (مبہم کی بجائے)، مخصوص کوڈ کی مثالیں دکھاتا ہے کہ انہیں ابہام سے بچنے کے لیے کیا نہیں کرنا چاہیے، اور ایجنٹ کو بتاتا ہے کہ اس کے بجائے کیا کرنا ہے۔

کہ _build...() ٹریننگ ڈیٹا میں پیٹرن بہت عام ہے (ہم اسے سادگی کے لیے ٹیوٹوریلز میں اکثر استعمال کرتے ہیں)۔ اس کا مطلب یہ ہے کہ اگر آپ کسی مخصوص مثال کے بغیر کہتے ہیں کہ "پرہیز کریں"، تو آپ سیکھے ہوئے رویے کو اوور رائیڈ نہ کرنے کا خطرہ چلاتے ہیں۔

سے بچنے کے لیے صحیح کوڈ کے نمونوں کو دکھانا اور متبادلات کے ساتھ ان کا مقابلہ کرنا رہنمائی کو ہر ممکن حد تک واضح کرتا ہے۔

## Component Extraction

Do not place large amounts of UI inside a single widget.

Extract logical sections into reusable components whenever appropriate.

Examples include:

- Header sections
- Statistics cards
- Filter bars
- Search bars
- Lists
- Table rows
- Buttons
- Empty states
- Loading views
- Form sections
- Dialog content

Favor small, reusable widgets over large build methods.

اجزاء نکالنے والے حصے میں مثالوں کی فہرست حقیقی دنیا کے تجربے پر مبنی ہے۔ یہ اصل UI حصے ہیں جو آپ کی پروڈکشن فلٹر ایپ کے اسکرین ویجیٹس کے اندر جمع ہوتے ہیں۔ ایک ایجنٹ جو اس فہرست کو پڑھتا ہے وہ ان نمونوں کو اس کوڈ میں پہچان لے گا جس کا وہ معائنہ کرتا ہے اور جان لے گا کہ انہیں کیسے نکالا جائے۔

فہرست کے بغیر، "منطقی حصے نکالیں" قابل اعتماد ہونے کے لیے بہت مبہم ہے۔ ایجنٹوں کو خاص طور پر یہ جاننے کی ضرورت ہے کہ "منطقی سیکشن" کیا سمجھا جاتا ہے۔

## Code Comments

Do not write code comments.

This rule applies everywhere and to every layer.

کوڈ پر تبصرہ کرنے کے اصول مطلق اور اس لیے آسان ہیں۔ جملہ "ہر جگہ لاگو ہوتا ہے، تمام تہوں پر" جان بوجھ کر ہے۔ اس اسکوپ کوالیفائر کے بغیر، ایجنٹ اس اصول کی تشریح صرف موجودہ فائل کنفیگریشن آپریشن پر لاگو کرنے کے طور پر کر سکتا ہے اور اپنی تخلیق یا ترمیم کردہ دیگر فائلوں میں تبصرہ شامل کرنے کے لیے واپس جا سکتا ہے۔ واضح دائرہ کار ابہام کو دور کرتا ہے اور تمام سیاق و سباق میں اصول کے ارادے کو واضح کرتا ہے۔

اپنی خود کی مہارت بنائیں: مکمل گائیڈ

رسمی مہارتیں آپ کی بنیاد ہیں۔ لیکن سب سے قیمتی مہارت اکثر اپنی لکھنے کی مہارت ہوتی ہے، مخصوص پیٹرن، غلطیوں اور اپنے پروجیکٹ کے معیارات کو انکوڈنگ کرنا۔

لکھنے کے بارے میں سوچنے کا صحیح طریقہ

ٹیکنالوجی کے لیے لکھنا انسانوں کے لیے لکھنے سے مختلف ہے۔ انسانوں کے لیے دستاویزات مشترکہ سیاق و سباق، مضمر تفہیم، اور سوالات پوچھنے کی صلاحیت پر انحصار کرتی ہیں۔ ایجنٹ کی مہارتیں واضح اور درست ہونی چاہئیں، اور مہارت کی فائل میں جو کچھ ہے اس سے بڑھ کر کوئی علم فرض نہیں کیا جائے گا۔

بہترین مہارتیں کوڈ بیس کے ساتھ حقیقی دنیا کے تجربے سے حاصل ہوتی ہیں۔ جب بھی آپ AI سے تیار کردہ کوڈ میں دستی طور پر ترمیم کریں تو چلتی فہرست کو برقرار رکھیں۔ تمام ترامیم مہارت کے اصول ہیں۔ جب آپ ٹیم کے کسی نئے رکن کو قواعد کی وضاحت کرتے ہیں، تو وہ وضاحت تکنیکی مواد ہے۔ اگر آپ کو کوڈ کے جائزے میں لگاتار تین بار ایک ہی غلطی نظر آتی ہے، تو اس غلطی کے لیے مہارت کی ضرورت ہوتی ہے۔

اس سے پہلے کہ آپ کوئی اصول لکھیں، اپنے آپ سے پوچھیں: "کیا کوئی ایجنٹ جو میرے کوڈبیس کو نہیں جانتا وہ ایسا کر سکے گا؟" اگر جواب نفی میں ہے تو اصول تکنیکی ہے۔

تفصیل: 20 اہم ترین الفاظ

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

# Poor: too vague, no trigger phrases
description: How to handle state in Flutter apps.

# Better: specific, multiple trigger phrases, clear scope
description: Implement state management using flutter_bloc in Flutter applications.
Use when adding state management to screens, creating new features that have loading
or error states, fetching data from APIs, handling user interactions that change
UI state, or implementing BlocProvider, BlocBuilder, BlocListener, or BlocConsumer.
Applies when you see references to bloc, cubit, state, event, or stream in a task.

دوسری وضاحت کئی مخصوص وجوہات کی بنا پر بہتر ہے۔ مخصوص ٹرگر منظرناموں کی فہرست بنائیں ("لوڈنگ یا ایرر اسٹیٹس کے ساتھ نیا فنکشن بنائیں") جو کہ مبہم "ہینڈل اسٹیٹ" کے مقابلے میں اصل کام کی تفصیل سے مماثل ہیں۔ اس میں متعلقہ پیکیج کی API سطح شامل ہے (BlocProvider, BlocBuilder) ممکنہ طور پر ملازمت کی تفصیل میں ظاہر ہوگا۔ اور تصوراتی مطلوبہ الفاظ کی فہرست (bloc, cubit, stateاور event) سگنل کے طور پر کام کرتا ہے۔

ایجنٹ کے رویے کو تبدیل کرنے کے لیے قواعد لکھیں۔

تمام قوانین برابر نہیں ہیں۔ وہ قواعد جو ایجنٹوں کو کہتے ہیں کہ وہ پہلے سے کیا کر رہے ہیں کوئی اہمیت نہیں دیتے۔ وہ قواعد جو ایجنٹ کے کام کو تبدیل کرتے ہیں قیمتی اصول ہیں۔ رویے کو تبدیل کرنے کے لیے اصول لکھنے کے لیے، مشاہدات سے شروع کریں۔ ایجنٹ نے اصل میں کیا تخلیق کیا جو غلط تھا، اور کن اصولوں نے اسے روکا؟

## Rules That Work vs Rules That Do Not

DO NOT WORK (agent was already trying to do these):
- Write clean, readable code.
- Follow Flutter best practices.
- Use appropriate state management.
- Keep the codebase maintainable.

WORK (these change specific agent behavior):
- Extract any widget build section exceeding 30 lines into a separate class in widgets/.
- Never call setState inside a widget that has a corresponding BlocBuilder.
- Name Bloc events as past-tense verbs: ProfileLoadRequested, not LoadProfile.
- Place all Bloc files (bloc, event, state) in a bloc/ subdirectory inside the feature.
- The state class uses sealed keyword: sealed class ProfileState {}.
- Provide super.key in every widget constructor: const MyWidget({super.key}).
- Check mounted before calling setState in any async method.

کام کرنے کے قوانین میں ایک مخصوص نمبر (30 لائنیں)، ایک مخصوص فولڈر کا نام (widgets/، bloc/)، مثالوں کے ساتھ ایک مخصوص نام کا نمونہ، اور ایک مخصوص کوڈ پیٹرن شامل ہیں۔ "کلین کوڈ لکھیں" جیسے مبہم اصول بیان کرتے ہیں کہ ایجنٹ پہلے سے طے شدہ طور پر کیا کرنے کی کوشش کر رہا ہے۔ کچھ اصول، جیسے "مخصوص مثالوں کے ساتھ ماضی کے تناؤ کے فعل کے ساتھ نام بلاک واقعات"، اصل پیداوار کو تبدیل کرتے ہیں۔

متضاد نمونہ

تربیت کے اعداد و شمار میں عام نمونوں کا احاطہ کرنے والے اصولوں کے لیے، درست نمونوں کے ساتھ غلط نمونوں کو ظاہر کرنا صرف متن میں اصول کو بیان کرنے سے کہیں زیادہ مؤثر ہے۔ ایجنٹوں نے تربیت کے دوران ہزاروں بار غلط نمونے دیکھے۔ متنی اصول شاید اتنے طاقتور نہ ہوں کہ سیکھے ہوئے رویے کو اوور رائیڈ کر سکیں۔ بصری تضاد ارادے کو واضح کرتا ہے۔

## Error State Naming

Do not name error states with the word "Error" alone at the end.

Do not do this:

```
final class ProfileError extends ProfileState {
  const ProfileError();
}

غلطی کے سیاق و سباق پر مشتمل ہے۔

final class ProfileLoadFailure extends ProfileState {
  const ProfileLoadFailure({required this.message});
  final String message;
}

کام کا نام شامل کریں (Load) ناکام آپریشن کے لیے مخصوص خرابی کی حالت پیدا کرتا ہے۔ یہ اس وقت اہم ہے جب ایک بلاک متعدد کاموں کو سنبھالتا ہے جو آزادانہ طور پر ناکام ہو سکتے ہیں۔ ProfileLoadFailure اور ProfileUpdateFailure ہم بامعنی طور پر ایک ساتھ رہ سکتے ہیں۔ ProfileError اور ProfileError2 نہیں کر سکتے

جوابی مثال کے بعد کی وضاحت ("ایکشن کے نام کے ساتھ...") اصول کو ایک وجہ سے جوڑتی ہے، جس سے ایجنٹ کو صرف اصول کے خط پر عمل کرنے کی بجائے انتہائی صورتوں میں اصول کو درست طریقے سے لاگو کرنے میں مدد ملتی ہے۔

ضروری پھڑپھڑانے کی مہارتیں ہر ٹیم کو ہونی چاہئیں

سب سے عام علاقوں کی بنیاد پر جہاں AI ایجنٹ غلط فلٹر آؤٹ پٹ تیار کرتے ہیں، یہاں ضروری ٹیکنالوجیز ہیں جو ہر فلٹر ٹیم کو بنانا اور برقرار رکھنی چاہیے: ہر ایک کو مکمل طور پر پیش کیا جاتا ہے تاکہ اسے آپ کے مخصوص اصولوں کے مطابق بنایا جا سکے۔

ریاستی انتظامی ٹیکنالوجی کو بلاک کریں۔

---
name: flutter-bloc-state-management
description: Implement state management using flutter_bloc. Use when creating new features,
adding state to screens, fetching data from APIs, handling user interactions that produce
loading or error states, using BlocProvider, BlocBuilder, BlocListener, BlocConsumer,
adding a Cubit, or any task involving state transitions in Flutter.
---

# Flutter Bloc State Management

This project uses flutter_bloc for all state management. Do not use setState, ChangeNotifier,
Provider, or Riverpod unless explicitly instructed.

## File Structure

Every feature that requires state management has three Bloc files in a bloc/ subdirectory:

lib/
  features/
    profile/
      bloc/
        profile_bloc.dart      <- Bloc class and handler methods
        profile_event.dart     <- All events as sealed class hierarchy
        profile_state.dart     <- All states as sealed class hierarchy
      screens/
        profile_screen.dart
      widgets/
        profile_card.dart
      profile.dart              <- barrel export

مہربند کلاس

تقریبات اور ریاستیں ڈارٹ کے مہر بند کلاس سسٹم کو مکمل ہینڈلنگ کے لیے استعمال کرتی ہیں۔

// profile_event.dart
sealed class ProfileEvent {}

final class ProfileLoadRequested extends ProfileEvent {
  const ProfileLoadRequested({required this.userId});
  final String userId;
}

final class ProfileUsernameUpdated extends ProfileEvent {
  const ProfileUsernameUpdated({required this.newUsername});
  final String newUsername;
}

// profile_state.dart
sealed class ProfileState {}

final class ProfileInitial extends ProfileState {}

final class ProfileLoading extends ProfileState {}

final class ProfileLoaded extends ProfileState {
  const ProfileLoaded({required this.profile});
  final UserProfile profile;
}

final class ProfileLoadFailure extends ProfileState {
  const ProfileLoadFailure({required this.message});
  final String message;
}

sealed class ایک مکمل درجہ بندی بنائیں۔ ڈارٹ کا کمپائلر اس بات کو یقینی بنا سکتا ہے کہ تمام ممکنہ ریاستوں کو سوئچ اسٹیٹمنٹ میں ہینڈل کیا جائے۔ final class ٹھوس عمل درآمد غیر ارادی ذیلی طبقے کو روکتا ہے۔ تمام ریاستیں اور واقعات final اور sealed.

نام دینے کا کنونشن

بلاک کلاس کو فنکشن کے نام کے بعد فنکشن کا نام استعمال کرنا چاہیے۔ Blocاس طرح ProfileBloc, AuthBlocیا CartBloc. واقعات کو ماضی کے زمانہ فعل کے فقرے، فنکشن کے نام، اور فنکشن کے نام استعمال کرنے چاہئیں۔ Event لاحقے جیسے ProfileLoadRequested یا AuthLoginAttempted. ریاستوں کو فنکشن کے نام کے بعد درج ذیل وضاحتی اسم یا صفت کا استعمال کرنا چاہیے: ProfileInitial, ProfileLoading, ProfileLoadedیا ProfileLoadFailure.

کمانڈ کے طور پر ایونٹ کا نام متعین نہ کریں ( LoadProfileلیکن ProfileLoadRequested)۔ غلطی کی حالت کو اس طرح کا نام نہ دیں: ProfileError. درج ذیل کاموں پر مشتمل ہے: ProfileLoadFailure, ProfileUpdateFailure.

بلاک کلاس

// profile_bloc.dart
class ProfileBloc extends Bloc {
  final ProfileRepository _repository;

  ProfileBloc({required ProfileRepository repository})
      : _repository = repository,
        super(ProfileInitial()) {
    on(_onProfileLoadRequested);
    on(_onProfileUsernameUpdated);
  }

  Future _onProfileLoadRequested(
    ProfileLoadRequested event,
    Emitter emit,
  ) async {
    emit(ProfileLoading());

    final result = await _repository.getProfile(event.userId);

    result.fold(
      (failure) => emit(ProfileLoadFailure(message: _mapFailure(failure))),
      (profile) => emit(ProfileLoaded(profile: profile)),
    );
  }

  String _mapFailure(AppFailure failure) => switch (failure) {
    NetworkFailure(:final message) => message,
    ServerFailure(:final message) => message,
    NotFoundFailure() => 'Profile not found',
    UnauthorizedFailure() => 'Please sign in again',
    _ => 'An unexpected error occurred',
  };
}

ہر ایونٹ ہینڈلر ایک نجی طریقہ ہے: _on + ایونٹ کلاس کا نام۔ پیٹرن تمام بلاکس میں یکساں ہے۔ تمام ہینڈلرز غیر مطابقت پذیر آپریشن سے پہلے لوڈنگ کی حیثیت اور اس کے بعد کامیابی یا ناکامی کی حیثیت کا اخراج کرتے ہیں۔ ہینڈلر براہ راست ڈیٹا واپس نہیں کرتے ہیں۔ تمام مواصلت خارج ہونے والی ریاستوں کے ذریعے ہوتی ہے۔

ویجیٹ انضمام

class ProfileScreen extends StatelessWidget {
  const ProfileScreen({super.key, required this.userId});
  final String userId;

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (context) => ProfileBloc(
        repository: context.read(),
      )..add(ProfileLoadRequested(userId: userId)),
      child: BlocConsumer(
        listener: (context, state) {
          if (state is ProfileLoadFailure) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(content: Text(state.message)),
            );
          }
        },
        builder: (context, state) => switch (state) {
          ProfileInitial() => const SizedBox.shrink(),
          ProfileLoading() => const Center(child: CircularProgressIndicator()),
          ProfileLoaded(:final profile) => ProfileContent(profile: profile),
          ProfileLoadFailure(:final message) => ProfileErrorView(message: message),
        },
      ),
    );
  }
}

BlocConsumer سننے والوں (سائیڈ ایفیکٹس) اور بلڈرز (UI) کو یکجا کرتا ہے۔ مہربند حالت میں سوئچ ایکسپریشنز مکمل ہیں۔ مرتب کرنے والا ہر ریاست کو ایک متعلقہ UI رکھنے پر مجبور کرتا ہے۔

حرام پیٹرن

استعمال نہ کریں setState ان تمام ویجٹس پر جن کے پاس وہ بلاک ہے۔ فون مت کرو context.read().add(event) اندر سے initState اداکاری کے بغیر addPostFrameCallback. قریب نہ جاؤ BuildContext جب سے await چیک کیے بغیر mounted. اندر بلاکس نہ بنائیں۔ StatelessWidget.build طریقہ (ہر تعمیر نو پر دوبارہ بنایا گیا)

فنکشنل آرکیٹیکچر ٹیکنالوجی

---
name: flutter-feature-architecture
description: Structure Flutter features using clean architecture with repository, service,
and presentation layers. Use when creating new features, adding screens, implementing
data fetching, organizing existing code, deciding where a new file belongs, or any task
that involves folder structure, layer boundaries, or the project's directory organization.
---

# Flutter Feature Architecture

This project uses feature-first folder structure with clean architecture layers.

اعلی سطح کی ساخت

lib/
  core/
    constants/     <- app-wide constants, not feature-specific
    errors/         <- AppFailure sealed class hierarchy
    extensions/     <- Dart extension methods
    theme/          <- theme extensions, color tokens, typography
    utils/          <- pure utility functions
  features/
    auth/
    profile/
    home/
    settings/
  shared/
    widgets/        <- widgets used in 3+ features
    models/         <- models shared between features
    services/       <- services used by multiple features
  app.dart          <- MaterialApp setup
  main.dart         <- entry point

فنکشن فولڈر کا ڈھانچہ

تمام افعال درج ذیل اندرونی ساخت کی پیروی کرتے ہیں:

features/
  profile/
    bloc/
      profile_bloc.dart
      profile_event.dart
      profile_state.dart
    data/
      profile_repository.dart          <- interface
      profile_repository_impl.dart     <- implementation
      profile_remote_data_source.dart
      profile_local_data_source.dart
    domain/
      profile_model.dart                <- freezed domain model
    screens/
      profile_screen.dart
      edit_profile_screen.dart
    widgets/
      profile_card.dart
      profile_header.dart
      profile_stats_row.dart
    profile.dart                         <- barrel export

پرت پر انحصار کے اصول

پریزنٹیشن پرت (اسکرین اور ویجٹ) صرف بلاک اور ڈومین ماڈلز پر انحصار کرتی ہے۔ بلاک صرف اسٹوریج انٹرفیس پر انحصار کرتا ہے (عمل درآمد نہیں)۔ ڈیٹا ماخذ کے لحاظ سے اسٹوریج کا نفاذ مختلف ہوتا ہے۔ ڈیٹا کے ذرائع کا انحصار بیرونی پیکجز (Firebase، HTTP، SharedPreferences) پر ہوتا ہے۔

غلط سمت میں تہوں کو درآمد کرنے سے گریز کریں۔ ڈیٹا پرت پریزنٹیشن پرت سے نہیں آتی ہے۔ ڈومین پرت آپ کے پروجیکٹ سے کچھ بھی درآمد نہیں کرتی ہے۔

بیرل برآمد فائل

ہر فنکشن میں ایک بیرل فائل ہوتی ہے جو صرف اس فنکشن کے پبلک API کو ایکسپورٹ کرتی ہے۔

// features/profile/profile.dart
export 'domain/profile_model.dart';
export 'screens/profile_screen.dart';
export 'screens/edit_profile_screen.dart';
export 'bloc/profile_bloc.dart';
export 'bloc/profile_event.dart';
export 'bloc/profile_state.dart';

اندرونی نفاذ کی فائلیں (ڈیٹا سورس، ریپوزٹری کا نفاذ) برآمد نہیں کی جاتی ہیں۔ کوڈ درآمد کا استعمال کریں۔ package:myapp/features/profile/profile.dartیہ کسی بھی طرح سے گہرا راستہ نہیں ہے۔

بنیادی فولڈر کے قواعد

ایک فائل کا تعلق بنیادی/ صرف اس صورت میں ہے جب اسے تین یا زیادہ فنکشنز کے ذریعے استعمال کیا گیا ہو۔ اگر یہ صرف ایک یا دو خصوصیات میں استعمال ہوتا ہے، تو اس کا تعلق اس فیچر کے فولڈر میں ہوتا ہے۔ آئٹمز کو مستقبل میں کہاں استعمال کیا جائے گا اس کی بنیاد پر ان کو بنیادی طور پر منتقل نہ کریں۔

غلطی سے نمٹنے کی تکنیک

---
name: flutter-error-handling
description: Implement error handling using typed AppFailure classes and Either return types.
Use when handling errors from API calls, repository methods, Bloc error states, catching
exceptions in data sources, showing error UI, implementing try-catch, or any task that
involves failure, exception, error state, or error message handling.
---

# Flutter Error Handling

This project uses a typed failure system. Raw exceptions do not cross layer boundaries.

ایپ کی ناکامی کا درجہ بندی

// core/errors/app_failure.dart
sealed class AppFailure {
  const AppFailure();
}

final class NetworkFailure extends AppFailure {
  const NetworkFailure({required this.message});
  final String message;
}

final class ServerFailure extends AppFailure {
  const ServerFailure({required this.statusCode, required this.message});
  final int statusCode;
  final String message;
}

final class CacheFailure extends AppFailure {
  const CacheFailure({required this.message});
  final String message;
}

final class NotFoundFailure extends AppFailure {
  const NotFoundFailure();
}

final class UnauthorizedFailure extends AppFailure {
  const UnauthorizedFailure();
}

final class ValidationFailure extends AppFailure {
  const ValidationFailure({required this.field, required this.message});
  final String field;
  final String message;
}

sealed class AppFailure ایک مکمل درجہ بندی بنائیں۔ نئی ناکامی کی اقسام شامل کی گئی ہیں: final class ذیلی کلاس مرتب کرنے والا بیانات کو لاگو کرنے پر مجبور کرتا ہے۔ AppFailure تمام ممکنہ ذیلی قسموں کو ہینڈل کرتا ہے۔

ذخیرہ کی واپسی کی قسم

ذخیرہ کرنے کا طریقہ واپسی Either پر fpdart پیکیج:

abstract class ProfileRepository {
  Future> getProfile(String userId);
  Future> updateUsername(String userId, String username);
}

واپسی کے راستے میں Either ناکامی کو قابل بناتا ہے، لیکن اسے قسم کی سطح پر واضح کرتا ہے۔ ذخیرہ کرنے والے صارف کو واپسی کی قسم کی وجہ سے دونوں شاخوں کو ہینڈل کرنا چاہیے، اس لیے وہ نادانستہ طور پر ناکامی کے امکان کو نظر انداز نہیں کر سکتا۔

ڈیٹا ماخذ استثنیٰ ہینڈلنگ

ڈیٹا سورس واحد پرت ہے جو ٹرائی کیچ استعمال کرتی ہے۔ خام استثناء کو پکڑیں ​​اور اسے AppFailure آبجیکٹ میں تبدیل کریں۔

class ProfileRemoteDataSource {
  Future> getProfile(String userId) async {
    try {
      final doc = await _firestore.collection('users').doc(userId).get();

      if (!doc.exists) return left(const NotFoundFailure());

      return right(UserProfileDto.fromJson(doc.data()!));
    } on FirebaseException catch (e) {
      return switch (e.code) {
        'permission-denied' => left(const UnauthorizedFailure()),
        'unavailable' => left(NetworkFailure(message: e.message ?? 'Network error')),
        _ => left(ServerFailure(statusCode: 0, message: e.message ?? 'Server error')),
      };
    } catch (e) {
      return left(NetworkFailure(message: e.toString()));
    }
  }
}

حرام پیٹرن

استعمال نہ کریں try-catch بلاک، اسٹوریج یا پریزنٹیشن لیئر کوڈ میں۔ سٹوریج کے طریقوں میں مستثنیات نہ پھینکیں۔ استعمال نہ کریں String اسٹیٹس کلاس کے لیے غلطی کے پیغام کی قسم کے طور پر استعمال کیا جاتا ہے۔ ان پٹ کی ناکامی کا استعمال کریں۔ UI کو خام استثنائی پیغامات نہ بھیجیں۔ بلاک میں صارف دوست پیغامات میں نقشہ کی ناکامی۔

تھیم کی مہارت

---
name: flutter-theming
description: Apply colors, typography, spacing, and visual styling using the project's
theme extension system. Use whenever writing code that involves colors, text styles,
padding, margin, border radius, shadows, or any visual appearance of UI components.
Apply when you see requests involving styling, colors, fonts, spacing, or visual design.
---

# Flutter Theming

This project uses theme extensions for all visual styling. Hardcoded visual values are not permitted anywhere in the codebase.

رنگ تک رسائی

// Do not do this
color: const Color(0xFF6750A4)
color: Colors.deepPurple
backgroundColor: Theme.of(context).colorScheme.primary

// Do this
color: context.appColors.primary
backgroundColor: context.appColors.surface

context.appColors کی توسیع ہے BuildContext میں بیان کیا گیا ہے۔ core/theme/app_colors_extension.dart. ایک نام کا استعمال کرتے ہوئے مکمل رنگ پیلیٹ تک ٹائپ شدہ رسائی فراہم کرتا ہے جو ارادے کو ظاہر کرتا ہے۔

دستیاب رنگ: کے ذریعے فراہم کردہ سیمنٹک رنگ استعمال کریں۔ context.appColors.

کے لیے برانڈنگ اور سطحیں۔استعمال کریں context.appColors.primary برانڈ کے اہم رنگ کے طور پر، context.appColors.secondary ثانوی لہجے کے لیے context.appColors.surface کارڈ اور کنٹینر کے پس منظر کے لیے context.appColors.background اسکرین کے پس منظر کے لیے۔

کے لیے اہماستعمال کریں context.appColors.error غلطی کی حیثیت اور context.appColors.success کامیابی کی حیثیت کے لیے۔

کے لیے متناستعمال کریں context.appColors.textPrimary مقامی طور پر پڑھنے کے قابل متن کے لیے context.appColors.textSecondary کیپشنز، لیبلز اور معاون معلومات کے لیے context.appColors.textDisabled غیر فعال کنٹرولز اور متن کے لیے۔

وقفہ

// Do not do this
padding: const EdgeInsets.all(16)
margin: const EdgeInsets.symmetric(horizontal: 24, vertical: 8)

// Do this
padding: const EdgeInsets.all(AppSpacing.md)
margin: const EdgeInsets.symmetric(
  horizontal: AppSpacing.lg,
  vertical: AppSpacing.sm,
)

AppSpacing میں بیان کیا گیا ہے۔ core/constants/app_spacing.dart درج ذیل وقفہ کی قدریں فراہم کریں:

xs: 4 · sm: 8 · ایم ڈی: 16 · LG: 24 · بڑا سائز: 32 · xxl: 48

نوع ٹائپ

// Do not do this
style: const TextStyle(fontSize: 16, fontWeight: FontWeight.w600)

// Do this
style: context.appTypography.bodyMedium
style: context.appTypography.headlineLarge.copyWith(
  color: context.appColors.textPrimary,
)

context.appTypography کی توسیع ہے BuildContext مکمل قسم کا پیمانہ فراہم کرتا ہے۔

سرحدی رداس

// Do not do this
borderRadius: BorderRadius.circular(8)

// Do this
borderRadius: BorderRadius.circular(AppRadius.sm)

AppRadius مستقل: xs (4)، sm (8) md (12) lg (16) xl (24) round (999)

نیویگیشن کی مہارت

---
name: flutter-navigation
description: Implement navigation using GoRouter. Use when adding routes, navigating
between screens, implementing deep links, setting up route guards or redirects,
handling authentication-gated routes, working with nested navigation or shell routes,
or any task involving navigation, routing, back button, browser URL, or deep link.
---

# Flutter Navigation

This project uses GoRouter for all navigation. Do not use Navigator.push, Navigator.pushNamed, Navigator.pop (only via GoRouter), or any Navigator API that bypasses GoRouter.

راستہ مسلسل

تمام راستے کے راستے مستقل ہیں۔ core/router/routes.dart:

abstract class Routes {
  static const splash="/";
  static const login = '/auth/login';
  static const register="/auth/register";
  static const home="/home";
  static const profile="/home/profile/:userId";
  static const editProfile="/home/profile/:userId/edit";
  static const settings="/settings";
}

نیویگیشن میں سٹرنگ لٹریلز استعمال کرنے سے گریز کریں۔ ہمیشہ استعمال کریں۔ Routes.homeنہیں '/home'.

نیویگیٹ کرنے کا طریقہ

// Replace the current location (no back button to previous)
context.go(Routes.home);

// Push on top (back button returns to previous location)
context.push(Routes.profile.replaceAll(':userId', userId));

// Pop (go back)
context.pop();

// Pop with a result
context.pop(result);

اسے کبھی استعمال نہ کریں۔ Navigator.of(context).push(...). GoRouter کو بائی پاس کریں اور ڈیپ لنکنگ کو توڑ دیں۔

روٹر کی تعریف

تمام راستے اس میں بیان کیے گئے ہیں: core/router/app_router.dart:

final router = GoRouter(
  initialLocation: Routes.splash,
  redirect: _redirectLogic,
  routes: [
    GoRoute(
      path: Routes.home,
      pageBuilder: (context, state) => NoTransitionPage(
        child: const HomeScreen(),
      ),
    ),
    GoRoute(
      path: Routes.profile,
      builder: (context, state) {
        final userId = state.pathParameters['userId']!;
        return ProfileScreen(userId: userId);
      },
    ),
  ],
);

درج کردہ پیرامیٹرز

راستے کے پیرامیٹرز کو اس سے نکالیں: state.pathParametersاور استفسار کے پیرامیٹرز state.uri.queryParameters. راستے کے تاروں کو دستی طور پر پارس نہ کریں۔

ضروری ڈارٹ مہارتیں ہر ڈویلپر کو لکھنا چاہئے۔

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

ڈارٹ ماڈل اور منجمد مہارت

---
name: dart-models-freezed
description: Create immutable data models using the freezed package with json_serializable
for serialization. Use when creating new data models, DTOs, request or response objects,
value objects, or any Dart class that represents structured data. Applies when working
with JSON parsing, API response mapping, or defining data structures.
---

# Dart Models with Freezed

All data models use the freezed package for immutability and code generation.

ماڈل کی تعریف

import 'package:freezed_annotation/freezed_annotation.dart';

part 'user_profile.freezed.dart';
part 'user_profile.g.dart';

@freezed
class UserProfile with _$UserProfile {
  const factory UserProfile({
    required String id,
    required String name,
    required String email,
    String? avatarUrl,
    @Default(false) bool isVerified,
    required DateTime createdAt,
  }) = _UserProfile;

  factory UserProfile.fromJson(Map json) =>
      _$UserProfileFromJson(json);
}

@freezed نامزد کنسٹرکٹر کا استعمال کرتے ہوئے ایک ناقابل تغیر کلاس بنانے کے لیے کوڈ جنریشن کو متحرک کرتا ہے۔ copyWith ایک ترمیم شدہ کاپی بنانے کے لیے == اور hashCode تمام شعبوں کی بنیاد پر، toString ڈیبگنگ کے لیے fromJson/toJson کے ذریعے json_serializable.

کہ part ہدایت درکار ہے اور فائل کے نام سے مماثل ہونی چاہیے۔ user_profile.dart بنائیں user_profile.freezed.dart اور user_profile.g.dart.

فیلڈ کے قوانین

استعمال کریں required ان فیلڈز کے لیے جو ہمیشہ موجود ہونا چاہیے۔ استعمال کریں String? (ناقابل قبول) اختیاری فیلڈ۔ استعمال کریں @Default(value) مناسب ڈیفالٹ اقدار کے ساتھ فیلڈز کے لیے جو منسوخی کو روکتی ہیں۔ اور استعمال کریں @JsonKey(name: 'field_name') JSON فیلڈ کا نام ڈارٹ فیلڈ کے نام سے مختلف ہے۔

ماڈل کو شامل کرنے یا اس میں ترمیم کرنے کے بعد

ہمیشہ چلائیں:

dart run build_runner build --delete-conflicting-outputs

دستی طور پر ترمیم نہ کریں۔ .freezed.dart یا .g.dart فائل اگلی تعمیر میں تخلیق اور اوور رائٹ کیا جائے گا۔

ڈی ٹی او اور ڈومین ماڈل

ڈیٹا ٹرانسفر آبجیکٹ (DTOs) پر واقع ہیں: data/ نقشے براہ راست API فارم پر۔ جہاں ڈومین ماڈل رہتا ہے۔ domain/ ایپ کے اندرونی ڈیٹا ماڈل کی نمائندگی کرتا ہے۔

ایک DTO میں درج ذیل فیلڈز ہو سکتی ہیں: created_at (API میں snake_case)۔ ڈومین ماڈل میں createdAt (اونٹ کیس) ریپوزٹریز کو DTOs سے ڈومین ماڈلز میں میپ کیا جاتا ہے۔

ڈارٹ پیٹرن کے ملاپ کی مہارت

---
name: dart-pattern-matching-idiomatic
description: Use Dart 3 pattern matching, switch expressions, and sealed class hierarchies
for exhaustive control flow. Use when working with sealed classes, enums, discriminated
unions, conditional logic on types, or any switch statement that could be a switch
expression. Applies when refactoring if-else chains, handling multiple subtypes, or
implementing business logic that branches on type.
---

# Dart Pattern Matching

Use Dart 3 pattern matching for all control flow that involves type discrimination, sealed class hierarchies, or structural decomposition of data.

سوئچ اسٹیٹمنٹس کے لیے ایکسپریشنز سوئچ کریں۔

// Do not do this (switch statement is an imperative flow)
switch (state) {
  case ProfileLoading():
    return const CircularProgressIndicator();
  case ProfileLoaded():
    return ProfileContent(profile: state.profile);
  case ProfileLoadFailure():
    return ErrorView(message: state.message);
  default:
    return const SizedBox.shrink();
}

// Do this (switch expression is a value, works in build methods)
return switch (state) {
  ProfileInitial() => const SizedBox.shrink(),
  ProfileLoading() => const CircularProgressIndicator(),
  ProfileLoaded(:final profile) => ProfileContent(profile: profile),
  ProfileLoadFailure(:final message) => ErrorView(message: message),
};

سوئچ اظہار اقدار ہیں، بیانات نہیں۔ وہ قدرتی طور پر درج ذیل دلیل کے ساتھ کام کرتے ہیں: return یا متغیر کی قدر کے طور پر۔ مہر بند طبقاتی درجہ بندی اس کو مکمل بناتی ہے۔ جب آپ ایک نئی حالت شامل کرتے ہیں، تو مرتب کرنے والا آپ کو سوئچ کے وہ تمام تاثرات بتاتا ہے جو اسے سنبھالنے چاہئیں۔

پیٹرن کی تباہی

// Access fields directly in the pattern
case ProfileLoaded(:final profile) => ProfileContent(profile: profile),
// Equivalent to:
case ProfileLoaded() => ProfileContent(profile: state.profile),

کہ :final field پیٹرن کے اندر نحو فیلڈ کی اقدار کو کیس برانچ میں براہ راست باندھتا ہے۔ اس سے رسائی کی ضرورت ختم ہو جائے گی۔ state.profile الگ سے یہ کوڈ کو مزید جامع بناتا ہے۔

تحفظ کی شق

return switch (state) {
  ProfileLoaded(:final profile) when profile.isVerified => VerifiedProfileView(profile: profile),
  ProfileLoaded(:final profile) => UnverifiedProfileView(profile: profile),
  _ => const LoadingView(),
};

when پیٹرن میں ایک محفوظ شق شامل کریں۔ کیس صرف اس صورت میں مماثل ہے جب دونوں پیٹرن مماثل ہوں اور گارڈ کی حالت درست ہو۔ گارڈز ایک ہی قسم کے اندر باریک دانے دار شاخیں لگانے کی اجازت دیتے ہیں۔

ریکارڈنگ پیٹرن

// Matching on records
final (name, age) = getUserInfo();

// In switch expressions
final description = switch ((user.name, user.isAdmin)) {
  (final name, true) => '$name (Admin)',
  (final name, false) => name,
};

ریکارڈ ایک ساختی ٹوپل ہے۔ ریکارڈ پر پیٹرن کی مماثلت بغیر کسی نامزد ایکسیسر کے جزو کو براہ راست نکالتی ہے۔

اگر دوسری زنجیر کی تبدیلی

اگر آپ کو قسم یا قدر کے لحاظ سے ایک if-else چین برانچنگ نظر آتی ہے تو اسے سوئچ ایکسپریشن میں تبدیل کریں۔

// Do not do this
String label;
if (priority == Priority.high) {
  label="Urgent";
} else if (priority == Priority.medium) {
  label="Normal";
} else {
  label="Low";
}

// Do this
final label = switch (priority) {
  Priority.high => 'Urgent',
  Priority.medium => 'Normal',
  Priority.low => 'Low',
};

ڈارٹ ٹیسٹ کے قواعد کی تکنیک

---
name: dart-testing-conventions
description: Write Dart unit tests following package:test conventions with mocktail mocks,
descriptive group/test naming, and correct async testing patterns. Use when writing any test
file, adding tests to existing files, mocking dependencies, testing async functions,
or verifying error handling behavior.
---

# Dart Testing Conventions

ٹیسٹ فائل کا ڈھانچہ

import 'package:flutter_test/flutter_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:myapp/features/profile/data/profile_repository_impl.dart';
import 'package:myapp/core/errors/app_failure.dart';

class MockProfileRemoteDataSource extends Mock
    implements ProfileRemoteDataSource {}

class MockProfileLocalDataSource extends Mock
    implements ProfileLocalDataSource {}

void main() {
  late MockProfileRemoteDataSource mockRemote;
  late MockProfileLocalDataSource mockLocal;
  late ProfileRepositoryImpl repository;

  setUp(() {
    mockRemote = MockProfileRemoteDataSource();
    mockLocal = MockProfileLocalDataSource();
    repository = ProfileRepositoryImpl(
      remote: mockRemote,
      local: mockLocal,
    );
  });

  group('ProfileRepositoryImpl', () {
    group('getProfile', () {
      test(
        'returns Right(profile) when remote data source succeeds',
        () async {
          when(() => mockRemote.getProfile(any()))
              .thenAnswer((_) async => right(fakeProfileDto));

          final result = await repository.getProfile('user123');

          expect(result.isRight(), isTrue);
          expect(result.getOrElse(() => null)?.id, equals('user123'));
        },
      );

      test(
        'returns Left(NetworkFailure) when remote throws network error',
        () async {
          when(() => mockRemote.getProfile(any()))
              .thenAnswer((_) async => left(NetworkFailure(message: 'No internet')));

          final result = await repository.getProfile('user123');

          expect(result.isLeft(), isTrue);
          expect(result.fold((f) => f, (_) => null), isA());
        },
      );
    });
  });
}

اپنے ٹیسٹ کا نام دیں۔

وضاحتی ٹیسٹ کے نام استعمال کریں جو پیٹرن کی پیروی کریں۔ "جب Y، میں X کرتا ہوں" یا "اگر Y، تو X واپس کریں۔".

ہاں: returns Right(profile) when remote data source succeeds, returns Left(NetworkFailure) when connection failsاور calls local data source when remote fails.

استعمال کرنے سے گریز کریں۔ "ٹیسٹ" یا "مجھے یہ کرنا ہے" ٹیسٹ نام کے ساتھ۔ مثال کے طور پر returns profile when repository call succeeds اس کے بجائے test that profile is returned correctly یا should return profile when called.

فرضی ترتیبات

ایک نیا فرضی ماڈل بنائیں setUpاعلی سطح پر نہیں main. یہ اس بات کو یقینی بناتا ہے کہ ایک ٹیسٹ سے ریاست دوسرے ٹیسٹ میں لیک نہیں ہو سکتی۔

استعمال کریں registerFallbackValue کو setUpAll تمام حسب ضرورت اقسام کے لیے any():

setUpAll(() {
  registerFallbackValue(const ProfileLoadRequested(userId: ''));
  registerFallbackValue(left(const NotFoundFailure()));
});

غیر مطابقت پذیر ٹیسٹنگ

// For Future results
final result = await repository.getProfile('user123');
expect(result.isRight(), isTrue);

// For Stream results
expectLater(
  bloc.stream,
  emitsInOrder([ProfileLoading(), ProfileLoaded(profile: fakeProfile)]),
);

ہمیشہ استعمال کریں۔ await تحفے کے لیے۔ استعمال کریں expectLater کے ساتھ emitsInOrder ندیوں کے لیے۔ استعمال نہ کریں await Future.delayed(...) جانچ میں۔ استعمال کریں pump() ویجٹ کی جانچ کے لیے، یا استعمال کرتے ہوئے غیر مطابقت پذیر رویے کا مذاق اڑانے کے لیے: thenAnswer.

فن تعمیر اور بڑے کوڈ بیس میں مہارت

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

کارکردگی کی مہارت

---
name: flutter-performance
description: Apply Flutter performance best practices including const widgets, selective
rebuilds, lazy loading, and proper use of keys. Use when optimizing screens, implementing
lists, adding animations, working with images, or any task where rendering performance,
jank, frame rate, or memory usage is relevant.
---

# Flutter Performance

Const ویجیٹ

کوئی بھی ویجیٹ جو const ہو سکتا ہے const ہونا چاہیے۔ کوئی بھی کنسٹرکٹر جو const ہوسکتا ہے اس کے پاس const کنسٹرکٹر ہونا ضروری ہے۔

// Do not do this
class UserAvatar extends StatelessWidget {
  UserAvatar({super.key, required this.url}); // Missing const
  final String url;

  @override
  Widget build(BuildContext context) {
    return CircleAvatar(  // Missing const where possible
      backgroundImage: NetworkImage(url),
    );
  }
}

// Do this
class UserAvatar extends StatelessWidget {
  const UserAvatar({super.key, required this.url});
  final String url;

  @override
  Widget build(BuildContext context) {
    return CircleAvatar(
      backgroundImage: NetworkImage(url),
    );
  }
}

کارکردگی کی فہرست بنائیں

استعمال کریں ListView.builder نامعلوم یا بڑی تعداد میں آئٹمز والی فہرستوں کے لیے۔ اسے کبھی استعمال نہ کریں۔ ListView کے ساتھ children ان فہرستوں کے لیے جو 20 سے زیادہ اشیاء تک بڑھ سکتی ہیں۔

// Do not do this for variable-length lists
ListView(
  children: items.map((item) => ItemCard(item: item)).toList(),
)

// Do this
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => ItemCard(item: items[index]),
)

بلاک سلیکٹر کا استعمال کرتے ہوئے سلیکٹیو ری بلڈ

اگر ویجیٹ ٹری کا صرف ایک حصہ ریاست کے کچھ حصے پر منحصر ہے، تو صرف انحصار ویجٹ کو دوبارہ بنانے کے لیے بلاک سلیکٹر کا استعمال کریں۔

// Do not do this (entire subtree rebuilds on any state change)
BlocBuilder(
  builder: (context, state) => CartBadge(count: state is CartLoaded ? state.itemCount : 0),
)

// Do this (rebuilds only when item count changes)
BlocSelector(
  selector: (state) => state is CartLoaded ? state.itemCount : 0,
  builder: (context, count) => CartBadge(count: count),
)

امیج آپٹیمائزیشن

استعمال کریں cached_network_image نیٹ ورک کی تصاویر کے لیے۔ اسے کبھی استعمال نہ کریں۔ Image.network براہ راست استعمال کریں cacheWidth اور cacheHeight فہرست کے آئٹمز کو ڈی کوڈ کرتے وقت تصویر کو اسکیل کرتا ہے۔ بہت چھوٹے فائل سائز کے لیے، Android پر WebP فارمیٹ اور iOS پر HEIC/WebP استعمال کریں۔

رسائی ٹیکنالوجی

---
name: flutter-accessibility
description: Implement accessibility features including semantic labels, focus management,
contrast requirements, and screen reader support. Use when creating interactive widgets,
images, icons, form fields, or any element that needs to be usable by people with
disabilities. Apply when working with Semantics, ExcludeSemantics, Focus, or FocusNode.
---

# Flutter Accessibility

انٹرایکٹو عناصر کے لیے سیمنٹک لیبلز

ہر IconButton, FloatingActionButtonاور GestureDetector اگر آپ کوئی معنی خیز کام کر رہے ہیں، تو آپ کے پاس سیمنٹک لیبل ہونا چاہیے۔

// Do not do this
IconButton(
  onPressed: _onShare,
  icon: const Icon(Icons.share),
)

// Do this
IconButton(
  onPressed: _onShare,
  icon: const Icon(Icons.share),
  tooltip: 'Share post', // Used as semantic label on mobile
)

تصاویر اور آرائشی شبیہیں

شبیہیں اور تصاویر جو خالصتاً کاسمیٹک ہیں ڈسپلے کی جانی چاہئیں تاکہ اسکرین ریڈرز انہیں چھوڑ سکیں۔

// Decorative icon (no semantic value)
Icon(
  Icons.star,
  semanticLabel: '', // Empty label marks it as decorative
)

// Informative icon (has semantic value)
Icon(
  Icons.warning,
  semanticLabel: 'Warning: action cannot be undone',
)

فارم کی رسائی

تمام فارم فیلڈز میں ایک لیبل ہونا چاہیے جو اسکرین ریڈر کو بتائے کہ کیا کرنا ہے۔ فیلڈز کی شناخت کے لیے مکمل طور پر پلیس ہولڈر ٹیکسٹ پر انحصار نہ کریں۔

TextFormField(
  decoration: const InputDecoration(
    labelText: 'Email address',    // Screen readers announce this
    hintText: 'name@example.com', // Only visible when empty
  ),
)

کم از کم ٹچ ہدف کا سائز

تمام متعامل عناصر کم از کم 48x48dp ہونے چاہئیں۔ جب بصری سائز چھوٹا ہوتا ہے۔ SizedBox یا Padding ہٹ ایریا کو بڑھانے کے لیے:

SizedBox(
  width: 48,
  height: 48,
  child: IconButton(
    iconSize: 20,
    onPressed: _onClose,
    icon: const Icon(Icons.close),
  ),
)

اعلی درجے کی مہارت کے پیٹرن

اسائنمنٹس کو مکمل کرنے کے حصے کے طور پر تعلیمی ٹولز کا استعمال کریں۔

ٹیکنالوجی بعض کمانڈز کو "کام کرنے" کی تعریف کا حصہ بنا سکتی ہے۔ یہ سب سے طاقتور نمونوں میں سے ایک ہے کیونکہ یہ خود بخود کوالٹی لوپ کو بند کر دیتا ہے۔

## Required Verification Steps

After any code generation or modification task, always:

1. Run `dart format .` to format all Dart files
2. Run `flutter analyze` to check for analyzer errors and warnings
3. Run `flutter test` to verify no tests are broken by the changes
4. If any of the above produce errors, fix them before reporting the task as complete

Do not report a task complete if any of these commands fail.

یہ نمونہ کوڈ جنریشن گائیڈ کی تکنیکوں کا مکمل کوالٹی ایشورنس ورک فلو میں ترجمہ کرتا ہے۔ ایجنٹ صرف کوڈ نہیں لکھتے۔ ہم یہ کہنے سے پہلے کہ یہ ہو گیا ہے معیار کے معیار کے مطابق آپ کے کوڈ کی توثیق کرتے ہیں۔

حالات پر منحصر مشروط قواعد

کچھ اصول صرف مخصوص حالات میں لاگو ہوتے ہیں۔ ہم ان کا اظہار مشروط تاثرات میں کرتے ہیں جو ایجنٹ کو صحیح طریقے سے لاگو کرنے میں مدد کرتے ہیں۔

## Context-Dependent Rules

When a widget initiates a network request:
- Disable all interactive elements while the request is in flight
- Show a loading indicator appropriate to the UI scope
- Handle errors with a user-readable message
- Re-enable interactive elements when the request completes (success or failure)

When a Bloc handles multiple independent operations:
- Create separate error states for each operation (not a single generic Error state)
- Name each error state after the operation: ProfileLoadFailure, ProfileUpdateFailure

When creating a widget that appears in a ListView:
- Always provide a key
- Use const constructors wherever possible
- Consider using ListView.builder at the list level if the list may exceed 50 items

کراس حوالہ دینے کی تکنیک

پیچیدہ کاموں کے لیے مل کر کام کرنے کے لیے متعدد مہارتوں کی ضرورت پڑ سکتی ہے۔ اسکل باڈی میں متعلقہ مہارتوں کا واضح طور پر حوالہ دیں تاکہ ایجنٹ جانتا ہو کہ اس مہارت کو کیسے لوڈ کرنا ہے۔

## Related Skills

When this skill's rules result in widget extraction, also apply the
flutter-file-organization skill to determine the correct file location.

When the extracted component requires state management, apply the
flutter-bloc-state-management skill to determine whether it needs its own Bloc.

When writing tests for code created using this skill, apply the
dart-testing-conventions skill for test naming and structure.

مشکل سے جیتنے والے پروڈکشن اسباق کو انکوڈنگ کرنے کا فن

کچھ انتہائی قیمتی تکنیکی مواد مخصوص پروڈکشن ایونٹس سے آتا ہے۔ واقعے سے سیکھے گئے اسباق کو تکنیکی اصولوں کے ساتھ کافی سیاق و سباق کے ساتھ دستاویز کریں تاکہ ہر کوئی (اور ہر ایجنٹ) یہ سمجھ سکے کہ واقعہ کیوں موجود ہے۔

غیر مطابقت پذیر وقفہ کے بعد تعمیر کا حوالہ (پیداوار سے سیکھیں)

انتظار کے بعد BuildContext استعمال کرنے سے پہلے ہمیشہ ماؤنٹ کی جانچ کریں۔

Future _onSubmit() async {
  final result = await _repository.save(formData);

  // WRONG: context may be stale if widget was disposed during the await
  ScaffoldMessenger.of(context).showSnackBar(...);

  // CORRECT: check mounted first
  if (!mounted) return;
  ScaffoldMessenger.of(context).showSnackBar(...);
}

یہ خرابی ترقی میں خاموش ہے (ویجیٹ عام طور پر اس وقت تک نصب رہے گا جب تک کہ غیر مطابقت پذیر آپریشن مکمل نہ ہو جائے)، لیکن پروڈکشن میں، جہاں نیٹ ورک میں تاخیر زیادہ ہوتی ہے اور صارف اس وقت چلا جاتا ہے جب آپریشن جاری ہوتا ہے، ایک "FlutterError (ایک غیر فعال ویجیٹ کی تلاش کا اجداد)" کریش ہوتا ہے۔

پیکیج کی سطح کی مہارت: لائبریریوں میں ایجنٹوں کو تربیت دیں۔

کہ skills CLI ٹول (ایک ڈارٹ پیکیج کے طور پر دستیاب ہے یہاں سے: pub.dev/packages/skills) ایک طاقتور پیٹرن کو قابل بناتا ہے: آپ کے پروجیکٹ کے پیکیج کے انحصار سے براہ راست ٹیکنالوجیز کو انسٹال کرنا۔

# Install the Dart skills CLI globally
dart pub global activate skills

# Install skills from all packages in your project that ship skills
skills get

پیکیج شامل کرنا pubspec.yaml اور چلائیں skills getCLI ہر پیکج کو انحصار کے درخت میں تلاش کرتا ہے اور فراہم کرتا ہے۔ skills/ ڈائریکٹری کو براؤز کریں اور خود بخود ٹیکنالوجی کو انسٹال کریں۔ اس کا مطلب یہ ہے کہ پیکیج کے مصنفین اپنے استعمال کی ہدایات براہ راست ایجنٹ صارفین تک پہنچا سکتے ہیں۔

یہ کیوں اہمیت رکھتا ہے۔

پیکیج کی سطح کی ٹیکنالوجیز سے پہلے، جب آپ فلٹر پروجیکٹ میں ایک نیا پیکج شامل کرتے ہیں، تو ایجنٹ ٹریننگ ڈیٹا سے جان لے گا کہ پیکج موجود ہے، لیکن ہو سکتا ہے موجودہ API، ترجیحی استعمال کے نمونوں، یا عام غلطیوں کو نہیں جانتا ہو۔ یہ ایجنٹوں کو طریقہ کار کے ناموں کو غلط طریقے سے پیش کرنے، فرسودہ APIs کا استعمال کرنے، یا پیکیج کے مصنف کی طرف سے بنائے گئے محاوراتی استعمال کے نمونوں کو یاد کرنے کا سبب بن سکتا ہے۔

پیکیج کی سطح کی ٹیکنالوجی کے ساتھ، ایجنٹوں کو براہ راست اس شخص سے قابل اعتماد استعمال کی ہدایات موصول ہوتی ہیں جس نے پیکیج لکھا تھا۔ جب go_router ترسیل skills/go-router-navigation.md فائلیں، تمام فلٹر ٹیمیں چل رہی ہیں۔ skills get GoRouter کو شامل کرنے کے بعد، آپ کو GoRouter ٹیم سے مہارتیں حاصل ہوں گی تاکہ آپ اپنے ایجنٹوں کو بالکل سکھائیں کہ GoRouter کیسے کام کرتا ہے۔

آپ کے اپنے پیکجوں کے لیے لکھنے کی تکنیک

اگر آپ اندرونی ڈارٹ یا فلٹر پیکج کو برقرار رکھتے ہیں جسے آپ کی ٹیم استعمال کرتی ہے، تو ان کے ذریعے مہارت فراہم کرنا ایک اعلیٰ قیمتی سرمایہ کاری ہے۔

my_design_system/
  lib/
    src/
      components/
    my_design_system.dart
  skills/
    my-design-system-components.md    <- teaches agents how to use your components
    my-design-system-theming.md       <- teaches agents your theming system
  pubspec.yaml
  README.md

---
name: my-design-system-components
description: Use the MyDesignSystem component library for UI elements. Use when creating
any UI elements including buttons, cards, form fields, navigation elements, or any visual
component. Apply instead of raw Material or Cupertino widgets wherever a design system
component exists.
---

# MyDesignSystem Component Usage

Always use MyDesignSystem components instead of raw Flutter widgets where equivalents exist.

## Available Components

DsButton replaces ElevatedButton, TextButton, and OutlinedButton.
DsCard replaces Card.
DsTextField replaces TextFormField.
DsAvatar replaces CircleAvatar.
DsChip replaces Chip.
DsBottomSheet replaces showModalBottomSheet.

## DsButton Usage

نہ کریں: ElevatedButton( onPressed: _onSubmit, child: const Text('Submit'), ).

درج ذیل کام کریں: DsButton( label: 'Submit', onPressed: _onSubmit, variant: DsButtonVariant.primary, ).

`DsButton.variant` accepts `primary`, `secondary`, `destructive`, and `ghost`. When loading, pass `isLoading: true` to show the button's built-in loading state.

جب ٹیم کے ڈویلپرز چلتے ہیں۔ skills getیہ ٹیکنالوجی کسی بھی سرکاری فلٹر یا ڈارٹ ٹیکنالوجی کے ساتھ خود بخود انسٹال ہو جاتی ہے، جس سے ایجنٹوں کو اندرونی اجزاء کی لائبریریوں کا مکمل علم حاصل ہوتا ہے۔

ٹیکنالوجی بمقابلہ قواعد بمقابلہ MCP: فرق جانیں۔

ایجنٹ ٹیکنالوجی دو دیگر ایجنٹ حسب ضرورت میکانزم کے ساتھ موجود ہے: AI رول فائلز اور MCP سرورز۔ ہر ایک کے منفرد کردار کو سمجھنے سے آپ کو اپنے علم کو صحیح جگہ پر رکھنے میں مدد ملے گی۔

تین حسب ضرورت میکانزم

1. AI قواعد (ہمیشہ سیاق و سباق میں، پروجیکٹ کے وسیع حقائق)۔

CLAUDE.md, AGENTS.mdاور .cursorrules اس میں ہمیشہ اس منصوبے کے بارے میں حقائق شامل ہونے چاہئیں جو سچ ہیں۔ یہ فائلیں ہر کام اور ہر سیشن کے لیے لوڈ ہوتی ہیں۔

یہ معلومات کے لیے بہترین موزوں ہے جیسے کہ پروجیکٹ کا نام اور پیکیج شناخت کنندہ، فلٹر اور ڈارٹ SDK ورژن، اور بنیادی پیکجز جیسے: flutter_bloc اور go_routerکم از کم پلیٹ فارم ورژن، جیسے Android API 24 اور iOS 15، اور پروجیکٹ فن تعمیر کا انداز، جیسے کہ فیچر فرسٹ یا کلین آرکیٹیکچر۔ تفصیلی ہدایات تکنیکی ہیں اور انہیں یہاں نہیں رکھا جانا چاہیے۔

2. ہنر (.agents/skills/*.mdآہستہ آہستہ لوڈ کیا گیا)۔

مہارتوں میں مخصوص قسم کے کاموں کو انجام دینے کے بارے میں ہدایات شامل ہونی چاہئیں۔ اسے صرف اس صورت میں لوڈ کیا جائے گا جب ایجنٹ کو پتہ چل جائے کہ یہ موجودہ کام سے متعلق ہے۔

یہ رہنمائی کے لیے بہترین موزوں ہے جیسے فلٹر فائلز کو کیسے ڈھانچہ بنایا جائے، BLoC اسٹیٹ مینجمنٹ کو کیسے لاگو کیا جائے، ٹیسٹ کیسے لکھیں، غلطیوں کو کیسے ہینڈل کیا جائے، اور کام کے لیے مخصوص پیٹرن جو ہمیشہ متعلقہ نہیں ہوتے ہیں۔ پراجیکٹ کے وسیع حقائق پراجیکٹ کے قواعد سے تعلق رکھتے ہیں اور انہیں تفصیل میں نہیں رکھا جانا چاہیے۔

3. MCP سرور (آلات کا استعمال کرتے ہوئے ایجنٹ کی فعالیت کو بڑھاتا ہے)۔

MCP سرور کو ایجنٹ کے لیے مخصوص MCP کنفیگریشن کے ذریعے ترتیب دیا جاتا ہے اور اسے ٹولز اور بیرونی ڈیٹا تک رسائی فراہم کر کے ایجنٹ کی فعالیت کو بڑھانے کے لیے استعمال کیا جاتا ہے۔ ٹول پورے سیشن میں دستیاب رہے گا۔

یہ ڈارٹ ایم سی پی سرور کے ذریعے فلٹر دستاویزات کی بازیافت، ڈارٹ ایم سی پی سرور سے پیکیج کی معلومات کی بازیافت، اور مزید کاموں کے لیے بہترین ہے۔ pub.devاپنے پروجیکٹ میں فلٹر کمانڈز چلائیں، منسلک آلات سے لاگز پڑھیں، اور ریپوزٹریز میں کوڈ تلاش کریں۔ رہنما خطوط، قواعد، اور پراجیکٹ کے لیے مخصوص اصول قواعد اور تکنیک سے تعلق رکھتے ہیں اور انہیں MCP سرور پر نہیں رکھا جانا چاہیے۔

ایک مفید ہوورسٹک: اگر معلومات README میں ہے، تو شاید اس کا تعلق قواعد کی فائل یا ٹیکنالوجی میں ہے۔ اگر معلومات کے لیے نیٹ ورک کال یا پروگرام کے عمل کی ضرورت ہے، تو وہ معلومات MCP سرور سے تعلق رکھتی ہے۔ اگر معلومات کا تعلق صرف ایک خاص قسم کے کام سے ہے، تو اس کا تعلق قواعد کی فائل کے بجائے ٹیکنالوجی میں ہے۔

ایک اور ہوورسٹک: سیاق و سباق کا بجٹ۔ قواعد کی فائلیں ہمیشہ سیاق و سباق میں ہوتی ہیں، اس لیے تمام کارروائیاں، قطع نظر اس سے قطع نظر کہ سیاق و سباق کے بجٹ کو استعمال کرتی ہیں۔ اپنے قواعد کی فائلوں کو مختصر رکھیں (50 لائنوں سے کم) اور حقیقت پر مبنی۔ ہنر صرف متعلقہ ہونے پر لوڈ کیے جاتے ہیں، اس طرح سیاق و سباق کی لاگت کو کم کیا جاتا ہے۔ ٹول کالز پر مبنی MCP سرورز کا اپنا لاگت کا ماڈل ہے۔

ٹیموں کے اندر مہارتوں کی تنظیم

مشترکہ ٹیم کے علم کے طور پر ہنر

کہ .agents/skills/ ڈائرکٹری کو گٹ ریپوزٹری سے وابستہ ہونا ضروری ہے۔ جب آپ کسی مہارت کا ارتکاب کرتے ہیں، تو آپ کی ٹیم کے ہر ڈویلپر کو اگلی بار وہ مہارت حاصل ہوتی ہے۔ git pull. جب کوئی نیا ڈویلپر شامل ہوتا ہے، تو وہ ذخیرہ کو کلون کرتے ہیں اور فوری طور پر جمع شدہ تکنیکی علم حاصل کرتے ہیں جو ٹیم نے بنایا ہے۔ جب کوئی پروڈکشن کے واقعے سے مہارتیں لکھتا ہے، تو وہ اسباق اس کوڈ کے ساتھ ذخیرہ میں محفوظ کیے جاتے ہیں جس کی وہ حفاظت کرتی ہے۔

یہ ٹیکنالوجی کو ایک زندہ ادارہ جاتی علمی نظام بناتا ہے۔ تکنیکی فائل بیک وقت AI ایجنٹوں کے لیے ایک رہنما اور خود معیاری دستاویز ہے۔ وکی پیجز یا کنفلوئنس آرٹیکلز کے برعکس، ٹیکنالوجیز کو ایسے ٹولز کے ذریعے پڑھا جاتا ہے جو اصل میں کوڈ تیار کرتے ہیں، نہ صرف ان ڈویلپرز کے ذریعے جو ان کو لاگو کرنا یاد رکھ سکتے ہیں یا نہیں کرسکتے۔

تکنیکی جائزہ لینے کا عمل

تکنیکی فائل کی تبدیلیوں کو کوڈ کی تبدیلیوں کے طور پر اسی پل کی درخواست پر نظرثانی کے عمل سے گزرنا چاہیے۔ وہ مہارتیں جو قواعد کو غلط طریقے سے انکوڈ کرتی ہیں یا بہت مبہم طور پر قواعد کا اظہار کرتی ہیں وہ پوری ٹیم کے ایجنٹ کے استعمال میں اس وقت تک غلط آؤٹ پٹ پیدا کر سکتی ہیں جب تک کہ ان کو درست نہیں کیا جاتا۔

تکنیکی تبدیلیوں کو ضم کرنے سے پہلے چیک کرنے کے لیے یہاں ایک تکنیکی جائزہ چیک لسٹ ہے:

• تفصیل ان صورتوں کو درست اور مکمل طور پر بیان کرتی ہے جن میں اس تکنیک کا اطلاق ہوتا ہے۔

• تمام اصول مخصوص ہیں اور مبہم رہنما خطوط نہیں جو ایک مشیر کے رویے کو تبدیل کر سکتے ہیں۔

• تربیتی ڈیٹا میں مشترکہ نمونوں کے لیے جوابی مثالیں فراہم کی جاتی ہیں۔

• کوڈ کی مثالیں آزادانہ اور صحیح طریقے سے مرتب کرتی ہیں۔

• یہ مہارت دیگر مہارتوں سے مواد کی نقل نہیں کرتی ہے۔

• ایجنٹ کو متعلقہ کام انجام دینے کے لیے کہہ کر اور اس بات کی تصدیق کر کے مہارت کی جانچ کی گئی کہ آؤٹ پٹ نے مہارت کے اصولوں پر عمل کیا۔

• ٹیکنالوجی کا جائزہ ٹیم کے کم از کم ایک دوسرے رکن نے لیا ہے جو اسے اپنے روزمرہ کے کام میں استعمال کریں گے۔

اپنی ٹیکنالوجی کو اپ ٹو ڈیٹ رکھیں

جب کسی ٹیم کے اصول بدلتے ہیں تو ٹیکنالوجی پرانی ہو جاتی ہے۔ چاہے آپ ایک نیویگیشن لائبریری سے دوسری میں منتقل ہو رہے ہوں، ایک نیا ٹیسٹنگ فریم ورک اپنا رہے ہوں، اپنے ڈیزائن کے نظام کو اپ ڈیٹ کر رہے ہوں، یا اپنی غلطی سے نمٹنے کے طریقہ کار کو ری فیکٹر کر رہے ہوں۔ پرانی ٹیکنالوجی کسی ٹیکنالوجی سے بدتر ہے کیونکہ یہ ایجنٹوں کو فعال طور پر فرسودہ نمونوں میں لے جاتی ہے۔

انحصار اپ گریڈ کو تکنیکی جائزے کے محرکات کے طور پر سمجھیں۔ اپ گریڈ کرتے وقت go_router اگر آپ نئے بڑے ورژن پر جا رہے ہیں، تو اپنی نیویگیشن تکنیک کا جائزہ لیں تاکہ یہ یقینی بنایا جا سکے کہ وہ موجودہ API کی عکاسی کرتی ہیں۔ اگر آپ اپنی ٹیم کے سابقہ ​​انداز میں ایک نیا نمونہ اپناتے ہیں، تو اسی PR میں متعلقہ تکنیکوں کو اپ ڈیٹ کریں۔

ٹیم کے اندر مہارت کی دریافت کا امکان

جیسے جیسے ٹیکنالوجی لائبریری بڑھتی ہے، ڈویلپرز کو اپنے کام کے لیے صحیح ٹیکنالوجی تلاش کرنے کے قابل ہونے کی ضرورت ہوتی ہے۔ مسلسل نام دینے کے کنونشنز کو استعمال کرنے اور ایک سادہ تکنیکی اشاریہ کو برقرار رکھنے پر غور کریں۔

# .agents/skills/README.md (not a skill, just an index)

## Flutter Skills
flutter-feature-architecture      -- Feature folder structure and layer rules
flutter-bloc-state-management     -- Bloc events, states, and widget integration
flutter-file-organization         -- File splitting, extraction, and naming
flutter-error-handling            -- Typed failures and Either return types
flutter-navigation                -- GoRouter routes, navigation methods, deep links
flutter-theming                   -- Design tokens, color extensions, spacing constants
flutter-testing                   -- Widget tests, Bloc tests, and test naming
flutter-accessibility             -- Semantic labels, focus, and touch targets
flutter-performance               -- Const widgets, selective rebuilds, list optimization

## Dart Skills
dart-models-freezed               -- Freezed models, json_serializable, DTOs
dart-testing-conventions          -- package:test conventions, mocktail, async testing
dart-pattern-matching-idiomatic   -- Switch expressions, sealed classes, destructuring
dart-run-static-analysis          -- analysis_options.yaml, dart analyze, dart fix

یہ انڈیکس ایجنٹ کے ذریعہ پڑھنے کے قابل نہیں ہے۔ README.md(مہارت کی فائلیں نہیں)۔ ڈویلپرز کے لیے جو کسی پروجیکٹ میں نئے ہیں اور یہ جاننا چاہتے ہیں کہ ایجنٹ سے کام کرنے کو کہنے سے پہلے کون سی مہارتیں دستیاب ہیں۔

لکھنے کی مہارت کے لیے بہترین طریقے

حقیقی غلطیوں سے شروع کریں، مثالی نمونوں سے نہیں۔

سب سے مؤثر تکنیک ایک مخصوص اور دوبارہ پیدا کرنے کے قابل طریقے سے ناقص AI سے تیار کردہ کوڈ کا مشاہدہ کرنے سے آتی ہے۔ غلطیاں اس بات کا ثبوت ہیں کہ ایجنٹ کے پہلے سے طے شدہ رویے کو پروجیکٹ میں ترمیم کی ضرورت ہے۔ جب بھی آپ AI آؤٹ پٹ کو دستی طور پر ترمیم کرتے ہیں، وہ ترمیم ایک مہارت کا اصول ہے۔

مثالی پیٹرن کی تکنیک ("نظریہ میں، بلاک اس طرح کام کرتا ہے") غلطی کی اصلاح کی تکنیکوں سے کم موثر ہیں ("ایجنٹ ہمیشہ X پیدا کرتا ہے، لیکن ہمیں Y کی ضرورت ہے، لہذا اصول Z ہے")۔ غلطیاں آپ کو بتاتی ہیں کہ آپ کا تربیتی ڈیٹا اصولوں سے کہاں انحراف کرتا ہے۔ قواعد اس کو ٹھیک کرتے ہیں۔

ارتکاب کرنے سے پہلے اپنی صلاحیتوں کی جانچ کریں۔

ایک مہارت پیدا کرنے کے بعد، ایجنٹوں کو ہنر کے تحت کام کرنے کے لیے کہہ کر اس کی جانچ کریں۔ اپنے ایجنٹوں سے بلاک اسٹیٹ مینجمنٹ کے ساتھ نئی اسکرینیں بنانے، بڑی فائلوں کو تقسیم کرنے، یا اپنے ریپوزٹری کے لیے یونٹ ٹیسٹ لکھنے کو کہیں۔ پھر یقینی بنائیں کہ آؤٹ پٹ تکنیک کے تمام اصولوں کی پیروی کرتا ہے۔

جن قوانین کی پیروی نہیں کی جاتی ہے ان کو جوابی مثالیں فراہم کر کے مزید واضح کیا جانا چاہیے، یا مزید مخصوص وضاحت کے ساتھ جوڑا جانا چاہیے جس سے ایجنٹ کو یہ پہچاننے میں مدد ملے کہ کب کوئی مہارت لوڈ کرنی ہے۔

ایک مہارت فی خاصیت

ہر چیز کا احاطہ کرنے والی ایک بڑی تفصیل لکھنے کے لالچ سے بچیں۔ ڈومین کے لیے مخصوص مہارتیں (فائل آرگنائزیشن، اسٹیٹ مینجمنٹ، ٹیسٹنگ، تھیمنگ، نیویگیشن، ایرر ہینڈلنگ) کو برقرار رکھنا آسان ہے، آہستہ آہستہ لوڈ کیا جاتا ہے (لہذا ہر مہارت صرف متعلقہ ہونے پر سیاق و سباق میں ہوتی ہے) اور دوسری ٹیموں کے ساتھ اشتراک کرنا یا کمیونٹی وسائل کے طور پر شائع کرنا آسان ہوتا ہے۔

محرک الفاظ کی کثرت کے ساتھ وضاحتیں لکھیں۔

وضاحتیں مہارت کا واحد حصہ ہیں جو ہمیشہ پڑھتی ہیں۔ اپنی مہارت کو مخصوص محرک الفاظ اور فقروں کے ساتھ ترتیب دیں جو ان کی مطابقت کی نشاندہی کرتے ہیں۔

# Trigger-poor description
description: How to set up navigation in Flutter.

# Trigger-rich description
description: Implement navigation using GoRouter in Flutter apps. Use when adding routes,
navigating between screens, setting up deep links, handling authentication redirects,
configuring nested navigation, working with ShellRoutes, or any task involving
Navigator, route, path, deep link, URL, back button, or go_router package.

ٹرگر سے بھرپور تفصیل جاب کی تفصیل کی بہت وسیع رینج سے ملتی ہے، اس بات کو یقینی بناتی ہے کہ متعلقہ ہونے پر مہارتیں بھری ہوئی ہوں اور ساتھ ہی ساتھ ایک درست نحوی مماثلت بھی۔

تفصیل لکھتے وقت عام غلطیاں

رویے کو تبدیل کرنے کے لیے قوانین بہت مبہم ہیں۔

# These change nothing: the agent was already trying to do these
- Write clean, maintainable code.
- Follow Flutter best practices.
- Use the appropriate state management solution.
- Organize files logically.

# These change specific behavior: the agent was doing something different
- Place every extracted widget class in the widgets/ subdirectory of its feature folder.
- Name BlocEvent subclasses as past-tense verb phrases: ProfileLoadRequested, not LoadProfile.
- Never use Navigator.push; use context.go() or context.push() from GoRouter.
- Mark every widget constructor parameter with required unless it has a default value.

مبہم اصول خواہشات کو بیان کرتے ہیں۔ مخصوص اصول مخصوص، قابل تصدیق رویے کی وضاحت کرتے ہیں۔ مہارت کے ہر قاعدے کو اس سوال کا جواب دینا چاہیے: "اس اصول کو پڑھنے کے بعد ایجنٹ پہلے سے مختلف طریقے سے کیا کرے گا؟"

اعلی تعدد کے غلط نمونوں کی جوابی مثالیں غائب ہیں۔

تربیتی ڈیٹا میں کچھ غلط نمونے لاکھوں بار ظاہر ہوتے ہیں۔ سیکھا ایجنٹ _buildHeaderSection() اس کی وجہ یہ ہے کہ پھڑپھڑانے کے درست نمونوں کی ہزاروں مثالوں کو صرف ٹیکسٹ رولز سے ترک نہیں کیا جا سکتا۔

بالکل وہی کوڈ دکھائیں جو ایجنٹ تیار کرے گا اور اس کا آپ کے مطلوبہ کوڈ سے موازنہ کریں۔ یہ مؤثر ہے کیونکہ ایجنٹ مخصوص کوڈ پیٹرن کو پہچانتا ہے اور متن کی سطح کے بجائے کوڈ کی سطح پر قواعد کی بات چیت کے لیے اس کے برعکس استعمال کرتا ہے۔

تفصیل صحیح کام پر نہیں چل رہی ہے۔

اگر آپ "براہ کرم ادائیگی کی سکرین پر لوڈنگ اسٹیٹ شامل کریں" کی درخواست کرتے ہیں تو "ریاست کے انتظام کو نافذ کریں" کی وضاحت کے ساتھ بلاک اسٹیٹ مینجمنٹ سے متعلق مہارتیں لوڈ نہیں ہوں گی۔ تفصیل میں "لوڈ اسٹیٹس" کو محرک جملے کے طور پر شامل کرنا چاہیے۔

مختلف طریقوں کے بارے میں سوچ کر اپنی تفصیل کی جانچ کریں کہ کوئی شخص کسی ایسے کام کی وضاحت کرے گا جس کے لیے اس مہارت کی ضرورت ہے، اور یقینی بنائیں کہ آپ کی تفصیل میں ان تمام طریقوں کے لیے محرک جملے شامل ہیں۔

ورژن کنٹرول کے لیے پرعزم نہیں۔

کسی ایک ڈویلپر کے کمپیوٹر پر چھوڑی گئی مہارتیں ذاتی نوٹس ہیں، ٹیم کا علم نہیں۔ سرشار مہارتیں ادارہ جاتی علم ہے جو نئے ملازمین کو پہلے دن سے حاصل ہوتا ہے، جس سے پوری ٹیم کے ایجنٹ استعمال کنندگان بغیر کسی سیٹ اپ کے فائدہ اٹھاتے ہیں، اور اس کا جائزہ لیا جا سکتا ہے، بہتر کیا جا سکتا ہے اور کوڈ کی طرح برقرار رکھا جا سکتا ہے۔ ہمیشہ عزم .agents/skills/ خوش ہو جاؤ

لکھنے کی تکنیک جو بہت زیادہ نسخہ جاتی ہیں۔

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

ٹکنالوجی کو ساختی اور تعمیراتی نمونوں پر قبضہ کرنا چاہئے جو رہنمائی کے بغیر عملی طور پر متضاد ہوں گے۔ ایک ٹیکنالوجی کو نفاذ کی تفصیل نہیں ہونی چاہیے جس میں بہت سے یکساں طور پر درست انتخاب ہوں۔

نتیجہ

Flutter میں ایجنٹ کی ترقی کی طرف منتقلی ڈویلپرز کو تبدیل کرنے کے بارے میں نہیں ہے۔ یہ ڈویلپرز جو کچھ کر سکتے ہیں اسے ضرب دینے کے بارے میں ہے۔

ایک طاقتور ہنر مند AI ایجنٹ منٹوں میں ایک مکمل، فن تعمیر سے متعلق خصوصیت کے نفاذ کا مسودہ تیار کر سکتا ہے جو آپ کی ٹیم کے قطعی اصولوں کی پیروی کرتا ہے۔ ایک سینئر ڈویلپر اس کا جائزہ لیتا ہے، ایڈجسٹمنٹ کرتا ہے اور اسے جاری کرتا ہے۔ ہنر ایک ایجنٹ کے عمومی علم اور ٹیم کے مخصوص معیارات کے درمیان فرق کو ختم کرنے کے بارے میں ہے۔

جو چیز ٹیکنالوجی کو حقیقی معنوں میں طاقتور بناتی ہے وہ یہ ہے کہ ماڈل AI ڈویلپمنٹ ورک فلو کا واحد حصہ ہے جس میں غیر تربیت یافتہ علم ہوتا ہے۔ ماڈل کو پبلک فلٹر اور ڈارٹ کوڈ کی لاکھوں لائنوں سے تربیت دی گئی تھی۔ لیکن میں نے آپ کا کوڈ بیس کبھی نہیں دیکھا۔ آپ کے پروجیکٹ میں کبھی کوئی غلطی نہیں ہوئی اور نہ ہی اسے ٹھیک کیا گیا ہے۔ میں نے کبھی بھی ٹیم کے فن تعمیر کے مباحثوں یا پسپائیوں میں شرکت نہیں کی۔ آپ کو یہ احساس نہیں ہے کہ ایک ٹیم نے ایک پیٹرن کو آزمایا، محسوس کیا کہ یہ تکلیف دہ تھا، اور جان بوجھ کر ایک مختلف پیٹرن کا انتخاب کیا۔ آپ کی مہارت وہ برتن ہے جو تمام علم رکھتا ہے۔

آفیشل فلٹر ٹیکنالوجیز github.com/flutter/agent-plugins اور سرکاری ڈارٹ اسکل ہے۔ github.com/dart-lang/skills یہ ایک پیداواری معیار کا نقطہ آغاز فراہم کرتا ہے جس میں سب سے زیادہ عام فلٹر اور ڈارٹ ڈیولپمنٹ پیٹرن شامل ہیں۔ کہ skills CLI ٹول انسٹالیشن کو اتنا ہی آسان بناتا ہے جتنا کہ ایک این پی ایم کمانڈ۔ پیکیج کی سطح کی وضاحت کے نظام کا مطلب یہ ہے کہ انحصار اپنے استعمال کی ہدایات فراہم کرتا ہے اور پیکج کے تیار ہونے کے ساتھ ہی اسے اپ ڈیٹ کیا جا سکتا ہے۔

لیکن وہ تکنیکیں جو آپ خود لکھتے ہیں، آپ کے اپنے پروڈکشن ایونٹس، کوڈ ریویو فیڈ بیک، اور تعمیراتی فیصلوں کی بنیاد پر، سب سے زیادہ اثر ڈالے گی۔ یہ ایسے علم کو خفیہ کرتا ہے جو ناقابل تلافی ہے کیونکہ یہ عوامی ذخیروں میں نہیں پایا جا سکتا۔

"StatefulWidget کو کبھی بھی ریاستی طبقے سے الگ نہ کریں" جیسے اصول Flutter کے کمپائلیشن ماڈل کو اس سطح پر سمجھنے سے آتے ہیں جس کا زیادہ تر تربیتی ڈیٹا بیان نہیں کرتا ہے۔ "تمام بلاک ایونٹس اور ریاستوں کے لیے حتمی کنکریٹ کلاس کے ساتھ مہر بند کلاس درجہ بندی کا استعمال کریں" جیسے اصول Dart 3 کے ٹائپ سسٹم اور مکمل تبدیلی کے حقیقی دنیا کے فوائد دونوں کو سمجھنے سے آتے ہیں۔ "انتظار کے بعد BuildContext کو استعمال کرنے سے پہلے ماؤنٹڈ کے لیے چیک کریں" جیسے قواعد اس اصول کی خلاف ورزی کے وقت پروڈکشن میں ہونے والے کچھ کریشوں کی جانچ کرنے سے آتے ہیں۔

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

حوالہ جات

پھڑپھڑاہٹ اور ڈارٹ میں ایجنٹ ٹیکنالوجی (فلٹر دستاویزات): ایجنٹ ٹیکنالوجی کے لیے ایک جامع گائیڈ، بشمول پروگریسو ریلیز ماڈل، آفیشل ریپوزٹریز، اور یونیورسل انسٹالیشن کمانڈز۔ https://docs.flutter.dev/ai/agent-skills

Flutter میں AI کے ساتھ شروع کرنا (Flutter دستاویزات): کلاڈ کوڈ، اینٹی گریویٹی، کوڈیکس، کرسر، اور دیگر ایجنٹوں کے لیے مرحلہ وار سیٹ اپ گائیڈز، بشمول ہر ٹول کے لیے آفیشل فلٹر پلگ ان انسٹالیشن ہدایات۔ https://docs.flutter.dev/ai/get-started

فلٹر ایجنٹ پلگ ان ریپوزٹری (GitHub): Flutter ایجنٹ ٹیکنالوجیز کا آفیشل ریپوزٹری جو Flutter ٹیم کے زیر انتظام ہے جس میں ریسپانسیو لے آؤٹ، GoRouter نیویگیشن، JSON سیریلائزیشن، ویجیٹ ٹیسٹنگ، انٹیگریشن ٹیسٹنگ، BLoC پیٹرنز اور بہت کچھ شامل ہے۔ https://github.com/flutter/agent-plugins

ڈارٹ ٹیکنالوجی کا ذخیرہ (GitHub): ڈارٹ ایجنٹ ٹیکنالوجی کا باضابطہ ذخیرہ جو ڈارٹ ٹیم کے زیر انتظام ہے، جس میں یونٹ ٹیسٹنگ، جامد تجزیہ، پیکیجنگ ٹولز، پیٹرن میچنگ، CLI ایپس، مقامی اثاثے اور بہت کچھ شامل ہے۔ https://github.com/dart-lang/skills

فلٹر اے آئی رولز دستاویزات (فلٹر دستاویزات): دستاویزی اور تکنیکی ضمیمہ پراجیکٹ وسیع AI قوانین کی فائلوں کے لیے (CLAUDE.md، AGENTS.md، .cursorrules)۔ https://docs.flutter.dev/ai/ai-rules

ایجنٹ تکنیکی وضاحتیں: ایک تصریح سائٹ جو عالمگیر SKILL.md فارمیٹ، ڈائرکٹری کے قواعد، اور ایجنٹ کی مطابقت کے تقاضوں کی وضاحت کرتی ہے۔ تکنیکی معیارات پر معلومات کا ذریعہ۔ https://agentskills.io

ٹیک ڈارٹ پیکیج (pub.dev): پراجیکٹ کے انحصار سے ایجنٹ ٹیکنالوجیز کو انسٹال کرنے کے لیے ڈارٹ CLI ٹول۔ پیکیج کے مصنفین خودکار تنصیب کو فعال کرنے کے لیے اپنے پیکجز اور ٹیموں کے ساتھ ٹیکنالوجی فراہم کرتے ہیں۔ https://pub.dev/packages/skills

تکنیکی CLI (npm): npm ایک GitHub ریپوزٹری سے ایجنٹ ٹیکنالوجی کو انسٹال کرنے کے لیے CLI تعینات کرتا ہے۔ معیار میں استعمال کیا جاتا ہے npx skills add flutter/agent-plugins کمانڈ انسٹال کریں۔ https://www.npmjs.com/package/skills

ٹیکنیکل رجسٹری سرور پاٹ: مقبول ڈارٹ اور فلٹر پیکجز کے لیے ایجنٹ ٹیکنالوجیز کا مجموعہ جو ابھی تک اپنی ٹیکنالوجی فراہم نہیں کرتے ہیں، بشمول Riverpod، flutter-shadcn-ui، اور دیگر۔ Serverpod ٹیم کی طرف سے برقرار رکھا. https://github.com/serverpod/skills-registry

dhruvanbhalara/Skills Premium Flutter تکنیکی دستاویزات: یہ ایک وسیع دستاویزی پروجیکٹ ہے جو دستیاب فلٹر ایجنٹ ٹیکنالوجیز کی مکمل فہرست کا احاطہ کرتا ہے، جس میں ہر ٹیکنالوجی کا احاطہ کیا جاتا ہے اور کیا سکھایا جاتا ہے اس کی تفصیلی وضاحت ہوتی ہے۔ https://github.com/dhruvanbhalara/skills