সমস্যা: AI কোড লেখে বারবার একই জায়গায় কেন ফেইল করে

Cursor, Windsurf বা Claude Code দিয়ে প্রজেক্ট চালানো মানুষদের প্রায় সবার একই অভিজ্ঞতা আছে: AI একটা বড় ব্লক কোড থুড়ে দেয়, আপনি কপি-পেস্ট করে রান করেন — বিল্ড ভাঙে, টেস্ট লাল হয়, ডিপেন্ডেন্সি ভুল জায়গায় বসে। সমস্যাটা AI-এর বুদ্ধিতে নেই, সমস্যা হলো আপনার প্রজেক্টের “অলিখিত নিয়ম” সে জানে না।

AGENTS.md হলো প্রজেক্ট রুটে রাখা একটা Markdown ফাইল, বিশেষভাবে AI-এর জন্য লেখা — কীভাবে বিল্ড করতে হবে, কীভাবে টেস্ট করতে হবে, কোন কনভেনশন মানতে হবে। README.md মানুষের জন্য — প্রজেক্ট পরিচিতি, কন্ট্রিবিউশন গাইড, ব্র্যান্ড স্টোরি সব থাকে। AI এসব পড়ে এমন হয় যেন নতুন বস প্রথম দিনে কোম্পানির প্রচার ব্রোশিওর হাতে পেয়ে সাথে সাথে কোড লিখতে বলা হলো — কোম্পানি কী করে জানে, কিন্তু বিল্ড কমান্ড কী, টেস্ট কীভাবে রান হয়, ESLint রুল কী — কিছুই জানে না। ফলাফল? প্রতিটা চ্যাটে একই ঝামেলা: “pnpm ব্যবহার করো, npm না”, “টেস্ট packages/web-এ”, “lint ভুলে যেও না”। এই একই কথা ১০০ বার বললেও প্রজেক্ট এলোমেলো থাকে।

ফ্রিল্যান্স কাজে ক্ষতিটা সরাসরি: একটা Next.js + Prisma প্রজেক্ট পেলেন, Cursor দিয়ে স্পিড বাড়াতে চাইলেন, AI চালিয়ে দিল npm install, পুরো pnpm workspace কনফিগারেশন নষ্ট; ডাটাবেস স্কিমা কোথায় সেটাও জানে না, জেনারেট করা migration ফাইল সরাসরি এরর। ক্লায়েন্ট ডেডলাইন চাপ দিচ্ছে, আপনি AI-এর জেনারেট করা কোড ডিবাগ করতে বসে ৩ ঘণ্টা পার করলেন — টাকাটা উপার্জন না, শাস্তি।

AI প্রজেক্টের অলিখিত নিয়ম না জানার ৩টা ক্লাসিক বিপদ: ① প্যাকেজ ম্যানেজার ভুল (প্রজেক্টে pnpm, AI ডিফল্টভাবে npm install চালায়), ডিপেন্ডেন্সি ভুল জায়গায় বসে, workspace কনফিগ ভাঙে; ② টেস্ট এন্ট্রি পয়েন্ট হারাম (প্রজেক্টে টেস্ট packages/web-এ, AI রুটে pnpm test চালায়, “টেস্ট ফাইল পাওয়া যায়নি”); ③ কোড স্টাইল ইনকনসিস্টেন্ট (প্রজেক্টে ESLint + Prettier, AI-এর কোডে ইন্ডেন্টেশন আর কোটেশন সব ভুল, CI সরাসরি ফেইল)।

সুযোগ: AGENTS.md “মানুষের ডকুমেন্ট” আর “মেশিনের ডকুমেন্ট” আলাদা করে দেয়

GitHub-এর ওপেন সোর্স প্রজেক্ট AGENTS.md (রিপো github.com/agentsmd/agents.md, ২০২৬-০৮-২৫ পর্যন্ত প্রায় ২৪,০০০ স্টার) ঠিক এই সমস্যাটা সমাধান করে। মূল ধারণাটা অত্যন্ত সহজ: প্রজেক্ট রুটে একটা Markdown ফাইল রাখুন, AI-কে বলুন কীভাবে বিল্ড করতে হবে, কীভাবে টেস্ট করতে হবে, কোন কোড স্টাইল মানতে হবে।

এটা README-এর বিকল্প না, সম্পূরক। README মানব কন্ট্রিবিউটরের জন্য, AGENTS.md AI এজেন্টের জন্য। দুটোর দায়িত্ব আলাদা, কোনো ওভারল্যাপ নেই।

সূত্র অনুযায়ী, AGENTS.md ইতিমধ্যে হাজার হাজার ওপেন সোর্স প্রজেক্টে ব্যবহৃত হচ্ছে (সঠিক সংখ্যা যাচাই বাকি), এবং VS Code, Cursor, Windsurf, Aider, GitHub Copilot-সহ প্রধান AI কোডিং টুলগুলো সাপোর্ট করে (যাচাইকৃত); কমিউনিটি ফিডব্যাক অনুযায়ী OpenAI Codex, Google Jules-ও সাপোর্ট দেয় (⚠️অযাচাইকৃত)। আপনি এখন না শিখলে AI-কে উপজাতীয় ভাষায় কথা বলানো হচ্ছে।

পথ ১: ন্যূনতম ব্যবহারযোগ্য AGENTS.md নিজে লিখুন

খরচ প্রায় শূন্য। নতুন ফাইল, তিনটা সেকশন — ব্যস।

আগে জানা দরকার: নিচের উদাহরণে pnpm ব্যবহার করা হয়েছে (npm-এর চেয়ে ডিস্কে কম জায়গা নেয়, monorepo workspace সাপোর্ট করে), turbo হলো monorepo টাস্ক অর্কেস্ট্রেটর, --filter প্যারামিটার দিয়ে নির্দিষ্ট সাব-প্যাকেজে টার্গেট করা যায়, পুরো রিপোতে প্রভাব ফেলে না।

প্রথম সেকশন “Dev environment tips”: AI-কে বলুন কোন প্যাকেজ ম্যানেজার, কীভাবে সাব-প্যাকেজে যাবে, কীভাবে নতুন মডিউল তৈরি করবে। অফিসিয়াল উদাহরণ:

• pnpm dlx turbo run where <project_name> — সরাসরি নির্দিষ্ট সাব-প্যাকেজ ডিরেক্টরিতে যায়, ls দিয়ে একটা একটা ঘাঁটতে হয় না
• pnpm install --filter <project_name> — শুধু একটা সাব-প্যাকেজের ডিপেন্ডেন্সি ইনস্টল করে, পুরো monorepo ছুঁয়ে যায় না
• pnpm create vite@latest <project_name> -- --template react-ts — TypeScript চেকিংসহ নতুন React + Vite সাব-প্যাকেজ তৈরি করে

এই কমান্ডগুলো AI নিজে থেকে অনুমান করতে পারে না, কিন্তু লিখে দিলে ঠিকঠাক মতো পালন করে।

দ্বিতীয় সেকশন “Testing instructions”: টেস্ট কীভাবে রান হয়, CI প্ল্যান কোথায়, কমিটের আগে কী কী চেক বাধ্যতামূলক। অফিসিয়াল উদাহরণ:

• pnpm turbo run test --filter <project_name> — নির্দিষ্ট সাব-প্যাকেজের সব চেক রান করে
• pnpm vitest run -t "<test name>" — নাম মিলানো একটা মাত্র টেস্ট রান করে
• “Fix any test or type errors until the whole suite is green” — পুরো স্যুট সবুজ না হওয়া পর্যন্ত থামবে না
• “Add or update tests for the code you change, even if nobody asked” — এই শেষ লাইনটাই ক্রিটিক্যাল, না লিখলে AI টেস্ট লেখা এড়িয়ে যায়

তৃতীয় সেকশন “PR instructions”: কমিট টাইটেল ফরম্যাট, lint আর test বাধ্যতামূলক। অফিসিয়াল উদাহরণ: Title format: [<project_name>] <Title>, এবং “Always run pnpm lint and pnpm test before committing”।

এই তিনটা সেকশন মিলে ৫০ লাইনের কম, কিন্তু AI-এর কোড ফার্স্ট-টাইম পাস রেট লক্ষণীয়ভাবে বাড়ায় (কমিউনিটি ফিডব্যাক অনুযায়ী, সঠিক সংখ্যা যাচাই বাকি)।

পথ ২: বড় monorepo-তে নেস্টেড কনফিগ ব্যবহার

এন্টারপ্রাইজ-লেভেল প্রজেক্ট হলে, কোডবেস monorepo স্ট্রাকচারে (একই Git রিপোতে একাধিক সম্পর্কিত প্রজেক্ট, যেমন ফ্রন্টএন্ড, ব্যাকএন্ড, শেয়ার্ড কোড আলাদা সাব-ডিরেক্টরিতে), একটা মাত্র AGENTS.md যথেষ্ট না। AGENTS.md নেস্টিং সাপোর্ট করে: প্রতিটা সাব-ডিরেক্টরিতে আলাদা AGENTS.md রাখুন, AI স্বয়ংক্রিয়ভাবে “সবচেয়ে কাছের” ফাইলটা পড়ে নেয়।

বাস্তবায়ন: রুটের AGENTS.md-তে গ্লোবাল নিয়ম (প্যাকেজ ম্যানেজার, CI ফ্লো, সিকিউরিটি গাইডলাইন), তারপর packages/web/, packages/api/, packages/shared/-এ আলাদা আলাদা ফাইল — প্রতিটায় ওই সাব-প্যাকেজের নির্দিষ্ট বিল্ড কমান্ড, টেস্ট এন্ট্রি, বিশেষ ডিপেন্ডেন্সি। যেমন ফ্রন্টএন্ড প্যাকেজে লিখুন “কম্পোনেন্ট লাইব্রেরি shadcn, স্টাইল Tailwind, আইকন lucide-react”; ব্যাকএন্ড প্যাকেজে লিখুন “ডাটাবেস migration Prisma দিয়ে, API রাউট src/routes-এ, অথ JWT দিয়ে”।

AI সাব-ডিরেক্টরিতে কাজ করার সময় স্বয়ংক্রিয়ভাবে কাছের AGENTS.md লোড করে, রুটের চেয়ে প্রায়োরিটি বেশি। এর মানে একই প্রজেক্টে ফ্রন্টএন্ড AI অ্যাসিস্ট্যান্ট আর ব্যাকএন্ড AI অ্যাসিস্ট্যান্ট সম্পূর্ণ আলাদা ইনস্ট্রাকশন পায়, কেউ কারো ওপর চড়াও হয় না।

পথ ৩: ফ্রিল্যান্স কাজে ডিফারেনশিয়েটর হিসেবে ব্যবহার

AI দিয়ে ক্লায়েন্ট কাজ নেওয়ার মার্কেট এখন লাল সাগর — সবাই Cursor চালায়, কিন্তু ডেলিভারি কোয়ালিটি বিশাল ওঠানামা। প্রপোজালে একটা লাইন লিখুন “এই প্রজেক্টে AGENTS.md স্ট্যান্ডার্ড ডকুমেন্টেশন কনফিগার করা আছে, AI-অ্যাসিস্টেড ডেভেলপমেন্ট প্রজেক্ট কনভেনশন মেনে চলে” — “আমি AI দিয়ে কোড লিখি” বলা প্রতিযোগীদের চেয়ে উইন রেট লক্ষণীয়ভাবে বেশি।

কার্যকরী পদ্ধতি: কাজ পাওয়ার পর প্রথমে ৩০ মিনিট ক্লায়েন্টের প্রজেক্ট স্ট্রাকচার বুঝুন, তারপর কাস্টমাইজড AGENTS.md লিখুন। এই ডকুমেন্টটা নিজেই ডেলিভারেবলের অংশ — ক্লায়েন্ট পরে নিজে AI দিয়ে কোড মেইনটেইন করলেও সুবিধা পাবে।

AGENTS.md কনফিগ সার্ভিস আলাদা দামে অফার করুন (রেফারেন্স প্রাইসিং, লোকাল মার্কেট অনুযায়ী সমন্বয় করুন): বেসিক ৳৫,০০০ (সিঙ্গেল ফাইল কনফিগ + README গাইড), এন্টারপ্রাইজ ৳৩০,০০০ (monorepo নেস্টিং + সিকিউরিটি স্ট্যান্ডার্ড + টিম ট্রেনিং)। ডেলিভারেবল: ① কাস্টম AGENTS.md ফাইল ② ৩০ দিন WhatsApp সাপোর্ট ③ ১০ মিনিটের স্ক্রিন রেকর্ড ট্রেনিং। উপযুক্ত: ক্লায়েন্টের কাছে ইতিমধ্যে Cursor/Windsurf সাবস্ক্রিপশন আছে কিন্তু কাজে লাগাতে পারছে না। অনুপযুক্ত: ক্লায়েন্ট এখনো পুরোপুরি ম্যানুয়াল ডেভেলপমেন্টে আছে, কোনো AI টুল নেই।

কেস স্টাডি: AGENTS.md-এর কম্প্যাটিবিলিটি মোচ্ছর

AGENTS.md MIT লাইসেন্সে (উৎস নিশ্চিত) প্রকাশিত, কমিউনিটি দ্বারা মেইনটেইন করা (গভর্নেন্স স্ট্রাকচার যাচাই বাকি), অফিসিয়াল সাইট agents.md।

কম্প্যাটিবিলিটিই এর সবচেয়ে বড় মোচ্ছর: যাচাইকৃত সিদ্ধান্ত অনুযায়ী VS Code, Cursor, Windsurf, Aider, GitHub Copilot সব AGENTS.md পড়তে পারে; কমিউনিটি ফিডব্যাক অনুযায়ী OpenAI Codex, Claude Code, Gemini CLI, Google Jules-ও সাপোর্ট দেয় (⚠️অযাচাইকৃত)। এর মানে একটা ফাইল লিখলে প্রধান সব AI অ্যাসিস্ট্যান্ট কাজে লাগায় — প্রতিটা টুলের জন্য আলাদা কনফিগ লেখার দরকার নেই।

অন্যান্য সলিউশনের সাথে তুলনা: Cursor-এর .cursorrules শুধু Cursor-এ কাজ করে, Windsurf-এ সুইচ করলে অকেজো; Claude Code-এর CLAUDE.md শুধু Claude-এর জন্য; GitHub Copilot-এর ইনস্ট্রাকশন সিস্টেম আবার সম্পূর্ণ আলাদা। AGENTS.md-এর “একবার লিখুন, সব জায়গায় চালান” বৈশিষ্ট্যই এটাকে এত দ্রুত ছড়িয়ে পড়ার মূল কারণ।

টুল মাইগ্রেশন খরচ শূন্য। আজ Cursor ব্যবহার করলেন, কাল Windsurf-এ সুইচ করলেন, AGENTS.md সরাসরি রিইউজ — রুল আবার লেখার দরকার নেই।

কল টু অ্যাকশন: আজ রাতেই প্রজেক্টে মেশিন ম্যানুয়াল যোগ করুন

৫ মিনিটের অ্যাকশন চেকলিস্ট: ① প্রজেক্ট রুট ওপেন করুন ② নতুন AGENTS.md তৈরি করুন ③ অফিসিয়াল টেমপ্লেট কপি করুন (github.com/agentsmd/agents.md) ④ তিনটা কমান্ড পূরণ করুন (বিল্ড, টেস্ট, lint) ⑤ পরের বার AI দিয়ে কোড লেখানোর সময় ফলাফল দেখুন।

monorepo ব্যবহার করলে আজ রাতে আরো ২০ মিনিট ব্যয় করে প্রতিটা সাব-প্যাকেজে নেস্টেড কনফিগ যোগ করুন। কাল সকালে কাজ শুরু করলে দেখবেন AI-এর জেনারেট করা কোড নিয়ে বারবার ত্রুটি সংশোধনের দরকার নেই।

AGENTS.md এই মুহূর্তে সবচেয়ে বেশি ROI দেওয়া AI কোডিং কনফিগ — ৩০ মিনিটের বিনিয়োগে প্রতি মাসে কয়েক ঘণ্টা ডিবাগ টাইম বাঁচে।