AGENTS.md ও HUMAN.md: কী, কেন এবং কী লিখবেন

AGENTS.md কী

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

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

কোনো field বাধ্যতামূলক নয়। Site-এ বিষয়টি স্পষ্টভাবে বলা আছে: “AGENTS.md শুধুই standard Markdown। আপনার পছন্দের যেকোনো heading ব্যবহার করুন; agent আপনার দেওয়া text-ই parse করে।” এটিই সম্পূর্ণ specification। এর মূল্য format-এ নয়। মূল্য হলো এমন একটি path-এ file থাকা, যেটি প্রতিটি 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 validate করে"—এই ধরনের নিয়ম endpoint-গুলোর পাশে রাখা উচিত। root file-এ রাখলে প্রতিটি অসংশ্লিষ্ট task-এও এটি load হয়, কিন্তু কোনো সুবিধা দেয় না। আপনার root file-এ যদি ইতিমধ্যে প্রতিটি service-এর জন্য আলাদা section তৈরি হয়ে থাকে, তাহলে nested layout-এ ভাগ করে নেওয়াই সমাধান। এতে কোন নিয়ম নিচের স্তরে যাবে এবং কোনগুলো উপরে থাকবে, সেটিও নির্ধারিত হয়।

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

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

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

Negative rule-ও এখানে স্থান পাওয়ার যোগ্য। "npm run build দিয়ে তৈরি হওয়ায় dist/-এর অধীনে থাকা ফাইল কখনো edit করবেন না"—এই নিয়মটি একটি নির্দিষ্ট ভুল প্রতিরোধ করে। কারণটি উল্লেখ করা আছে বলে agent আপনার লেখা হয়নি এমন সমতুল্য ক্ষেত্রও বুঝতে পারে। Scope সম্পর্কিত নিয়মও এখানে রাখা উচিত। Agent-কে নিজের বিচারবুদ্ধির ওপর ছেড়ে দিলে আপনি যতটা চেয়েছেন তার চেয়ে বেশি পরিবর্তন করে ফেলতে পারে: বহুল ব্যবহৃত একটি skill-এর কাজই হলো কার্যকর সবচেয়ে ছোট পরিবর্তনের ওপর জোর দেওয়া।

একটিতেও যা কখনো রাখা উচিত নয়

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

Agent দেখে নিজে যা নির্ধারণ করতে পারে, তা বাদ দিন। Paste করা directory listing, dependency list-এর একটি অনুলিপি, folder name-গুলো পুনরায় উল্লেখ করা architecture overview—এসব লেখার এক সপ্তাহ পরই পুরোনো হয়ে যায়, অথচ এর মধ্যে প্রতিটি session-এ context খরচ করে। কোন বিষয়গুলোতে ভুল হতে পারে এবং তার কারণগুলো রাখুন। Inventory বাদ দিন। কারণগুলো আলাদা করে রাখা গুরুত্বপূর্ণ। কোনো unusual shape কেন আছে তা agent বুঝতে না পারলে সেটি নীরবে refactor করে সরিয়ে দেবে। এই কারণেই এটির পাশে একটি DESIGN.md রাখা হয়।

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

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

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

@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 দেখা যাচ্ছে কি না নিশ্চিত করুন। ওই তালিকায় এটি না থাকলে file-টি কখনো load হয়নি, তাই এর কোনো নির্দেশ কার্যকর হয়নি। নিজে file না লিখে প্রথম খসড়া তৈরি করতে /init চালান। এটি codebase পড়ে একটি প্রাথমিক file তৈরি করে। CLAUDE.md আগে থেকেই থাকলে এটি সেটি overwrite না করে উন্নতির পরামর্শ দেয়।

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

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

আপনার হয়ে এই ফাইল তৈরি করে এমন Tools

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

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

Initialize DOX tree for this project now.

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

HUMAN.md, একই কৌশলটি এবার আপনার দিকে নির্দেশিত

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

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

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

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

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

এটি ইচ্ছাকৃতভাবে সংক্ষিপ্ত রাখা হয়েছে। যে 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-এ দুবার লিখেছেন। এই একটি নিয়ম ফাইলটিকে কার্যকর রাখে এবং এটিকে এমন একটি document-এ পরিণত হওয়া ঠেকায়, যা কেউ পড়ে না, machine-ও নয়। স্থিতিশীল হলে ফাইলটি 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 এগুলো enforce করে।

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

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

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

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