CLAUDE.md ও AGENTS.md: এগুলো কী, কী লিখবেন, এবং এজেন্ট নিয়ম উপেক্ষা করে কেন

CLAUDE.md ও AGENTS.md কী

দুটিই রিপোজিটরির মূলে থাকা সাধারণ Markdown ফাইল, যা সেশনের শুরুতে এজেন্ট স্বয়ংক্রিয়ভাবে প্রসঙ্গে লোড করে। এখানে আপনি এজেন্টকে এমন কথা জানান, যা সে কোড থেকে নিজে জানতে পারে না: পরিবেশ কীভাবে চালু করতে হবে, কোন কমান্ড দিয়ে কাজ যাচাই করতে হবে, কোন প্রকল্প-নিয়ম আলোচনাযোগ্য নয়, এবং বিস্তারিত নথি কোথায়।

CLAUDE.md হলো Claude Code-এর পড়া ফাইল। AGENTS.md একটি উন্মুক্ত ফরম্যাট, একই ধারণার ওপর ভিত্তি করে, যা অনেক coding এজেন্ট সমর্থন করে। দলে যদি একাধিক এজেন্ট ব্যবহৃত হয়, মূল বিষয়বস্তু AGENTS.md-এ রাখা সুবিধাজনক, আর CLAUDE.md-এ সেটির উল্লেখ থাকবে। Claude Code @ চিহ্ন দিয়ে অন্য ফাইল আমদানি সমর্থন করে:

# CLAUDE.md
@AGENTS.md

এভাবে নিয়মগুলো একটি জায়গায় থাকে এবং দুই ফাইলের মধ্যে গরমিল হয় না।

এজেন্ট এই ফাইলগুলো কীভাবে পড়ে

নির্দেশনার ফাইলের বিষয়বস্তু system prompt-এর সঙ্গে মডেলের প্রসঙ্গ-জানালায় ঢোকে এবং পুরো সেশন ধরে সেখানে থাকে। এর তিনটি গুরুত্বপূর্ণ ফল আছে।

• প্রতিটি লাইন প্রসঙ্গে জায়গা নেয়। প্রতিটি শুরুতে পুরো ফাইল পড়া হয়, যদিও বর্তমান কাজের জন্য তার এক-দশমাংশই লাগে।
• এগুলো কার্যকর নিয়ম নয়, লেখা মাত্র। মডেল সেগুলো অন্য প্রসঙ্গের সঙ্গে বিবেচনা করে, এবং শতভাগ মেনে চলার কোনো নিশ্চয়তা নেই। কঠোর নিষেধ যান্ত্রিক ব্যবস্থা দিয়ে সমর্থন করতে হয়: যাচাই, hook ও প্রবেশাধিকার সীমা।
• ফাইল স্তরে স্তরে রাখা যায়। Claude Code প্রকল্পের মূল থেকে ও ~/.claude/ ব্যবহারকারী-ফোল্ডার থেকে CLAUDE.md লোড করে, আর সাব-ফোল্ডারের ফাইল লোড হয় যখন এজেন্ট সেই ফোল্ডারের ফাইল নিয়ে কাজ করে। ফলে মডিউলের নিয়ম মডিউলের পাশেই রাখা যায়।

CLAUDE.md ও AGENTS.md-এ কী লিখবেন

ভালো নির্দেশনার ফাইল মানচিত্র, পাঠ্যবই নয়। নতুন কর্মী প্রথম দিনে সিনিয়র সহকর্মীকে যে প্রশ্নগুলো করত, ফাইলটি সেগুলোর উত্তর দেয়।

১. প্রকল্প কীভাবে গড়তে ও যাচাই করতে হয়

সবচেয়ে মূল্যবান অংশ। যেসব নির্দিষ্ট কমান্ড এজেন্টকে «সম্পন্ন» বলার আগে অবশ্যই চালাতে হবে: test, linter, type check, পরিবেশ চালু করা। এগুলো না থাকলে এজেন্ট নিজেকে «চোখের আন্দাজে» যাচাই করে।

২. কঠোর সীমা

এমন একটি ছোট তালিকা, যা কোনো অবস্থাতেই লঙ্ঘন করা যাবে না: নিরাপত্তা ও ডেটার invariant। এগুলো invariant হিসেবে লিখুন, বাস্তবায়নের নির্দেশ হিসেবে নয়: «সব SQL query parameterized», «নির্দিষ্ট ফাইলের নির্দিষ্ট ফাংশন ব্যবহার করো» নয়।

৩. প্রকল্পের মানচিত্র

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

৪. কাজের অবস্থা কোথায় থাকে

আগের সেশন যেখানে থামল সেখান থেকে এগোতে কোথায় তাকাতে হবে: পরিকল্পনার ফাইল, অগ্রগতির লগ বা backlog। এতে সেশনের মধ্যে এজেন্টের «বিস্মৃতি» সারে।

যা লিখবেন না

• এজেন্ট যা কোড থেকে জানতে পারে। Dependency-র তালিকা package.json বা pyproject.toml-এ আছে, ক্লাসের কাঠামো কোডেই আছে।
• সাধারণ পরামর্শ। «পরিষ্কার কোড লেখো» বা «সতর্ক থেকো» আচরণ বদলায় না, শুধু জায়গা নেয়।
• প্রকল্পের ইতিহাস ও এককালীন নোট। «মার্চে আমরা MySQL 5.7 থেকে সরেছি» বর্তমান কাজে সাহায্য করে না।
• বিরল কাজের বিস্তারিত নির্দেশ। Deploy বা ডেটা migration-এর প্রক্রিয়া সপ্তাহে একবার লাগে — আলাদা নথি বা skill-এ রাখুন।
• গোপন তথ্য। ফাইলটি repository-তে থাকে এবং পুরোটাই মডেলে যায়। Token ও পাসওয়ার্ড শুধু পরিবেশ-ভেরিয়েবলে রাখুন।

ফাইলে লেখা নিয়ম এজেন্ট কেন উপেক্ষা করে

একটি পরিচিত ঘটনা: এজেন্ট ভুল করল, ফাইলে একটি নিয়ম যোগ হলো। আবার ভুল, আরেকটি নিয়ম। কয়েক মাস পরে ফাইলে শত শত লাইন, আর গুরুত্বপূর্ণ নিরাপত্তা-নিয়ম এজেন্ট এমনভাবে লঙ্ঘন করে যেন সেটি কখনো ছিলই না। সাধারণত চারটি কারণ একসঙ্গে কাজ করে।

ফুলে ওঠা ফাইল

৬০০ লাইনের ফাইল মোটামুটি ১০–২০ হাজার টোকেন। প্রসঙ্গ-জানালা বিশাল মনে হয়, কিন্তু সেটি কোড, কমান্ডের আউটপুট ও কথোপকথনের ইতিহাসের মধ্যে ভাগাভাগি হয়। নির্দেশনা যত জায়গা নেয়, প্রতিটি নিয়ম তত কম মনোযোগ পায় এবং কাজের নিজের জন্য জায়গা তত কমে।

মাঝখানের নিয়ম

ভাষা মডেল দীর্ঘ লেখার মাঝখানের তথ্য শুরু ও শেষের তুলনায় অনেক দুর্বলভাবে ব্যবহার করে। ৬০০ লাইনের মধ্যে ৩০০তম লাইনের নিয়ম সবচেয়ে দুর্বল জায়গায় পড়ে।

অগ্রাধিকার নেই

একটি অলঙ্ঘনীয় নিষেধ আর একটি ক্ষণিকের স্টাইল-নোট একই রকমভাবে লেখা হয়, তালিকার এক লাইন হিসেবে। এজেন্ট জানে না কোনটি বেশি গুরুত্বপূর্ণ। আর যদি তিনটি পরস্পরবিরোধী স্টাইল-নিয়ম থাকে, তার আচরণ এক চালানো থেকে আরেক চালানো পর্যন্ত এলোমেলো হয়।

পচন

নিয়ম যোগ করা বিনামূল্যে, কিন্তু মুছতে ভয় হয়: «হয়তো এর ওপর কিছু নির্ভর করছে»। তাই ফাইল একটানা বাড়তে থাকে, আর কাজের লাইনের অনুপাত কমে। এটি মাপা যায় সংকেত-ও-শব্দের অনুপাতে: একটি সাধারণ কাজের জন্য কতটি লাইন সত্যিই দরকার, আর কতটি দরকার নেই।

কীভাবে ঠিক করবেন: বস্তার বদলে রাউটার

একটি কারণ ঠিক করলেই হবে না: ফাইল ছোট করলেও কাঠামো না থাকলে নিয়মগুলো মিশে থাকে। কয়েকটি ব্যবস্থার সমন্বয় কাজ করে।

1. প্রবেশ-ফাইলকে রাউটার বানান। ৫০–১৫০ লাইন: যাচাই-কমান্ড, কঠোর সীমা, প্রকল্পের মানচিত্র ও বিষয়ভিত্তিক নথির লিংক।
2. বিষয়গুলো আলাদা ফাইলে সরান। যেমন docs/agents/deploy.md, docs/agents/database.md। প্রয়োজনে এজেন্ট খুলবে। Claude Code-এ পুনরাবৃত্ত প্রক্রিয়ার জন্য skills ভালো, কারণ সেগুলো শুধু দরকার হলে লোড হয়।
3. গুরুত্বপূর্ণটা উপরে তুলুন। কঠোর সীমা ফাইলের শুরুতে, MUST চিহ্নসহ একটি ছোট আলাদা ব্লকে।
4. পরস্পরবিরোধ দূর করুন। প্রতিটি বিষয়ে একটি নিয়ম। ব্যতিক্রম থাকলে সেটি নিয়মের পাশেই লিখুন।
5. নিয়মকে যান্ত্রিক ব্যবস্থা দিয়ে সমর্থন করুন। লঙ্ঘন অসম্ভব হওয়া উচিত হলে শুধু লেখা যথেষ্ট নয়। লাগবে এমন যাচাই যা ধরে ফেলে: linter, test, pre-commit hook বা এজেন্টের hook, অথবা প্রবেশাধিকারের সীমা।
6. নিয়মিত পর্যালোচনা করুন। লাইনের সীমা ঠিক করুন, আর প্রতিবার নতুন কিছু যোগ করার সময় জিজ্ঞেস করুন কী বাদ দেওয়া বা সরানো যায়।

নিয়ম না যাচাই?

একটি সংক্ষিপ্ত AGENTS.md-এর উদাহরণ

# AGENTS.md — payment backend (FastAPI, PostgreSQL)

## MUST — লঙ্ঘন নয়
- টাকার পরিমাণ int, পয়সায়; কখনো float নয়
- শুধু parameterized SQL, f-string নয়
- প্রয়োগ হওয়া migration বদলাবে না, শুধু নতুন migration যোগ করবে
- Secret শুধু পরিবেশ-ভেরিয়েবল থেকে

## «সম্পন্ন» বলার আগে যাচাই
docker compose up -d     # পরিবেশ
make lint                # ruff + mypy
make test                # pytest
make e2e                 # checkout পরিস্থিতি
শুধু unit test সবুজ হলে, e2e ছাড়া, তা «সম্পন্ন» নয়।

## মানচিত্র
- app/payments/   — হিসাব, ছাড়, provider webhook
- app/api/        — HTTP endpoint
- tests/e2e/      — ব্যবহারকারীর পরিস্থিতি
বিস্তারিত: docs/agents/architecture.md, docs/agents/database.md

## কাজের অবস্থা
- PLAN.md      — বর্তমান লক্ষ্য, সমাপ্তির মানদণ্ড, পরের ধাপ
- PROGRESS.md  — কী করা হয়েছে ও কীভাবে যাচাই হয়েছে, বন্ধ পথ
- BACKLOG.md   — «সঙ্গে» চোখে পড়া বিষয়: এখানে লিখুন, এখনই ঠিক করবেন না

সেশনের শেষে PROGRESS.md ও PLAN.md-এর পরের ধাপ হালনাগাদ করো।

লক্ষ্য করুন কী নেই: লাইব্রেরির তালিকা, স্টাইল-পরামর্শ, প্রকল্পের ইতিহাস। এগুলো হয় কোড থেকে দেখা যায়, নয়তো যাচাই দিয়ে আটকানো, নয়তো বিষয়ভিত্তিক নথিতে।

সেশনের বিস্মৃতি: নির্দেশনার ফাইল ও পরিকল্পনার ফাইল

নির্দেশনার ফাইল বলে প্রকল্পে কীভাবে কাজ করতে হয়, কিন্তু এখন কী চলছে তা বলে না। সে জন্য আলাদা একটি অবস্থার ফাইল দরকার, যা এজেন্ট শুরুতে পড়ে এবং সেশনের শেষে হালনাগাদ করে। এতে থাকে: লক্ষ্য, সম্পন্ন কাজ ও কীভাবে যাচাই হয়েছে, সিদ্ধান্ত ও কারণ, বাতিল বিকল্পসমূহ, এবং পরের ধাপের একটি বাক্য। মানের পরীক্ষা সহজ: নতুন সেশন খুলে «চালিয়ে যাও» লিখুন এবং দেখুন এজেন্ট প্রশ্ন ছাড়াই কার্যকর কাজ শুরু করে কি না।

দুটি ফাইল মেশাবেন না। নির্দেশনা কম বদলায় এবং সব কাজে প্রযোজ্য। পরিকল্পনা প্রতি সেশনে বদলায় এবং বর্তমান কাজে প্রযোজ্য। মেশালে নির্দেশনার ফাইল দ্রুত পুরনো নোটে ভরে যায়।

ফাইল কাজ করছে কি না, কীভাবে যাচাই করবেন

নির্দেশনার ফাইলেরও যাচাই দরকার। কয়েকটি সাধারণ কাজ নিন — bug ঠিক করা, ছোট ফিচার, refactor — এবং দেখুন এজেন্ট ইঙ্গিত ছাড়া কী করে: সঠিক কমান্ড চালায় কি না, সঠিক বিষয়ভিত্তিক নথি খোলে কি না, কঠোর সীমা মানে কি না। কোনো নিয়ম লঙ্ঘিত হলে আগে জিজ্ঞেস করুন: নিয়মটি দৃশ্যমান কি না, এর সঙ্গে বিরোধ আছে কি না, এবং এটিকে স্বয়ংক্রিয় যাচাই দিয়ে বদলানো যায় কি না। নতুন লাইন যোগ করা সর্বশেষ উপায়।

সারসংক্ষেপ

CLAUDE.md ও AGENTS.md এজেন্টের প্রকল্পে প্রবেশদ্বার। সংক্ষিপ্ত মানচিত্র হিসেবে থাকলেই এগুলো কাজ করে: যাচাই-কমান্ড, উপরে কঠোর সীমা, বিস্তারিতের ও পরিকল্পনার ফাইলের লিংক। কোনো নিয়ম উপেক্ষিত হলে কারণ প্রায় সবসময় ফুলে ওঠা, অগোছালো ফাইল, আর সত্যিকারের গুরুত্বপূর্ণ নিয়মগুলোকে যাচাই ও hook দিয়ে সমর্থন করতে হবে। নির্দেশনা ও অবস্থা কীভাবে সাজাতে হয়, তা হাতে-কলমে harness engineering কোর্সে শেখানো হয়।