SSD Nodes Learn Hosting plans →
নির্দেশিকা Matt Connorদ্বারা Matt Connor · আপডেট করা হয়েছে 2026-10-30

monorepo-তে nested AGENTS.md কীভাবে সাজাবেন

একটি বড় root AGENTS.md কেন stale হয়ে যায় তা জানুন। service directory অনুযায়ী nested layout সাজিয়ে agent-এর অপ্রয়োজনীয় context কমানোর ব্যবহারিক পদ্ধতি দেখুন।

monorepo-তে nested AGENTS.md-এর অর্থ

monorepo-তে nested AGENTS.md বলতে repository root-এ একটি ছোট ফাইল এবং প্রতিটি service directory-র ভিতরে আরও একটি ফাইল বোঝায়। root file-এ সর্বত্র প্রযোজ্য কয়েকটি নিয়ম এবং অন্য ফাইলগুলো কোথায় আছে তার একটি map থাকে। প্রতিটি service file-এ শুধু ওই directory-র commands এবং conventions থাকে। কোনো agent services/worker/queue.py সম্পাদনা করার সময় root file এবং worker file পড়ে; যে front end-এ সে কখনো কাজ করবে না, তার জন্য কোনো context ব্যয় হয় না।

কিছু install করার দরকার নেই। AGENTS.md একটি convention, এবং upstream project-ও তা স্পষ্টভাবে জানায়:

AGENTS.md শুধু standard Markdown। আপনার পছন্দমতো heading ব্যবহার করুন; agent কেবল আপনার দেওয়া text parse করে।

এই কারণেই কৌশলটি সঠিকভাবে শেখা গুরুত্বপূর্ণ। Format আপনার অজান্তে পরিবর্তিত হবে না। সমস্যা হয় placement এবং maintenance-এ, আর দুটির দায়িত্বই আপনার।

একটি বড় root AGENTS.md কেন আর কাজ করে না?

একটি repository-র root-এ থাকা 600-line-এর একক AGENTS.md, যেখানে একটি web app, একটি background worker এবং একটি Terraform directory আছে, চারটি পৃথক সমস্যায় ব্যর্থ হয়।

এটি পুরোনো হয়ে যায়, কারণ এর মালিক কেউ নয়। apps/web-এ থাকা test script-এর নাম যে engineer পরিবর্তন করেন, তিনি apps/web-এর অধীনে থাকা file সম্পাদনা করছেন। root AGENTS.md সেই diff-এর অংশ নয়, তাই কোনো reviewer এই অমিল দেখতে পান না। ছয় সপ্তাহ পরে file-টি এমন একটি build step বর্ণনা করে, যেটি আর নেই, আর যিনি পরিবর্তনটি করেছিলেন তিনি সেটি ভুলে গেছেন।

প্রতিটি task-এ এটি context খরচ করে। আপনি কী জিজ্ঞাসা করবেন agent তা জানার আগেই, session-এর শুরুতে এই file-গুলো load হয়। Claude Code-এর documentation-এ এর জন্য একটি নির্দিষ্ট সীমা দেওয়া আছে: "প্রতি CLAUDE.md file-এর জন্য 200 line-এর নিচে রাখুন। বড় file বেশি context খরচ করে এবং instruction মেনে চলার হার কমায়।" Codex instruction file-গুলোর সম্মিলিত আকার 32 KiB-এ পৌঁছালে সেগুলো merge করা বন্ধ করে; এটিই default project_doc_max_bytes। চারটি service-এর documentation থাকা একটি root file প্রতিটি task-এ সেই budget-এর তিনটি service-এর অংশ খরচ করে।

Instruction-গুলো পরস্পরবিরোধী হতে শুরু করে। web directory-র প্রয়োজন pnpm test। worker-এর প্রয়োজন pytest -q। এগুলো এক file-এ লিখলে প্রতিটি rule কেবল কিছু সময়ে সঠিক হয়, তাই কোনটি প্রযোজ্য agent-কে অনুমান করতে হয়। Claude Code-এর docs ফলাফলটি এভাবে বর্ণনা করে: "দুটি instruction পরস্পরবিরোধী হলে Claude যেকোনো একটি ইচ্ছামতো বেছে নিতে পারে।" File ভাগ করলেও অন্য rule context-এর বাইরে থাকে না। Claude Code একটি file দিয়ে অন্যটি প্রতিস্থাপন না করে, load করা প্রতিটি instruction file একত্র করে। তাই root file সবসময় থাকে, এবং agent একবার apps/web ও services/worker উভয় directory-র file খুললে, দুই directory file-ই একসঙ্গে context-এ থাকে। Per-directory file যা করে, তা হলো প্রতিটি rule-কে সেই rule-এর অধীন directory-র সঙ্গে যুক্ত করে। File-এর শুরুতে directory-টির নাম লিখুন, যেমন নিচের উদাহরণগুলোতে # apps/web দিয়ে করা হয়েছে। তাহলে একসঙ্গে একাধিক file load হলেও প্রতিটি command এখনও কোন directory-তে প্রযোজ্য তা স্পষ্ট থাকে। কোনো rule স্পষ্টভাবে লিখেছেন বলে নিশ্চিত থাকা সত্ত্বেও সেটি বাদ পড়লে, কেন কোনো instruction কার্যকর হয় না তার কারণগুলো ধরে এগিয়ে যাওয়া একই wording চতুর্থবার নতুন করে লেখার চেয়ে বেশি কার্যকর।

Agent code থেকে পড়ে নিতে পারত এমন তথ্যে file-টি ভরে যায়। একটি directory tree, একটি dependency list, প্রতিটি package কী করে তার একটি summary। Claude Code-এর /doctor check ঠিক এই ধরনের তথ্য বাদ দেওয়ার জন্য আছে। এটি "codebase থেকে Claude যে content নিজে নির্ণয় করতে পারে, যেমন directory layout, dependency list এবং architecture overview, তা বাদ দেয়" এবং "tool-এর default থেকে ভিন্ন pitfalls, rationale এবং conventions" রেখে দেয়। কোনো line আদৌ file-এ থাকা উচিত কি না যাচাই করার জন্য আমি এই বাক্যটিকেই সেরা test মনে করি।

এজেন্ট কি root ফাইল পড়ে, নাকি শুধু সবচেয়ে কাছের ফাইলটি পড়ে?

এখানেই অধিকাংশ মানুষ model-এর আচরণ ভুল বোঝেন। তাই upstream convention-এর বক্তব্য paraphrase না করে উদ্ধৃত করা উপযুক্ত:

প্রতিটি package-এর মধ্যে আরেকটি AGENTS.md রাখুন। Agent-গুলো directory tree-তে সবচেয়ে কাছের ফাইলটি স্বয়ংক্রিয়ভাবে পড়ে। তাই সবচেয়ে কাছের ফাইলটি অগ্রাধিকার পায় এবং প্রতিটি subproject নিজস্ব উপযোগী নির্দেশনা রাখতে পারে।

Conflict-এর ক্ষেত্রে:

যে ফাইল সম্পাদনা করা হচ্ছে, তার সবচেয়ে কাছের AGENTS.md কার্যকর হয়; ব্যবহারকারীর সরাসরি chat prompt সবকিছুর ওপর অগ্রাধিকার পায়।

"Takes precedence" কথাটি অনেকের কাছে "root ফাইল উপেক্ষা করা হয়" বলে মনে হয়। তা নয়। এই convention বাস্তবায়নকারী tools-এ repository root থেকে working directory পর্যন্ত path-এর প্রতিটি ফাইল পড়ে একত্র করা হয়। দুটি ফাইলে একই বিষয় নিয়ে ভিন্ন নির্দেশনা থাকলে শুধু সেই ক্ষেত্রে সবচেয়ে কাছের ফাইলটি অগ্রাধিকার পায়।

Codex এই mechanism স্পষ্টভাবে ব্যাখ্যা করে: "Codex root থেকে নিচের দিকে ফাইলগুলো জোড়ে এবং blank line দিয়ে একত্র করে। আপনার current directory-এর কাছের ফাইলগুলো আগের নির্দেশনার ওপর অগ্রাধিকার পায়।" Claude Code-ও একই path অনুসরণ করে। Session শুরু হলে এটি "আপনার working directory এবং তার ওপরের directory-গুলোতে থাকা প্রতিটি AGENTS.md এবং .claude/AGENTS.md পড়ে", এবং এর documentation loading model-টি স্পষ্টভাবে জানায়: "আবিষ্কৃত সব ফাইল একে অপরকে override না করে context-এ একত্র করা হয়।" Working directory-এর নিচের directory-গুলোর আচরণ আলাদা: Claude Code সেই subdirectory-র AGENTS.md প্রয়োজন অনুযায়ী load করে, "যখন Claude Read tool ব্যবহার করে সেখানে কোনো ফাইল খোলে।"

এর ফলে দুটি ব্যবহারিক বিষয় বোঝা যায়। Repository-র প্রতিটি session-এ root ফাইলটি prefix হিসেবে যুক্ত হয়। তাই সেখানে থাকা প্রতিটি লাইনকে এমন একটি লাইন হিসেবে বিবেচনা করুন, যার খরচ সপ্তাহে একশোবার দিতে হয়। Per-directory ফাইল agent সেই directory-র কোনো ফাইল না খোলা পর্যন্ত কোনো খরচ তৈরি করে না। তাই বিস্তারিত নির্দেশনা সেখানে রাখা সাশ্রয়ী এবং উপযুক্ত।

এই আচরণ 27 October 2026 তারিখে Codex এবং Claude Code-এর documentation-এর সঙ্গে মিলিয়ে যাচাই করা হয়েছে। Tools-গুলো convention-টি কিছুটা ভিন্নভাবে বাস্তবায়ন করে এবং সময়ের সঙ্গে পরিবর্তিতও হয়। তাই আপনার team যে agent ব্যবহার করে, তার loading rules নিশ্চিত করে নিন।

তিনটি service-সহ একটি repository-এর সম্পূর্ণ বিন্যাস

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

Root file-টি ইচ্ছাকৃতভাবে ছোট। এতে কোথায় দেখতে হবে তা বলা থাকে এবং প্রতিটি directory-তে প্রযোজ্য নিয়মগুলোই শুধু থাকে।

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

প্রতিটি directory-এর file-এ বিস্তারিত নির্দেশনা থাকে। Directory-এর প্রয়োজন অনুযায়ী file-টি যত দীর্ঘ দরকার হতে পারে।

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

Worker file-টির কাঠামো একই, তবে বিষয়বস্তু আলাদা: install command, pytest -q, consumer-কে কেন idempotent থাকতে হবে তার কারণ, এবং tests pass করার আগে যে migration চালাতে হবে। Infra file-এ এমন নিয়ম লিখবেন, যা কোনো agent-কে ক্ষতিকর কাজ করা থেকে আটকায়। কখনো terraform apply চালাবেন না। শুধু terraform plan চালিয়ে থামুন। ইতিমধ্যে configured থাকা state backend-এর নাম উল্লেখ করুন, যাতে agent নতুন backend initialise করার চেষ্টা না করে।

লক্ষ করুন, এই file-গুলোর কোনোটিতেই প্রতিটি service কী কাজে ব্যবহৃত হয় তার বর্ণনা নেই। সেটি মানুষের জন্য। Upstream-ও একই সীমারেখা নির্ধারণ করেছে: "README.md files are for humans: quick starts, project descriptions, and contribution guidelines"; আর AGENTS.md-এ থাকে "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions." AGENTS.md এবং মানুষের জন্য লেখা README-এর বিভাজন এই সীমারেখাটি বাক্য ধরে ব্যাখ্যা করে। আর কোডের কাঠামো এমন কেন, তা নথিবদ্ধ করা DESIGN.md তৃতীয় file-টি ব্যাখ্যা করে, যেখানে commands-এর বদলে সিদ্ধান্তগুলোর কারণ লেখা থাকে।

কোড পরিবর্তন হলে ফাইলটি কে আপডেট করবে?

একটি নিয়ম রাখুন, এবং সেটি root file-এ লিখুন: যে ব্যক্তি কোনো directory-তে code পরিবর্তন করবেন, তাঁকেই একই commit-এ ওই directory-এর AGENTS.md আপডেট করতে হবে।

এটি সাংস্কৃতিক কারণে নয়, একটি যান্ত্রিক কারণে কার্যকর। প্রতি-directory file-টি code-এর সঙ্গে একই diff-এ থাকে। ফলে pull request-এর reviewer দুটিই একসঙ্গে দেখতে পান। একটি root file সবার, তাই কার্যত কারও নয়। কেউ যে diff আগে থেকেই পড়ছেন, সেটিতে এটি সাধারণত থাকে না।

Pull request-এ একটি check যোগ করে এই নিয়ম প্রয়োগ করুন। এটি প্রতিটি পরিবর্তিত file-এর উপরে থাকা সবচেয়ে কাছের AGENTS.md খুঁজে বের করবে। তারপর জানাবে, ওই AGENTS.md পরিবর্তন করা হয়নি।

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

যে branch-এ docs পরিবর্তন না করে API client পুনর্গঠন করা হয়েছে, সেখানে output এমন দেখাবে:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

এটিকে failure না করে warning হিসেবে রাখুন। কঠোর gate মানুষকে file-এ একটি ফাঁকা line যোগ করতে শেখায়, যাতে CI সফল হয়। কোনো robot-এর সন্তুষ্টির জন্য সম্পাদিত file অনেক সময় file না থাকার চেয়েও কম মূল্যবান। Warning reviewer-কে একটি প্রশ্ন করার সুযোগ দেয়। কার্যকর অংশটি আসলে সেটিই।

পুরোনো হয়ে যাওয়া AGENTS.md কীভাবে শনাক্ত করব?

আজ আপনি দুটি পরীক্ষা চালাতে পারেন। একটি লক্ষণও সেশনের ভেতরে দেখা যাবে।

প্রতিটি ফাইলের বয়স, সেটি যে কোডের বর্ণনা দেয় সেই কোডের বয়সের সঙ্গে তুলনা করুন। %cs commit-এর তারিখ YYYY-MM-DD হিসেবে দেখায়।

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done
apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

কোডের তারিখের চেয়ে কোনো ডকুমেন্টের তারিখ ছয় মাস পুরোনো হলেই ফাইলটি ভুল—এমন প্রমাণ হয় না। তবে কোন ফাইলটি আগে পড়বেন তা বোঝা যায়। এক সেকেন্ডে সম্পন্ন হওয়া একটি পরীক্ষার কাছ থেকে আপনার এটুকুই দরকার।

যে path আর বিদ্যমান নেই, সেগুলো খুঁজুন। Documentation একটি নির্দিষ্ট উপায়ে পুরোনো হয়ে যায়: মুছে ফেলা কোডের বর্ণনা দিতে থাকে। এই ফাইলগুলোর প্রতিটি path backtick-এর মধ্যে লেখা থাকে। তাই সেগুলো সহজে বের করে পরীক্ষা করা যায়।

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

এই পরীক্ষাটি CI-তে যুক্ত না করে output পড়ুন। এটি src/**/*.ts-এর মতো glob এবং আপনার উদ্ধৃত যেকোনো URL-ও flag করে, কারণ উভয়ের মধ্যেই slash আছে এবং কোনোটিই disk-এর কোনো file নয়। Claude Code v2.1.283 বা পরবর্তী সংস্করণে /doctor prompt-audit আপনার হয়ে একই ধরনের পরীক্ষা চালায়। এটি "যেসব file বা command বিদ্যমান নেই, সেগুলোর reference" এবং পরস্পরবিরোধী file খোঁজে, ডিফল্টভাবে আপনার AGENTS.md file-গুলোও পরীক্ষা করে, এবং আপনি প্রস্তাবিত edit প্রয়োগ করতে বলার আগে কিছু পরিবর্তন করে না।

সেশনের ভেতরের লক্ষণ। Agent file-টি পড়ে, file-এর নির্দেশ অনুযায়ী src/api/client.ts খোলার চেষ্টা করে, এবং tool এই output ফেরত দেয়:

No such file or directory

তখন agent স্বাভাবিকভাবেই নিজের fetch wrapper লিখে। পুরোনো file-এর প্রকৃত খরচ এখানেই। Agent আপনার documentation উপেক্ষা করে না। সে documentation অনুসরণ করে, তিন মাস আগে মুছে ফেলা একটি path-এ পৌঁছায়, এবং আপনার কাছে আগে থেকেই থাকা code আবার তৈরি করে। Ponytail-এর মতো একটি skill, যা agent-কে কাজের জন্য প্রয়োজনীয় সর্বনিম্ন পরিবর্তনে সীমাবদ্ধ রাখে, এই পুনর্নির্মাণের প্রবণতা কমায়। তবে আপনার file যদি কোনো helper-এর ভুল path নির্দেশ করে, সেটি খুঁজে বের করতে পারে না।

Claude Code কি AGENTS.md ফাইল পড়ে?

হ্যাঁ, Claude Code v2.1.277 থেকে পড়ে। সঠিক নিয়মটি গুরুত্বপূর্ণ, কারণ nested layout সেটির ওপর নির্ভর করে। 27 October 2026-এ documentation যাচাই করা হয়েছে: "Claude Code আপনার project instructions হিসেবে AGENTS.md পড়তে পারে। তাই কোনো repository ইতিমধ্যে অন্য coding agent-এর জন্য প্রস্তুত থাকলে CLAUDE.md, import বা setting যোগ করার প্রয়োজন হয় না।" Default Project instructions value, claude-md-or-agents-md, পড়ে "আপনার AGENTS.md files, যখন আপনার working directory-তে বা তার ওপরে কোনো CLAUDE.md বা CLAUDE.local.md নেই।" Nested files-ও এর অন্তর্ভুক্ত: Claude কোনো subdirectory-তে Read tool দিয়ে file খুললে সেই subdirectory-এর AGENTS.md পড়ে, তবে শর্ত হলো "সেই subdirectory-তে নিজস্ব তিনটির কোনো CLAUDE.md file থাকবে না।" ওই তিনটি হলো CLAUDE.md, .claude/CLAUDE.md এবং CLAUDE.local.md। তাই apps/web-এ একটি ব্যক্তিগত CLAUDE.local.md থাকলেই apps/web/AGENTS.md load হওয়া বন্ধ হয়।

এর ফলে প্রতিটি AGENTS.md-এর পাশে একটি CLAUDE.md রাখার পুরোনো পরামর্শটি সমস্যার কারণ হতে পারে। আপনার working directory-তে বা তার ওপরে একটি AGENTS.md এবং CLAUDE.md বা CLAUDE.local.md থাকলে documentation অনুযায়ী Claude শুধু "আপনার CLAUDE.md files" পড়ে। একটি .claude/CLAUDE.md-ও একইভাবে গণ্য হয়। Root-এ একটি companion file রেখে তাতে একটি মাত্র Claude-specific line লিখলেও path-এর ওপরের সব AGENTS.md আড়াল হয়ে যায়। ব্যক্তিগত CLAUDE.local.md-ও একই কাজ করে। একটি ফাইল রাখতে চাইলে /config লিখে Project instructions-কে claude-md-and-agents-md-এ সেট করুন। এটি উভয় ফাইল পড়ে: প্রতিটি directory-এর CLAUDE.md আগে এবং তার AGENTS.md পরে।

শুধু version number দেখলেই এটি কাজ করেছে বলে নিশ্চিত হওয়া যায় না। আপনার v2.1.277 বা পরবর্তী version দরকার। তবে v2.1.281-এর আগে Amazon Bedrock-এ চলা বা telemetry disabled থাকা কিছু session শুধু CLAUDE.md files পড়ত। কিছু ক্ষেত্রে v2.1.276 বা তার আগের version থেকে upgrade করার পর প্রথম session-টি AGENTS.md-ও এড়িয়ে যেতে পারে। Documentation বলছে: "Claude আপনার পরবর্তী session থেকে AGENTS.md পড়বে।" তাই session নিজেই পরীক্ষা করুন। Interactive session-এ Claude Code no CLAUDE.md found; AGENTS.md loaded:-এর মতো একটি line দেখায়, যার পরে path থাকে। বর্তমান version-গুলোতে /memory file-টির তালিকা দেখায়। v2.1.280-এর আগে /memory এবং /context Claude সরাসরি পড়া AGENTS.md তালিকাভুক্ত করত না। তাই ওই version-গুলোতে Claude-কে তার project instructions কী, তা জিজ্ঞাসা করুন।

যেখানে Claude সরাসরি AGENTS.md পড়তে পারে না, সেখানে import পদ্ধতিটি এখনও সঠিক: পুরোনো version, Amazon Bedrock-এ বা telemetry disabled অবস্থায় v2.1.281-এর আগের session, built-in plugin disabled থাকা session, অথবা Project instructions-কে claude-md-এ সেট করা কোনো CLAUDE.md-সহ project-এর ক্ষেত্রে। services/worker/CLAUDE.md-এ এটি লিখুন:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

Tool-specific কিছু যোগ করার প্রয়োজন না থাকলে symlink পদ্ধতিটি ব্যবহার করুন।

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

সফল হলে ln কিছু output দেয় না। তাই listing পরীক্ষা করুন: apps/web/CLAUDE.md -> AGENTS.md। এরপর একটি session শুরু করে /context চালান। Loaded files Memory files-এর অধীনে দেখা যাবে। Windows-এ symlink তৈরি করতে Administrator rights বা Developer Mode দরকার। এছাড়া core.symlinks enabled না থাকলে Git committed symlink-কে plain text file হিসেবে checkout করে। ফলে ওই clone-এ আপনার instructions-এর বদলে এক লাইনের CLAUDE.md থাকে। Repository clone করা কেউ Windows-এ কাজ করলে @AGENTS.md import ব্যবহার করুন। Claude Code নিজে AGENTS.md পড়ার আগে কোনো workaround সেট করলেও সেটি রেখে দিতে পারেন। Documentation অনুযায়ী import রাখলে "Claude কখনও AGENTS.md দুবার পড়ে না"। Symlink করা CLAUDE.md-ও একবারই পড়া হয়।

এই বিষয়টির সঙ্গে আরেকটি সমস্যা জড়িত। /compact-এর পরে project-root-এর CLAUDE.md disk থেকে আবার পড়া হয়। কিন্তু subdirectory-র nested files পুনরায় inject করা হয় না। Agent পরের বার ওই directory-র কোনো file নিয়ে কাজ করলে Claude Code সেগুলো প্রয়োজন অনুযায়ী আবার load করে। Documentation-এ CLAUDE.md files-এর ক্ষেত্রে এটি স্পষ্ট বলা হয়েছে। সরাসরি পড়া AGENTS.md-এর compaction সম্পর্কে আলাদা কিছু বলা হয়নি। তাই উভয় নামের nested files একইভাবে কাজ করবে বলে ধরে নিন। দীর্ঘ session-এর মাঝখানে কোনো per-directory rule প্রয়োগ হওয়া বন্ধ হয়েছে বলে মনে হলে সাধারণত এটাই কারণ। ওই directory-র যেকোনো file পড়লে rule-টি আবার load হয়।

যেসব setting অন্য agent-কে AGENTS.md ব্যবহার করতে নির্দেশ করে

Codex স্বাভাবিকভাবেই AGENTS.md পড়ে। প্রতিটি level-এ এটি প্রথমে AGENTS.override.md খোঁজে। এতে shared file সম্পাদনা না করেই একটি directory-তে local override দেওয়া যায়। Combined size 32 KiB-এ পৌঁছালে এটি merge বন্ধ করে। Default project_doc_max_bytes হলো 32 KiB। Root file ছোট রাখার এটি আরেকটি কারণ।

Aider .aider.conf.yml-এর মাধ্যমে এটি গ্রহণ করে। সেখানে read: AGENTS.md line ব্যবহার করুন।

Gemini CLI .gemini/settings.json-এর মাধ্যমে এটি গ্রহণ করে। সেখানে { "context": { "fileName": "AGENTS.md" } } ব্যবহার করুন।

পুরোনো singular name ব্যবহার করা repository-গুলোর জন্য upstream backward-compatible rename নথিভুক্ত করেছে: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md।

খুব বড় monorepo-তে Claude Code-এর claudeMdExcludes setting path বা glob অনুযায়ী ancestor files বাদ দিতে পারে। আপনার directory-র ওপরে অন্য team-এর directory থাকলে এটি উপযোগী। এই pattern-গুলো Claude Code যে AGENTS.md files পড়ে, সেগুলোর ক্ষেত্রেও প্রযোজ্য।

এটি agent memory বা skill থেকে কীভাবে আলাদা?

এই প্রক্রিয়াগুলো দেখতে একই রকম হলেও ব্যর্থ হওয়ার ধরন সম্পূর্ণ ভিন্ন। তাই আপনি কোনটি ব্যবহার করতে চাইছেন, তা নির্দিষ্টভাবে বোঝা গুরুত্বপূর্ণ।

AGENTS.md আপনি লিখবেন, git-এ commit করবেন এবং pull request-এ review করা হবে। Repository clone করা সবার জন্য ফাইলটি একই থাকবে। Agent memory agent নিজে লিখবে, repository-এর বাইরে সংরক্ষিত থাকবে এবং একটি মেশিনেই সীমাবদ্ধ থাকবে। Claude Code-এর documentation-এও একই পার্থক্য করা হয়েছে: CLAUDE.md-তে আপনি লেখা “Instructions and rules” থাকে, auto memory-তে Claude-এর লেখা “Learnings and patterns” থাকে, এবং memory directory একাধিক মেশিনের মধ্যে share হয় না। পরীক্ষাটি সহজ। কোনো তথ্য fresh clone করা সহকর্মীর জন্যও সত্য হওয়া আবশ্যক হলে, সেটি memory-তে রাখা যাবে না। session-এর মধ্যে agent memory কীভাবে স্থায়ী থাকে অংশে এই বিষয়টির প্রথম দিকটি ব্যাখ্যা করা হয়েছে।

Skill হলো তৃতীয় বিষয়। AGENTS.md প্রতিটি session-এ load হওয়া context; skill হলো প্রয়োজনের সময় load হওয়া procedure। Claude Code-এর documentation-এ একটি কার্যকর নিয়ম দেওয়া আছে: “কোনো entry যদি multi-step procedure হয় বা codebase-এর কেবল একটি অংশের জন্য প্রযোজ্য হয়, তাহলে সেটিকে skill অথবা path-scoped rule-এ সরান।” এই বাক্যের দ্বিতীয় অংশের সমস্যাই nested AGENTS.md সমাধান করে। প্রথম অংশের জন্য agent skills ব্যবহার করা হয়। একই procedure একাধিক repository-তে প্রয়োজন হলে, একই paragraph দশটি আলাদা AGENTS.md ফাইলে paste না করে একাধিক repo-তে skill share করুন।

Upstream-এ বলা হয়েছে, “লেখার সময় মূল OpenAI repo-তে 88টি AGENTS.md file রয়েছে।” এই সংখ্যাটিই পুরো যুক্তিটি স্পষ্ট করে। বড় repository-এর জন্য আরও বড় file দরকার নেই। দরকার আরও বেশি ছোট file। প্রতিটি file-কে তার বর্ণিত code-এর পাশে রাখতে হবে এবং যে ব্যক্তি সর্বশেষ সেই code পরিবর্তন করেছেন, fileটির ownership তার হওয়া উচিত।

FAQ

একটি নেস্টেড AGENTS.md কি root ফাইলকে প্রতিস্থাপন করে, নাকি তার সঙ্গে যুক্ত হয়?

এটি root ফাইলের সঙ্গে যুক্ত হয়। Upstream-এ বলা হয়েছে, "সবচেয়ে কাছেরটি অগ্রাধিকার পায়"। এর অর্থ conflict হলে কী ঘটে, কোন ফাইল load হয় তা নয়। Codex root থেকে নিচের দিকে ফাইলগুলো একত্র করে এবং ফাঁকা লাইন দিয়ে যুক্ত করে। Claude Code-ও ফাইল override না করে working directory থেকে উপরের দিকে হাঁটার সময় পাওয়া প্রতিটি ফাইল একত্র করে। দুটি ফাইলে একই বিষয় সম্পর্কে ভিন্ন নির্দেশনা থাকলেই শুধু সবচেয়ে কাছের ফাইলটি প্রাধান্য পায়। Shared rule একবার root-এ লিখুন। প্রতিটি directory-তে সেগুলো পুনরাবৃত্তি করবেন না।

root AGENTS.md কত বড় হওয়া উচিত?

এত ছোট হওয়া উচিত যে repository-র প্রতিটি request-এর শুরুতে এটি যুক্ত হলেও আপনার আপত্তি না থাকে। কারণ বাস্তবে সেটিই ঘটে। Claude Code-এর documentation প্রতি ফাইলে 200 line-এর কম রাখার পরামর্শ দেয় এবং সতর্ক করে যে বড় ফাইল "নির্দেশনা অনুসরণ কমিয়ে দেয়"। Codex ডিফল্টভাবে মোট 32 KiB-এর পর instruction file merge করা বন্ধ করে। আপনার root ফাইলে যদি চারটি service-এর documentation থাকে, তবে কোনো একক task-এর জন্য এর বেশির ভাগই অপ্রয়োজনীয়। বিস্তারিত per-directory ফাইলে সরিয়ে দিন এবং একটি map রেখে দিন।

এই ফাইলগুলো stale হয়ে যাওয়া কীভাবে বন্ধ করব?

Root ফাইলে একটি rule রাখুন: কোনো directory-তে code পরিবর্তনকারী ব্যক্তি একই commit-এ সেই directory-র AGENTS.md আপডেট করবেন। Code-এর পাশে ফাইল রাখলে rule কার্যকর থাকে, কারণ পরিবর্তনটি তখন মানুষ যে pull request diff পড়ছে তার একই অংশে থাকে। এমন একটি CI warning যোগ করুন, যা প্রতিটি পরিবর্তিত path-কে তার উপরের নিকটতম AGENTS.md-এর সঙ্গে map করে। এরপর নির্দিষ্ট বিরতিতে প্রতিটি ফাইলের ওপর git log -1 --format=%cs চালিয়ে পাওয়া ফলাফল, ফাইলটি যে directory নথিভুক্ত করে সেখানে একই command চালিয়ে পাওয়া ফলাফলের সঙ্গে তুলনা করুন।

Claude Code কি AGENTS.md ফাইল পড়ে?

হ্যাঁ, v2.1.277 থেকে। 27 October 2026-এর documentation অনুযায়ী, আপনার working directory-তে বা তার উপরে কোনো CLAUDE.md অথবা CLAUDE.local.md না থাকলে Claude Code ডিফল্টভাবে AGENTS.md পড়ে। কোনো subdirectory-তে Read tool দিয়ে ফাইল খোলার সময়, সেই subdirectory-তে নিজস্ব CLAUDE.md, .claude/CLAUDE.md বা CLAUDE.local.md না থাকলে Claude Code ওই subdirectory-র AGENTS.md পড়ে। প্রতিটি AGENTS.md-এর পাশে CLAUDE.md যোগ করবেন না। Working directory-তে বা তার উপরে একটি থাকলে Claude শুধু "Your CLAUDE.md files only" পড়ে। আপনার যদি একটি CLAUDE.md-ও প্রয়োজন হয়, তবে /config-এ Project instructions-কে claude-md-and-agents-md হিসেবে সেট করুন, অথবা তার প্রথম line-এ @AGENTS.md রাখুন। একটি session-এ /memory চালিয়ে list-এ AGENTS.md path দেখা যাচ্ছে কি না নিশ্চিত করুন।

কোনো rule শুধু মাঝে মাঝে প্রযোজ্য হলে সেটি কোথায় রাখব?

AGENTS.md-তে নয়। এই ফাইলটি প্রতিটি session-এ load হয়। তাই এতে থাকা প্রতিটি line আপনার আসল লেখা request-এর সঙ্গে মনোযোগের জন্য প্রতিযোগিতা করে। মাঝে মাঝে প্রয়োজন হয় এমন একাধিক ধাপের procedure skill-এ রাখা উচিত, যা প্রয়োজন হলে load হয়। শুধু একটি directory-তে প্রযোজ্য rule সেই directory-র AGENTS.md-তে রাখুন। Agent code থেকে সরাসরি পড়তে পারে এমন তথ্য, যেমন directory tree বা dependency list, কোনো জায়গাতেই রাখার দরকার নেই।

এই লেখাটি কি কাজে লেগেছে?