Monorepo میں nested AGENTS.md فائلیں کیسے استعمال کریں

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) کرتا ہے۔

یہی وجہ ہے کہ یہ تکنیک درست طریقے سے سیکھنے کے قابل ہے۔ اس کا فارمیٹ آپ کے استعمال کے دوران تبدیل نہیں ہوگا۔ جو چیز خراب ہو سکتی ہے وہ اس کا مقام اور دیکھ بھال ہے، اور یہ دونوں آپ کی ذمہ داری ہیں۔

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

ایک ویب ایپ، بیک گراؤنڈ ورکر اور Terraform ڈائریکٹری پر مشتمل ریپوزٹری کی روٹ میں موجود 600 لائنوں کی ایک ہی AGENTS.md فائل چار مختلف طریقوں سے ناکام ہوتی ہے۔

یہ پرانی (stale) ہو جاتی ہے، کیونکہ اس کا کوئی ذمہ دار نہیں ہوتا۔ جو انجینئر apps/web میں ٹیسٹ اسکرپٹ کا نام تبدیل کرتا ہے، وہ apps/web کے تحت فائلیں ایڈٹ کر رہا ہوتا ہے۔ روٹ AGENTS.md اس diff میں شامل نہیں ہوتی، اس لیے کوئی بھی جائزہ لینے والا (reviewer) اس تضاد کو نہیں دیکھ پاتا۔ چھ ہفتے بعد، فائل ایک ایسے بلڈ اسٹیپ کی وضاحت کر رہی ہوتی ہے جو اب موجود ہی نہیں، اور جس شخص نے اسے توڑا تھا وہ اس تبدیلی کو بھول چکا ہوتا ہے۔

یہ ہر ٹاسک پر کانٹیکسٹ (context) ضائع کرتی ہے۔ یہ فائلیں سیشن کے آغاز میں ہی لوڈ ہو جاتی ہیں، اس سے پہلے کہ ایجنٹ کو معلوم ہو کہ آپ کیا پوچھنے والے ہیں۔ Claude Code کی دستاویزات اس پر ایک حد مقرر کرتی ہیں: "ہر CLAUDE.md فائل کو 200 لائنوں سے کم رکھیں۔ لمبی فائلیں زیادہ کانٹیکسٹ استعمال کرتی ہیں اور عمل درآمد (adherence) کو کم کرتی ہیں۔" جب انسٹرکشن فائلز کا مجموعی سائز 32 KiB (جو کہ ڈیفالٹ project_doc_max_bytes ہے) تک پہنچ جاتا ہے تو Codex انہیں ضم کرنا بند کر دیتا ہے۔ چار سروسز کو ڈاکومنٹ کرنے والی روٹ فائل ہر ایک ٹاسک کے لیے ان میں سے تین کا بجٹ ضائع کر دیتی ہے۔

ہدایات ایک دوسرے سے متصادم ہونے لگتی ہیں۔ ویب ڈائریکٹری pnpm test چاہتی ہے۔ ورکر pytest -q چاہتا ہے۔ ایک ہی فائل میں لکھے جانے کی وجہ سے، ہر اصول صرف کچھ وقت کے لیے درست ہوتا ہے، اس لیے ایجنٹ کو اندازہ لگانا پڑتا ہے کہ کون سا اصول لاگو ہوتا ہے۔ Claude Code کی دستاویزات اس کے نتیجے کو بیان کرتی ہیں: "اگر دو اصول ایک دوسرے سے متصادم ہوں، تو Claude کسی ایک کو من مانی طور پر منتخب کر سکتا ہے۔" فی ڈائریکٹری فائل اس اندازے کو ختم کر دیتی ہے، کیونکہ ان دو اصولوں میں سے صرف ایک ہی کانٹیکسٹ میں موجود ہوتا ہے۔ جب کوئی اصول جسے آپ نے واضح طور پر لکھا ہو، پھر بھی نظر انداز ہو جائے، تو ہدایت کے لاگو نہ ہونے کی وجوہات کو سمجھنا، اسے چوتھی بار دوبارہ لکھنے سے بہتر ہے۔

یہ ان حقائق سے بھر جاتی ہے جو ایجنٹ کوڈ سے خود پڑھ سکتا ہے۔ ڈائریکٹری ٹری، ڈیپینڈنسی لسٹ، ہر پیکیج کے کام کا خلاصہ۔ Claude Code کا /doctor چیک اسی چیز کو ہٹانے کے لیے موجود ہے۔ یہ "اس مواد کو کاٹ دیتا ہے جسے Claude کوڈ بیس سے اخذ کر سکتا ہے، جیسے ڈائریکٹری لے آؤٹ، ڈیپینڈنسی لسٹ، اور آرکیٹیکچر کا جائزہ" اور صرف "ان مسائل، منطق، اور کنونشنز کو برقرار رکھتا ہے جو ٹول کی ڈیفالٹس سے مختلف ہوں۔" یہ جملہ اس بات کو جانچنے کا بہترین طریقہ ہے کہ آیا کوئی لائن فائل میں شامل ہونی چاہیے یا نہیں۔

کیا ایجنٹ صرف root فائل پڑھتا ہے، یا قریب ترین فائل؟

یہ وہ مقام ہے جہاں زیادہ تر لوگ ماڈل کو غلط سمجھتے ہیں، اس لیے اسے اپنے الفاظ میں بیان کرنے کے بجائے upstream کنونشن کا حوالہ دینا بہتر ہے:

ہر پیکیج کے اندر ایک اور AGENTS.md رکھیں۔ ایجنٹس خود بخود ڈائریکٹری ٹری میں قریب ترین فائل پڑھ لیتے ہیں، لہذا قریب ترین فائل کو ترجیح حاصل ہوتی ہے اور ہر ذیلی پروجیکٹ (subproject) اپنی مخصوص ہدایات کے ساتھ آ سکتا ہے۔

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

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

"ترجیح حاصل ہونا" (Takes precedence) کا مطلب بہت سے لوگ یہ لیتے ہیں کہ "root فائل کو نظر انداز کر دیا جاتا ہے"۔ ایسا نہیں ہے۔ ان ٹولز میں جو اس کنونشن کو نافذ کرتے ہیں، repository root سے لے کر working directory تک کے راستے میں آنے والی ہر فائل کو پڑھا اور جوڑا جاتا ہے۔ قریب ترین فائل صرف اس صورت میں جیتتی ہے جب دو فائلیں ایک ہی موضوع پر مختلف باتیں کہیں۔

Codex اس میکانزم کے بارے میں واضح ہے: "Codex روٹ سے نیچے تک فائلوں کو جوڑتا ہے، اور انہیں خالی لائنوں کے ساتھ ملاتا ہے۔ آپ کی موجودہ ڈائریکٹری کے قریب والی فائلیں ابتدائی ہدایات پر حاوی ہو جاتی ہیں۔" Claude Code اپنے فائل نام کے لیے اسی راستے پر چلتا ہے۔ working directory سے اوپر ڈائریکٹری ہیرارکی میں موجود فائلیں "لانچ کے وقت مکمل لوڈ ہو جاتی ہیں"، اور "تمام دریافت شدہ فائلیں ایک دوسرے پر حاوی ہونے کے بجائے سیاق و سباق (context) میں جوڑ دی جاتی ہیں۔" working directory سے نیچے والی ڈائریکٹریز مختلف برتاؤ کرتی ہیں: Claude Code ان فائلوں کو ضرورت پڑنے پر لوڈ کرتا ہے، "جب Claude ان ڈائریکٹریز میں فائلیں پڑھتا ہے۔"

اس کے دو عملی نتائج نکلتے ہیں۔ root فائل repository میں ہر سیشن کا ایک prefix ہوتی ہے، لہذا وہاں موجود ہر لائن کو ایسی لائن سمجھیں جس کی قیمت آپ ہفتے میں سو بار ادا کرتے ہیں۔ فی ڈائریکٹری فائل کی کوئی قیمت نہیں ہوتی جب ایجنٹ کہیں اور کام کر رہا ہو، جس کا مطلب ہے کہ وہاں تفصیلات سستی ہیں اور وہیں ہونی چاہئیں۔

اس رویے کی تصدیق اگست 2026 میں Codex اور Claude Code کی دستاویزات کے مطابق کی گئی تھی۔ ٹولز اس کنونشن کو قدرے مختلف طریقے سے نافذ کرتے ہیں اور وہ تبدیل بھی ہوتے رہتے ہیں، لہذا اس ایجنٹ کے لیے لوڈنگ کے قواعد کی تصدیق کریں جو آپ کی ٹیم استعمال کرتی ہے۔

تین سروسز پر مشتمل ریپوزٹری کے لیے ایک کارآمد خاکہ

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 پرانا ہو چکا ہے؟

آپ آج دو چیک چلا سکتے ہیں، اور ایک علامت ایسی ہے جو آپ کو سیشن کے دوران نظر آئے گی۔

ہر فائل کی عمر کا موازنہ اس کوڈ کی عمر سے کریں جس کی وہ وضاحت کرتی ہے۔ %cs کمٹ کی تاریخ کو 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

کوڈ کی تاریخ سے چھ ماہ پرانی دستاویز کا مطلب یہ نہیں کہ فائل غلط ہے۔ یہ صرف آپ کو یہ بتاتی ہے کہ پہلے کون سی فائل پڑھنی ہے، اور ایک سیکنڈ میں ہونے والے چیک سے آپ کو بس اتنا ہی جاننا کافی ہے۔

ایسے پاتھس (paths) تلاش کریں جو اب موجود نہیں ہیں۔ دستاویزات ایک خاص طریقے سے خراب ہوتی ہیں: وہ ایسے کوڈ کی وضاحت کرتی رہتی ہیں جو ڈیلیٹ کیا جا چکا ہے۔ ان فائلوں میں ہر پاتھ بیک ٹکس (backticks) میں لکھا ہوتا ہے، اس لیے انہیں نکالنا اور ٹیسٹ کرنا آسان ہے۔

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 میں شامل کرنے کے بجائے اس کی آؤٹ پٹ کو خود پڑھیں۔ یہ src/**/*.ts جیسے گلوبز (globs) اور آپ کے دیے گئے کسی بھی URL کو بھی فلیگ (flag) کر دیتا ہے، کیونکہ دونوں میں سلیش (slash) ہوتا ہے اور ان میں سے کوئی بھی ڈسک پر موجود فائل نہیں ہے۔

سیشن میں علامت۔ ایجنٹ فائل پڑھتا ہے، src/api/client.ts کو کھولنے کی کوشش کرتا ہے کیونکہ فائل نے اسے ایسا کرنے کو کہا تھا، اور ٹول یہ جواب دیتا ہے:

No such file or directory

چنانچہ وہ معقول کام کرتا ہے اور اپنا fetch ریپر (wrapper) لکھ لیتا ہے۔ یہی پرانی فائل کی اصل قیمت ہے۔ ایجنٹ آپ کی دستاویزات کو نظر انداز نہیں کرتا۔ وہ دستاویزات پر عمل کرتا ہے، ایسے پاتھ پر پہنچتا ہے جو تین ماہ پہلے ڈیلیٹ ہو چکا تھا، اور وہ کوڈ دوبارہ بناتا ہے جو آپ کے پاس پہلے سے موجود ہے۔ Ponytail، جو ایجنٹ کو کام کرنے والی سب سے چھوٹی تبدیلی تک محدود رکھتا ہے، جیسے سکلز اس دوبارہ بنانے کے رجحان کو کم کر دیتے ہیں، لیکن یہ اس ہیلپر کو نہیں ڈھونڈ سکتے جس کی طرف آپ کی فائل نے غلط جگہ اشارہ کیا ہو۔

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

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

import فارم اس وقت درست ہے جب آپ مشترکہ لائنوں کے اوپر ٹول کے لیے مخصوص لائنیں شامل کرنا چاہتے ہیں۔ اسے services/worker/CLAUDE.md میں رکھیں:

@AGENTS.md

## Claude Code

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

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 کامیاب ہونے پر کچھ پرنٹ نہیں کرتا، لہذا لسٹنگ چیک کریں: apps/web/CLAUDE.md -> AGENTS.md۔ پھر ایک سیشن شروع کریں اور /context چلائیں، جہاں لوڈ شدہ فائلیں Memory files کے تحت ظاہر ہوتی ہیں۔ ونڈوز پر symlink کے لیے Administrator حقوق یا Developer Mode درکار ہوتا ہے، لہذا وہاں @AGENTS.md import استعمال کریں۔

اس کے ساتھ ایک مسئلہ وابستہ ہے۔ /compact کے بعد، روٹ فائل کو ڈسک سے دوبارہ پڑھا جاتا ہے، لیکن سب ڈائریکٹریز میں موجود nested فائلیں دوبارہ انجیکٹ نہیں ہوتیں۔ وہ اگلی بار واپس آتی ہیں جب ایجنٹ اس ڈائریکٹری میں کوئی فائل پڑھتا ہے۔ اگر فی ڈائریکٹری رول طویل سیشن کے دوران آدھے راستے میں کام کرنا چھوڑ دے، تو عام طور پر یہی وجہ ہوتی ہے، اور ڈائریکٹری میں کسی بھی فائل کو touch کرنے سے وہ دوبارہ فعال ہو جاتا ہے۔

یہ 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 فائل روٹ فائل کی جگہ لے لیتی ہے یا اس میں اضافہ کرتی ہے؟

یہ اس میں اضافہ کرتی ہے۔ Upstream کا کہنا ہے کہ "سب سے قریبی فائل کو ترجیح دی جاتی ہے"، جو کہ تنازعہ کی صورت میں ہونے والے عمل کی وضاحت ہے، نہ کہ اس کی کہ کیا لوڈ ہوتا ہے۔ Codex "روٹ سے نیچے کی طرف فائلز کو اکٹھا کرتا ہے اور انہیں خالی لائنوں کے ساتھ جوڑتا ہے"، اور Claude Code ورکنگ ڈائریکٹری سے اوپر کی طرف جاتے ہوئے ملنے والی ہر فائل کو اکٹھا کرتا ہے، بجائے اس کے کہ وہ انہیں اوور رائڈ کرے۔ سب سے قریبی فائل صرف اس صورت میں غالب آتی ہے جب دو فائلیں ایک ہی موضوع پر مختلف ہدایات دے رہی ہوں۔ مشترکہ اصول ایک بار روٹ میں لکھیں، اور انہیں ہر ڈائریکٹری میں دہرانے کی ضرورت نہیں ہے۔

روٹ AGENTS.md کا سائز کتنا ہونا چاہیے؟

اتنا چھوٹا کہ آپ کو اس بات پر اعتراض نہ ہو کہ اسے اس ریپوزٹری میں آپ کی ہر درخواست کے اوپر پیسٹ کیا جائے، کیونکہ یہی ہوتا ہے۔ Claude Code کی دستاویزات ہر فائل کے لیے 200 لائنوں سے کم رکھنے کا مشورہ دیتی ہیں اور خبردار کرتی ہیں کہ لمبی فائلیں "عمل درآمد کو کم" کرتی ہیں۔ Codex بائی ڈیفالٹ 32 KiB پر انسٹرکشن فائلز کو ضم کرنا بند کر دیتا ہے۔ اگر آپ کی روٹ فائل چار سروسز کی دستاویزات رکھتی ہے، تو اس کا زیادہ تر حصہ کسی ایک ٹاسک کے لیے غیر ضروری بوجھ ہے۔ تفصیلات کو فی ڈائریکٹری فائلز میں منتقل کریں اور پیچھے ایک نقشہ چھوڑ دیں۔

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

روٹ فائل میں ایک اصول لکھیں: جو بھی کسی ڈائریکٹری میں کوڈ تبدیل کرے، وہ اسی کمٹ میں اس ڈائریکٹری کی AGENTS.md کو بھی اپ ڈیٹ کرے۔ فائل کو کوڈ کے ساتھ رکھنا ہی اس اصول کو مؤثر بناتا ہے، کیونکہ تبدیلی اسی پل ریکویسٹ (pull request) ڈف (diff) میں نظر آتی ہے جسے ایک انسان پہلے ہی پڑھ رہا ہوتا ہے۔ ایک CI وارننگ شامل کریں جو ہر تبدیل شدہ پاتھ کو اس کے اوپر موجود قریبی AGENTS.md سے منسلک کرے، اور وقتاً فوقتاً ہر فائل پر git log -1 --format=%cs کا موازنہ اس ڈائریکٹری پر چلنے والی اسی کمانڈ سے کریں جس کی وہ دستاویزات رکھتی ہے۔

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

نہیں۔ اگست 2026 تک کی دستاویزات کے مطابق "Claude Code CLAUDE.md کو پڑھتا ہے، AGENTS.md کو نہیں۔" اسی ڈائریکٹری میں ایک CLAUDE.md بنائیں جس کی پہلی لائن پر @AGENTS.md ہو، جو شیئرڈ فائل کو لوڈ کرتا ہے اور آپ کو اس کے نیچے Claude سے متعلقہ ہدایات شامل کرنے کی اجازت دیتا ہے۔ ln -s AGENTS.md CLAUDE.md کے ساتھ بنائی گئی symlink تب کام کرتی ہے جب مزید کچھ شامل نہ کرنا ہو، حالانکہ ونڈوز پر اس کے لیے ایڈمنسٹریٹر حقوق یا ڈویلپر موڈ درکار ہوتا ہے۔ سیشن میں /context چلائیں اور تصدیق کریں کہ فائل Memory files کے تحت ظاہر ہوتی ہے۔

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

AGENTS.md میں نہیں۔ وہ فائل ہر سیشن میں لوڈ ہوتی ہے، لہذا اس کی ہر لائن آپ کی ٹائپ کردہ درخواست کے ساتھ توجہ حاصل کرنے کے لیے مقابلہ کرتی ہے۔ کئی مراحل پر مشتمل طریقہ کار جو کبھی کبھار درکار ہو، وہ ایک skill میں ہونا چاہیے، جو ضرورت پڑنے پر لوڈ ہوتا ہے۔ وہ اصول جو ایک ڈائریکٹری پر لاگو ہو، وہ اسی ڈائریکٹری کی AGENTS.md میں ہونا چاہیے۔ وہ حقیقت جسے ایجنٹ براہ راست کوڈ سے پڑھ سکتا ہے، جیسے کہ ڈائریکٹری ٹری یا ڈیپینڈنسی لسٹ، ان میں سے کسی میں نہیں ہونی چاہیے۔