monorepo میں nested AGENTS.md فائلیں کیسے ترتیب دیں

monorepo میں nested AGENTS.md کا مطلب

monorepo میں nested AGENTS.md سے مراد یہ ہے کہ repository root میں ایک مختصر فائل ہو اور ہر service directory کے اندر ایک مزید فائل ہو۔ root فائل میں وہ چند قواعد شامل ہوتے ہیں جو ہر جگہ لاگو ہوتے ہیں، ساتھ ہی یہ نقشہ بھی ہوتا ہے کہ دوسری فائلیں کہاں موجود ہیں۔ ہر service فائل میں صرف اسی directory کے commands اور conventions شامل ہوتے ہیں۔ services/worker/queue.py میں ترمیم کرنے والا agent پہلے root فائل اور worker فائل پڑھتا ہے، اور front end کے بارے میں کوئی context استعمال نہیں کرتا، کیونکہ اسے وہاں کام نہیں کرنا۔

کچھ بھی install کرنے کی ضرورت نہیں۔ AGENTS.md ایک convention ہے، اور upstream project یہ بات واضح طور پر کہتا ہے:

AGENTS.md صرف standard Markdown ہے۔ اپنی پسند کی کوئی بھی headings استعمال کریں؛ agent صرف آپ کا فراہم کردہ متن parse کرتا ہے۔

اسی لیے اس تکنیک کو درست طریقے سے سیکھنا مفید ہے۔ format آپ کے استعمال کے دوران تبدیل نہیں ہوگا۔ مسئلہ placement اور maintenance سے پیدا ہوتا ہے، اور دونوں کی ذمہ داری آپ کی ہے۔

ایک بڑی root AGENTS.md فائل کام کرنا کیوں بند کر دیتی ہے؟

کسی repository کی root میں موجود 600 لائنوں کی ایک AGENTS.md فائل، جس میں web app، background worker اور Terraform directory شامل ہوں، چار الگ طریقوں سے ناکام ہو جاتی ہے۔

یہ پرانی ہو جاتی ہے، کیونکہ اس کا کوئی مالک نہیں ہوتا۔ جو engineer apps/web میں موجود test script کا نام تبدیل کرتا ہے، وہ apps/web کے تحت موجود فائلوں میں ترمیم کر رہا ہوتا ہے۔ root AGENTS.md اس diff میں شامل نہیں ہوتی، اس لیے کوئی reviewer اس عدم مطابقت کو نہیں دیکھتا۔ چھ ہفتے بعد فائل ایسے build step کو بیان کر رہی ہوتی ہے جو اب موجود نہیں، اور جس شخص نے اسے توڑا تھا وہ تبدیلی بھول چکا ہوتا ہے۔

ہر task پر یہ context استعمال کرتی ہے۔ یہ فائلیں session کے آغاز میں load ہوتی ہیں، اس سے پہلے کہ agent کو معلوم ہو کہ آپ کیا کام کہیں گے۔ Claude Code کی documentation میں اس کی حد بیان کی گئی ہے: "ہر CLAUDE.md فائل کو 200 لائنوں سے کم رکھنے کی کوشش کریں۔ بڑی فائلیں زیادہ context استعمال کرتی ہیں اور ہدایات پر عمل کم کرتی ہیں۔" Codex ہدایاتی فائلوں کو اس وقت merge کرنا روک دیتا ہے جب ان کا مجموعی حجم 32 KiB، یعنی default project_doc_max_bytes، تک پہنچ جائے۔ چار services کی وضاحت کرنے والی root فائل ہر task پر اس budget کا ایک حصہ ان تین services پر خرچ کرتی ہے جن سے اس task کا تعلق نہیں ہوتا۔

ہدایات ایک دوسرے سے متصادم ہونے لگتی ہیں۔ web directory کو pnpm test درکار ہوتا ہے۔ worker کو pytest -q درکار ہوتا ہے۔ ایک ہی فائل میں لکھنے پر ہر rule صرف کچھ حالات میں درست ہوتا ہے، اس لیے agent کو اندازہ لگانا پڑتا ہے کہ کون سا rule لاگو ہوتا ہے۔ Claude Code کی documentation اس نتیجے کو یوں بیان کرتی ہے: "اگر دو rules ایک دوسرے سے متصادم ہوں تو Claude کسی ایک کو من مانے انداز میں منتخب کر سکتا ہے۔" ہر directory کے لیے الگ فائل یہ اندازہ ختم کر دیتی ہے، کیونکہ دونوں میں سے صرف ایک rule ہی context میں آتا ہے۔

اس میں وہ معلومات بھر جاتی ہیں جو agent code سے پڑھ سکتا ہے۔ مثلاً directory tree، dependency list، اور ہر package کے کام کا خلاصہ۔ Claude Code کا /doctor check خاص طور پر یہی مواد ہٹانے کے لیے موجود ہے۔ یہ "ایسا content کم کرتا ہے جو Claude codebase سے اخذ کر سکتا ہے، جیسے directory layouts، dependency lists اور architecture overviews" اور "ان pitfalls، وجوہات اور conventions کو برقرار رکھتا ہے جو tool defaults سے مختلف ہوں۔" میرے علم میں یہ جملہ اس بات کا بہترین معیار ہے کہ آیا کوئی line فائل میں شامل ہونی بھی چاہیے یا نہیں۔

کیا agent root فائل پڑھتا ہے، یا صرف سب سے قریب والی فائل؟

یہ وہ نکتہ ہے جس میں زیادہ تر لوگ model کو غلط سمجھتے ہیں۔ اس لیے اسے paraphrase کرنے کے بجائے upstream convention کا حوالہ دینا مفید ہے:

ہر package کے اندر ایک اور AGENTS.md رکھیں۔ Agents directory tree میں سب سے قریب والی فائل خودکار طور پر پڑھتے ہیں، اس لیے قریب ترین فائل کو ترجیح حاصل ہوتی ہے اور ہر subproject اپنی مخصوص ہدایات شامل کر سکتا ہے۔

اور تنازعات کے بارے میں:

جس فائل میں ترمیم ہو رہی ہو، اس کے سب سے قریب موجود AGENTS.md کو ترجیح حاصل ہوتی ہے؛ صارف کے واضح chat prompts ہر چیز پر مقدم ہوتے ہیں۔

بہت سے لوگوں کے لیے "ترجیح حاصل ہوتی ہے" کا مطلب یہ ہوتا ہے کہ "root فائل نظرانداز کر دی جاتی ہے"۔ ایسا نہیں ہے۔ جو tools اس convention کو نافذ کرتے ہیں، ان میں repository root سے working directory تک path میں موجود ہر فائل پڑھی جاتی ہے اور انہیں یکجا کیا جاتا ہے۔ قریب ترین فائل کو صرف اس وقت ترجیح ملتی ہے جب دو فائلیں ایک ہی موضوع کے بارے میں مختلف ہدایات دیں۔

Codex اس طریقۂ کار کو واضح طور پر بیان کرتا ہے: "Codex فائلوں کو root سے نیچے کی سمت پڑھ کر blank lines کے ساتھ جوڑتا ہے۔ آپ کی موجودہ directory کے قریب فائلیں پہلے کی ہدایات کو override کرتی ہیں۔" Claude Code بھی اپنی file name کے لیے یہی path دیکھتا ہے۔ Working directory سے اوپر directory hierarchy میں موجود فائلیں "launch کے وقت مکمل طور پر load کی جاتی ہیں"، اور "دریافت ہونے والی تمام فائلیں ایک دوسرے کو override کرنے کے بجائے context میں جوڑی جاتی ہیں۔" Working directory سے نیچے موجود directories کا طریقۂ کار مختلف ہے: Claude Code ان فائلوں کو ضرورت کے وقت load کرتا ہے، یعنی "جب Claude ان directories میں فائلیں پڑھتا ہے۔"

اس کے دو عملی نتائج ہیں۔ Root فائل repository کے ہر session میں prefix کے طور پر شامل ہوتی ہے، اس لیے اس کی ہر سطر کو ایسی لاگت سمجھیں جو آپ ہفتے میں سو بار ادا کرتے ہیں۔ Per-directory فائل اس وقت کوئی لاگت نہیں ڈالتی جب agent کسی دوسری جگہ کام کر رہا ہو۔ اس لیے وہاں تفصیل رکھنا سستا ہے اور تفصیلی ہدایات بھی وہیں ہونی چاہییں۔

اس رویے کی Codex اور Claude Code کی documentation کے مطابق August 2026 میں جانچ کی گئی تھی۔ مختلف tools اس convention کو معمولی فرق کے ساتھ نافذ کرتے ہیں اور ان کے طریقۂ کار تبدیل بھی ہو سکتے ہیں، اس لیے اپنی ٹیم کے استعمال کردہ agent کے loading rules کی تصدیق کریں۔

تین services والی repository کے لیے ایک عملی layout

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 جان بوجھ کر مختصر ہے۔ اس میں بتایا گیا ہے کہ کہاں دیکھنا ہے، اور اس میں صرف وہ rules شامل ہیں جو ہر 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.

Per-directory file میں تفصیلات شامل کی جاتی ہیں، اور اسے اتنا ہی طویل رکھا جا سکتا ہے جتنی اس directory کو ضرورت ہو۔

# 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 کی ساخت یہی ہے، لیکن اس کا content مختلف ہے: install command، pytest -q، consumer کو idempotent رکھنے کی وجہ، اور وہ migration جو tests کے کامیاب ہونے سے پہلے چلنی ضروری ہے۔ Infra file میں وہ rules درج کیے جاتے ہیں جو agent کو نقصان پہنچانے سے روکتے ہیں۔ terraform apply کو کبھی نہ چلائیں۔ terraform plan چلائیں اور وہیں رک جائیں۔ پہلے سے configured state backend کا نام بھی درج کریں تاکہ agent نیا backend initialize کرنے کی کوشش نہ کرے۔

غور کریں کہ ان میں سے کسی file میں بھی ہر service کے مقصد کی description شامل نہیں ہے۔ یہ معلومات humans کے لیے ہے۔ 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 اور human-facing README کے درمیان تقسیم اس حد کو جملہ بہ جملہ واضح کرتا ہے، جبکہ ایک DESIGN.md جو code کی ساخت کی وجوہات درج کرتی ہے اس تیسرے file کا احاطہ کرتا ہے، جو commands کے بجائے فیصلوں کی وضاحت کرتی ہے۔

کوڈ تبدیل ہونے پر فائل کو کون اپ ڈیٹ کرتا ہے؟

ایک اصول بنائیں، اور اسے root فائل میں درج کریں: جو شخص کسی directory میں code تبدیل کرے، وہ اسی commit میں اس directory کی AGENTS.md بھی اپ ڈیٹ کرے۔

یہ اصول ثقافتی وجہ سے نہیں بلکہ ایک عملی وجہ سے مؤثر ہے۔ ہر directory کی فائل code کے ساتھ اسی diff میں شامل ہوتی ہے، اس لیے pull request کا reviewer دونوں کو ایک ساتھ دیکھ لیتا ہے۔ root فائل سب کی ہوتی ہے، جس کا مطلب ہے کہ وہ کسی ایک شخص کی ذمہ داری نہیں رہتی، اور عموماً کسی ایسے diff میں شامل نہیں ہوتی جسے کوئی پہلے ہی پڑھ رہا ہو۔

pull request پر ایک check کے ذریعے اس اصول کو نافذ کریں۔ یہ ہر تبدیل شدہ فائل کے اوپر موجود قریب ترین 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 لوگوں کو یہ سکھاتا ہے کہ CI کو green کرنے کے لیے فائل میں ایک خالی سطر شامل کر دیں۔ کسی robot کو مطمئن کرنے کے لیے تبدیل کی گئی فائل، فائل نہ ہونے سے بھی کم مفید ہوتی ہے۔ warning reviewer کو ایک سوال پوچھنے کا موقع دیتی ہے، اور عملی طور پر مؤثر حصہ یہی ہے۔

باسی شدہ AGENTS.md فائل کی شناخت کیسے کریں؟

آج آپ دو checks چلا سکتے ہیں، اور session کے اندر ایک symptom دیکھ سکتے ہیں۔

ہر فائل کی عمر کا اس 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")"
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

Code date سے چھ ماہ پیچھے doc date ہونا اس بات کا ثبوت نہیں کہ فائل غلط ہے۔ یہ صرف بتاتا ہے کہ پہلے کون سی فائل پڑھنی ہے۔ ایک سیکنڈ میں مکمل ہونے والے check سے آپ کو اتنا ہی درکار ہے۔

ایسے paths تلاش کریں جو اب موجود نہیں ہیں۔ Documentation ایک مخصوص طریقے سے باسی ہوتی ہے: یہ deleted code کو بیان کرتی رہتی ہے۔ ان فائلوں میں ہر path backticks میں لکھا ہوتا ہے، اس لیے انہیں آسانی سے نکال کر test کیا جا سکتا ہے۔

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

Output پڑھیں، اور اس check کو CI میں شامل نہ کریں۔ یہ src/**/*.ts جیسے globs اور آپ کے quote کیے ہوئے ہر URL کو بھی flag کرتا ہے، کیونکہ دونوں میں slash ہوتا ہے اور disk پر دونوں میں سے کوئی بھی file نہیں ہوتا۔

Session کے اندر symptom۔ Agent فائل پڑھتا ہے، src/api/client.ts کھولنے کی کوشش کرتا ہے کیونکہ فائل نے اسے ایسا کرنے کو کہا تھا، اور tool یہ واپس کرتا ہے:

No such file or directory

چنانچہ وہ مناسب طور پر اپنا fetch wrapper لکھ دیتا ہے۔ باسی فائل کی اصل لاگت یہی ہے۔ Agent آپ کی documentation کو نظرانداز نہیں کرتا۔ وہ documentation پر عمل کرتا ہے، اس path تک پہنچتا ہے جو تین ماہ پہلے delete ہو چکا تھا، اور وہ code دوبارہ بناتا ہے جو آپ کے پاس پہلے سے موجود ہے۔ Ponytail جیسی skill، جو agent کو کام کرنے والی کم سے کم تبدیلی تک محدود رکھتی ہے، دوبارہ code بنانے کے اس رجحان کو کم کرتی ہے، لیکن اگر آپ کی فائل نے helper کا غلط path دیا ہو تو یہ اسے تلاش نہیں کر سکتی۔

کیا Claude Code، AGENTS.md فائلیں پڑھتا ہے؟

نہیں۔ یہ بات واضح طور پر کہنا ضروری ہے، کیونکہ nested layout اسی پر منحصر ہے۔ August 2026 تک دستاویزات میں لکھا ہے: "Claude Code، CLAUDE.md پڑھتا ہے، AGENTS.md نہیں۔" یہ طریقہ اب بھی کام کرتا ہے؛ آپ کو صرف ہر AGENTS.md کے ساتھ ایک CLAUDE.md رکھنا ہوگا۔

جب آپ مشترکہ ہدایات کے علاوہ tool-specific ہدایات شامل کرنا چاہیں تو import form درست ہے۔ یہ services/worker/CLAUDE.md میں شامل کریں:

@AGENTS.md

## Claude Code

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

جب کسی tool-specific ہدایت کی ضرورت نہ ہو تو symlink form درست ہے۔

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 درکار ہوتا ہے، اس لیے وہاں @AGENTS.md import استعمال کریں۔

اس حوالے سے ایک اہم نکتہ بھی ہے۔ /compact کے بعد root file کو disk سے دوبارہ پڑھا جاتا ہے، لیکن subdirectories میں موجود nested files دوبارہ inject نہیں کی جاتیں۔ یہ files اگلی بار واپس آتی ہیں جب agent اس directory میں کوئی file پڑھتا ہے۔ اگر طویل session کے دوران کسی directory کے لیے مخصوص rule کا اطلاق رک جائے تو عموماً وجہ یہی ہوتی ہے۔ Directory میں موجود کسی بھی file کو touch کرنے سے rule دوبارہ load ہو جاتا ہے۔

یہ agent memory یا skill سے کیسے مختلف ہے؟

یہ طریقہ کار بظاہر ایک جیسے ہیں، لیکن ان کی ناکامی کی وجوہات بالکل مختلف ہوتی ہیں۔ اس لیے یہ واضح رکھنا ضروری ہے کہ آپ کو کس طریقہ کار کی ضرورت ہے۔

AGENTS.md آپ لکھتے ہیں، اسے git میں commit کیا جاتا ہے، pull request میں اس کا جائزہ لیا جاتا ہے، اور repository clone کرنے والے ہر شخص کے لیے یہ یکساں ہوتا ہے۔ agent memory agent لکھتا ہے، repository سے باہر محفوظ ہوتی ہے، اور ایک ہی machine تک محدود رہتی ہے۔ Claude Code کی documentation بھی یہی فرق بیان کرتی ہے: CLAUDE.md میں وہ "Instructions and rules" شامل ہوتی ہیں جو آپ لکھتے ہیں، جبکہ auto memory میں وہ "Learnings and patterns" شامل ہوتے ہیں جو Claude لکھتا ہے، اور memory directory مختلف machines کے درمیان shared نہیں ہوتی۔ جانچ کا آسان اصول یہ ہے: اگر کوئی حقیقت fresh clone حاصل کرنے والے colleague کے لیے بھی درست ہونی چاہیے، تو وہ memory میں نہیں رہ سکتی۔ sessions کے درمیان agent memory کیسے برقرار رہتی ہے میں اس معاملے کے دوسرے حصے کی وضاحت ہے۔

skill تیسری چیز ہے۔ AGENTS.md وہ context ہے جو ہر session میں load ہوتا ہے؛ skill وہ procedure ہے جو ضرورت پڑنے پر load ہوتا ہے۔ Claude Code کی documentation ایک قابلِ عمل اصول پیش کرتی ہے: "اگر کوئی entry متعدد مراحل پر مشتمل procedure ہو یا codebase کے صرف ایک حصے کے لیے اہم ہو، تو اسے skill یا path-scoped rule میں منتقل کریں۔" اس جملے کا دوسرا حصہ بالکل وہ مسئلہ ہے جسے nested AGENTS.md حل کرتا ہے۔ پہلا حصہ agent skills کے لیے ہے، اور جب یہی procedure ایک سے زیادہ repositories میں درکار ہو تو ایک ہی paragraphs کو دس مختلف AGENTS.md files میں paste کرنے کے بجائے skill کو repos کے درمیان share کریں۔

Upstream میں درج ہے کہ "تحریر کے وقت مرکزی OpenAI repo میں 88 AGENTS.md files موجود ہیں"۔ یہی تعداد پوری دلیل ہے۔ بڑی repository کو بڑی file کی ضرورت نہیں ہوتی۔ اسے زیادہ چھوٹی files کی ضرورت ہوتی ہے، جن میں سے ہر file اس code کے ساتھ موجود ہو جس کی وہ وضاحت کرتی ہے، اور ہر file کی ذمہ داری اس شخص کے پاس ہو جس نے اس code میں آخری تبدیلی کی ہو۔

FAQ

کیا nested AGENTS.md، root فائل کو replace کرتی ہے یا اس میں شامل ہوتی ہے؟

یہ root فائل میں شامل ہوتی ہے۔ Upstream کے مطابق، "closest one takes precedence"، جس کا مطلب یہ ہے کہ conflict کی صورت میں کیا ہوگا، نہ کہ کون سی فائل load ہوگی۔ Codex "concatenates files from the root down, joining them with blank lines"، جبکہ Claude Code working directory سے اوپر کی طرف جاتے ہوئے ملنے والی ہر فائل کو concatenate کرتا ہے، override نہیں کرتا۔ قریب ترین فائل صرف اس وقت غالب آتی ہے جب دو فائلیں ایک ہی موضوع کے بارے میں مختلف ہدایات دیتی ہوں۔ مشترکہ rules ایک بار root میں لکھیں اور انہیں ہر directory میں دوبارہ نہ لکھیں۔

root AGENTS.md کتنی بڑی ہونی چاہیے؟

اتنی مختصر کہ آپ کو اس repository میں کی جانے والی ہر request کے اوپر اسے paste کیے جانے پر اعتراض نہ ہو، کیونکہ یہی ہوتا ہے۔ Claude Code کی documentation ہر فائل کو 200 lines سے کم رکھنے کا ہدف تجویز کرتی ہے اور خبردار کرتی ہے کہ طویل فائلیں "reduce adherence"۔ Codex default طور پر مجموعی طور پر 32 KiB پر instruction files کو merge کرنا روک دیتا ہے۔ اگر root فائل چار services document کرتی ہے تو کسی ایک task کے لیے اس کا بیشتر حصہ غیر ضروری ہے۔ تفصیل per-directory files میں منتقل کریں اور پیچھے ایک map چھوڑ دیں۔

میں ان فائلوں کو stale ہونے سے کیسے روکوں؟

root فائل میں ایک rule شامل کریں: جو شخص کسی directory میں code تبدیل کرے، وہ اسی commit میں اس directory کی AGENTS.md بھی update کرے۔ فائل کو code کے ساتھ رکھنے سے rule پر عمل برقرار رہتا ہے، کیونکہ تبدیلی اسی pull request diff میں شامل ہوتی ہے جسے انسان پہلے ہی پڑھ رہا ہوتا ہے۔ ایک CI warning شامل کریں جو ہر changed path کو اس کے اوپر موجود nearest AGENTS.md سے map کرے، اور وقتاً فوقتاً ہر فائل میں موجود git log -1 --format=%cs کا موازنہ اسی command کو اس directory پر چلا کر حاصل ہونے والے output سے کریں جسے وہ document کرتی ہے۔

کیا Claude Code، AGENTS.md files پڑھتا ہے؟

نہیں۔ August 2026 تک documentation میں لکھا ہے: "Claude Code reads CLAUDE.md, not AGENTS.md." اسی directory میں CLAUDE.md بنائیں اور پہلی line پر @AGENTS.md رکھیں۔ اس سے shared file load ہوگی اور آپ اس کے نیچے Claude-specific instructions شامل کر سکیں گے۔ اگر مزید کچھ شامل نہ کرنا ہو تو ln -s AGENTS.md CLAUDE.md سے بنایا گیا symlink کام کرتا ہے، تاہم Windows پر اس کے لیے Administrator rights یا Developer Mode درکار ہے۔ کسی session میں /context چلائیں اور تصدیق کریں کہ file Memory files کے تحت ظاہر ہو رہی ہے۔

ایسی rule کہاں رکھوں جو صرف کبھی کبھار اہم ہوتی ہے؟

AGENTS.md میں نہیں۔ یہ فائل ہر session میں load ہوتی ہے، اس لیے اس کی ہر line آپ کی لکھی ہوئی اصل request کے ساتھ توجہ حاصل کرنے کے لیے مقابلہ کرتی ہے۔ کئی steps پر مشتمل وہ procedure جس کی کبھی کبھار ضرورت پڑتی ہے، skill میں ہونی چاہیے؛ skill ضرورت کے وقت load ہوتی ہے۔ جو rule صرف ایک directory پر لاگو ہوتی ہے، اسے اسی directory کی AGENTS.md میں رکھیں۔ وہ fact جسے agent براہ راست code سے پڑھ سکتا ہے، مثلاً directory tree یا dependency list، نہ AGENTS.md میں ہونا چاہیے اور نہ skill میں۔