AGENTS.md এবং CLAUDE.md: এমন একটা কনফিগ ফাইল কীভাবে লিখবেন যেটা এজেন্ট আসলেই ব্যবহার করে

একটা ভালো কনফিগ ফাইল লেখা agentic coding-এ সবচেয়ে হাই-লেভারেজ, লো-এফোর্ট মুভ। একবার কনটেক্সট সেট করলে প্রতিটা সেশন লাভবান হয়: এজেন্ট আর টেস্ট কমান্ড গেস করে না, নিজের ডিফল্ট অনুযায়ী রিফরম্যাট করে না, যে ডিরেক্টরিতে ঢুকতে বারণ করেছ সেখানে এডিট করে না। এই পেজটা হলো AI-native "context & configuration" স্কিল-এর পেছনের কনক্রিট ক্রাফট — 17টা AI-native স্কিলের একটা, যেগুলো আমরা লেভেলজুড়ে গ্রেড করি। CLAUDE.md / AGENTS.md-এ ডিউরেবল প্রজেক্ট মেমরি রাখাটা Level 3 Agentic Developer-এর একটা ডিফাইনিং সিগন্যাল, তাই এটা ঠিকভাবে করা worth it।

মূল আইডিয়াটা সব টুলে একই, যদিও মেকানিক্স আলাদা: কনফিগ ফাইল সেসব জিনিস বহন করে যা এজেন্ট কোড থেকে নিজে অনুমান করতে পারে না। মডেল তোমার ল্যাঙ্গুয়েজ তো আগে থেকেই জানে। কিন্তু ও জানে না যে তোমার টেস্টে একটা স্পেসিফিক ফ্ল্যাগ লাগে, তিন মাস আগে তুমি একটা লাইব্রেরি থেকে মাইগ্রেট করেছ, বা infra/ জেনারেটেড আর হাতে এডিট করা যাবে না। এই গ্যাপটাই ফাইল ফিল করে।

ল্যান্ডস্কেপ: এক দর্শন, অনেক ফাইল

প্রতিটা মেজর এজেন্ট একটা প্রজেক্ট কনটেক্সট ফাইল পড়ে। ফিলোসফি সবার এক, কিন্তু ফাইলনেম আর লোডিং মেকানিক্সে আলাদা। এখানে 2026-এর ম্যাপ:

ফাইল	টুল(গুলো)	স্ট্যাটাস
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20টা টুল	ওপেন ক্রস-টুল স্ট্যান্ডার্ড
CLAUDE.md	Claude Code	Claude Code-এর নেটিভ ফরম্যাট
GEMINI.md	Gemini CLI	Gemini-এর নেটিভ ফরম্যাট
.github/copilot-instructions.md	GitHub Copilot	Copilot-এর রেপো ইনস্ট্রাকশন
.cursor/rules (আগে .cursorrules)	Cursor	Cursor-এর রুলস ফরম্যাট

মূল কথা: AGENTS.md হয়ে উঠছে একটা সিঙ্গেল সোর্স অফ ট্রুথ — একটা ওপেন স্পেক যেটা ইতিমধ্যে ~20টা টুল পড়ে। ক্যাচ হলো, Claude Code নেটিভলি AGENTS.md পড়ে না — শুধু CLAUDE.md পড়ে। তাই ক্যানোনিকাল ওয়ান-সোর্স-অফ-ট্রুথ প্যাটার্ন হলো AGENTS.md-কে ক্যানোনিকাল রেখে একটা ছোট্ট CLAUDE.md দিয়ে Claude-এর সাথে ব্রিজ করা যেটা সেটাকে import করে:

@AGENTS.md

<!-- Claude-specific notes can go below -->

সিমলিংকও কাজ করে (ln -s AGENTS.md CLAUDE.md), তবে Windows-এ @import প্রেফার করো — ওখানে সিমলিংকের জন্য admin rights লাগে। এভাবে তুমি একটা ফাইল মেইনটেইন করো আর দুই ইকোসিস্টেমই সেটা পড়ে।

আসলে কী রাখবে

2500+ রেপোজিটরির ওপর GitHub-এর অ্যানালিসিসে ("How to write a great AGENTS.md") দেখা গেছে, যেসব কনফিগ মেজারেবলি এজেন্টদের হেল্প করে তাদের ছয়টা কমন সেকশন থাকে। মোটামুটি প্রায়োরিটি অর্ডারে:

1. কমান্ড — আগে বসানো, এক্স্যাক্ট এক্সিকিউটেবল কমান্ড আর ফ্ল্যাগ সহ (npm test, npm run build, pytest -v), শুধু টুলের নাম না। এটা হাইয়েস্ট-ROI সেকশন: এজেন্ট এমনিতেই জানে pytest আছে; ও জানে না তোমার প্রজেক্টের রিকোয়ার্ড ফ্ল্যাগগুলো কী। ওপরের দিকে রাখো।
2. টেস্টিং প্র্যাকটিস — কীভাবে টেস্ট করো, কমিটের আগে কী রান করবে, কভারেজ এক্সপেক্টেশন।
3. প্রজেক্ট স্ট্রাকচার — কোনটা কোথায় থাকে, যাতে এজেন্টকে খুঁজতে না হয়।
4. কোড স্টাইল — একটা রিয়েল কোড স্নিপেট দেখাও, তিন প্যারাগ্রাফ প্রোজ না।
5. Git ওয়ার্কফ্লো — ব্রাঞ্চ নেমিং, কমিট কনভেনশন, PR রুল।
6. বাউন্ডারি — এজেন্ট কখনো কী টাচ করবে না (জেনারেটেড ডিরেক্টরি, সিক্রেট, ভেন্ডর্ড কোড, মাইগ্রেশন)।

লেভারেজের অর্ডারটা খেয়াল করো। "ফ্ল্যাগসহ কমান্ড" প্রথমে থাকার একটা কারণ আছে: এটা এমন একটা জিনিস যা মডেল সবচেয়ে রিলায়েবলি গেস করতে পারে না, আর সবচেয়ে বেশি ভুল করে। আর কিছু ভালো না লিখলেও, এটা লিখো।

Include / exclude: লাইন-বাই-লাইন টেস্ট

Anthropic-এর memory docs একটা এক্সপ্লিসিট টু-কলাম লাইন টানে। প্রতিটা লাইন যোগ করার আগে এটাকে ফিল্টার হিসেবে ইউজ করো।

রাখো	বাদ দাও
Bash কমান্ড যা এজেন্ট গেস করতে পারে না	কোড থেকে অনুমানযোগ্য যেকোনো কিছু
কোড-স্টাইল রুল যা ডিফল্ট থেকে আলাদা	স্ট্যান্ডার্ড ল্যাঙ্গুয়েজ কনভেনশন যা মডেল এমনিতেই জানে
টেস্টিং ইনস্ট্রাকশন / প্রেফার্ড টেস্ট রানার	ডিটেইলড API ডক্স (এর বদলে লিংক দাও)
রেপো এটিকেট (ব্রাঞ্চ নেমিং, PR কনভেনশন)	ঘন ঘন বদলানো ইনফো
প্রজেক্ট-স্পেসিফিক আর্কিটেকচারাল ডিসিশন	লম্বা এক্সপ্ল্যানেশন আর টিউটোরিয়াল
ডেভ-এনভায়রনমেন্ট quirks (রিকোয়ার্ড env ভ্যারিয়েবল)	ফাইল-বাই-ফাইল কোডবেস ডেসক্রিপশন
নন-অবভিয়াস গচা	"clean code লেখো"-এর মতো সেলফ-এভিডেন্ট প্র্যাকটিস

একটা টেস্ট আছে যেটা পুরো টেবিলকে একটা হ্যাবিটে কলাপ্স করে দেয়:

পার-লাইন টেস্ট: "এই লাইনটা সরালে এজেন্ট মিসটেক করবে? না করলে, কেটে দাও।"

প্রতিটা লাইনে এই টেস্ট রান করো। "TypeScript ইউজ করো" — এজেন্ট .ts ফাইলগুলো দেখতেই পাচ্ছে; কেটে দাও। "ডেটাবেস মাইগ্রেশন npm run db:migrate দিয়ে রান করো, কখনো migrations/ হাতে এডিট করো না" — এটা ও গেস করতে পারত না, আর ভুল করলে স্টেট করাপ্ট হবে; রাখো।

সঠিক altitude-এ লেখো

Anthropic-এর কনটেক্সট-ইঞ্জিনিয়ারিং গাইডেন্স ভালো authoring-কে চারটা প্রিন্সিপলে নামায়।

১. Specificity / verifiability। রুলগুলো এতটা কনক্রিট লেখো যাতে এজেন্টের আউটপুটের বিপরীতে চেক করা যায়। ভেগ গাইডেন্স ভেরিফাই করা যায় না, তাই রিলায়েবলি ফলো করাও যায় না।

• "2-স্পেস ইন্ডেন্টেশন ইউজ করো" — "কোড ঠিকমতো ফরম্যাট করো" না।
• "কমিটের আগে npm test রান করো" — "তোমার চেঞ্জ টেস্ট করো" না।
• "API হ্যান্ডলার src/api/handlers/-এ থাকে" — "ফাইল অর্গানাইজড রাখো" না।

২. Right altitude। ব্রিটল হার্ডকোডেড লজিক আর ভেগ hand-waving-এর মাঝামাঝি টার্গেট করো: "বিহেভিয়ার গাইড করার মতো যথেষ্ট স্পেসিফিক, স্ট্রং হিউরিস্টিক হওয়ার মতো যথেষ্ট ফ্লেক্সিবল"। খুব রিজিড হলে প্রথম edge case-এই ভেঙে যাবে; খুব লুজ হলে কিছুই গাইড করবে না।

৩. Minimal-but-sufficient। Minimal মানে ছোট না। মানে হলো আগে থেকেই এত কনটেক্সট দেওয়া যাতে এজেন্টকে গেস বা re-discover করতে না হয় — আর তার বেশি কিছু না। ফিলার কাটো, load-bearing ডিটেইল রাখো।

৪. Structure। লেবেলড সেকশন ইউজ করো — Markdown হেডার বা XML ট্যাগ। একটা স্ক্যানেবল ফাইল হলো এমন একটা ফাইল যা এজেন্ট (আর তোমার টিমমেটরা) আসলেই পার্স করে।

লিন রাখো

লিন থাকার আসল কারণ হলো টোকেন বাজেট। কনফিগ ফাইল প্রতিটা সিঙ্গেল সেশনে পুরোপুরি লোড হয়। এটা অন-ডিমান্ড রিট্রিভ হয় না; লঞ্চের সময় কনটেক্সটে prepend হয়ে যায়। তাই bloat-এর একটা ডিরেক্ট, মেজারড কস্ট আছে: একটা bloated CLAUDE.md মেজারেবলি instruction adherence কমায়। Anthropic-এর নিজের ফ্রেমিংটাই ব্লান্ট — bloated CLAUDE.md ফাইল Claude-কে তোমার আসল ইনস্ট্রাকশন ইগনোর করাতে বাধ্য করে। প্রতিটা junk লাইন তোমার ভালো লাইনগুলোকে দুর্বল করে দেয়।

টার্গেটগুলো কনক্রিট:

• Anthropic CLAUDE.md-এর জন্য সফট গোল হিসেবে ~200 লাইনের নিচে টার্গেট করে।
• Codex AGENTS.md-এ (project_doc_max_bytes) হার্ড 32 KiB ক্যাপ এনফোর্স করে; ওভারসাইজড ফাইল ট্রাংকেট হয়ে যায়, তাই ক্যাপের পরের অংশ silently লোড হয় না।

আর একটা ফাঁদ বলে রাখা দরকার: import বাজেট বাঁচায় না। একটা @imported ফাইল লঞ্চের সময় কনটেক্সটে লোড হয়েই যায় — তুমি ফাইলটা স্প্লিট করেছ, ফুটপ্রিন্ট কমাওনি। প্রতিটা সেশনে যা লোড হয় তা আসলে কমাতে হলে, কন্ডিশনালি-রিলেভ্যান্ট কনটেন্ট অফলোড করো:

• Path-scoped rules ক্রস-কাটিং কনসার্নের জন্য যা অনেক ফাইল টাচ করে — এগুলো শুধু তখনই লোড হয় যখন এজেন্ট সেই পাথে কাজ করে।
• Skills অন-ডিমান্ড প্রসিডিউরের জন্য — এগুলো শুধু ইনভোক করলে লোড হয়।
• লিংক লম্বা বা ডিটেইলড রেফারেন্স ম্যাটেরিয়ালের জন্য — inline না করে সেদিকে পয়েন্ট করো।

প্রিন্সিপলটা পার-লাইন টেস্টের মতোই, শুধু সেকশন লেভেলে অ্যাপ্লাই করা: যদি কিছু মাঝেমধ্যেই রিলেভ্যান্ট হয়, সেটা সবসময়-লোড-হওয়া ফাইলে থাকা উচিত না।

DESIGN.md: একটা টিম কনভেনশন, স্ট্যান্ডার্ড না

DESIGN.md হলো "কনফিগ লিন রাখো, ডিটেইল লিংক করো"-এর টেক্সটবুক অ্যাপ্লিকেশন। এটা আলাদা একটা ডিজাইন/আর্কিটেকচার ডক — কি ডিসিশন, ডোমেইন মডেল, আর্কিটেকচারাল প্যাটার্ন, কেন এভাবে বানানো — যেটা তোমার AGENTS.md inline না করে @imports করে বা রেফারেন্স করে। এতে সবসময়-লোড-হওয়া কনফিগ ছোট থাকে, আর ডিপ কনটেক্সট এক hop দূরে থেকে যায়।

তবে এর স্ট্যাটাস নিয়ে honest থাকো: AGENTS.md আর CLAUDE.md-এর মতো না, DESIGN.md-কে স্ট্যান্ডার্ড এজেন্ট-কনফিগ ফাইল হিসেবে প্রতিষ্ঠা করার মতো কোনো প্রাইমারি সোর্স নেই। এটা একটা পাওয়ারফুল টিম কনভেনশন, ডকুমেন্টেড স্ট্যান্ডার্ড না। এটা ইউজ করো কারণ তোমার টিমের জন্য কাজ করে, কোনো স্পেক ম্যান্ডেট করে বলে না।

স্কোপ ও হায়ারার্কি

দুই ইকোসিস্টেমই ফাইলগুলোকে ব্রড থেকে স্পেসিফিক লেয়ার করে, কিন্তু প্রায়োরিটি রেজলভ করে আলাদাভাবে।

CLAUDE.md-এর চারটা স্কোপ আছে, ব্রড → স্পেসিফিক লোড হয়:

1. Managed policy — তোমার org / IT সেট করে, org-ওয়াইড অ্যাপ্লাই হয়।
2. User — ~/.claude/CLAUDE.md, তোমার সব প্রজেক্টে অ্যাপ্লাই হয়।
3. Project — ./CLAUDE.md, git-এ চেক-ইন করা আর টিমের সাথে শেয়ার্ড।
4. Local — ./CLAUDE.local.md, gitignore করা, তোমার পার্সোনাল ওভাররাইডের জন্য।

মনোরেপোতে, প্যারেন্ট-ডিরেক্টরির ফাইল অটো-লোড হয় আর চাইল্ড-ডিরেক্টরির ফাইল অন-ডিমান্ড লোড হয়। ইমপোর্ট @path/to/file সিনট্যাক্স ইউজ করে (রিলেটিভ বা অ্যাবসোলিউট), 4 hop পর্যন্ত নেস্ট হতে পারে, আর পার্সার কোড ব্লক স্কিপ করে দেয় — তাই fenced ব্লকের ভেতরের একটা পাথ ইমপোর্ট হিসেবে ট্রিট হয় না।

AGENTS.md রেজলভ করে closest-wins। Codex Git root থেকে নিচে তোমার কারেন্ট ওয়ার্কিং ডিরেক্টরি পর্যন্ত হাঁটে আর যা পায় সেগুলো concatenate করে, root-first। কাছের ফাইল পরে আসে বলে সেগুলো ওভাররাইড করে — closest ফাইল জেতে। মনোরেপোতে প্রতি প্যাকেজে একটা করে AGENTS.md রাখো, আর যেটা এডিট হওয়া কোডের সবচেয়ে কাছে সেটাই প্রায়োরিটি পায়। এসবের ওপরে: চ্যাটের একটা এক্সপ্লিসিট ইনস্ট্রাকশন প্রতিটা ফাইলকে ওভাররাইড করে।

আর আগের ক্রস-টুল ব্রিজটা দুই সিস্টেমকে একসাথে টাই করে: AGENTS.md-কে ক্যানোনিকাল রাখো, একটা CLAUDE.md যোগ করো যেটা @AGENTS.md করে, আর তোমার হায়ারার্কি ডুপ্লিকেশন ছাড়াই সব টুলে শেয়ারড হয়ে যায়।

Advisory, এনফোর্সমেন্ট না

এখানে একটা nuance আছে যেটা তোমাকে একটা false sense of safety থেকে বাঁচায়: এই ফাইলগুলো advisory কনটেক্সট, deterministic এনফোর্সমেন্ট না। এগুলো এজেন্টকে স্টিয়ার করে; বাইন্ড করে না।

IMPORTANT আর YOU MUST-এর মতো এমফ্যাসিস ওয়ার্ড adherence মেজারেবলি ইমপ্রুভ করে — কিন্তু গ্যারান্টি দেয় না। যেসব রিকোয়ারমেন্ট প্রতিবার হওয়া লাগে (ফরম্যাটার রান করা, ফেইল হওয়া টেস্টের কমিট ব্লক করা, কখনো main-এ রাইট না করা), তার জন্য deterministic ব্যাকস্টপ হলো hooks (Claude Code-এ), কনফিগে জোরালো ওয়ার্ডিং না।

রুল অফ থাম্ব: গাইডেন্স আর হিউরিস্টিকের জন্য কনফিগ ইউজ করো; যেই মুহূর্তে "এজেন্ট usually এটা করে" যথেষ্ট না হয় আর তোমার "এজেন্ট always এটা করে" লাগে, তখনই hooks-এ যাও।

কোডের মতো মেইনটেইন করো

কনফিগ ফাইল একটা লিভিং আর্টিফ্যাক্ট, ওয়ান-টাইম রাইট না। বাকি রেপোর মতোই ট্রিট করো।

• /init দিয়ে বুটস্ট্র্যাপ করো। টুলকে তোমার কোডবেস থেকে প্রথম ড্রাফট জেনারেট করতে দাও, তারপর হাতে রিফাইন করো — জেনারেটেড ভার্সনটা একটা স্টার্টিং পয়েন্ট, ফিনিশড ফাইল না।
• যখন কিছু ভুল হয়, রিভিউ করো। যখনই এজেন্ট কোনো dumb জিনিস করে, জিজ্ঞেস করো কনফিগে মিসিং বা মিসলিডিং কোনো লাইন এর কারণ কি না।
• রেগুলার prune করো। পুরো ফাইলে আবার পার-লাইন টেস্ট রান করো। যেসব লাইন গত কোয়ার্টারে load-bearing ছিল সেগুলো এখন dead weight হতে পারে।
• বিহেভিয়ার দিয়ে চেঞ্জ টেস্ট করো। একটা এডিট হেল্প করেছে বলে বিশ্বাস করো না — অবজার্ভ করো এজেন্টের বিহেভিয়ার আসলেই শিফট হলো কি না। ডিফারেন্স দেখতে না পেলে, লাইনটা সম্ভবত কোনো কাজ করছে না।
• Git-এ চেক করো। একটা শেয়ার্ড, ভার্সন-কন্ট্রোলড কনফিগ মানে পুরো টিম কনট্রিবিউট করে আর বেনিফিট পায়, আর চেঞ্জগুলো রিভিউতে দেখা যায়।

সবচেয়ে ভ্যালুয়েবল হ্যাবিট হলো self-improving loop: এজেন্ট যখন ভুল করে, একটা সিঙ্গেল ওয়ান-লাইন রুল অ্যাড করো যাতে সেটা রিপিট না হয়। কয়েক সপ্তাহে এই লুপ তোমার কনফিগকে কনভার্জ করে দেয় ঠিক তোমার প্রজেক্টের আসল গচাগুলোর দিকে — বেশি না, কমও না।

একটা স্টার্টার AGENTS.md

এখানে একটা রিয়েল, কপি-পেস্ট করার মতো স্কেলিটন যেখানে সব ছয়টা হাই-ROI সেকশন রিয়েলিস্টিক প্লেসহোল্ডার দিয়ে ভরা। তোমার স্পেসিফিক জিনিস বসাও আর পার-লাইন টেস্টে যা টেকে না সেটা মুছে দাও।

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

সব টুলে একটা সিঙ্গেল সোর্স অফ ট্রুথের জন্য, পাশে একটা ওয়ান-লাইন `CLAUDE.md` রাখো যাতে `@AGENTS.md` আছে, আর তোমার ডিপার আর্কিটেকচার নোট (একটা `DESIGN.md`, তোমার ADR) পেস্ট না করে লিংক করো।

## এরপর কোথায় যাবে

একটা লিন, স্পেসিফিক কনফিগ ফাইল হলো সেই কনক্রিট বিহেভিয়ারগুলোর একটা যেটা AI-assisted ডেভেলপারদের সত্যিকার AI-native ডেভেলপারদের থেকে আলাদা করে। তিন মিনিটে [তোমার AI-native লেভেল বের করো](/quiz) — এটা ঠিক এই ধরনের ক্রাফট গ্রেড করে — আর যখন তোমার টুলচেইন ওয়্যার-আপ করার জন্য রেডি, [রেকমেন্ডেড ProCoders স্ট্যাক](/stack) দিয়ে শুরু করো।

> **সম্পর্কিত:** [a compound system-এর অ্যানাটমি](/compound-v/system) দেখায় কীভাবে ProCoders-এর Compound V এই আইডিয়াগুলোকে একটা রিয়েল, রিভিউড মাল্টি-এজেন্ট ওয়ার্কফ্লোতে অ্যাসেম্বল করে।