AGENTS.md اور HUMAN.md کیا ہیں؟ مکمل رہنما

AGENTS.md کیا ہے

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

یہ convention عملی ضرورت کی وجہ سے موجود ہے۔ آپ کی ٹیم میں نیا شخص README پڑھتا ہے، build command کا اندازہ لگاتا ہے، اور غلطی ہونے پر کسی سے پوچھ لیتا ہے۔ Agent سوال نہیں کر سکتا۔ وہ اندازے سے ایسے project پر npm test چلاتا ہے جو 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

یہ nesting استعمال کرنا مفید ہے، کیونکہ کسی ایک folder میں درست اور اگلے folder میں غلط ہونے والی بات بیان کرنے کا یہی طریقہ ہے۔ "ہر endpoint اپنے input کی توثیق کرتا ہے" جیسا rule endpoints کے ساتھ والی فائل میں ہونا چاہیے۔ root file میں یہ ہر غیر متعلقہ task کے دوران load ہوگا اور کوئی فائدہ نہیں دے گا۔ اگر آپ کی root file میں پہلے ہی ہر service کے لیے الگ section بن چکا ہے تو اسے nested layout میں تقسیم کرنا درست حل ہے۔ اس سے یہ بھی واضح ہوتا ہے کہ کون سے rules نیچے منتقل کرنے ہیں اور کون سے اوپر رکھنے ہیں۔

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

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

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

منفی قواعد بھی شامل کرنے چاہییں۔ "dist/ کے اندر موجود files میں کبھی ترمیم نہ کریں؛ یہ npm run build سے generate ہوتی ہیں" ایک مخصوص غلطی کو روکتا ہے۔ چونکہ اس میں وجہ بھی بیان کی گئی ہے، agent اس مساوی صورتِ حال کا خود اندازہ لگا سکتا ہے جسے آپ نے صراحتاً درج نہیں کیا۔ Scope سے متعلق rule بھی یہاں شامل ہونا چاہیے، کیونکہ اپنے فیصلے پر چھوڑا جائے تو agent آپ کی مطلوبہ حد سے زیادہ تبدیلیاں کر دے گا: ایک وسیع پیمانے پر نقل کی جانے والی skill صرف اس بات پر اصرار کرتی ہے کہ کام کرنے والی سب سے چھوٹی تبدیلی کی جائے۔

جو کسی ایک فائل میں نہیں ہونا چاہیے

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

وہ چیزیں شامل نہ کریں جنہیں agent دیکھ کر خود اخذ کر سکتا ہے۔ Paste کی گئی directory listing، dependency list کی copy، یا folder names کو دوبارہ بیان کرنے والا architecture overview—یہ سب لکھنے کے ایک ہفتے بعد پرانا ہو جاتا ہے، جبکہ اس دوران ہر session میں context کی گنجائش استعمال کرتا رہتا ہے۔ Pitfalls اور ان کی وجوہات برقرار رکھیں۔ Inventory حذف کر دیں۔ وجوہات کو الگ سے رکھنا مفید ہے، کیونکہ جو agent یہ نہیں دیکھ سکتا کہ کوئی غیر معمولی structure کیوں موجود ہے، وہ اسے خاموشی سے refactor کر دے گا۔ یہی وجہ ہے کہ اس کے ساتھ DESIGN.md رکھنا ضروری ہے۔

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

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

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

@AGENTS.md

## Claude Code

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

اگر آپ کو اضافی مواد شامل نہیں کرنا تو symlink کافی ہے:

ln -s AGENTS.md CLAUDE.md

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

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

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

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

30 July 2026 کو GitHub کی trending فہرست میں شامل دو projects دکھاتے ہیں کہ یہ convention کس سمت جا رہی ہے۔

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

Initialize DOX tree for this project now.

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

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

Intuition-Lab/personal-model (July 2026 تک 1,260 stars) اسی pattern کو repository کے بجائے ایک شخص پر لاگو کرتا ہے۔ یہ project آپ کے HUMAN.md کو آپ کی لکھی ہوئی file کے بجائے system کے output کے طور پر پیش کرتا ہے: "اس وقت کیا اہم ہے، آپ عموماً فیصلے کیسے کرتے ہیں، اور آپ کی توجہ کس سمت بڑھ رہی ہے، اس کا ایک زندہ ماڈل۔" یہ macOS 13 یا اس کے بعد کے ورژن پر مقامی طور پر چلتا ہے، macOS کی اجازت دینے کے بعد activity 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 ہوتی ہے اور اسی طرح استعمال کی جاتی ہے۔

ایک ابتدائی template جسے آپ copy کر سکتے ہیں

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

# 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.

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

FAQ

کیا AGENTS.md وہی file ہے جو CLAUDE.md ہے؟

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

کیا AGENTS.md لکھنے سے یہ یقینی ہو جاتا ہے کہ agent اس پر عمل کرے گا؟

نہیں۔ اس کا content context کے طور پر فراہم کیا جاتا ہے، اس لیے model اسے پڑھتا ہے اور عموماً اس پر عمل کرتا ہے، لیکن ایسی action کو روکنے والا کچھ نہیں ہوتا جو اس کی خلاف ورزی کرے۔ مبہم ہدایات پر سب سے کم قابلِ اعتماد طریقے سے عمل ہوتا ہے، اور مخالف ہدایات دینے والی دو files کی صورت میں agent کسی ایک کو من مانے طور پر منتخب کر سکتا ہے۔ جو rule ہر بار نافذ ہونا ضروری ہو، اس کے لیے hook یا permission rule استعمال کریں۔ Client انہیں model کے فیصلے سے قطع نظر نافذ کرتا ہے۔

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

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

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

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