AGENTS.md ও HUMAN.md: পার্থক্য ও ব্যবহার

AGENTS.md কী

AGENTS.md হলো একটি repository-এর root-এ থাকা সাধারণ markdown ফাইল। এটি coding agent-কে প্রকল্পে কীভাবে কাজ করতে হবে তা জানায়। অফিসিয়াল সাইটে এটিকে বলা হয়েছে: “agents-এর জন্য একটি README: আপনার প্রকল্পে AI coding agent-কে কাজ করতে সাহায্য করার জন্য প্রাসঙ্গিক তথ্য ও নির্দেশনা দেওয়ার একটি নির্দিষ্ট, পূর্বানুমেয় স্থান।” এই format-এর তত্ত্বাবধান করে Linux Foundation-এর অধীন Agentic AI Foundation। 2026 সালের July পর্যন্ত Codex, Cursor, Jules, Devin এবং GitHub Copilot-সহ 20-এর বেশি agent এটি পড়ে।

এই convention-এর কারণ ব্যবহারিক। আপনার দলের নতুন একজন সদস্য README পড়ে build command অনুমান করেন। অনুমান ভুল হলে তিনি কাউকে জিজ্ঞেস করেন। Agent তা করতে পারে না। এটি এমন একটি প্রকল্পে npm test চালায়, যেখানে pnpm test ব্যবহৃত হয়। ব্যর্থতার ফল পড়ে অন্য কিছু চেষ্টা করে। এই প্রতিটি token-এর জন্য আপনার খরচ হয়। প্রকৃত command একবার লিখে রাখলে এই ধরনের সম্পূর্ণ ব্যর্থতা এড়ানো যায়।

কোনো field বাধ্যতামূলক নয়। সাইটে বিষয়টি স্পষ্টভাবে বলা হয়েছে: “AGENTS.md শুধু standard Markdown। আপনার পছন্দের যেকোনো heading ব্যবহার করুন; agent আপনার দেওয়া text পার্স করে।” এটিই সম্পূর্ণ specification। এর মূল্য format-এ নয়। মূল্য হলো এমন একটি path-এ ফাইলটি থাকা, যেখানে প্রতিটি tool আগে থেকেই এটি খোঁজে।

ফাইলটি কোথায় রাখতে হবে এবং কোন ফাইল প্রাধান্য পায়

প্রথম ফাইলটি repository root-এ রাখুন। একটি monorepo-তে প্রতিটি subproject-এর ভেতরেও অতিরিক্ত ফাইল যোগ করতে পারেন। নিয়মটি সহজ: “agents directory tree-তে নিকটতম ফাইলটি স্বয়ংক্রিয়ভাবে পড়ে, তাই সবচেয়ে কাছের ফাইলটি প্রাধান্য পায়।” দুটি ফাইলের মধ্যে বিরোধ হলে যে ফাইলটি সম্পাদনা করা হচ্ছে, সেই ফাইলের দিকেই সমাধান নির্ধারিত হয়। আর chat-এ আপনি যা লিখবেন, তা উভয় ফাইলের নির্দেশনাকে অগ্রাহ্য করে।

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

এই nesting ব্যবহার করা উপযোগী, কারণ একই folder-এ সত্য এবং পরের folder-এ মিথ্যা—এমন কিছু বলার এটিই একমাত্র উপায়। “প্রতিটি endpoint তার input যাচাই করে”—এমন নিয়ম endpoints-এর পাশে থাকা উচিত। root file-এ রাখলে এটি সম্পর্কহীন প্রতিটি task-এ load হবে এবং কোনো উপকার দেবে না।

AGENTS.md-এ কী থাকা উচিত

কোড পড়ে কোনো agent যে তথ্য নির্ধারণ করতে পারে না, তা লিখে রাখুন। প্রথমে সঠিক build, test এবং lint কমান্ড দিন, এমনভাবে লিখুন যেন সেগুলো টার্মিনালে পেস্ট করা যায়। একটি test চালানোর কমান্ডও যোগ করুন। কারণ, কোনো agent যদি শুধু পুরো test suite চালানোর পদ্ধতি জানে, তাহলে সে পুরো suite চল্লিশবার চালাবে। যেসব convention tool-এর default থেকে ভিন্ন, সেগুলোর নাম উল্লেখ করুন। agent default জানে; তাকে শুধু আপনার ভিন্নতার কথা জানাতে হবে। Commit message-এর কাঠামো এবং pull request-এর নিয়ম থাকলে সেগুলোও যোগ করুন।

এমন নির্দিষ্ট নির্দেশনা দিন, যাতে কোনো দাবি যাচাই করা যায়। “2-space indentation ব্যবহার করুন” একটি কার্যকর নির্দেশনা, কারণ এটি মানা হয়েছে কি না যাচাই করা যায়। “কোড সঠিকভাবে format করুন” কার্যকর নয়, কারণ এর কোনো অংশ যাচাই করা যায় না। Location-এর ক্ষেত্রেও একই কথা প্রযোজ্য: “API handler-গুলো src/api/handlers/-এ থাকে” বলা “ফাইলগুলো সুসংগঠিত রাখুন”-এর চেয়ে ভালো।

Negative rule-গুলোরও স্থান থাকা উচিত। “dist/-এর অধীনে থাকা ফাইল কখনো সম্পাদনা করবেন না; এগুলো npm run build দ্বারা তৈরি হয়”—এই নির্দেশনা একটি নির্দিষ্ট ভুল ঠেকায়। কারণটি উল্লেখ থাকায়, agent আপনার লেখা হয়নি এমন সমতুল্য ক্ষেত্রও নির্ধারণ করতে পারে।

যেগুলো কখনো এতে রাখা উচিত নয়

এই ফাইলগুলোর কোনোটিতেই কখনো কোনো গোপন তথ্য রাখবেন না। ফাইলটি git-এ commit করা হয়, প্রতিটি session-এর শুরুতে context-এ load করা হয় এবং প্রতিটি request-এ model provider-এর কাছে পাঠানো হয়। AGENTS.md-তে থাকা একটি API key আপনার repository history-তেও থাকে এবং third party-এর logs-এও থাকে। গোপন তথ্যটি সরাসরি লিখে না দিয়ে তার অবস্থান উল্লেখ করুন: “database password .env-এ আছে, যা gitignored; এটি পড়ার আগে জিজ্ঞাসা করুন।” বৃহত্তর এই নীতিটি agent-এর নাগালের বাইরে credentials রাখা-এ ব্যাখ্যা করা হয়েছে।

Agent নিজে দেখে যা নির্ধারণ করতে পারে, তা বাদ দিন। সরাসরি লেখা directory listing, আপনার dependency list-এর একটি অনুলিপি, অথবা folder-এর নামগুলো পুনরাবৃত্তি করা architecture overview—এসবই লেখার এক সপ্তাহ পর পুরোনো হয়ে যায়, অথচ এর মধ্যে প্রতিটি session-এ context খরচ করে। সমস্যার ঝুঁকি এবং কারণগুলো রাখুন। তালিকাটি বাদ দিন।

CLAUDE.md একই ধারণার Claude Code সংস্করণ

Claude Code CLAUDE.md পড়ে, কিন্তু নিজে থেকে AGENTS.md পড়ে না। একটি প্রকল্পের ফাইল ./CLAUDE.md অথবা ./.claude/CLAUDE.md-এ থাকে, প্রতিটি প্রকল্পের জন্য ব্যক্তিগত পছন্দ ~/.claude/CLAUDE.md-এ রাখা হয়, এবং Linux-এ কোনও প্রতিষ্ঠান /etc/claude-code/CLAUDE.md-এ পুরো মেশিনের জন্য একটি ফাইল স্থাপন করতে পারে। আবিষ্কৃত ফাইলগুলো ফাইলসিস্টেমের root থেকে আপনার working directory পর্যন্ত ক্রমানুসারে যুক্ত হয়। তাই আপনি যে স্থান থেকে session চালু করেছেন, তার সবচেয়ে কাছের ফাইলটি সর্বশেষে পড়া হয়।

আপনার repository-তে যদি ইতিমধ্যে AGENTS.md থাকে, তাহলে দ্বিতীয় একটি কপি রক্ষণাবেক্ষণ করবেন না। সেটি import করুন, তারপর শুধু Claude-নির্দিষ্ট বিষয় যোগ করুন:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

অতিরিক্ত কিছু যোগ করার না থাকলে একটি symlink কাজ করে:

ln -s AGENTS.md CLAUDE.md

সফল হলে command কোনও output দেয় না। পরের session-এ /context চালান এবং Memory files-এর অধীনে CLAUDE.md দেখা যাচ্ছে কি না নিশ্চিত করুন। ওই তালিকায় এটি না থাকলে ফাইলটি কখনও load হয়নি, তাই এর কোনও নির্দেশ কার্যকর হয়নি। নিজে ফাইল না লিখে প্রথম খসড়া তৈরি করতে /init চালান। এটি codebase পড়ে একটি প্রাথমিক ফাইল তৈরি করে। CLAUDE.md ইতিমধ্যে থাকলে সেটি overwrite না করে উন্নতির পরামর্শ দেয়।

প্রতিটি ফাইল প্রায় 200 লাইনের মধ্যে রাখুন। দীর্ঘ ফাইল window-এর বেশি অংশ ব্যবহার করে এবং নির্দেশ মেনে চলার হার কমে যায়। ওই জায়গার জন্য আর কী কী প্রতিযোগিতা করে তা দেখতে agent-এর context window-তে আসলে কী থাকে বিষয়টি বিস্তারিত ব্যাখ্যা করে।

একটি বিষয় বিশেষভাবে মনে রাখুন। AGENTS.md হল নির্দেশনা, permission system নয়। এর বিষয়বস্তু সাধারণ context হিসেবে আসে। তাই model এটি পড়ে এবং সাধারণত মেনে চলে, কিন্তু এর বিরোধী কোনও action-কে এটি আটকায় না। "never push to main"-এর মতো যে নিয়ম প্রতিবারই কার্যকর থাকতে হবে, তার জন্য hook অথবা permission setting ব্যবহার করুন। এগুলো code হিসেবে চলে এবং model মেনে চলার সিদ্ধান্ত নেবে কি না, তার ওপর নির্ভর করে না।

আপনার হয়ে এই ফাইলগুলো লেখে এমন টুল

30 July 2026-এর GitHub trending তালিকার 2টি প্রকল্প দেখায়, এই রীতি কোন দিকে এগোচ্ছে।

agent0ai/dox (July 2026 পর্যন্ত 1,368টি star) হলো AGENTS.md ফাইলগুলোর একটি tree হালনাগাদ রাখার framework। এটি কোনো package বা runtime ship করে না। আপনি এর AGENTS.md-এর বিষয়বস্তু নিজের root AGENTS.md-তে কপি করবেন, আর এটিই install প্রক্রিয়া। আগে থেকেই থাকা কোনো project-এর জন্য agent-কে বলুন:

Initialize DOX tree for this project now.

এরপর agent child AGENTS.md ফাইল ও তাদের index তৈরি করে। কোনো কিছু edit করার আগে এটি ওই tree পর্যালোচনা করে। কোনো change প্রয়োগ হলে এটি প্রভাবিত documentation হালনাগাদ করে। এর পেছনের ধারণা হলো, agent তার কাজের পার্শ্বপ্রতিক্রিয়া হিসেবে যে documentation রক্ষণাবেক্ষণ করে, তা সঠিক থাকে। কিন্তু কোনো ব্যক্তি হাতে যে documentation হালনাগাদ করে, তা সঠিক থাকে না।

HUMAN.md, আপনার ওপর প্রয়োগ করা একই কৌশল

Intuition-Lab/personal-model (July 2026 পর্যন্ত 1,260টি star) repository-এর পরিবর্তে একজন ব্যক্তির ওপর এই প্যাটার্ন প্রয়োগ করে। প্রকল্পটি আপনার HUMAN.md-কে আপনার টাইপ করা ফাইল হিসেবে নয়, বরং সিস্টেমের আউটপুট হিসেবে উপস্থাপন করে: "বর্তমানে কোন বিষয়গুলো গুরুত্বপূর্ণ, আপনি সাধারণত কীভাবে সিদ্ধান্ত নেন এবং আপনার মনোযোগ কোন দিকে যাচ্ছে—তার একটি চলমান মডেল।" এটি macOS 13 বা পরবর্তী সংস্করণে স্থানীয়ভাবে চলে, আপনি macOS-এর অনুমতি দেওয়ার পর কার্যকলাপ সংগ্রহ করে এবং MCP (model context protocol)-এর মাধ্যমে agents-এর কাছে ফলাফল প্রকাশ করে। সংক্ষিপ্ত ইনস্টল পদ্ধতি:

uv tool install personal-model
persome onboard
persome model open --after 30

বেশিরভাগ সুবিধা পেতে এর কোনোটিই আপনার প্রয়োজন নেই। হাতে লেখা HUMAN.md প্রায় বিশ লাইনের হয়: আপনার ভূমিকা, আপনার timezone, আপনি বাস্তবে যে stack ব্যবহার করেন, ইতিমধ্যে নেওয়া এবং পুনরায় আলোচনায় আনতে চান না এমন সিদ্ধান্তগুলো, এবং আপনি কতটা ব্যাখ্যা ফিরে পেতে চান। এটি project file যে পুনরাবৃত্ত ব্যাখ্যা সাশ্রয় করে, একই কাজটি এক স্তর ওপরে করে।

একটি সতর্কতা মনে রাখুন। HUMAN.md একজন ব্যক্তির profile, তাই এটি স্বভাবতই সংবেদনশীল। এটিকে public repository-এর বাইরে রাখুন। এটি ~/.claude/CLAUDE.md-এ রাখুন, অথবা project root-এ gitignored CLAUDE.local.md-এ রাখুন। এটি committed file-এর পাশাপাশি load হয় এবং একইভাবে ব্যবহৃত হয়।

কপি করার জন্য একটি প্রাথমিক টেমপ্লেট

এটি ইচ্ছাকৃতভাবে সংক্ষিপ্ত। যেসব section প্রযোজ্য নয়, সেগুলো মুছে দিন। যেসব section নিয়মিত আপডেট রাখতে পারবেন না, সেগুলো যোগ করা এড়িয়ে চলুন।

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

এটি লিখে একই জায়গায় সংশোধন করুন। কোনো line যোগ করার সংকেত হলো, আপনি chat-এ একই সংশোধন দুবার লিখেছেন। এই একটি নিয়ম file-টিকে কার্যকর রাখে। একই সঙ্গে এটি file-টি এমন document-এ পরিণত হওয়া বন্ধ করে, যা কেউ পড়ে না, এমনকি machine-ও নয়। file-টি স্থিতিশীল হলে এটি repository-এর সঙ্গেই থাকে। Agent যখন আপনার laptop ছাড়া অন্য কোথাও চলে, তখন এটি বিশেষভাবে গুরুত্বপূর্ণ: নিজের server-এ coding agent চালানো-তে সেই setup ব্যাখ্যা করা হয়েছে।

FAQ

AGENTS.md কি CLAUDE.md-এর একই ফাইল?

একই ধারণা, তবে দুটি filename-এর অধীনে। Claude Code CLAUDE.md পড়ে এবং AGENTS.md উপেক্ষা করে, যদি না আপনি দুটিকে সংযুক্ত করেন। একটি ফাইলকে মূল উৎস হিসেবে রাখুন এবং অন্যটিকে তার সঙ্গে link করুন। এর জন্য আপনার CLAUDE.md-এর শুরুতে @AGENTS.md লেখা একটি line রাখতে পারেন, অথবা ln -s AGENTS.md CLAUDE.md ব্যবহার করতে পারেন। আলাদাভাবে রক্ষণাবেক্ষণ করা দুটি সম্পূর্ণ copy এক মাসের মধ্যেই অসামঞ্জস্যপূর্ণ হয়ে যাবে।

AGENTS.md লিখলেই কি agent তা মেনে চলবে?

না। এর content context হিসেবে দেওয়া হয়। তাই model এটি পড়ে এবং সাধারণত মেনে চলে। তবে এর বিরোধী কোনো action নেওয়া আটকানোর ব্যবস্থা থাকে না। অস্পষ্ট instruction সবচেয়ে কম নির্ভরযোগ্যভাবে মানা হয়। বিপরীত নির্দেশনা দেওয়া দুটি file থাকলে agent ইচ্ছামতো যেকোনো একটি বেছে নিতে পারে। যে rule প্রতিবার কার্যকর হওয়া আবশ্যক, তার জন্য hook বা permission rule ব্যবহার করুন। Model যে সিদ্ধান্তই নিক, client এগুলো প্রয়োগ করে।

AGENTS.md কি git-এ commit করা উচিত?

হ্যাঁ, project সম্পর্কে সত্য এমন সব বিষয়ের জন্য। এর মধ্যে build command, layout এবং convention অন্তর্ভুক্ত। ফাইলটির উদ্দেশ্যই হলো আপনার teammates-এর agent-গুলো যেন আপনার agent-এর মতো একই context দিয়ে শুরু করে। ব্যক্তিগত বা নির্দিষ্ট কোনো machine-এর জন্য প্রযোজ্য বিষয় আলাদা gitignored file-এ রাখুন। Credentials কোনো file-এ রাখবেন না।

HUMAN.md কী এবং আমার কি এটি দরকার?

HUMAN.md হলো project-এর পরিবর্তে কোনো ব্যক্তির machine-readable profile। এতে আপনার role, constraints এবং ইতিমধ্যে চূড়ান্ত করা সিদ্ধান্ত থাকে, যাতে প্রতিটি session-এ সেগুলো আবার আলোচনায় না আসে। শুরু করার জন্য কোনো tooling দরকার নেই। আপনার user-level instructions file-এ নিজে লেখা বিশটি line-ই বেশিরভাগ সুবিধা দেবে। এটিকে personal data হিসেবে বিবেচনা করুন এবং push করা কোনো repository-তে রাখবেন না।