AGENTS.md اور HUMAN.md کیا ہیں؟ مکمل وضاحت

AGENTS.md کیا ہے

AGENTS.md ایک سادہ markdown فائل ہے جو repository کے root میں موجود ہوتی ہے اور coding agent کو بتاتی ہے کہ اس project پر کیسے کام کرنا ہے۔ سرکاری site اسے یوں بیان کرتی ہے: "agents کے لیے README: context اور instructions فراہم کرنے کی ایک مخصوص، متوقع جگہ، تاکہ AI coding agents آپ کے project پر کام کر سکیں۔" اس format کی نگرانی Linux Foundation کے تحت Agentic AI Foundation کرتی ہے، اور 20 سے زیادہ agents اسے پڑھتے ہیں، جن میں Codex، Cursor، Jules، Devin اور GitHub Copilot شامل ہیں (July 2026 تک)۔

اس convention کی وجہ عملی ہے۔ آپ کی team میں شامل نیا شخص README پڑھتا ہے، build command کا اندازہ لگاتا ہے، اور اندازہ غلط ہونے پر کسی سے پوچھتا ہے۔ Agent ایسا نہیں کر سکتا۔ وہ اندازہ لگاتا ہے، npm test کو ایسے project پر چلاتا ہے جو pnpm test استعمال کرتا ہے، failure پڑھتا ہے، اور پھر کچھ اور آزماتا ہے۔ آپ ان تمام tokens کی قیمت ادا کرتے ہیں۔ اصل command کو ایک بار لکھ دینے سے اس پوری قسم کی failure ختم ہو جاتی ہے۔

کوئی required fields نہیں ہیں۔ site اس بارے میں واضح ہے: "AGENTS.md صرف standard Markdown ہے۔ اپنی پسند کی کوئی بھی headings استعمال کریں؛ agent صرف فراہم کردہ متن کو parse کرتا ہے۔" یہی مکمل specification ہے۔ اس کی قدر format میں نہیں ہے۔ قدر اس فائل کے ایسے path پر موجود ہونے میں ہے جسے ہر tool پہلے ہی تلاش کرتا ہے۔

فائل کہاں رکھی جاتی ہے اور کون سی فائل ترجیح پاتی ہے

پہلی فائل repository root میں رکھیں۔ monorepo میں آپ ہر subproject کے اندر مزید فائلیں شامل کر سکتے ہیں۔ اصول سادہ ہے: "agents directory tree میں قریب ترین فائل خودکار طور پر پڑھتے ہیں، اس لیے سب سے قریب والی فائل کو ترجیح حاصل ہوتی ہے۔" دو فائلوں میں تضاد ہو تو ترجیح اس فائل کو ملتی ہے جس میں ترمیم کی جا رہی ہو۔ chat میں آپ جو کچھ لکھتے ہیں، وہ دونوں فائلوں کی ہدایات پر فوقیت رکھتا ہے۔

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

درجاتی ساخت استعمال کرنا مفید ہے، کیونکہ اسی کے ذریعے آپ ایسی بات بیان کر سکتے ہیں جو ایک folder میں درست اور اگلے folder میں غلط ہو۔ "ہر endpoint اپنے input کی توثیق کرتا ہے" جیسا اصول endpoints کے ساتھ والی فائل میں ہونا چاہیے۔ root فائل میں یہ اصول ہر غیر متعلقہ task کے دوران load ہوگا اور کوئی فائدہ نہیں دے گا۔

AGENTS.md میں کیا شامل ہونا چاہیے

وہ باتیں لکھیں جنہیں ایجنٹ کوڈ پڑھ کر معلوم نہیں کر سکتا۔ سب سے پہلے build، test اور lint کے عین وہ commands دیں جنہیں آپ terminal میں paste کریں گے۔ ایک test چلانے کا command بھی شامل کریں، کیونکہ جو ایجنٹ صرف پوری test suite چلانا جانتا ہو، وہ پوری suite چالیس بار چلائے گا۔ ان conventions کا نام دیں جو tool کے default سے مختلف ہیں، کیونکہ ایجنٹ default پہلے ہی جانتا ہے اور اسے صرف آپ کی تبدیلی بتانے کی ضرورت ہے۔ اگر آپ کے پاس commit message کی ساخت اور pull request کے قواعد ہیں تو انہیں بھی شامل کریں۔

اتنی واضح ہدایات دیں کہ ہر دعوے کی جانچ ہو سکے۔ "2-space indentation استعمال کریں" قابلِ استعمال ہدایت ہے، کیونکہ یہ واضح طور پر دیکھا جا سکتا ہے کہ ایسا ہوا یا نہیں۔ "کوڈ کو درست طور پر format کریں" قابلِ جانچ نہیں، کیونکہ اس میں کسی مخصوص چیز کی تصدیق نہیں ہو سکتی۔ مقامات کے بارے میں بھی یہی اصول ہے: "API handlers src/api/handlers/ میں موجود ہوتے ہیں" کہنا "فائلوں کو منظم رکھیں" سے بہتر ہے۔

منفی قواعد کے لیے بھی جگہ مختص کریں۔ "dist/ کے اندر موجود فائلوں میں کبھی ترمیم نہ کریں؛ انہیں npm run build generate کرتا ہے" ایک مخصوص غلطی روکتا ہے۔ چونکہ اس میں وجہ بھی دی گئی ہے، اس لیے ایجنٹ وہ مساوی صورت خود سمجھ سکتا ہے جسے آپ نے تحریر نہیں کیا۔

جو چیز کبھی شامل نہیں کرنی چاہیے

ان فائلوں میں کبھی کوئی راز شامل نہ کریں۔ فائل git میں commit ہوتی ہے، ہر session کے آغاز پر context میں لوڈ کی جاتی ہے، اور ہر request پر model provider کو بھیجی جاتی ہے۔ AGENTS.md میں موجود API key آپ کی repository history اور کسی third party کے logs میں موجود API key ہے۔ راز کو نقل کرنے کے بجائے اس کی طرف اشارہ کریں: "database password .env میں ہے، جسے gitignore کیا گیا ہے؛ اسے پڑھنے سے پہلے اجازت لیں۔" وسیع تر طریقہ کار agent کی رسائی سے credentials کو باہر رکھنا میں بیان کیا گیا ہے۔

ایسی کوئی چیز شامل نہ کریں جسے agent دیکھ کر اخذ کر سکتا ہو۔ نقل کی گئی directory listing، dependencies کی فہرست کی copy، یا ایسا architecture overview جو folder names کو دوبارہ بیان کرے: یہ سب لکھنے کے ایک ہفتے بعد پرانا ہو جاتا ہے، اور اس دوران ہر session میں context کی گنجائش استعمال کرتا ہے۔ مسائل اور ان کی وجوہ برقرار رکھیں۔ فہرست حذف کریں۔

CLAUDE.md اسی تصور کی Claude Code مثال ہے

Claude Code CLAUDE.md کو پڑھتا ہے، لیکن خود سے AGENTS.md نہیں پڑھتا۔ پروجیکٹ فائل ./CLAUDE.md یا ./.claude/CLAUDE.md میں ہوتی ہے، ہر پروجیکٹ کے لیے ذاتی ترجیحات ~/.claude/CLAUDE.md میں رکھی جاتی ہیں، اور کوئی ادارہ Linux پر مشین کی سطح کی فائل /etc/claude-code/CLAUDE.md میں رکھ سکتا ہے۔ دریافت کی گئی فائلیں فائل سسٹم کے root سے آپ کی working directory تک ترتیب وار یکجا کی جاتی ہیں، اس لیے جہاں سے آپ نے session شروع کیا ہو، اس کے قریب ترین فائل آخر میں پڑھی جاتی ہے۔

اگر آپ کی repository میں پہلے سے AGENTS.md موجود ہے تو دوسری نقل برقرار نہ رکھیں۔ اسے import کریں، پھر صرف Claude سے متعلق ہدایات شامل کریں:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

جب اضافی چیز شامل نہ کرنی ہو تو symlink کام کرتا ہے:

ln -s AGENTS.md CLAUDE.md

کامیابی کی صورت میں command کچھ بھی ظاہر نہیں کرتا۔ اپنے اگلے session میں /context چلائیں اور تصدیق کریں کہ CLAUDE.md، Memory files کے تحت ظاہر ہوتا ہے۔ اگر یہ اس فہرست میں موجود نہ ہو تو فائل load نہیں ہوئی، اس لیے اس میں شامل کوئی ہدایت لاگو نہیں ہوئی۔ فائل خود لکھنے کے بجائے پہلا مسودہ تیار کرنے کے لیے /init چلائیں: یہ codebase پڑھ کر ابتدائی فائل بناتا ہے، اور اگر CLAUDE.md پہلے سے موجود ہو تو اسے overwrite کرنے کے بجائے بہتریاں تجویز کرتا ہے۔

ہر فائل کو تقریباً 200 سطروں سے کم رکھیں۔ طویل فائلیں window کا زیادہ حصہ استعمال کرتی ہیں اور ہدایات کی پابندی کم ہو جاتی ہے۔ اگر آپ دیکھنا چاہتے ہیں کہ اس جگہ کے لیے اور کیا چیزیں مقابلہ کرتی ہیں تو agent کے context window کو حقیقت میں کیا چیزیں بھرتی ہیں اس کی تفصیل بیان کرتا ہے۔

ایک نکتے پر زور دینا ضروری ہے۔ AGENTS.md رہنمائی ہے، permission system نہیں۔ اس کا مواد عام context کے طور پر شامل ہوتا ہے، اس لیے model اسے پڑھتا ہے اور عموماً اس کی پابندی کرتا ہے، لیکن اس کے خلاف جانے والی کارروائی کو کوئی چیز نہیں روکتی۔ ایسی rule کے لیے جو ہر بار لازماً لاگو ہونی چاہیے، مثلاً "کبھی main پر push نہ کریں"، hook یا permission setting استعمال کریں، کیونکہ یہ code کے طور پر چلتے ہیں اور model کے خود اطاعت کرنے کے فیصلے پر منحصر نہیں ہوتے۔

یہ فائلیں خود تیار کرنے والے ٹولز

30 July 2026 کو GitHub کی trending فہرست میں شامل دو projects سے اندازہ ہوتا ہے کہ یہ طریقہ کس سمت جا رہا ہے۔

agent0ai/dox (July 2026 تک 1,368 stars) AGENTS.md فائلوں کے درخت کو تازہ رکھنے کے لیے ایک framework ہے۔ یہ کوئی package یا runtime فراہم نہیں کرتا۔ آپ اس کی AGENTS.md فائل کا مواد اپنی root AGENTS.md میں copy کرتے ہیں، اور یہی اس کی installation ہے۔ پہلے سے موجود project کے لیے اپنے agent کو یہ ہدایت دیں:

Initialize DOX tree for this project now.

اس کے بعد agent child AGENTS.md فائلیں اور ان کے indexes بناتا ہے، کسی بھی چیز میں ترمیم کرنے سے پہلے اس درخت کا جائزہ لیتا ہے، اور change مکمل ہونے کے بعد متاثرہ documentation کو update کرتا ہے۔ اس کا بنیادی مفروضہ یہ ہے کہ agent اپنے کام کے ضمنی نتیجے کے طور پر برقرار رکھی گئی documentation درست رہتی ہے، جبکہ وہ documentation جسے کوئی شخص دستی طور پر update کرتا ہے، درست نہیں رہتی۔

HUMAN.md، یہی طریقہ آپ پر لاگو

Intuition-Lab/personal-model (جولائی 2026 تک 1,260 ستارے) اس طریقے کو repository کے بجائے کسی شخص پر لاگو کرتا ہے۔ یہ project آپ کے HUMAN.md کو آپ کے لکھے ہوئے file کے بجائے system کے output کے طور پر پیش کرتا ہے: "اس وقت کیا اہم ہے، آپ عموماً فیصلے کیسے کرتے ہیں، اور آپ کی توجہ کس سمت جا رہی ہے، اس کا ایک مسلسل تازہ ہونے والا model۔" یہ macOS 13 یا بعد کے ورژنز پر مقامی طور پر چلتا ہے، macOS کی اجازت دینے کے بعد سرگرمی capture کرتا ہے، اور نتیجہ MCP (model context protocol) کے ذریعے agents کو فراہم کرتا ہے۔ مختصر installation طریقہ:

uv tool install personal-model
persome onboard
persome model open --after 30

زیادہ تر فائدہ حاصل کرنے کے لیے آپ کو ان میں سے کسی چیز کی ضرورت نہیں۔ ہاتھ سے لکھا ہوا HUMAN.md تقریباً 20 سطروں پر مشتمل ہوتا ہے: آپ کا کردار، آپ کا timezone، وہ stack جو آپ حقیقت میں استعمال کرتے ہیں، وہ فیصلے جو آپ پہلے ہی کر چکے ہیں اور دوبارہ زیرِ بحث نہیں لانا چاہتے، اور یہ کہ آپ کتنی وضاحت چاہتے ہیں۔ یہ بار بار وضاحت دینے کی وہی ضرورت کم کرتا ہے جسے project file کم کرتی ہے، مگر ایک سطح اوپر۔

ایک احتیاط ضروری ہے۔ HUMAN.md کسی شخص کا profile ہوتا ہے، اس لیے یہ بنیادی طور پر حساس معلومات پر مشتمل ہوتا ہے۔ اسے public repository میں نہ رکھیں۔ اسے ~/.claude/CLAUDE.md میں رکھیں، یا project root میں gitignored CLAUDE.local.md میں رکھیں۔ یہ committed file کے ساتھ load ہوتا ہے اور اسی طرح استعمال کیا جاتا ہے۔

ایک ابتدائی سانچہ جسے آپ نقل کر سکتے ہیں

یہ جان بوجھ کر مختصر رکھا گیا ہے۔ جو حصے لاگو نہ ہوں انہیں حذف کریں، اور ایسے حصے شامل کرنے سے گریز کریں جنہیں آپ تازہ حالت میں برقرار نہیں رکھ سکتے۔

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

اسے لکھیں، پھر وہیں درست کریں۔ کسی سطر کو شامل کرنے کا اشارہ یہ ہے کہ آپ نے چیٹ میں ایک ہی تصحیح دو بار لکھی ہو۔ یہ ایک اصول فائل کو مفید رکھتا ہے اور اسے ایسی دستاویز بننے سے روکتا ہے جسے کوئی نہیں پڑھتا، حتیٰ کہ مشینیں بھی نہیں۔ مستحکم ہونے کے بعد یہ repository کے ساتھ رہتی ہے۔ یہ خاص طور پر اس وقت اہم ہے جب agent آپ کے laptop کے علاوہ کسی اور جگہ چل رہا ہو: اپنے server پر coding agent چلانا میں اس setup کا احاطہ کیا گیا ہے۔

FAQ

کیا AGENTS.md وہی فائل ہے جو CLAUDE.md ہے؟

یہ دو فائل ناموں کے تحت ایک ہی تصور ہیں۔ Claude Code CLAUDE.md پڑھتا ہے اور AGENTS.md کو نظرانداز کرتا ہے، جب تک آپ انہیں مربوط نہ کریں۔ ایک فائل کو اصل ماخذ رکھیں اور دوسری کو اس سے لنک کریں۔ اس کے لیے اپنی CLAUDE.md کے آغاز میں @AGENTS.md والی سطر لکھیں، یا ln -s AGENTS.md CLAUDE.md استعمال کریں۔ الگ الگ برقرار رکھی گئی دو مکمل نقول ایک ماہ کے اندر مختلف ہو جائیں گی۔

کیا AGENTS.md لکھنے سے ایجنٹ کی جانب سے اس پر عمل کرنے کی ضمانت ملتی ہے؟

نہیں۔ اس کا متن context کے طور پر فراہم کیا جاتا ہے، اس لیے ماڈل اسے پڑھتا ہے اور عموماً اس پر عمل کرتا ہے، لیکن کوئی ایسی چیز کسی متضاد کارروائی کو نہیں روکتی جو اس کے خلاف ہو۔ مبہم ہدایات پر سب سے کم قابلِ اعتماد طریقے سے عمل ہوتا ہے، اور متضاد رہنمائی دینے والی دو فائلیں ایجنٹ کو کسی ایک کو من مانے طور پر منتخب کرنے پر چھوڑ دیتی ہیں۔ جس اصول پر ہر بار عمل ضروری ہو، اس کے لیے hook یا permission rule استعمال کریں۔ ماڈل کے فیصلے سے قطع نظر client انہیں نافذ کرتا ہے۔

کیا AGENTS.md کو git میں commit کرنا چاہیے؟

ہاں، ہر اس چیز کے لیے جو project کے بارے میں درست ہو، مثلاً build commands، layout اور conventions۔ یہی اس فائل کا مقصد ہے، کیونکہ اس کے بعد آپ کے ساتھیوں کے agents بھی اسی context کے ساتھ شروع ہوتے ہیں جس کے ساتھ آپ کا agent شروع ہوتا ہے۔ ذاتی یا صرف ایک machine سے متعلق چیزیں الگ gitignored فائل میں رکھیں، اور credentials کو کسی بھی فائل میں نہ رکھیں۔

HUMAN.md کیا ہے، اور کیا مجھے اس کی ضرورت ہے؟

HUMAN.md کسی project کے بجائے کسی شخص کا machine-readable profile ہوتا ہے۔ اس میں آپ کا role، پابندیاں اور وہ فیصلے درج ہوتے ہیں جنہیں آپ پہلے ہی حتمی کر چکے ہیں، تاکہ ہر session میں انہیں دوبارہ زیرِ بحث نہ لایا جائے۔ آغاز کے لیے کسی tooling کی ضرورت نہیں: آپ کی user-level instructions file میں ہاتھ سے لکھی ہوئی بیس سطریں زیادہ تر فائدہ فراہم کرتی ہیں۔ اسے personal data سمجھیں اور جس repository کو آپ push کرتے ہیں، اس میں شامل نہ کریں۔