Monorepo میں nested AGENTS.md فائلیں کیسے استعمال کریں
ایک بڑی root AGENTS.md فائل پرانے ہونے پر غیر متعلقہ context ضائع کرتی ہے۔ اس گائیڈ میں سیکھیں کہ کیسے ہر service کے لیے الگ فائل بنا کر ایجنٹ کی کارکردگی کو بہتر بنایا جائے۔
monorepo میں nested AGENTS.md کا کیا مطلب ہے
monorepo میں nested AGENTS.md کا مطلب یہ ہے کہ ایک مختصر فائل repository کے root میں موجود ہو اور ایک مزید فائل ہر service کی ڈائریکٹری کے اندر ہو۔ root فائل میں وہ چند اصول ہوتے ہیں جو ہر جگہ لاگو ہوتے ہیں، اس کے ساتھ یہ نقشہ بھی ہوتا ہے کہ دوسری فائلیں کہاں واقع ہیں۔ ہر service کی فائل میں صرف اس مخصوص ڈائریکٹری کے لیے کمانڈز اور کنونشنز درج ہوتے ہیں۔ جب کوئی ایجنٹ services/worker/queue.py میں ترمیم کرتا ہے، تو وہ root فائل اور متعلقہ ورکر فائل کو پڑھتا ہے، اور اسے اس front end پر کوئی context ضائع نہیں کرنا پڑتا جسے وہ کبھی استعمال نہیں کرے گا۔
اس کے لیے کچھ بھی انسٹال کرنے کی ضرورت نہیں ہے۔ AGENTS.md ایک کنونشن ہے، اور upstream پروجیکٹ اسے واضح طور پر بیان کرتا ہے:
AGENTS.md صرف ایک معیاری Markdown فائل ہے۔ آپ اپنی مرضی کے مطابق کوئی بھی ہیڈنگ استعمال کریں؛ ایجنٹ صرف آپ کے فراہم کردہ متن کو پارس (parse) کرتا ہے۔
یہی وجہ ہے کہ یہ تکنیک درست طریقے سے سیکھنے کے قابل ہے۔ اس کا فارمیٹ آپ کے استعمال کے دوران تبدیل نہیں ہوگا۔ جو چیز خراب ہو سکتی ہے وہ اس کا مقام اور دیکھ بھال ہے، اور یہ دونوں آپ کی ذمہ داری ہیں۔
ایک بڑا root AGENTS.md کام کرنا کیوں بند کر دیتا ہے؟
کسی repository کے root میں موجود 600 لائنوں کی ایک AGENTS.md فائل، جس میں web app، background worker اور Terraform directory شامل ہوں، چار الگ طریقوں سے ناکام ہوتی ہے۔
یہ پرانی ہو جاتی ہے، کیونکہ اس کا کوئی مالک نہیں ہوتا۔ apps/web میں test script کا نام تبدیل کرنے والا engineer، apps/web کے تحت موجود files میں ترمیم کر رہا ہوتا ہے۔ root AGENTS.md اس diff میں شامل نہیں ہوتی، اس لیے کوئی reviewer اس عدم مطابقت کو نہیں دیکھتا۔ چھ ہفتے بعد یہ file ایسے build step کی وضاحت کر رہی ہوتی ہے جو اب موجود نہیں، اور جس شخص نے اسے توڑا تھا وہ تبدیلی بھول چکا ہوتا ہے۔
ہر task پر context خرچ ہوتا ہے۔ یہ files session کے آغاز میں load ہوتی ہیں، اس سے پہلے کہ agent کو معلوم ہو کہ آپ کیا پوچھنے والے ہیں۔ Claude Code کی documentation میں اس کی حد بھی دی گئی ہے: "ہر CLAUDE.md file کو 200 lines سے کم رکھنے کا ہدف رکھیں۔ طویل files زیادہ context استعمال کرتی ہیں اور instruction پر عمل درآمد کم کرتی ہیں۔" Codex instruction files کو merge کرنا اس وقت روک دیتا ہے جب ان کا مجموعی size 32 KiB، یعنی default project_doc_max_bytes، تک پہنچ جائے۔ چار services کی documentation رکھنے والی root file ہر task پر اس budget کا کچھ حصہ ان تین services کے لیے خرچ کرتی ہے جن سے اس task کا تعلق نہیں ہوتا۔
Instructions ایک دوسرے سے متصادم ہونے لگتی ہیں۔ web directory کو pnpm test چاہیے۔ worker کو pytest -q چاہیے۔ ایک ہی file میں لکھے جانے پر ہر rule صرف کچھ حالات میں درست ہوتا ہے، اس لیے agent کو اندازہ لگانا پڑتا ہے کہ کون سا rule لاگو ہوتا ہے۔ Claude Code کی documentation اس نتیجے کو یوں بیان کرتی ہے: "اگر دو instructions ایک دوسرے سے متصادم ہوں تو Claude کسی ایک کو من مانے طریقے سے منتخب کر سکتا ہے۔" File کو تقسیم کرنے سے دوسرا rule context سے خارج نہیں ہوتا۔ Claude Code ہر loaded instruction file کو ایک file سے دوسری file replace کرنے کے بجائے concatenate کرتا ہے، اس لیے root file ہمیشہ موجود رہتی ہے۔ جب agent نے apps/web اور services/worker دونوں میں files کھول لی ہوں، تو دونوں directories کی files ایک ساتھ context میں موجود رہتی ہیں۔ Per-directory file کا فائدہ یہ ہے کہ ہر rule کو اس directory کے ساتھ وابستہ کرتی ہے جس پر وہ لاگو ہوتا ہے۔ File کے آغاز میں directory کا نام لکھیں، جیسا کہ ذیل کی مثالوں میں # apps/web کے ساتھ کیا گیا ہے۔ اس طرح ایک وقت میں متعدد files load ہونے پر بھی ہر command کے دائرۂ اطلاق کی وضاحت رہتی ہے۔ جب کوئی ایسا rule، جسے آپ یقین سے سمجھتے ہوں کہ آپ نے واضح طور پر لکھا تھا، پھر بھی نظر انداز ہو جائے، تو ان وجوہات کو سمجھنا کہ instruction کیوں اثر انداز نہیں ہوتی الفاظ کو چوتھی بار دوبارہ لکھنے سے زیادہ مفید ہے۔
یہ ان facts سے بھر جاتی ہے جو agent code سے پڑھ سکتا ہے۔ Directory tree، dependencies کی فہرست، اور ہر package کے کام کا خلاصہ۔ Claude Code کا /doctor check خاص طور پر اسی مواد کو ہٹانے کے لیے موجود ہے۔ یہ "ایسا content ہٹاتا ہے جو Claude codebase سے اخذ کر سکتا ہے، جیسے directory layouts، dependency lists اور architecture overviews"، اور "ان pitfalls، rationale اور conventions کو برقرار رکھتا ہے جو tool defaults سے مختلف ہوں۔" میرے علم میں یہ جملہ اس بات کا بہترین test ہے کہ کوئی line file میں شامل ہونی بھی چاہیے یا نہیں۔
کیا agent root file پڑھتا ہے یا صرف قریب ترین file؟
یہ وہ مقام ہے جہاں اکثر لوگ model کے بارے میں غلط سمجھتے ہیں، اس لیے اسے paraphrase کرنے کے بجائے upstream convention کو نقل کرنا مفید ہے:
ہر package کے اندر ایک اور AGENTS.md رکھیں۔ Agents directory tree میں خودکار طور پر قریب ترین file پڑھتے ہیں، اس لیے قریب ترین file کو ترجیح حاصل ہوتی ہے اور ہر subproject اپنی ضرورت کے مطابق instructions شامل کر سکتا ہے۔
اور conflicts کے بارے میں:
edited file کے قریب ترین AGENTS.md کو ترجیح حاصل ہوتی ہے؛ explicit user chat prompts ہر چیز پر غالب ہوتے ہیں۔
"ترجیح حاصل ہوتی ہے" بہت سے لوگوں کو یہ سمجھاتا ہے کہ "root file نظر انداز کی جاتی ہے"۔ ایسا نہیں ہے۔ جو tools اس convention کو implement کرتے ہیں، ان میں repository root سے working directory تک path میں موجود ہر file پڑھی جاتی ہے اور انہیں یکجا کیا جاتا ہے۔ قریب ترین file کو صرف اس وقت ترجیح حاصل ہوتی ہے جب دو files ایک ہی موضوع کے بارے میں مختلف ہدایات دیں۔
Codex اس mechanism کو واضح طور پر بیان کرتا ہے: "Codex files کو root سے شروع کرتے ہوئے concatenate کرتا ہے اور انہیں blank lines کے ذریعے جوڑتا ہے۔ آپ کی موجودہ directory کے قریب files پہلے کی guidance کو override کرتی ہیں۔" Claude Code بھی یہی path دیکھتا ہے۔ Session کے آغاز پر یہ "آپ کی working directory اور اس سے اوپر کی directories میں موجود ہر AGENTS.md اور .claude/AGENTS.md" پڑھتا ہے، اور اس کی documentation loading model کو صاف بیان کرتی ہے: "دریافت ہونے والی تمام files context میں شامل کی جاتی ہیں، نہ کہ ایک دوسرے کو override کرتی ہیں۔" Working directory سے نیچے موجود directories مختلف انداز میں کام کرتی ہیں: Claude Code subdirectory کی AGENTS.md کو on demand load کرتا ہے، "جب Claude Read tool کے ذریعے وہاں موجود کوئی file کھولتا ہے۔"
اس کے دو عملی نتائج ہیں۔ Root file repository کے ہر session میں prefix کے طور پر شامل ہوتی ہے، اس لیے اس کی ہر line کو ایسی لاگت سمجھیں جو آپ ہفتے میں سو بار ادا کرتے ہیں۔ Per-directory file اس وقت تک کوئی لاگت نہیں رکھتی جب تک agent اس directory میں موجود file نہ کھولے، اس لیے تفصیل وہاں کم لاگت رکھتی ہے اور وہیں شامل ہونی چاہیے۔
اس رویے کی Codex اور Claude Code documentation کے خلاف 27 October 2026 کو جانچ کی گئی تھی۔ مختلف tools اس convention کو قدرے مختلف انداز میں implement کرتے ہیں اور ان میں تبدیلی بھی آ سکتی ہے، اس لیے اپنی team کے استعمال کردہ agent کے loading rules کی تصدیق کریں۔
تین سروسز پر مشتمل ریپوزٹری کے لیے ایک کارآمد خاکہ
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روٹ فائل کو جان بوجھ کر مختصر رکھا گیا ہے۔ یہ بتاتی ہے کہ کہاں دیکھنا ہے، اور اس میں صرف وہی اصول شامل ہیں جو ہر ڈائریکٹری پر لاگو ہوتے ہیں۔
# 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.فی ڈائریکٹری فائل وہ جگہ ہے جہاں تفصیلات درج ہوتی ہیں، اور یہ اتنی طویل ہو سکتی ہے جتنی کہ ڈائریکٹری کی ضرورت ہو۔
# 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.ورکر فائل کی ساخت تو وہی ہے لیکن مواد مختلف ہے: انسٹال کمانڈ، pytest -q، وہ وجہ جس کی بنا پر کنزیومر کو idempotent رہنا چاہیے، اور وہ مائیگریشن جو ٹیسٹ پاس ہونے سے پہلے چلنی چاہیے۔ انفرا فائل وہ جگہ ہے جہاں آپ وہ اصول لکھتے ہیں جو کسی ایجنٹ کو نقصان پہنچانے سے روکتے ہیں۔ کبھی بھی terraform apply نہ چلائیں۔ terraform plan چلائیں اور وہیں رک جائیں، اور اس اسٹیٹ بیک اینڈ کا نام دیں جو پہلے سے کنفیگرڈ ہے تاکہ ایجنٹ نیا بیک اینڈ شروع کرنے کی کوشش نہ کرے۔
غور کریں کہ ان میں سے کسی بھی فائل میں کیا نہیں ہے: ہر سروس کس مقصد کے لیے ہے اس کی تفصیل۔ یہ انسانوں کا کام ہے۔ اپ اسٹریم بھی یہی حد مقرر کرتا ہے، یہ کہتے ہوئے کہ "README.md فائلیں انسانوں کے لیے ہیں: کوئیک اسٹارٹس، پروجیکٹ کی تفصیلات، اور کنٹری بیوشن گائیڈ لائنز"، جبکہ AGENTS.md میں "وہ اضافی، بعض اوقات تفصیلی سیاق و سباق ہوتا ہے جس کی کوڈنگ ایجنٹس کو ضرورت ہوتی ہے: بلڈ اسٹیپس، ٹیسٹ، اور کنونشنز۔" AGENTS.md اور انسانوں کے لیے تیار کردہ README کے درمیان تقسیم اس حد کو جملہ بہ جملہ واضح کرتی ہے، اور ایک DESIGN.md جو یہ ریکارڈ کرتی ہے کہ کوڈ کی ساخت ایسی کیوں ہے تیسری فائل کا احاطہ کرتی ہے، جو کمانڈز کے بجائے فیصلوں کی وضاحت کرتی ہے۔
کوڈ تبدیل ہونے پر فائل کو کون اپ ڈیٹ کرتا ہے؟
ایک اصول ہے، اور یہ روٹ فائل میں جاتا ہے: جو بھی کسی ڈائریکٹری میں کوڈ تبدیل کرتا ہے، وہ اسی کمٹ (commit) میں اس ڈائریکٹری کی AGENTS.md کو اپ ڈیٹ کرتا ہے۔
یہ ایک میکانکی وجہ سے کام کرتا ہے، نہ کہ ثقافتی وجہ سے۔ فی ڈائریکٹری فائل اسی ڈف (diff) میں موجود ہوتی ہے جس میں کوڈ ہوتا ہے، لہذا پل ریکویسٹ (pull request) کا جائزہ لینے والا دونوں کو ایک ساتھ دیکھتا ہے۔ روٹ فائل سب کی ملکیت ہوتی ہے، جس کا مطلب ہے کہ وہ کسی کی بھی نہیں ہے، اور وہ کبھی بھی اس ڈف میں نہیں ہوتی جسے کوئی پڑھ رہا ہو۔
اس اصول کو پل ریکویسٹ پر ایک چیک کے ساتھ سپورٹ کریں۔ یہ ہر تبدیل شدہ فائل کے اوپر قریب ترین 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ایک ایسی برانچ پر جس نے API کلائنٹ کو ڈاکس (docs) کو چھوئے بغیر دوبارہ ترتیب دیا، آؤٹ پٹ کچھ اس طرح نظر آتا ہے:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedاسے ناکامی (failure) کے بجائے ایک انتباہ (warning) رکھیں۔ ایک سخت رکاوٹ لوگوں کو یہ سکھاتی ہے کہ فائل میں ایک خالی لائن شامل کر دیں تاکہ CI سبز ہو جائے، اور ایک ایسی فائل جسے روبوٹ کو مطمئن کرنے کے لیے ایڈٹ کیا گیا ہو، اس فائل سے کم قیمت رکھتی ہے جو بالکل نہ ہو۔ انتباہ جائزہ لینے والے کو پوچھنے کے لیے ایک سوال دیتا ہے، اور یہی وہ حصہ ہے جو درحقیقت کام کرتا ہے۔
باسی ہو جانے والی AGENTS.md فائل کی نشان دہی کیسے کریں؟
آپ آج دو جانچیں چلا سکتے ہیں، اور ایک علامت آپ کو session کے اندر نظر آئے گی۔
ہر فائل کی عمر کا اس code کی عمر سے موازنہ کریں جسے وہ بیان کرتی ہے۔ %cs commit date کو 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")"
doneapps/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-01code date سے چھ ماہ پرانی doc date اس بات کا ثبوت نہیں کہ فائل غلط ہے۔ یہ صرف بتاتی ہے کہ پہلے کون سی فائل پڑھنی ہے، اور ایک سیکنڈ میں ہونے والی جانچ سے آپ کو اتنا ہی معلوم کرنا ہوتا ہے۔
ایسے paths تلاش کریں جو اب موجود نہیں ہیں۔ Documentation ایک خاص طریقے سے باسی ہوتی ہے: یہ ایسے code کی وضاحت جاری رکھتی ہے جسے delete کر دیا گیا ہو۔ ان فائلوں میں ہر path backticks میں لکھا ہوتا ہے، اس لیے انہیں نکال کر جانچنا آسان ہے۔
grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
[ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
doneOutput پڑھیں، اسے CI میں شامل نہ کریں۔ یہ src/**/*.ts جیسے globs اور آپ کے quote کیے ہوئے ہر URL کی بھی نشان دہی کرتا ہے، کیونکہ دونوں میں slash ہوتا ہے اور disk پر کوئی بھی file نہیں ہوتا۔ Claude Code v2.1.283 یا اس کے بعد کے version میں /doctor prompt-audit آپ کے لیے اسی طرح کی جانچ چلاتا ہے: یہ "ایسی files یا commands کے references تلاش کرتا ہے جو موجود نہیں ہیں" اور ایسی files بھی تلاش کرتا ہے جو ایک دوسرے سے متصادم ہوں، بطور default آپ کی AGENTS.md files کا احاطہ کرتا ہے، اور اس وقت تک کچھ تبدیل نہیں کرتا جب تک آپ اس سے اپنی تجویز کردہ edits لاگو کرنے کو نہ کہیں۔
session کے اندر نظر آنے والی علامت۔ agent فائل پڑھتا ہے، src/api/client.ts کھولنے کی کوشش کرتا ہے کیونکہ فائل نے اسے ایسا کرنے کو کہا ہوتا ہے، اور tool یہ واپس کرتا ہے:
No such file or directoryچنانچہ وہ مناسب طور پر اپنا fetch wrapper لکھ دیتا ہے۔ باسی فائل کی اصل لاگت یہی ہے۔ agent آپ کی documentation کو نظرانداز نہیں کرتا۔ وہ documentation پر عمل کرتا ہے، اس path تک پہنچتا ہے جسے تین ماہ پہلے delete کر دیا گیا تھا، اور وہ code دوبارہ بناتا ہے جو آپ کے پاس پہلے ہی موجود ہوتا ہے۔ Ponytail جیسی skill، جو agent کو کام کرنے والی کم سے کم تبدیلی تک محدود رکھتی ہے، دوبارہ code بنانے کے اس رجحان کو کم کرتی ہے، لیکن یہ ایسے helper کو تلاش نہیں کر سکتی جس کی طرف آپ کی فائل نے غلط جگہ اشارہ کیا ہو۔
کیا Claude Code، AGENTS.md فائلیں پڑھتا ہے؟
جی ہاں، Claude Code v2.1.277 سے یہ فائلیں پڑھتا ہے، اور درست اصول اہم ہے کیونکہ nested layout اسی پر منحصر ہے۔ 27 October 2026 کو documentation سے تصدیق کی گئی: "Claude Code AGENTS.md کو آپ کی project instructions کے طور پر پڑھ سکتا ہے، اس لیے پہلے سے دوسرے coding agents کے لیے تیار repository میں CLAUDE.md، import یا setting شامل کرنے کی ضرورت نہیں ہوتی۔" طے شدہ Project instructions قدر، claude-md-or-agents-md، کہتی ہے: "جب آپ کی working directory یا اس سے اوپر CLAUDE.md یا CLAUDE.local.md موجود نہ ہوں تو آپ کی AGENTS.md files۔" Nested files بھی شامل ہیں: Claude کسی subdirectory کی AGENTS.md "تب پڑھتا ہے جب Claude وہاں موجود file کو Read tool سے کھولتا ہے"، بشرطیکہ "اس subdirectory میں اپنی تین CLAUDE.md files میں سے کوئی موجود نہ ہو"۔ وہ تین files CLAUDE.md، .claude/CLAUDE.md اور CLAUDE.local.md ہیں، اس لیے apps/web میں موجود ذاتی CLAUDE.local.md، apps/web/AGENTS.md کو load ہونے سے روکنے کے لیے کافی ہے۔
اس سے ہر AGENTS.md کے ساتھ CLAUDE.md رکھنے کا پرانا مشورہ ایک trap بن جاتا ہے۔ اگر آپ کی working directory یا اس سے اوپر AGENTS.md اور CLAUDE.md یا CLAUDE.local.md موجود ہو تو documentation کے مطابق Claude صرف "آپ کی CLAUDE.md files" پڑھتا ہے۔ .claude/CLAUDE.md بھی اسی طرح شمار ہوتی ہے۔ Root میں موجود ایک companion file، جس میں Claude-specific صرف ایک line ہو، راستے میں موجود ہر AGENTS.md کو چھپا دیتی ہے، اور ذاتی CLAUDE.local.md بھی یہی کرتی ہے۔ اگر آپ ایک ہی file رکھنا چاہتے ہیں تو /config لکھیں اور Project instructions کو claude-md-and-agents-md پر set کریں؛ اس صورت میں دونوں files پڑھی جاتی ہیں، ہر directory کی CLAUDE.md پہلے اور اس کی AGENTS.md بعد میں۔
صرف version number اس بات کی تصدیق نہیں کرتا کہ یہ کام کر رہا ہے۔ آپ کو v2.1.277 یا بعد کا version درکار ہے، لیکن v2.1.281 سے پہلے کچھ sessions، مثلاً Amazon Bedrock پر یا telemetry disabled ہونے کی صورت میں، صرف CLAUDE.md files پڑھتے تھے۔ بعض صورتوں میں v2.1.276 یا اس سے پہلے کے version سے upgrade کرنے کے بعد پہلا session AGENTS.md بھی skip کرتا ہے: documentation کہتی ہے، "Claude اگلے session سے AGENTS.md پڑھتا ہے"۔ اس لیے خود session چیک کریں۔ Interactive session میں Claude Code no CLAUDE.md found; AGENTS.md loaded: جیسی line اور اس کے بعد path دکھاتا ہے، جبکہ موجودہ versions میں /memory file کی فہرست دکھاتا ہے۔ v2.1.280 سے پہلے /memory اور /context براہِ راست پڑھی گئی AGENTS.md کو فہرست میں شامل نہیں کرتے تھے، اس لیے ان versions پر Claude سے پوچھیں کہ اس کی project instructions کیا ہیں۔
Import کا طریقہ اب بھی وہاں درست ہے جہاں Claude براہِ راست AGENTS.md نہیں پڑھ سکتا: پرانا version، Amazon Bedrock پر یا telemetry disabled ہونے کی صورت میں v2.1.281 سے پہلے کا session، ایسا session جس میں اسے پڑھنے والا built-in plugin disabled ہو، یا ایسا project جس میں CLAUDE.md موجود ہو اور Project instructions کو claude-md پر set کیا گیا ہو۔ اسے services/worker/CLAUDE.md میں رکھیں:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.Symlink کا طریقہ اس وقت مناسب ہے جب tool-specific طور پر کچھ شامل نہ کرنا ہو۔
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 درکار ہوتا ہے۔ Git، committed symlink کو plain text file کے طور پر checkout کرتا ہے، جب تک core.symlinks enabled نہ ہو۔ اس صورت میں clone میں آپ کی instructions کی جگہ ایک سطری CLAUDE.md رہ جاتی ہے۔ اگر repository clone کرنے والے افراد Windows پر کام کرتے ہیں تو @AGENTS.md import استعمال کریں۔ اگر Claude Code کے خود AGENTS.md پڑھنے سے پہلے آپ نے کوئی workaround set up کر لیا تھا تو اسے برقرار رکھ سکتے ہیں: documentation کے مطابق import برقرار رکھنے سے "Claude AGENTS.md کو دو مرتبہ نہیں پڑھتا"، اور symlink کی گئی CLAUDE.md ایک مرتبہ پڑھی جاتی ہے۔
اس سے متعلق ایک اور trap بھی ہے۔ /compact کے بعد project-root CLAUDE.md کو disk سے دوبارہ پڑھا جاتا ہے، لیکن subdirectories میں موجود nested files دوبارہ inject نہیں کی جاتیں۔ Claude Code انہیں on demand reload کرتا ہے، یعنی اگلی مرتبہ جب agent اس directory میں موجود file کے ساتھ کام کرتا ہے۔ Documentation اس بات کو CLAUDE.md files کے لیے واضح کرتی ہے اور براہِ راست پڑھی گئی AGENTS.md کے لیے compaction کو الگ سے بیان نہیں کرتی، اس لیے توقع رکھیں کہ دونوں ناموں والی nested files اسی طرح کام کریں گی۔ اگر طویل session کے دوران per-directory rule اچانک لاگو ہونا بند محسوس ہو تو عموماً یہی وجہ ہوتی ہے؛ اس directory میں کوئی بھی file پڑھنے سے rule واپس load ہو جاتا ہے۔
وہ settings جو دوسرے agents کو AGENTS.md کی طرف بھیجتی ہیں
Codex، AGENTS.md کو native طور پر پڑھتا ہے۔ ہر level پر یہ پہلے AGENTS.override.md چیک کرتا ہے، جس سے shared file میں ترمیم کیے بغیر کسی ایک directory کے لیے local override دیا جا سکتا ہے۔ جب merged size 32 KiB تک پہنچ جائے، جو طے شدہ project_doc_max_bytes ہے، تو یہ merging روک دیتا ہے۔ Root file کو مختصر رکھنے کی یہ ایک اور وجہ ہے۔
Aider، .aider.conf.yml کے ذریعے اسے لیتا ہے، جس میں line read: AGENTS.md شامل ہوتی ہے۔
Gemini CLI، .gemini/settings.json کے ذریعے اسے لیتا ہے، جس میں { "context": { "fileName": "AGENTS.md" } } شامل ہوتا ہے۔
Upstream documentation ان repositories کے لیے backward-compatible rename درج کرتی ہے جو اب بھی پرانا singular نام استعمال کرتی ہیں: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md۔
بہت بڑے monorepo میں Claude Code کی claudeMdExcludes setting path یا glob کے ذریعے ancestor files کو skip کر سکتی ہے۔ یہ اس وقت مفید ہے جب کسی دوسری team کی directory آپ کی directory سے اوپر ہو۔ اس کے patterns ان AGENTS.md files پر بھی لاگو ہوتے ہیں جنہیں Claude Code پڑھتا ہے۔
یہ agent memory یا skill سے کس طرح مختلف ہے؟
یہ میکانزم دیکھنے میں ایک جیسے لگتے ہیں لیکن ان کی ناکامی کی وجوہات بالکل مختلف ہیں، اس لیے یہ واضح ہونا ضروری ہے کہ آپ کس چیز کا استعمال کر رہے ہیں۔
AGENTS.md آپ کی طرف سے لکھی جاتی ہے، git میں کمٹ کی جاتی ہے، pull request میں ریویو کی جاتی ہے، اور ہر اس شخص کے لیے یکساں ہوتی ہے جو ریپوزٹری کو clone کرتا ہے۔ Agent memory کو ایجنٹ خود لکھتا ہے، ریپوزٹری سے باہر اسٹور کرتا ہے، اور یہ ایک مشین تک محدود ہوتی ہے۔ Claude Code کی دستاویزات بھی یہی فرق واضح کرتی ہیں: CLAUDE.md میں وہ "ہدایات اور اصول" ہوتے ہیں جو آپ لکھتے ہیں، auto memory میں وہ "سیکھی ہوئی باتیں اور پیٹرن" ہوتے ہیں جو Claude خود لکھتا ہے، اور memory ڈائریکٹری مشینوں کے درمیان شیئر نہیں ہوتی۔ اس کا سادہ سا اصول یہ ہے: اگر کوئی حقیقت کسی ساتھی کے لیے ایک نئی clone پر بھی درست ہونی چاہیے، تو اسے memory میں نہیں ہونا چاہیے۔ How agent memory persists between sessions اس تصویر کے اس پہلو کا احاطہ کرتا ہے۔
Skill تیسری چیز ہے۔ AGENTS.md وہ سیاق و سباق (context) ہے جو ہر سیشن میں لوڈ ہوتا ہے؛ جبکہ skill ایک ایسا طریقہ کار (procedure) ہے جو ضرورت پڑنے پر لوڈ ہوتا ہے۔ Claude Code کی دستاویزات ایک قابلِ عمل اصول دیتی ہیں: "اگر کوئی اندراج کثیر الجہتی طریقہ کار ہے یا صرف کوڈ بیس کے ایک حصے کے لیے اہم ہے، تو اسے skill یا path-scoped اصول میں منتقل کریں۔" اس جملے کا دوسرا حصہ وہی ہے جسے nested AGENTS.md حل کرتی ہے۔ پہلا حصہ agent skills کے لیے ہے، اور جب ایک ہی طریقہ کار ایک سے زیادہ ریپوزٹریز میں درکار ہو، تو share the skill across repos کریں بجائے اس کے کہ وہی پیراگراف دس مختلف AGENTS.md فائلوں میں کاپی پیسٹ کریں۔
Upstream نوٹ کرتا ہے کہ "اس تحریر کے وقت مرکزی OpenAI ریپوزٹری میں 88 AGENTS.md فائلیں موجود ہیں۔" یہ تعداد ہی مکمل دلیل ہے۔ ایک بڑی ریپوزٹری کو ایک بڑی فائل کی ضرورت نہیں ہوتی۔ اسے مزید چھوٹی فائلوں کی ضرورت ہوتی ہے، جن میں سے ہر ایک اس کوڈ کے ساتھ موجود ہو جس کی وہ وضاحت کرتی ہے، اور ہر فائل کا ذمہ دار وہی ہو جس نے آخری بار اس کوڈ میں تبدیلی کی ہو۔
FAQ
کیا nested AGENTS.md فائل root فائل کو بدل دیتی ہے یا اس میں شامل ہوتی ہے؟
یہ اس میں شامل ہوتی ہے۔ Upstream کہتا ہے کہ "closest one takes precedence"، جس کا مطلب یہ ہے کہ اختلاف کی صورت میں کون سی ہدایت غالب ہوگی، نہ کہ کون سی فائل load ہوگی۔ Codex فائلوں کو root سے نیچے کی سمت جوڑتا ہے اور ان کے درمیان خالی سطریں شامل کرتا ہے۔ Claude Code بھی override کرنے کے بجائے working directory سے اوپر کی سمت ملنے والی ہر فائل کو جوڑتا ہے۔ nearest فائل صرف اس وقت غالب ہوتی ہے جب دو فائلیں ایک ہی موضوع پر مختلف ہدایات دیتی ہوں۔ مشترکہ قواعد ایک بار root میں لکھیں اور انہیں ہر directory میں نہ دہرائیں۔
root AGENTS.md فائل کتنی بڑی ہونی چاہیے؟
اتنی مختصر کہ آپ کو اس repository میں کی جانے والی ہر request کے اوپر اسے شامل کیے جانے پر اعتراض نہ ہو، کیونکہ یہی ہوتا ہے۔ Claude Code کی documentation ہر فائل کو 200 سطروں سے کم رکھنے کا مشورہ دیتی ہے اور خبردار کرتی ہے کہ طویل فائلیں "reduce adherence" کرتی ہیں۔ Codex بطور default مجموعی طور پر 32 KiB پر instruction files کو merge کرنا روک دیتا ہے۔ اگر آپ کی root فائل میں چار services کی documentation ہو تو کسی ایک task کے لیے اس کا زیادہ تر حصہ غیر ضروری ہوگا۔ تفصیل کو per-directory فائلوں میں منتقل کریں اور پیچھے ایک نقشہ چھوڑ دیں۔
میں ان فائلوں کو stale ہونے سے کیسے روکوں؟
root فائل میں ایک rule شامل کریں: جو شخص کسی directory میں code تبدیل کرے، وہ اسی commit میں اس directory کی AGENTS.md بھی update کرے۔ فائل کو code کے پاس رکھنے سے یہ rule برقرار رہتا ہے، کیونکہ تبدیلی اسی pull request diff میں شامل ہوتی ہے جسے انسان پہلے ہی پڑھ رہا ہوتا ہے۔ ایک CI warning شامل کریں جو ہر تبدیل شدہ path کو اس کے اوپر موجود nearest AGENTS.md سے map کرے، اور وقتاً فوقتاً ہر فائل پر git log -1 --format=%cs کا موازنہ اسی command کے directory پر چلائے گئے نتیجے سے کریں۔
کیا Claude Code، AGENTS.md فائلیں پڑھتا ہے؟
ہاں، v2.1.277 سے۔ 27 October 2026 کو documentation کے خلاف تصدیق کے مطابق، جب آپ کی working directory یا اس کے اوپر CLAUDE.md یا CLAUDE.local.md موجود نہ ہو تو Claude Code بطور default AGENTS.md پڑھتا ہے، اور جب وہ Read tool سے کسی subdirectory میں فائل کھولتا ہے اور اس subdirectory میں اپنی CLAUDE.md، .claude/CLAUDE.md یا CLAUDE.local.md موجود نہ ہوں تو اس subdirectory کی AGENTS.md پڑھتا ہے۔ ہر AGENTS.md کے ساتھ ایک CLAUDE.md شامل نہ کریں: working directory پر یا اس کے اوپر ایک فائل موجود ہو تو Claude صرف "Your CLAUDE.md files only" پڑھتا ہے۔ اگر آپ کو CLAUDE.md بھی درکار ہو تو Project instructions کو claude-md-and-agents-md پر /config میں set کریں، یا اس کی پہلی سطر پر @AGENTS.md رکھیں۔ session میں /memory چلائیں اور تصدیق کریں کہ فہرست میں AGENTS.md path ظاہر ہوتا ہے۔
ایسی rule کہاں رکھوں جو صرف کبھی کبھار اہم ہوتی ہے؟
AGENTS.md میں نہیں۔ یہ فائل ہر session میں load ہوتی ہے، اس لیے اس کی ہر سطر آپ کی اصل typed request کے ساتھ توجہ حاصل کرنے کے لیے مقابلہ کرتی ہے۔ کئی steps پر مشتمل ایسا طریقۂ کار جو کبھی کبھار درکار ہو، skill میں ہونا چاہیے، جو ضرورت کے وقت load ہوتی ہے۔ کسی ایک directory پر لاگو ہونے والی rule اسی directory کی AGENTS.md میں ہونی چاہیے۔ ایسی fact جسے agent براہِ راست code سے پڑھ سکتا ہے، مثلاً directory tree یا dependency list، نہ AGENTS.md میں ہونی چاہیے اور نہ skill میں۔