Abide-এর মাধ্যমে প্রতিটি সম্পাদনায় কোডিং-এজেন্টের নিয়ম প্রয়োগ করুন

Abide যা করে

Abide এমন প্রকল্প-নির্দিষ্ট নির্দেশনা প্রয়োগ করে, যা সাধারণ লিন্টার নির্ভরযোগ্যভাবে মূল্যায়ন করতে পারে না। এসব নির্দেশনা AGENTS.md বা CLAUDE.md-এর মতো ফাইলে থাকতে পারে এবং এর মধ্যে থাকতে পারে manual validation-এর পরিবর্তে Yup ব্যবহার করুন, শুধু একজন কলার আছে এমন হেল্পার তৈরি করবেন না, অথবা কখনো ব্যবহারকারীর কাছে raw error প্রকাশ করবেন না—এ ধরনের নিয়ম।

প্রতিটি সম্পাদনা বা সম্পূর্ণ হওয়া টার্নের পর Abide প্রাসঙ্গিক নিয়ম ও কোডের diff TypeSafe-এর Jev decision model-এ পাঠায়। Jev মুক্তধারার গদ্যের পরিবর্তে একটি সম্ভাব্যতা ফেরত দেয়। সেই সম্ভাব্যতা কোনো লঙ্ঘনের ইঙ্গিত দিলে Abide coding agent-কে জানায় কোন নিয়ম ভাঙা হয়েছে এবং একই টার্নে কোডটি ঠিক করতে বলে।

Jev নিয়ম ও diff দেখে, agent-এর কথোপকথন নয়। এর ফলে দীর্ঘ coding session জুড়ে Abide একই পরীক্ষা ধারাবাহিকভাবে প্রয়োগ করতে পারে। repository-তে প্রকাশিত replay benchmark অনুযায়ী, Jev-এ পরীক্ষাগুলো প্রায় 300 মিলিসেকেন্ড সময় নেয়, আর Node startup অন্তর্ভুক্ত করলে সম্পূর্ণ hook-এর সময় লাগে প্রায় এক সেকেন্ড।

প্রধান বৈশিষ্ট্য

• স্বয়ংক্রিয় সম্পাদনা পরীক্ষা: প্রতিটি কোড সম্পাদনার পরপরই নিয়ম চালানো যায়।
• টার্ন-স্তরের পরীক্ষা: সম্পূর্ণ task diff প্রয়োজন এমন নিয়ম একটি টার্নের শেষে একবার চালানো যায়।
• Agent integration: Abide Claude Code, Codex এবং OpenCode সমর্থন করে।
• Repository-owned rubric: সংকলিত নিয়ম পাঠযোগ্য এবং commit-friendly .abide/rubric.json ফাইলে সংরক্ষিত থাকে।
• Scope করা নিয়ম: একটি নিয়ম glob scope ব্যবহার করতে পারে, যাতে API route, stylesheet বা অন্যান্য file group-এর জন্য আলাদা প্রশ্ন প্রযোজ্য হয়।
• বিদ্যমান কোডের audit: Abide ফাইলগুলো এমনভাবে যাচাই করতে পারে, যেন সেগুলো刚 লেখা হয়েছে।
• Calibration ও tuning: এটি সাম্প্রতিক Git history-র বিরুদ্ধে নিয়ম পরীক্ষা করতে, অকার্যকর নিয়ম নিষ্ক্রিয় করতে এবং কখনো সক্রিয় না হওয়া নিয়ম পুনর্লিখতে সহায়তা করতে পারে।
• Fail-open hook: অনুপস্থিত credential, network failure বা hook error coding session আটকে দেয় না।
• অন্তর্নির্মিত policy নেই: Abide পূর্বনির্ধারিত ruleset চাপিয়ে দেওয়ার পরিবর্তে আপনার নিজস্ব instruction file থেকে উদ্ভূত নিয়ম প্রয়োগ করে।

পূর্বশর্ত

আপনার coding agent-এর জন্য নির্দেশনা-সহ একটি repository এবং অন্তত একটি সমর্থিত agent: Claude Code, Codex বা OpenCode প্রয়োজন। এছাড়াও typesafe.ai থেকে একটি TypeSafe API key প্রয়োজন। বিকল্পভাবে, AI_GATEWAY_API_KEY environment variable-এর মাধ্যমে বিদ্যমান Vercel AI Gateway key ব্যবহার করতে পারে Abide।

Abide ইনস্টল ও কনফিগার করুন

ধাপ 1: API key সংরক্ষণ করুন

login command চালিয়ে prompt এলে আপনার TypeSafe key পেস্ট করুন:

npx @coldtea/abide login

Abide owner-only access-সহ ~/.abide/.env-এ key সংরক্ষণ করে। চাইলে repository root-এর .env.local বা .env-এ credential রাখতে পারেন। Credential lookup প্রথমে environment, এরপর repository file এবং সবশেষে ~/.abide/.env পরীক্ষা করে।

Vercel AI Gateway ব্যবহার করলে TypeSafe key-এর পরিবর্তে AI_GATEWAY_API_KEY সেট করুন। Command-line flag-এর মাধ্যমে credential গ্রহণ করা হয় না এবং credential log করা হয় না।

ধাপ 2: agent hook ইনস্টল করুন

আপনার repository থেকে Abide initialize করুন:

npx @coldtea/abide init

কোনো agent name না দিলে init খুঁজে পাওয়া প্রতিটি সমর্থিত agent-এ ইনস্টল করে। নির্দিষ্ট একটি integration-ও লক্ষ্য করতে পারেন:

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-এ ইনস্টল হয়।

Checkout-এর সঙ্গে teammates-রা পেতে পারে এমন repository-level installation চাইলে --project যোগ করুন:

npx @coldtea/abide init claude --project

Codex-এর জন্য একটি অতিরিক্ত approval ধাপ প্রয়োজন। Codex চালু করে /hooks লিখুন এবং Abide-এর চারটি hook entry গ্রহণ করুন। প্রতিটি নতুন hook-এর জন্য Codex একবার এই approval চায়।

ধাপ 3: repository rule সংকলন করুন

স্বাভাবিকভাবে আপনার coding agent চালু করুন। প্রথম session-এর শুরুতে Abide instruction file পরিবর্তিত হয়েছে কি না পরীক্ষা করে। এরপর agent প্রযোজ্য instruction-গুলো .abide/rubric.json-এ সংকলন করে এবং কী পাওয়া গেছে তা জানায়।

নতুন session শুরু করার আগেও সংকলন করতে পারেন:

abide compile

Repository-এর প্রয়োগযোগ্য rubric টিমের কাছে দৃশ্যমান ও পর্যালোচনাযোগ্য রাখতে চাইলে .abide/rubric.json commit করুন। প্রতিটি verdict এই ফাইলের একটি rule শনাক্ত করে এবং যেখান থেকে rule-টি উদ্ভূত হয়েছে সেই source instruction উদ্ধৃত করে।

মৌলিক ব্যবহার

Abide দিয়ে agent-এর সম্পাদনা স্বয়ংক্রিয়ভাবে পরীক্ষা করুন

Initialize করার পর স্বাভাবিকভাবে claude, codex বা opencode চালু করুন। আলাদা কোনো background service প্রয়োজন নেই। ধরুন, একটি instruction-এ বলা আছে API endpoint-গুলোকে Yup ব্যবহার করতে হবে এবং input manualভাবে validate করা যাবে না। কোনো agent manual guard লিখলে Abide এ ধরনের একটি message ফেরত দিতে পারে:

Abide: এই সম্পাদনাটি এই রিপোজিটরির নির্দেশনার একটি নিয়ম ভঙ্গ করেছে বলে মনে হচ্ছে।
- ~/.codex/AGENTS.md-এর ৬৫ নম্বর লাইনের "api-validation-uses-yup" নিয়ম:
  "API endpoint লেখার সময় ইনপুট ভ্যালিডেশন ম্যানুয়ালি লিখবেন না।
  পরিষ্কার ভ্যালিডেশন বার্তাসহ Yup ব্যবহার করুন + API handler-এ আগেভাগে return করুন"।
  (0.86)
এখনই apps/web/src/pages/api/logout.ts মেরামত করুন, তারপর কাজটি চালিয়ে যান।

এজেন্ট মেরামতের অনুরোধটি গ্রহণ করে কাজ চালিয়ে যাওয়ার আগে লঙ্ঘনটি ঠিক করতে পারে। OpenCode ব্যবহার করলে, টুলের ফলাফলে সম্পাদনার লঙ্ঘনগুলো যুক্ত হয়। একটি turn-স্তরের লঙ্ঘন হলে turn শেষ হওয়ার পর একটি follow-up বার্তা পাঠানো হয়।

অকমিট করা পরিবর্তন ম্যানুয়ালি পরীক্ষা করুন

হুকগুলো যেভাবে মূল্যায়ন করে, একইভাবে বর্তমান অকমিট করা পরিবর্তন মূল্যায়ন করতে check ব্যবহার করুন:

abide check

পরীক্ষার পরিধি কমাতে চাইলে পথও দিতে পারেন:

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

বিদ্যমান কোড অডিট করুন

audit কমান্ড বিদ্যমান ফাইলগুলোকে এমনভাবে মূল্যায়ন করে যেন সেগুলো刚 তৈরি করা হয়েছে। প্রতিষ্ঠিত কোনো রিপোজিটরিতে Abide গ্রহণ করার সময় এটি উপযোগী:

abide audit src/

আউটপুটে নিয়ম অনুযায়ী একটি সারাংশ এবং ফাইলভিত্তিক একটি তালিকা থাকে। README অনুযায়ী, একটি বাস্তব Next.js অ্যাপ্লিকেশনের ৩৩টি API route অডিট করতে প্রায় ১২ সেকেন্ড এবং প্রায় এক সেন্ট খরচ হয়েছে, যদিও প্রকৃত ফলাফল রিপোজিটরি ও নিয়মের ওপর নির্ভর করে।

নিয়মের কার্যকলাপ পর্যালোচনা করুন

আপনার নিয়মগুলো, কোনগুলো সক্রিয় হয়েছে এবং কোনগুলো কখনো সক্রিয় হয়নি তা দেখতে report কমান্ড চালান:

abide report

মেশিন-পাঠযোগ্য আউটপুটের জন্য --json যোগ করুন। check, audit, bench এবং calibrate-এর জন্যও JSON আউটপুট পাওয়া যায়।

নিয়মের সময়পর্ব ও verdict বুঝুন

প্রতিটি কম্পাইল করা নিয়ম দুটি পর্যায়ের একটিতে চলে:

• Edit পর্যায়: প্রতিটি পৃথক সম্পাদনার পরে চলে এবং সেই hunk মূল্যায়ন করে।
• Turn পর্যায়: turn-এর শেষে একবার চলে এবং turn শুরুর সময় নেওয়া snapshot-এর বিপরীতে সম্পূর্ণ diff মূল্যায়ন করে।

প্রথম সম্পাদনা থেকেই যেসব প্রশ্নের উত্তর দেওয়া যায় না, সেগুলোর জন্য turn-স্তরের মূল্যায়ন গুরুত্বপূর্ণ। যেমন, এজেন্ট ব্যবহারকারী যা চাননি এমন কার্যকারিতা যোগ করেছে কি না। একটি turn-এর শেষে Abide shell command-এর মাধ্যমে তৈরি পরিবর্তনেও edit-পর্যায়ের নিয়ম প্রয়োগ করে।

Verdict-গুলো সম্ভাব্যতার কয়েকটি স্তরে ভাগ করা হয়:

• 0.8 বা তার বেশি: লঙ্ঘনটি মেরামত করার নির্দেশ এজেন্টকে দেওয়া হয়।
• 0.5 থেকে 0.8-এর কম: একটি নোট দেখানো হয়, কিন্তু এজেন্টকে মেরামতের নির্দেশ দেওয়া হয় না।
• 0.5-এর কম: কিছুই দেখানো হয় না।

উন্নত workflow

Git history-এর বিপরীতে নিয়ম calibrate করুন

খারাপভাবে লেখা কোনো নিয়ম অনেক সম্পর্কহীন পরিবর্তনে মাঝামাঝি স্কোর পেতে পারে এবং কখনো কার্যকর ফলাফল তৈরি নাও করতে পারে। calibration কমান্ডটি রিপোজিটরির Git history থেকে সাম্প্রতিক বাস্তব hunk-এর বিপরীতে প্রতিটি নিয়ম মূল্যায়ন করে:

abide calibrate

এই প্রক্রিয়ায় Abide সাম্প্রতিক ২০টি hunk ব্যবহার করে এবং অকার্যকর নিয়ম বন্ধ করে দিতে পারে। একটি দলের মধ্যে নতুন কম্পাইল করা rubric-এর ওপর নির্ভর করার আগে ফলাফল পর্যালোচনা করুন।

যেসব নিয়ম কখনো সক্রিয় হয় না সেগুলো tune করুন

অকার্যকর নিয়ম শনাক্ত করার পর, এজেন্টকে সেগুলো পুনর্লিখতে tune ব্যবহার করুন:

abide tune

প্রতিটি rubric entry-তে তার উৎস নির্দেশনার উদ্ধৃতি থাকে বলে সন্দেহজনক verdict-এর সূত্র ধরে সেই verdict তৈরি করা ভাষা পর্যন্ত পৌঁছানো যায়। অন্তর্নিহিত নির্দেশনা উন্নত করলে সাধারণত সংশ্লিষ্ট check আরও স্পষ্ট হয়।

আগের agent session replay করুন

সমর্থিত এজেন্টগুলোর একটির আগের session বিচার করতে replay ব্যবহার করুন:

abide replay claude
abide replay codex
abide replay opencode

এটি ভবিষ্যতের লঙ্ঘনের জন্য অপেক্ষা না করে ইতিমধ্যে সম্পন্ন কাজের বিপরীতে rubric মূল্যায়নে সহায়তা করতে পারে।

স্থানীয় latency ও খরচ পরিমাপ করুন

নিজের মেশিনে কর্মক্ষমতা ও খরচ পরিমাপ করতে benchmark কমান্ড চালান:

abide bench

রিপোজিটরির প্রতিবেদন অনুযায়ী, এর ১৩টি নিয়ম পরীক্ষা করতে প্রায় ১,০০০ থেকে ১,৬০০ input token ব্যবহার হয়, প্রতি check-এ প্রায় $0.00004 থেকে $0.00007 খরচ হয় এবং Jev-এ প্রায় ৩০০ মিলিসেকেন্ড সময় লাগে। এই পরিসংখ্যানগুলো TypeSafe-এর বিপরীতে সরাসরি পরিমাপ করা হয়েছে এবং পরিবর্তিত হতে পারে, তাই আপনার সেটআপের জন্য স্থানীয় benchmark-ই ভালো নির্দেশনা।

প্রাসঙ্গিক প্রশ্ন রাখতে scope ব্যবহার করুন

.abide/rubric.json-এর নিয়মগুলোতে glob-ভিত্তিক scope থাকতে পারে। কোনো নির্দেশনা শুধু নির্দিষ্ট ফাইলের ক্ষেত্রে প্রযোজ্য হলে এই scope ব্যবহার করুন। উদাহরণস্বরূপ, validation নিয়ম API route-এর জন্য প্রযোজ্য হতে পারে, আর styling নিয়ম stylesheet-এ সীমাবদ্ধ রাখা উচিত। সংকীর্ণ scope অপ্রাসঙ্গিক মূল্যায়ন কমায় এবং verdict বোঝা সহজ করে।

গোপনীয়তা ও ব্যর্থতার আচরণ

পরিবর্তিত লাইনগুলো প্রতিটি call-এ zero data retention চেয়ে আপনার নিজস্ব key-এর মাধ্যমে TypeSafe-এ পাঠানো হয়। README-তে বলা হয়েছে, ডেটা Abide পরিচালিত কোনো server-এ পাঠানো হয় না।

Abide-এর hook-গুলো agent session ভেঙে না দেওয়ার জন্য তৈরি। Hook path সফলভাবে exit করে, একটি hard deadline ব্যবহার করে এবং host যে আউটপুট প্রত্যাশা করে শুধু সেটিই প্রিন্ট করে। কোনো key না থাকলে বা network অনুপলব্ধ হলে edit কোনো check ছাড়াই এগিয়ে যায়। বাদ পড়া check .abide/events.jsonl-এ লেখা হয় এবং abide report তার count-এ এটি অন্তর্ভুক্ত করে।

Abide আনইনস্টল করুন

যে প্রতিটি agent-এ Abide ইনস্টল করা হয়েছে, সেখান থেকে এটি সরান:

abide uninstall

শুধু একটি integration সরাতে agent-এর নাম দিন:

abide uninstall codex

Project-level installation সরানোর সময় --project যোগ করুন। আনইনস্টলেশন শুধু Abide-এর নিজস্ব entry সরায়। আপনি নিজে মুছে না দেওয়া পর্যন্ত rubric ফাইল এবং ~/.abide/.env রেখে দেয়।

উপসংহার

Abide প্রাকৃতিক ভাষায় লেখা রিপোজিটরি নির্দেশনাগুলোকে এমন চেকে রূপান্তর করে, যা একটি AI কোডিং সেশনজুড়ে চলে। উপযুক্ত হুক ইনস্টল করুন, .abide/rubric.json কম্পাইল ও পর্যালোচনা করুন, তারপর নিয়মগুলো কার্যকর রাখতে স্বয়ংক্রিয় চেক, অডিট, রিপোর্ট, ক্যালিব্রেশন এবং টিউনিং ব্যবহার করুন। এর ফল হলো এমন কনভেনশনের জন্য একটি হালকা এনফোর্সমেন্ট স্তর, যা প্রচলিত লিন্টার প্রকাশ করতে পারে না।