Abide کے ذریعے ہر ترمیم پر کوڈنگ ایجنٹ کے اصول نافذ کریں

Abide کیا کرتا ہے

Abide ان منصوبہ مخصوص ہدایات کو نافذ کرتا ہے جن کا عام linters قابلِ اعتماد طریقے سے جائزہ نہیں لے سکتے۔ یہ ہدایات AGENTS.md یا CLAUDE.md جیسی فائلوں میں موجود ہو سکتی ہیں اور ان میں ایسی پابندیاں شامل ہو سکتی ہیں جیسے manual validation کے بجائے Yup استعمال کریں، صرف ایک caller والا helper نہ بنائیں، یا کسی صارف کو کبھی بھی خام error نہ دکھائیں۔

ہر edit یا مکمل ہونے والی turn کے بعد Abide متعلقہ rule اور code diff کو TypeSafe کے Jev decision model کو بھیجتا ہے۔ Jev آزاد نثر کے بجائے ایک probability واپس کرتا ہے۔ اگر probability کسی خلاف ورزی کی نشاندہی کرے تو Abide coding agent کو بتاتا ہے کہ کون سا rule توڑا گیا ہے اور اسی turn کے دوران code درست کرنے کو کہتا ہے۔

Jev کو rule اور diff نظر آتے ہیں، agent کی گفتگو نہیں۔ اس طرح Abide طویل coding session کے دوران یکساں checks لاگو کر سکتا ہے۔ repository کے شائع شدہ replay benchmark کے مطابق، Jev میں checks تقریباً 300 milliseconds لیتے ہیں، جبکہ Node startup شامل ہونے پر مکمل hook تقریباً ایک second لیتا ہے۔

اہم خصوصیات

• خودکار edit checks: Rules ہر code edit کے فوراً بعد چل سکتے ہیں۔
• Turn-level checks: وہ rules جنہیں مکمل task diff درکار ہو، turn کے اختتام پر ایک بار چل سکتے ہیں۔
• Agent integration: Abide، Claude Code، Codex، اور OpenCode کو support کرتا ہے۔
• Repository-owned rubric: مرتب شدہ rules قابلِ مطالعہ اور commit-friendly .abide/rubric.json فائل میں محفوظ ہوتے ہیں۔
• Scoped rules: ایک rule glob scopes استعمال کر سکتا ہے تاکہ API routes، stylesheets، یا دیگر file groups کے لیے مختلف سوالات لاگو ہوں۔
• Existing-code audits: Abide فائلوں کا فیصلہ ایسے کر سکتا ہے جیسے وہ ابھی لکھی گئی ہوں۔
• Calibration and tuning: یہ حالیہ Git history کے خلاف rules کو test، غیر مؤثر rules کو disable، اور کبھی فعال نہ ہونے والے rules کو دوبارہ لکھنے میں مدد کر سکتا ہے۔
• Fail-open hooks: Missing credentials، network failures، یا hook errors coding session کو نہیں روکتے۔
• No built-in policy: Abide پہلے سے متعین ruleset مسلط کرنے کے بجائے آپ کی اپنی instruction files سے اخذ کردہ rules نافذ کرتا ہے۔

ضروریات

آپ کو اپنے coding agent کے لیے instructions والی repository اور کم از کم ایک supported agent: Claude Code، Codex، یا OpenCode درکار ہے۔ آپ کو typesafe.ai سے TypeSafe API key بھی درکار ہے۔ متبادل طور پر، Abide موجودہ Vercel AI Gateway key کو AI_GATEWAY_API_KEY environment variable کے ذریعے استعمال کر سکتا ہے۔

Abide انسٹال اور configure کریں

Step 1: اپنی API key محفوظ کریں

login command چلائیں اور اشارہ ملنے پر اپنی TypeSafe key paste کریں:

npx @coldtea/abide login

Abide key کو ~/.abide/.env میں صرف مالک کی رسائی کے ساتھ محفوظ کرتا ہے۔ آپ credentials کو repository root میں موجود .env.local یا .env میں بھی رکھ سکتے ہیں۔ Credential lookup پہلے environment، پھر repository files، اور آخر میں ~/.abide/.env کو check کرتا ہے۔

اگر آپ Vercel AI Gateway استعمال کرتے ہیں تو TypeSafe key کے بجائے AI_GATEWAY_API_KEY set کریں۔ Credentials command-line flags کے ذریعے قبول نہیں کیے جاتے اور log بھی نہیں ہوتے۔

Step 2: Agent hooks انسٹال کریں

اپنی repository سے Abide کو initialize کریں:

npx @coldtea/abide init

Agent name نہ دینے پر init ہر اس supported agent میں انسٹال ہو جاتا ہے جسے وہ تلاش کرے۔ آپ کسی ایک integration کو واضح طور پر بھی target کر سکتے ہیں:

npx @coldtea/abide init claude
npx @coldtea/abide init codex
npx @coldtea/abide init opencode

• Claude Code: Integration کو ~/.claude/settings.json میں شامل کیا جاتا ہے۔
• Codex: Integration کو ~/.codex/hooks.json میں شامل کیا جاتا ہے۔
• OpenCode: Plugin کو ~/.config/opencode/plugins/abide.js میں انسٹال کیا جاتا ہے۔

جب آپ repository-level installation چاہتے ہوں جسے teammates checkout کے ساتھ حاصل کر سکیں تو --project شامل کریں:

npx @coldtea/abide init claude --project

Codex کو ایک اضافی approval step درکار ہے۔ Codex شروع کریں، /hooks درج کریں، اور Abide کی چاروں hook entries قبول کریں۔ Codex ہر نئے hook کے لیے یہ approval ایک بار مانگتا ہے۔

Step 3: Repository rules مرتب کریں

اپنا coding agent معمول کے مطابق شروع کریں۔ پہلے session کے آغاز میں Abide چیک کرتا ہے کہ instruction files تبدیل ہوئی ہیں یا نہیں۔ اس کے بعد agent قابلِ اطلاق instructions کو .abide/rubric.json میں مرتب کرتا ہے اور جو کچھ ملا ہے اس کی رپورٹ دیتا ہے۔

آپ نیا session شروع کرنے سے پہلے بھی compile کر سکتے ہیں:

abide compile

اگر آپ چاہتے ہیں کہ repository کا قابلِ نفاذ rubric ٹیم کے لیے نمایاں اور قابلِ جائزہ ہو تو .abide/rubric.json کو commit کریں۔ ہر verdict اس فائل میں موجود ایک rule کی شناخت کرتا ہے اور اس source instruction کا اقتباس دیتا ہے جس سے وہ اخذ کیا گیا ہے۔

بنیادی استعمال

Abide سے agent edits خودکار طور پر check کروائیں

Initialize کرنے کے بعد معمول کے مطابق claude، codex، یا opencode شروع کریں۔ کسی الگ background service کی ضرورت نہیں۔ فرض کریں کہ ایک instruction کہتی ہے کہ API endpoints کو Yup استعمال کرنا چاہیے اور input کو manually validate نہیں کرنا چاہیے۔ اگر agent manual guard لکھتا ہے تو Abide اس طرح کا message واپس کر سکتا ہے:

Abide: یہ ترمیم اس ریپوزٹری کی ہدایات کے ایک اصول کی خلاف ورزی کرتی معلوم ہوتی ہے۔
- ~/.codex/AGENTS.md کی سطر 65 کا اصول "api-validation-uses-yup":
  "API اینڈ پوائنٹس لکھتے وقت ان پٹ کی توثیق دستی طور پر نہ لکھیں۔
  واضح توثیقی پیغامات کے ساتھ Yup استعمال کریں، اور API ہینڈلر میں جلد واپسی کریں"۔
  (0.86)
اب apps/web/src/pages/api/logout.ts کی خلاف ورزی درست کریں، پھر کام جاری رکھیں۔

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

غیر کمٹ شدہ تبدیلیاں دستی طور پر چیک کریں

موجودہ غیر کمٹ شدہ تبدیلیوں کا اسی طرح جائزہ لینے کے لیے check استعمال کریں جیسے ہُکس کرتے ہیں:

abide check

جب آپ چیک کو محدود کرنا چاہیں تو پاتھ بھی فراہم کر سکتے ہیں:

abide check apps/web/src/pages/api/

موجودہ کوڈ کا آڈٹ کریں

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

abide audit src/

آؤٹ پٹ میں اصول کے لحاظ سے خلاصہ اور فائل کے لحاظ سے منظم فہرست شامل ہوتی ہے۔ README کے مطابق، ایک حقیقی Next.js ایپلیکیشن میں 33 API روٹس کا آڈٹ تقریباً 12 سیکنڈ میں مکمل ہوا اور اس کی لاگت تقریباً ایک سینٹ تھی، اگرچہ اصل نتائج ریپوزٹری اور اصولوں کے لحاظ سے مختلف ہو سکتے ہیں۔

اصولوں کی سرگرمی کا جائزہ لیں

اپنے اصول، ان اصولوں کو جو نافذ ہوئے، اور ان اصولوں کو دیکھنے کے لیے جنہیں کبھی نافذ نہیں کیا گیا، رپورٹ کمانڈ چلائیں:

abide report

مشین کے ذریعے قابلِ مطالعہ آؤٹ پٹ کے لیے --json شامل کریں۔ JSON آؤٹ پٹ check، audit، bench، اور calibrate کے لیے بھی دستیاب ہے۔

اصولوں کے وقت اور فیصلوں کو سمجھیں

ہر مرتب کردہ اصول دو مراحل میں سے ایک میں چلتا ہے:

• ترمیم کا مرحلہ: کسی انفرادی ترمیم کے بعد چلتا ہے اور اس ہَنک کا جائزہ لیتا ہے۔
• ٹرن کا مرحلہ: ٹرن کے آغاز میں لیے گئے اسنیپ شاٹ کے مقابل مکمل ڈِف کا جائزہ لیتے ہوئے ٹرن کے اختتام پر ایک بار چلتا ہے۔

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

فیصلوں کو امکان کے درجات میں تقسیم کیا گیا ہے:

• 0.8 یا اس سے زیادہ: ایجنٹ کو خلاف ورزی درست کرنے کی ہدایت دی جاتی ہے۔
• 0.5 سے کم 0.8: ایک نوٹ دکھایا جاتا ہے، لیکن ایجنٹ کو مرمت کی ہدایت نہیں دی جاتی۔
• 0.5 سے کم: کچھ بھی دکھایا نہیں جاتا۔

اعلیٰ درجے کے ورک فلو

Git ہسٹری کے مقابل اصولوں کی کیلیبریشن کریں

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

abide calibrate

Abide اس عمل کے لیے بیس حالیہ ہَنکس استعمال کرتا ہے اور ایسے اصولوں کو بند کر سکتا ہے جو مؤثر کارکردگی نہیں دکھاتے۔ پوری ٹیم میں نئے مرتب کردہ روبِرک پر انحصار کرنے سے پہلے نتیجے کا جائزہ لیں۔

ان اصولوں کو بہتر بنائیں جو کبھی نافذ نہیں ہوتے

غیر مؤثر اصولوں کی شناخت کے بعد ایجنٹ سے انہیں دوبارہ لکھوانے کے لیے tune استعمال کریں:

abide tune

چونکہ ہر روبِرک اندراج اپنی ماخذ ہدایت کا حوالہ دیتا ہے، اس لیے مشکوک فیصلے کا سراغ اس عبارت تک لگایا جا سکتا ہے جس نے اسے پیدا کیا۔ بنیادی ہدایت کو بہتر بنانے سے عموماً متعلقہ چیک زیادہ واضح ہو جاتا ہے۔

ایجنٹ کے سابقہ سیشن دوبارہ چلائیں

معاونت یافتہ ایجنٹس میں سے کسی ایک کے سابقہ سیشنز کا جائزہ لینے کے لیے replay استعمال کریں:

abide replay claude
abide replay codex
abide replay opencode

اس سے آپ مستقبل کی خلاف ورزیوں کا انتظار کرنے کے بجائے پہلے سے مکمل ہو چکے کام کے مقابل روبِرک کا جائزہ لے سکتے ہیں۔

مقامی تاخیر اور خرچ کی پیمائش کریں

اپنی مشین پر کارکردگی اور لاگت کی پیمائش کے لیے بینچ مارک کمانڈ چلائیں:

abide bench

ریپوزٹری کے مطابق اس کے 13 اصولوں کو چیک کرنے میں تقریباً 1,000 سے 1,600 ان پٹ ٹوکنز استعمال ہوتے ہیں، فی چیک تقریباً $0.00004 سے $0.00007 لاگت آتی ہے، اور Jev میں تقریباً 300 ملی سیکنڈ لگتے ہیں۔ یہ اعداد و شمار براہِ راست TypeSafe کے مقابل ماپے گئے تھے اور مختلف ہو سکتے ہیں، اس لیے آپ کے سیٹ اپ کے لیے مقامی بینچ مارک زیادہ قابلِ اعتماد رہنما ہے۔

سوالات کو متعلقہ رکھنے کے لیے اسکوپس استعمال کریں

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

رازداری اور ناکامی کا رویہ

تبدیل شدہ سطریں ہر کال پر صفر ڈیٹا برقرار رکھنے کی درخواست کے ساتھ، آپ کی اپنی کلید کے تحت TypeSafe کو بھیجی جاتی ہیں۔ README کے مطابق، ڈیٹا Abide کے زیرِ انتظام کسی سرور کو نہیں بھیجا جاتا۔

Abide کے ہُکس اس طرح بنائے گئے ہیں کہ ایجنٹ کا سیشن نہ ٹوٹے۔ ہُک کے پاتھ کامیابی کے ساتھ خارج ہوتے ہیں، ایک سخت آخری وقت استعمال کرتے ہیں، اور صرف وہی چیز پرنٹ کرتے ہیں جس کی میزبان کو توقع ہوتی ہے۔ اگر کوئی کلید دستیاب نہ ہو یا نیٹ ورک دستیاب نہ ہو تو ترمیم بغیر چیک کے جاری رہتی ہے۔ رہ جانے والا چیک .abide/events.jsonl میں لکھا جاتا ہے، اور abide report اسے اپنی گنتی میں شامل کرتی ہے۔

Abide کو اَن انسٹال کریں

Abide کو ہر اس ایجنٹ سے ہٹائیں جس میں اسے انسٹال کیا گیا ہے:

abide uninstall

صرف ایک انٹیگریشن ہٹانے کے لیے ایجنٹ کا نام دیں:

abide uninstall codex

پروجیکٹ کی سطح کی انسٹالیشن ہٹاتے وقت --project شامل کریں۔ اَن انسٹالیشن صرف Abide کی اپنی اندراجات ہٹاتی ہے۔ روبِرک فائلیں اور ~/.abide/.env اس وقت تک موجود رہتی ہیں جب تک آپ انہیں دستی طور پر حذف نہ کر دیں۔

نتیجہ

Abide قدرتی زبان میں لکھی گئی ریپوزٹری ہدایات کو ایسے چیکس میں تبدیل کرتا ہے جو AI کوڈنگ سیشن کے دوران مسلسل چلتے رہتے ہیں۔ موزوں ہُکس انسٹال کریں، .abide/rubric.json کو مرتب کرکے اس کا جائزہ لیں، پھر قواعد کو مؤثر رکھنے کے لیے خودکار چیکس، آڈٹس، رپورٹس، کیلیبریشن اور ٹیوننگ استعمال کریں۔ نتیجتاً یہ ان کنونشنز کے لیے ایک ہلکی پھلکی نفاذی تہہ فراہم کرتا ہے جنہیں روایتی لِنٹرز بیان نہیں کر سکتے۔