اگر آپ اپنے کوڈنگ ایجنٹ سے ایک نئے اینڈ پوائنٹ کی درخواست کرتے ہیں، تو آپ کے پاس 90 سیکنڈ میں کام کرنے والا اینڈ پوائنٹ ہوگا۔
پھر میں نے اختلافات کو پڑھا اور پایا کہ اس نے توثیق کی لائبریری درآمد کی ہے جو صارف کی لائبریری میں نہیں تھی۔ package.jsonپچھلی بہار میں ٹیم نوڈ ٹیسٹ رنر کے پاس چلی گئی، لیکن ہم جیسٹ میں اپنے ٹیسٹ لکھ رہے تھے اور یہ نہیں جان سکے کہ کوڈ بیس میں موجود ہر دوسرا ہینڈلر کسی سروس کو ڈیلیٹ کرے گا، اس لیے ہم نے روٹ ہینڈلر کے اندر ڈیٹا بیس کو مارا۔
آپ کا کوڈ چلے گا اور آپ کے لکھے ہوئے ٹیسٹ پاس ہو جائیں گے، لیکن آپ کو پھر بھی اس میں سے زیادہ تر کو دوبارہ لکھنا پڑے گا۔
اس میں سے کوئی بھی ماڈل کی طرف سے ایک نتیجہ کی ناکامی نہیں ہے۔ جیسا کہ میں نے مسئلہ کو سمجھا، میں نے ایک معقول حل پیش کیا، لیکن میں واقعی مسئلہ نہیں سمجھ سکا کیونکہ مجھے کسی نے نہیں بتایا کہ یہ مخصوص کوڈ بیس کیسے کام کرتا ہے۔
آپ کے قواعد آپ کی ٹیم کے سروں میں رہتے ہیں، کوڈ کے جائزے کے تبصروں میں، اور فیصلوں میں 18 مہینے پہلے کسی نے نہیں لکھا تھا۔ ایجنٹ ان میں سے کسی کو نہیں دیکھ سکتا، اس لیے یہ اب تک تربیت یافتہ تمام ڈبوں کی اوسط پر واپس آتا ہے۔ یہ وہی ہے جو آپ کو ملتا ہے.
ترمیمات کو ہر سیشن میں دوبارہ داخل کرنا ضروری ہے، اور مزید کوئی اشارے نہیں ہیں کیونکہ ہر ٹیم ممبر ایک مختلف ورژن لکھتا ہے۔ ترمیم ایک ذخیرہ میں فائلوں کا ایک مجموعہ ہے جو خود بخود لوڈ اور برقرار رہتا ہے اسی طرح جس طرح آپ اپنے کوڈ کو برقرار رکھتے ہیں۔
یہ ٹیوٹوریل آپ کو دکھاتا ہے کہ ان فائلوں کی ساخت کیسے بنائی جائے، چار یا پانچ مختلف فارمیٹس میں سچائی کے ایک ماخذ کو کیسے برقرار رکھا جائے جس کی مختلف ٹولز توقع کرتے ہیں، اور سب سے اہم، فائلوں کو خاموشی سے پرانے ہونے سے کیسے روکا جائے۔ بہر حال، ایک سیاق و سباق کی فائل جو ایک کوڈ بیس کی وضاحت کرتی ہے جسے آپ نے چھ ماہ قبل حذف کیا تھا، کسی بھی سیاق و سباق کی فائل سے بدتر ہے۔
یہاں سب کچھ ایک ساتھی ذخیرہ (github.com/Adeniyikayodee/MCF) پر بنایا گیا ہے جسے آپ کلون اور چلا سکتے ہیں۔ کوئی انحصار نہیں ہے، لہذا کوئی بھی نوڈ 20 یا اس سے زیادہ کافی ہے۔
انڈیکس
شروع کرنے سے پہلے آپ کو کیا ضرورت ہے۔
آپ کو گٹ اور ٹرمینل سے واقف ہونا چاہئے، آپ نے نوڈ 20 یا اس سے زیادہ انسٹال کیا ہے، اور آپ نے کم از کم ایک کوڈنگ ایجنٹ جیسے کلاڈ کوڈ، کرسر، گٹ ہب کوپائلٹ، یا کوڈیکس کو حقیقی پروجیکٹ پر استعمال کیا ہے۔
اس ٹیوٹوریل میں سب کچھ ڈسک پر موجود فائلوں کے بارے میں ہے، لہذا آپ کو اس بارے میں کچھ جاننے کی ضرورت نہیں ہے کہ ماڈلز اندرونی طور پر کیسے کام کرتے ہیں۔
سیاق و سباق کی کھڑکی ایک حقیقی حد کیوں ہے۔
ہر وہ چیز جو ایجنٹ کسی کام کو انجام دیتے وقت جانتا ہے ایک بفر میں ہے جسے سیاق و سباق کی کھڑکی کہتے ہیں۔ اس بفر میں سسٹم پرامپٹس، ڈائیلاگ، ایجنٹ کی طرف سے کھولی گئی تمام فائلیں، جاری کردہ تمام کمانڈز، اور کوئی بھی اسٹیک ہوتا ہے جو پرنٹ شدہ ان کمانڈز پر نظر رکھتا ہے۔
تاہم، یہ جاننا ضروری ہے کہ یہ محدود ہے اور زیادہ تر لوگوں کی توقع سے زیادہ تیزی سے بھر جائے گا۔ مثال کے طور پر، ایجنٹ کے کوڈ کی ایک لائن لکھنے سے پہلے ایک ہی ڈیبگنگ سیشن دسیوں ہزار ٹوکنز کو جلا سکتا ہے۔
اس ٹیوٹوریل کا اہم حصہ یہ ہے کہ جب بفر بھر جاتا ہے تو کیا ہوتا ہے۔ اینتھروپک کی انجینئرنگ ٹیم ایک اثر کو بیان کرتی ہے جسے وہ سیاق و سباق میں بدعنوانی کہتے ہیں، جہاں ٹوکنز کی تعداد بڑھنے کے ساتھ ہی مخصوص ہدایات کو بازیافت کرنے کی ماڈل کی صلاحیت بگڑ جاتی ہے۔ ماڈل ضد کی وجہ سے آپ کو نظر انداز نہیں کر رہی ہے، وہ ایک توجہ والے بجٹ کے ساتھ کام کر رہی ہے جو زیادہ مواد کے مقابلے کے ساتھ ساتھ پتلا ہوتا جاتا ہے۔
یہ واحد حقیقت سیاق و سباق کی فائلوں کے بارے میں زیادہ تر لوگوں کے وجدان کو پلٹ دیتی ہے۔ زیادہ لکھنا زیادہ محفوظ محسوس ہوتا ہے کیونکہ میں نے زیادہ کیسز کا احاطہ کیا ہے اور موقع کم ہی چھوڑا ہے۔ لیکن آپ جو بھی سطر شامل کرتے ہیں وہ محدود توجہ کے لیے ہر دوسری سطر کا مقابلہ کرتی ہے۔
کلاڈ کوڈ کی دستاویزات واضح طور پر نتائج کی وضاحت کرتی ہیں، یہ نوٹ کرتے ہوئے کہ پھولی ہوئی ہدایات کی فائلیں ایجنٹوں کو اپنے اندر موجود قواعد کو نظر انداز کرنے کا سبب بنتی ہیں۔ مزید برآں، اگر فائل بہت لمبی ہے، تو یہ ایجنٹ کی طرف سے واضح طور پر لکھے گئے قواعد کی بار بار خلاف ورزی کی علامت بن جاتی ہے۔
آپ کے سیشن کا بجٹ اصل کام پر کس طرح خرچ ہوتا ہے اس کا اندازہ یہ ہے:
system prompt and tool definitions ~12,000 tokens
context files loaded at startup ~4,800 tokens
three source files the agent opened ~9,000 tokens
one test run with a stack trace ~3,500 tokens
اس فہرست میں موجود 4,800 ٹوکن سیاق و سباق کی فائلیں اسٹیک ٹریس کے ساتھ مقابلہ کرتی ہیں جنہیں ایجنٹ کو بگ کو ٹھیک کرنے کے لیے پڑھنا چاہیے۔ صحیح راستے کا نام دینے والی 600 ٹوکن فائل ایجنٹ کے لیے خود کوڈ کو پڑھنے کے لیے جگہ چھوڑ دیتی ہے، جو بہت اچھا ہے۔
سیاق و سباق کی فائلیں بجٹ مختص کرنے کا مسئلہ ہیں اس سے پہلے کہ وہ دستاویزات کا مسئلہ ہوں، اور اس ٹیوٹوریل میں تقریباً تمام تر بہتری اسے سنجیدگی سے لینے سے آتی ہے۔
تین تہوں
کام پر ڈھانچہ مختلف اخراجات کے ساتھ سیاق و سباق کو تین الگ الگ تہوں کے طور پر مانتا ہے:
کہ پرتیں ہمیشہ بھری ہوتی ہیں۔ یہ ریپوزٹری کے روٹ میں ایک واحد فائل ہے جسے ایجنٹ ہر سیشن کے شروع میں پڑھتا ہے، چاہے وہ کام ٹائپنگ کی غلطی کو ٹھیک کر رہا ہو یا منتقلی کر رہا ہو۔ آپ جب بھی ان فائلوں کی درخواست کرتے ہیں ان کے لیے ادائیگی کرتے ہیں، اس لیے صرف وہی فائلیں رکھی جاتی ہیں جو آپ کے ذخیرے میں تمام کارروائیوں پر لاگو ہوتی ہیں۔ یہ اتنا چھوٹا بھی رہتا ہے کہ ایک منٹ سے بھی کم وقت میں بلند آواز میں پڑھا جا سکتا ہے۔
کہ دائرہ کار پرت یہ نیسٹڈ فائلوں پر مشتمل ہوتا ہے جو صرف اس وقت لوڈ ہوتی ہیں جب ایجنٹ کسی مخصوص ڈائریکٹری میں کام کرتا ہے۔ API پرت کے قواعد یہ ہیں: src/AGENTS.mdلہذا، آپریشن جو صرف فرنٹ اینڈ کو متاثر کرتے ہیں ادائیگی نہیں کرتے ہیں۔
کہ آن ڈیمانڈ پرت یہ ایک عام دستاویز ہے جہاں روٹ فائل ان لائن کے بجائے راستے کی طرف اشارہ کرتی ہے۔ ایک راستے پر کچھ ٹوکن لاگت آسکتی ہے، جبکہ اس کے پیچھے موجود دستاویز کی لاگت 2,000 ہوسکتی ہے، لہذا ایجنٹ صرف اس بجٹ کو خرچ کرتا ہے جب کام کو درحقیقت اس کی ضرورت ہو۔
یہ نئے انجینئرز کے کام کرنے کے طریقے کی عکاسی کرتا ہے کیونکہ انہیں اپنے پہلے دن فن تعمیر کی دستاویزات یاد نہیں رہتیں۔ انہیں یاد ہے کہ یہ موجود ہے اور جب ضرورت ہو تو اسے پڑھتے ہیں۔
ساتھی ذخیرہ کی مکمل ترتیب یہ ہے:
MCF/
├── AGENTS.md always loaded, budgeted
├── CLAUDE.md generated from AGENTS.md
├── .github/copilot-instructions.md generated from AGENTS.md
├── .cursor/rules/testing.mdc glob scoped, hand written
├── .claude/
│ ├── settings.json hook that runs the context linter
│ └── skills/add-endpoint/SKILL.md workflow, loaded on demand
├── docs/
│ ├── architecture.md
│ ├── testing.md
│ └── decisions/0001-in-memory-store.md
├── scripts/
│ ├── context-lint.mjs
│ └── sync-context.mjs
├── src/
│ ├── AGENTS.md scoped to the source tree
│ ├── api/tasks.js
│ ├── services/tasks.js
│ ├── lib/validate.js
│ ├── router.js
│ └── server.js
└── tests/
4 کاپیاں برقرار رکھے بغیر فارمیٹ کا انتخاب کریں۔
ہر وینڈر نے اسی خیال کے لیے ایک مختلف فائل کا نام منتخب کیا۔ یہ مایوس کن ہے، لیکن ایک بار جب آپ یہ طے کر لیں کہ سچائی کا ماخذ کون سا ہے۔
AGENTS.md یہ اشتراک کے اصول کے قریب ترین چیز ہے۔ یہ سادہ مارک ڈاؤن ہے جس میں کوئی مطلوبہ اسکیما نہیں ہے، اس کی حکمرانی کا تعلق لینکس فاؤنڈیشن کے ایجنٹی AI فاؤنڈیشن سے ہے، اور یہ مقامی طور پر Claude Code، Codex، Cursor، Copilot، Gemini CLI، Aider، Windsurf، Zed اور دیگر کی ایک طویل فہرست سے پڑھتا ہے۔
نیسٹڈ فائلیں قیاس کا حصہ ہیں، آپ جس کوڈ میں ترمیم کر رہے ہیں اس کے قریب ترین فائل کو فوقیت حاصل ہے، اور جو کچھ بھی آپ براہ راست چیٹ میں ٹائپ کرتے ہیں وہ ہر چیز پر فوقیت رکھتی ہے۔
ٹول کے ساتھ مخصوص فارمیٹس اب بھی ایک ساتھ موجود ہیں۔ کلاڈ کوڈ پڑھنا CLAUDE.mdیہ تمام پائی جانے والی اشیاء کو جوڑنے والی ڈائریکٹری ٹری کو عبور کرتا ہے اور حل کرتا ہے۔ @path/to/file درآمد کرسر کا مقصد .mdc اندر فائل .cursor/rules/ YAML ہیڈر استعمال کریں جو آپ کو اس طرح کے گلوب تک اصول کو دائرہ کار کرنے کی اجازت دیتے ہیں: tests/**/*.jsیہ فارمیٹس کا سب سے زیادہ تاثراتی اور کم سے کم پورٹیبل ہے کیونکہ اسے کرسر سے باہر کسی بھی چیز سے نہیں پڑھا جا سکتا ہے۔ GitHub Copilot مواد کا ایک حصہ پڑھتا ہے۔ .github/copilot-instructions.md مخزن کی جڑ سے۔
عملی جواب لکھنا ہے۔ AGENTS.md پہلے باقی بنائیں، اور صرف الگ فائلیں خود لکھیں اگر ٹول کچھ فراہم کرتا ہے جس کا اظہار مشترکہ فارمیٹ میں نہیں کیا جا سکتا۔ عملی طور پر اس کا مطلب ہے کرسر کی گلوب اسکوپنگ کی وضاحت کرنا۔ علامتی روابط کا استعمال کرتے ہوئے تخلیق کو پورا کیا جاسکتا ہے۔
ln -s AGENTS.md CLAUDE.md
Symlinks ونڈوز اور کچھ CI چیک آؤٹ کنفیگریشنز پر تعاون کرنے والوں کے لیے مسائل کا باعث بنتے ہیں، لیکن چونکہ یہ سب سے مختصر راستہ ہے، اس کے بجائے ساتھی ذخیرہ ایک چھوٹا اسکرپٹ استعمال کرتا ہے۔ اسکرپٹ تخلیق ہونے والی ہر فائل پر ایک بینر لکھتا ہے، نیک نیت ٹیم کے اراکین کو کاپی میں ترمیم کرنے اور اگلی مطابقت پذیری پر اپنا کام کھونے سے روکتا ہے۔
// scripts/sync-context.mjs
const banner = ``;
export const targets = [
// Claude Code resolves @path imports, so its file stays a pointer plus what is specific to it.
{ path: 'CLAUDE.md', render: () => `${banner}nn@${SOURCE}nn${CLAUDE_EXTRAS}` },
// Copilot has no import syntax, so the source is inlined.
{ path: '.github/copilot-instructions.md', render: (source) => `${banner}nn${source}` },
];
چونکہ کلاڈ کوڈ درآمد کو حل کرتا ہے، اس لیے تیار کردہ فائل پوائنٹرز اور چند ہدایات کو برقرار رکھتی ہے جو صرف اس ٹول کے لیے موزوں ہیں، اس لیے یہ پوری چیز کو نقل کرنے کے بجائے تقریباً 130 ٹوکنز کو برقرار رکھتی ہے۔
@AGENTS.md
## Claude Code specific
- Use plan mode for any change that touches more than three files, and skip it for a one line fix.
- Delegate codebase exploration to a subagent so the findings come back summarised rather than as
a hundred file reads in the main context.
اسکرپٹ کو چلانے سے دونوں فائلیں دوبارہ بنتی ہیں، اور اسے دوبارہ چلانے سے کچھ نہیں ہوتا۔ یہ وہی ہے جو آپ ہک یا کسی ایسی چیز سے چاہتے ہیں جو آپ کا CI ٹاسک بار بار کال کرتا ہے۔
روٹ فائل بنائیں
یہ وہ جگہ ہے جہاں زیادہ تر قدر ہوتی ہے اور جہاں زیادہ تر لوگ غلط ہو جاتے ہیں۔ کیونکہ جبلت ہر چیز کو ریکارڈ کرنا ہے۔
ہر اس لائن کے لیے ایک ترمیمی ٹیسٹ استعمال کریں جو آپ شامل کرنا چاہتے ہیں۔ اگر میں اس لائن کو حذف کرتا ہوں تو کیا ایجنٹ غلطی کرے گا؟ اگر جواب نفی میں ہے تو اس لائن کو کاٹ دیں کیونکہ یہ آپ کی ریاست کا بجٹ برباد کر رہا ہے اور کچھ نہیں خرید رہا ہے۔ اگر ایمانداری سے لاگو کیا جاتا ہے، تو یہ ٹیسٹ ان فائلوں میں لوگوں کی ڈالی ہوئی زیادہ تر چیزوں کو ہٹا دے گا۔
فائلوں کی جن اقسام کو ٹیسٹ پکڑنے کے لیے ڈیزائن کیا گیا ہے وہ ہیں:
# AGENTS.md
## About this project
This project is a REST API for managing tasks. It was originally built in 2023 by the platform
team and has since been maintained by the core services group. The codebase is written in modern
JavaScript using ES modules.
## Code style
- Use meaningful variable names
- Write clean, maintainable code
- Follow the DRY principle
- Use const instead of var
- Add comments where the code is complex
## Structure
- `src/server.js` contains the server
- `src/router.js` contains the router
- `src/api/tasks.js` contains the task handlers
- `src/services/tasks.js` contains the task service
وہاں کی ہر سطر امتحان میں ناکام ہو جاتی ہے۔ میں ماڈل کو پہلے ہی جانتا ہوں۔ const آپ دیکھ سکتے ہیں کہ اس طرح کی فائلیں ہیں: router.js راؤٹرز کو شامل کیا گیا ہے، اور یہ جان کر کہ 2023 میں کون سی ٹیم کوڈ کی مالک ہے، وہ ایک بھی فیصلہ تبدیل نہیں کرتا ہے۔
دریں اثنا، ایک چیز جسے ایجنٹ واقعی خود حل نہیں کر سکتا وہ یہ ہے کہ اس پروجیکٹ میں جان بوجھ کر کوئی انحصار نہیں ہے – وہ فائلوں میں کہیں نہیں ہیں۔
یہ ساتھی ذخیرہ میں فراہم کردہ ورژن ہے۔
# AGENTS.md
Task API used as the worked example for a tutorial on managing context files. This file is the
single source of truth for agent instructions, and `CLAUDE.md` plus
`.github/copilot-instructions.md` are generated from it by `npm run sync:context`, so edit this
file and never the generated ones.
## Commands
- Install: nothing to install, the project has zero dependencies
- Run the tests: `npm test`
- Start the server on port 3000: `npm start`
- Check the context files: `npm run lint:context`
- Regenerate the tool specific context files: `npm run sync:context`
## Conventions that are not obvious from the code
- The test runner is the Node built in runner invoked through `node --test`, so do not add Jest,
Vitest, or any other test dependency to this repository.
- This project stays dependency-free on purpose, so solve problems with the Node standard library
rather than by adding a package.
- Handlers in `src/api/` return `{ data }` or `{ error: { code, message } }` and never choose an
HTTP status, because `src/router.js` owns the mapping from error code to status.
- Handlers never touch the store directly, so any logic that reads or writes tasks belongs in
`src/services/tasks.js`.
- The store is module level state that survives between test cases, so any test file that creates
a task has to call `resetTasks()` in a `beforeEach` hook.
## Definition of done
Run `npm test` and `npm run lint:context` before you report a task as finished, and paste the
output rather than asserting that it passed.
## Where to look
- Architecture and request flow: `docs/architecture.md`
- Testing conventions and how to add a case: `docs/testing.md`
- Why the store is in memory: `docs/decisions/0001-in-memory-store.md`
- Rules that apply only to the API layer: `src/AGENTS.md`
دیکھیں کہ ہر سیکشن کیا کرتا ہے۔ کمانڈ موجود ہے کیونکہ ایجنٹ اسکرپٹ کے نام کا بھروسہ انداز میں اندازہ نہیں لگا سکتا، اور برا اندازہ عمل میں ناکامی کا سبب بنے گا۔ قاعدہ وہ چیز ہے جو کوڈ کو پڑھتے وقت یا تو پوشیدہ ہوتی ہے یا ماڈل کے مانے ہوئے اصولوں سے متصادم ہوتی ہے، اور ہر ریاست کو ایک وجہ سے منسلک کرتے ہیں کیونکہ وہ ایسے حالات میں بھی زندہ رہتے ہیں جن کی قاعدہ کے مصنف کو توقع نہیں تھی۔ آخری سیکشن صرف راستہ ہے، آن ڈیمانڈ پرت جو کام کرتی ہے۔
جگہ حاصل کرنے کے لیے سخت ہدایات:
| شامل | باہر جاؤ |
|---|---|
| ایسے احکامات جن کا ایجنٹ اندازہ نہیں لگا سکتا | جب آپ کوڈ پڑھتے ہیں تو سب کچھ آپ دیکھتے ہیں۔ |
| قواعد زبان کے ڈیفالٹس سے مختلف ہیں۔ | معیاری قواعد جو ماڈل پہلے ہی جانتا ہے۔ |
| ٹیسٹ رنر اور ٹیسٹ چلانے کا طریقہ | تفصیلی API دستاویزات، جو ایک لنک ہونا چاہیے۔ |
| برانچ کا نام اور پل کی درخواست کے آداب | معلومات جو ہر سپرنٹ کو تبدیل کرتی ہے۔ |
| آپ کے پروجیکٹ سے متعلق آرکیٹیکچرل فیصلے | لمبی وضاحتیں اور سبق |
| ماحولیاتی خصوصیات اور مطلوبہ متغیرات | درخت میں فائل کی تفصیل کے لحاظ سے فائلیں۔ |
| غیر واضح مسئلہ | مشورہ جیسے "کلین کوڈ لکھیں” |
درست اونچائی حاصل کرنا
غلط قواعد لکھنے کا دوسرا طریقہ یہ ہے کہ ان کی غلط سطح پر وضاحت کی جائے۔ اینتھروپک کی ہدایات اس کو صحیح اونچائی کو تلاش کرنے کے طور پر تیار کرتی ہیں، اور سخت کوڈڈ منطق کے درمیان بیٹھ جاتی ہیں جو پہلے غیر متوقع معاملے میں الگ ہوجاتی ہے اور مبہم حوصلہ افزائی جو ماڈل کو کچھ نہیں کرتی ہے۔
Too rigid, and it breaks on the first handler that does not fit:
- Every route handler must be exactly 40 lines and call validate() on line 3.
Too vague, and it changes nothing about what the agent does:
- Write clean, maintainable code.
Right altitude:
- Route handlers parse and validate input, then delegate to a function in `src/services/`.
Handlers do not touch the store directly. See `src/api/tasks.js` for the pattern to copy.
تیسرا ورژن ایجنٹ کو بتاتا ہے کہ قاعدہ کیسا نظر آنا چاہیے، اسے کن حدود کو عبور نہیں کرنا چاہیے، اور حقیقی دنیا کی مثالیں کہاں تلاش کی جائیں۔ یہ تقریباً وہی ہے جو آپ کسی باصلاحیت نئے ملازم کو ان کے پہلے دن کہیں گے۔
ڈائریکٹریز کے لیے اسکوپنگ کے اصول
کوئی بھی چیز جو درخت کے صرف ایک حصے کے اندر اہم ہے وہ نیسٹڈ فائل سے تعلق رکھتی ہے، اور یہ جانچنا کہ آیا کوئی قاعدہ مناسب ہے آسان ہے۔ کیا دوسری ڈائریکٹریوں میں کام کرنے والے ڈویلپرز کو یہ معلوم ہونا چاہیے؟ اگر نہیں تو نیچے کی طرف بڑھیں۔
# Source layer
Rules below apply to everything under `src/`, and they sit on top of the root `AGENTS.md` rather
than replacing it.
## Adding an endpoint
1. Add the handler to `src/api/tasks.js` following the shape the neighbouring handlers use.
2. Add one entry to the `routes` array in `src/router.js` with its success status.
3. Add a case to `tests/api.test.js` that covers the success path and the failure path.
## Validation
Validators live in `src/lib/validate.js`, they return an array of problem strings rather than
throwing, and they report every failing field instead of stopping at the first one, so a caller can
show the user all of their mistakes at once.
یہ توثیق کا اصول لکھنے کے قابل ایک اچھی مثال ہے کیونکہ اسے صرف کوڈ میں بیان نہیں کیا جا سکتا۔ ایجنٹ پڑھنا src/lib/validate.js کسی فنکشن کو دیکھ کر بتانے کا کوئی طریقہ نہیں ہے جو ایک صف کو لوٹاتا ہے کہ آیا یہ جان بوجھ کر اصول ہے یا صرف ایک نفاذ کا ایک فلوک، لہذا اگلا توثیق کنندہ جو آپ لکھتے ہیں وہ معقول طور پر ایک استثنا دے سکتا ہے۔
// src/lib/validate.js
export function validateTaskInput(input) {
if (typeof input !== 'object' || input === null || Array.isArray(input)) {
return ['body must be a JSON object'];
}
const problems = [];
if (typeof input.title !== 'string' || input.title.trim() === '') {
problems.push('title is required and must be a non-empty string');
} else if (input.title.length > TITLE_MAX) {
problems.push(`title must be ${TITLE_MAX} characters or fewer`);
}
if (input.done !== undefined && typeof input.done !== 'boolean') {
problems.push('done must be a boolean when present');
}
return problems;
}
ان لائننگ کے بجائے اشارہ کرنا
کہ Where to look روٹ فائل میں سیکشن اس پورے سیٹ اپ میں سب سے سستی چیز ہے۔ چار سطری راستے کی قیمت لوڈ کرنے کے لیے کچھ بھی نہیں ہے، اور اس کے پیچھے ہزاروں فن تعمیر کے نوٹ، ٹیسٹ کے اصول، اور فیصلے کی تاریخ کے ٹوکن ہیں جنہیں ایجنٹ صرف اس وقت کھینچتا ہے جب اس کے کام کی ضرورت ہو۔
آرکیٹیکچرل فیصلے کے ریکارڈ ان انفرنسز کے لیے قدرتی گھر ہیں جو روٹ فائل کو پھول سکتے ہیں۔ ساتھی ریپوزٹری میں ایک ذخیرہ ہوتا ہے جو بتاتا ہے کہ ورکنگ ریپوزٹری ایک باقاعدہ ذخیرہ کیوں ہے۔ Map سب سے مفید پیراگراف، ڈیٹا بیس نہیں، آخری ہے.
An agent working here should not add a database, an ORM, or a persistence layer unless the task
explicitly asks for one, and should treat the missing persistence as a deliberate choice rather than
a gap to fill.
بصورت دیگر، آپ نے جس ایجنٹ کو "API پروڈکشن ریڈی” کے لیے کہا ہے وہ پوسٹگریس کو شامل کرنے میں آپ کی مدد کرے گا۔ اس سے ایجنٹ کو معلوم ہوتا ہے کہ غیر موجودگی جان بوجھ کر ہے اور اسے تبدیل کرنے سے پہلے پوچھتا ہے۔ اس دن تک آپ کی کوئی قیمت نہیں ہے جب تک کہ یہ جملہ آپ کو ایک دوپہر کو بچائے۔
یہی منطق کبھی کبھار ورک فلو پر لاگو ہوتی ہے۔ اینڈ پوائنٹ کو شامل کرنے کے لیے مرحلہ وار عمل واقعی مفید ہے اور یہ تکنیکی فائل میں ہے جو اس وقت لوڈ ہو جاتی ہے جب کوئی واقعی اینڈ پوائنٹ کی درخواست کرتا ہے کیونکہ یہ ہر کام کے لیے لوڈ کرنے کے لیے بہت اہم فائل ہے۔
---
name: add-endpoint
description: Add a new endpoint to the task API following the layering this repository uses
---
# Add an endpoint
This workflow loads only when someone asks for a new endpoint, which is why it lives here instead
of in `AGENTS.md` where every session would pay for it.
Read `docs/architecture.md` first if you have not already, then work through these steps in order.
1. Decide which layer owns the new behaviour. Anything that reads or writes tasks belongs in
`src/services/tasks.js`, and anything about request shape belongs in `src/api/tasks.js`.
2. Add or extend a validator in `src/lib/validate.js` if the endpoint accepts input, returning an
array of problem strings so the handler can report every failure at once.
3. Add the handler to `src/api/tasks.js`, returning `{ data }` on success and
`{ error: { code, message } }` on failure, and using an existing error code where one fits.
4. Register the route in the `routes` array in `src/router.js` with the success status it should
return, and add the error code to `STATUS_BY_ERROR_CODE` if you introduced a new one.
5. Add at least one success case and one failure case to `tests/api.test.js`.
6. Run `npm test` and `npm run lint:context`, then paste both outputs into your summary.
Do not add a dependency, do not introduce a persistence layer, and do not set a status code inside
a handler.
سیاق و سباق کی فائل کو قابل تصدیق بنائیں
اب تک کی ہر چیز کافی معیاری مشورہ ہے، اور اپنے آپ میں ایک مختصر شیلف لائف ہے۔ سیاق و سباق کی فائلیں اسی وجہ سے خراب ہو جاتی ہیں کہ دستاویزات خراب ہو جاتی ہیں۔ دوسرے الفاظ میں، اگر دستاویز غلط ہے تو کچھ بھی نہیں ٹوٹا ہے۔ اپنا نام تبدیل کریں src/services/task.js کو src/services/tasks.jsاور سیاق و سباق کی فائل اعتماد کے ساتھ اس راستے کی طرف اشارہ کرتی رہتی ہے جو اب موجود نہیں ہے۔ آپ حذف کریں typecheck سکرپٹ لکھنے کے چھ ماہ بعد، ایجنٹ نے اسے چلانے کی کوشش میں دو باریاں گزاریں۔ پائپ لائن میں کوئی معائنہ نہ ہونے کی وجہ سے کوئی بھی اس کا نوٹس نہیں لیتا۔
لہذا اپنی پائپ لائن کو چیک کریں اور اسے ناکام ہونے دیں۔ ساتھی ذخیرہ درج ذیل مقام پر ایک لنٹر پر مشتمل ہے: scripts/context-lint.mjs یہ 4 چیک چلاتا ہے اور انحصار سے پاک JavaScript کی تقریباً 150 لائنیں ہیں جنہیں آپ ایک دوپہر میں اپنے ذخیرے میں درخواست دے سکتے ہیں۔
پہلا چیک شروع میں لوڈ ہونے والی تمام فائلوں کے لیے ٹوکن بجٹ ہے۔
// Loaded at the start of every session whether the task needs them or not. When one of these keeps
// pushing against its ceiling, move the detail into docs/ and leave a path behind.
const ALWAYS_LOADED = [
{ path: 'AGENTS.md', budget: 800 },
{ path: 'CLAUDE.md', budget: 300 },
{ path: '.github/copilot-instructions.md', budget: 900 },
{ path: 'src/AGENTS.md', budget: 400 },
];
// Rough average for English prose. Precision is not the point, catching a file that doubled is.
const CHARS_PER_TOKEN = 4;
const estimateTokens = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);
4 حروف فی ٹوکن ٹوکنائزرز کی اصل تعداد کے بجائے ایک تخمینہ ہے، اور یہ کوڈ ہیوی فائلوں میں قدرے پرامید کارکردگی دکھا سکتا ہے۔ یہ ٹھیک ہے کیونکہ آپ جس نمبر کا خیال رکھتے ہیں وہ اوپری حد ہے۔ 400 ٹوکنز سے 800 ٹوکنز تک بڑھتی ہوئی فائل سگنل ہے، اور مطلق نمبروں میں 8% فرق اس بات پر کوئی اثر نہیں ڈالتا کہ ہم کیسے جواب دیتے ہیں۔
دوسری اور تیسری جانچ سیاق و سباق کی فائل کو نثر کے طور پر پڑھتی ہے اور اس بات کی تصدیق کرتی ہے کہ جو کہا گیا ہے وہ حقیقی ہے۔ ایک بیک ٹک کے اندر کوئی بھی چیز جو راستے کی طرح نظر آتی ہے ڈسک پر موجود ہونی چاہیے، اور تمام npm اسکرپٹ ڈسک پر موجود ہونی چاہیے۔ package.json:
// Fenced blocks are stripped first so an example inside a snippet is never read as a real reference.
function inlineCodeSpans(text) {
const prose = text.replace(/```[sS]*?```/g, '');
return [...prose.matchAll(/`([^`n]+)`/g)].map((match) => match[1].trim());
}
for (const span of spans) {
if (looksLikePath(span)) {
if (!existsSync(join(ROOT, span))) {
problems.push(`${file} points at a path that does not exist: ${span}`);
}
continue;
}
const script = span.match(/^npm run ([w:-]+)$/) ?? span.match(/^npm (test|start)$/);
if (script && !scripts.includes(script[1])) {
problems.push(`${file} mentions an npm script that is not in package.json: ${span}`);
}
}
اسکیننگ سے پہلے فینس کوڈ بلاکس کو ہٹانا اس سے زیادہ اہم ہے جتنا کہ ظاہر ہوتا ہے۔ کیونکہ دستاویزات ایسی مثالوں سے بھری ہوئی ہیں جو حقیقی حوالہ جات نہیں ہو سکتیں، اور اس میں ناکام ہونے والے لنٹرز کو ایک ہفتے کے اندر بند کر دیا جائے گا۔
چوتھا چیک سنکرونائزیشن اسکرپٹ کو دوبارہ ڈرائی رن موڈ میں چلاتا ہے اور اگر تیار کردہ فائلیں مزید مماثل نہیں ہوتی ہیں تو ناکام ہوجاتی ہیں۔ AGENTS.mdترمیم کرنے والی ٹیم کے اراکین کو پکڑیں۔ CLAUDE.md بینر کے باوجود براہ راست۔
ایک صحت مند ذخیرے میں، تمام آپریشنز میں ایک سیکنڈ سے بھی کم وقت لگتا ہے۔
دلچسپ نتیجہ یہ ہوتا ہے کہ جب کوئی چیز خراب ہو جاتی ہے۔ ایک لائن شامل کریں جو قابل فہم نظر آئے۔ AGENTS.md حذف شدہ اسکرپٹس اور نام تبدیل شدہ فائلوں کا ذکر کرنے سے یہ پیدا ہوتا ہے:
اسکرپٹ ایک غیر صفر کی حیثیت کے ساتھ باہر نکلتا ہے، لہذا اسے CI سے جوڑنے کے لیے 4 لائنیں لگتی ہیں، یعنی فائل خاموشی سے دور نہیں جا سکتی۔
# .github/workflows/ci.yml
- name: Run the test suite
run: npm test
# The context files are checked on every pull request, which is what stops them from
# drifting away from the code they describe.
- name: Check the context files
run: npm run lint:context
اگر مجھے اس ٹیوٹوریل میں باقی سب کچھ پھینکنا پڑا تو میں یہ حصہ رکھوں گا۔ یہ ایک قابل تصدیق حقیقت ہے کہ ایک سادہ سیاق و سباق کی فائل خوبصورتی سے لکھی گئی سیاق و سباق کی فائل سے بہتر ہے جو پچھلے سال کے فن تعمیر کو بیان کرتی ہے۔ کیونکہ ایجنٹ کے پاس فرق جاننے کا کوئی طریقہ نہیں ہے اور وہ دونوں پر یکساں اعتماد کے ساتھ کام کرتا ہے۔
ایجنٹ کو چیک کرنے کے لیے کچھ دیں۔
اس روٹ فائل میں ایک اور لائن یاد رکھنے کے قابل ہے، جو مکمل کی تعریف ہے۔
ایجنٹ اس وقت روک سکتا ہے جب اس کا کام مکمل ہوتا دکھائی دے اور بغیر تصدیق کے خود ہی چلا جائے۔ آپ صرف "میرے خیال میں یہ ہو گیا” سگنل استعمال کر سکتے ہیں، لہذا یہ خاموش تصدیقی لوپ بن جاتا ہے۔ پھر آپ کی تمام غلطیاں آپ کے نوٹس کا انتظار کریں گی۔
کسی کمانڈ کا نام دینا جو پاس واپس کرتا ہے یا فیل ہو جاتا ہے اس کا ترجمہ ایجنٹ خود کر سکتا ہے، لہذا یہ کوڈ لکھتا ہے، چیک چلاتا ہے، نتائج پڑھتا ہے، اور چیک پاس ہونے تک جاری رہتا ہے۔
اسی لیے Run npm test and npm run lint:context before you report a task as finished ان کا آپ کے آؤٹ پٹ کے معیار پر کسی بھی طرز کے رہنما خطوط سے زیادہ اثر پڑتا ہے جو آپ لکھ سکتے ہیں۔ ایجنٹ سے کامیابی کا دعوی کرنے کے بجائے آؤٹ پٹ کو پیسٹ کرنے کے لیے کہنا بھی ضروری ہے، کیونکہ ثبوت کا جائزہ لینے میں چند سیکنڈ اور خود چیک کو دوبارہ چلانے میں کئی منٹ لگتے ہیں۔
تاہم، سیاق و سباق کی فائل میں دی گئی ہدایات مشورہ ہیں، اور سیاق و سباق کے آباد ہونے پر مشورہ ضائع ہو جاتا ہے۔ اگر آپ کو ہر بار بغیر کسی استثناء کے کچھ ہونے کی ضرورت ہے، تو ایک ہک استعمال کریں جو اسکرپٹ کو ایجنٹ لوپ میں ایک مقررہ مقام پر چلاتا ہے اور اس کے بارے میں کوئی کہنا نہیں ہے۔
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npm run lint:context --silent"
}
]
}
]
}
}
انگوٹھے کا اصول یہ ہے کہ تمام مشورے نثر میں ہیں، اور ضروری چیزیں ہک یا CI میں ہیں۔
دیکھیں کہ کیا یہ واقعی کام کرتا ہے۔
اس میں سے کسی کو بھی ایمان پر نہیں لینا چاہیے، اور آپ کے اپنے ذخیرے پر اس کی جانچ کرنے کے سستے طریقے ہیں۔
ایک ایسا کام چنیں جو یقینی طور پر صحیح لگ رہا ہو، پرامپٹ کو لکھیں تاکہ یہ پوری دوڑ میں ایک جیسا رہے، اور پھر اسے دو بار چلائیں۔ اسے ایک بار موجودہ برانچ میں اور ایک بار اس برانچ میں چلائیں جہاں آپ نے سیاق و سباق کی فائل کو حذف کیا تھا۔ ساتھی ذخیرے سے ایک اچھا امیدوار ہے "اضافہ کریں۔ GET /tasks/count ایک اختتامی نقطہ جو جانچ کے ذریعے کھلے کاموں کی تعداد واپس کرتا ہے۔
پھر ہم چار پوائنٹس کے لیے دو رنز کا موازنہ کرتے ہیں۔ کیا آپ کی مداخلت کے بغیر ٹیسٹ پاس ہوا؟ آپ کو کتنی بار اس میں ترمیم کرنی پڑی؟ کیا آپ کا کوڈ کسی موجودہ پرت کی پیروی کرتا ہے، یا یہ کسی ہینڈلر سے ذخیرہ تک پہنچتا ہے؟ کیا نیا انحصار ظاہر ہوا ہے؟
یہ ایک نمونہ ہے، معیار نہیں، اور اس کے ساتھ ایسا سلوک کیا جانا چاہیے۔ تاہم، یہ آپ کو یہ بتانے کے لیے کافی ہے کہ آیا فائل صحیح طریقے سے کام کر رہی ہے یا نہیں، اور اس سے یہ بھی واضح ہو جاتا ہے کہ مسائل کے پیش آنے پر کون سے مخصوص اصول غائب ہیں۔
اپنی فائلوں کو صحت مند رکھیں
ان فائلوں کو جس طرح سے آپ کوڈ پر کارروائی کرتے ہیں۔ اس کا مطلب ہے کہ فائلوں کا جائزہ لینا جیسے مسائل پیدا ہوتے ہیں بجائے اس کے کہ شیڈول پر عمل کریں۔
دونوں تشخیص آپ کو درپیش زیادہ تر حالات کا احاطہ کر سکتے ہیں۔ اگر ایجنٹ تحریری قواعد کی خلاف ورزی کرتا رہا تو یہ تقریباً طے ہے کہ فائل اتنی لمبی ہو جائے گی کہ رولز شور میں گم ہو جائیں گے۔ زور دینے کے بجائے جارحانہ طریقے سے کٹائی کریں۔
اگر ایجنٹ کوئی ایسا سوال پوچھ رہا ہے جس کا جواب فائل پہلے ہی دے چکا ہے، تو الفاظ مبہم ہیں، اس لیے اس کے آگے دوسری لائن شامل کرنے کے بجائے اس لائن کو دوبارہ لکھیں۔
اس کے علاوہ، ماڈل کے ڈیفالٹس ہر ریلیز کے ساتھ بہتر ہو جاتے ہیں، اور جو اصول پچھلے سال درکار تھے وہ اب اہم نہیں ہو سکتے، اس لیے ایجنٹ پہلے سے مطلع کیے بغیر ان قوانین کو چھوڑ دیتے ہیں جن کی وہ پہلے سے پیروی کرتے ہیں۔
لنٹر آؤٹ پٹ میں ٹوکن بجٹ کو کسی حد تک صحت کے اشارے کے طور پر دیکھیں۔ اس کی وجہ یہ ہے کہ ایک فائل جو اپنی حد تک پہنچتی رہتی ہے آپ کو بتاتی ہے کہ تفصیلات کو منتقل کرنے کی ضرورت ہے۔ docs/.
سے بچنے کے لئے غلطیاں
سب سے عام ناکامی کچن کے سنک کی فائل ہے۔ تمام قواعد جو کسی نے ذکر کیے ہیں اس وقت تک شامل کیے جاتے ہیں جب تک کہ فائل میں 3,000 ٹوکن نہ ہوں اور ایجنٹ ان میں سے تقریباً نصف کی پیروی کرے۔ ترمیم جذبات کے بغیر لاگو خاتمے کے ٹیسٹ ہیں۔
دوسرا README کو اپنی سیاق و سباق کی فائل میں نقل کرنا ہے۔ یہ ہر سیشن کی لاگت کو بغیر کچھ شامل کیے دوگنا کر دیتا ہے۔ اس کی وجہ یہ ہے کہ دونوں دستاویزات کے سامعین مختلف ہیں اور ایجنٹ ضرورت پڑنے پر README پڑھ سکتے ہیں۔
تیسرا دستاویز کرنا ہے جو ماڈل براہ راست دیکھ سکتا ہے۔ Giveaways وہ لائنیں ہیں جو بیان کرتی ہیں کہ فائل میں کیا ہے، نہ کہ ایجنٹ فائل کے ساتھ کیا کرنے کی توقع رکھتا ہے۔
چوتھا غیر تصدیق شدہ قواعد لکھنا ہے، جیسے پڑھنے کے قابل کوڈ یا اچھی کارکردگی کی ضرورت ہوتی ہے۔ یہ معقول لگتا ہے، اور ایجنٹوں کے لیے یہ جاننے کا کوئی طریقہ نہیں ہے کہ آیا وہ تعمیل کر رہے ہیں۔
پانچواں، اور بالآخر، اپنی ٹیم کو محفوظ بنانے کا طریقہ یہ ہے کہ اس بات کو یقینی بنایا جائے کہ ہر ٹول اپنی، براہ راست نظم شدہ کاپی کو برقرار رکھے۔ وہ ایک جیسے شروع ہوئے، لیکن ایک ماہ کے اندر الگ ہوگئے۔ کرسر اور کلاڈ کوڈ پھر ایک ہی ذخیرہ سے متضاد ہدایات کے تحت کام کر رہے ہیں۔ ایک کاپی بنائیں اور CI میں تخلیق کی تصدیق کریں۔
میں کہاں سے شروع کروں؟
اگر میں اسے پڑھنے کے بعد ایک کام کرنا چاہتا ہوں، تو یہ ہوگا کہ میرے پاس پہلے سے موجود سیاق و سباق کی فائل پر ٹوکن تخمینہ چلانا ہے، اور پھر اسے سطر بہ سطر پڑھیں اور پوچھیں کہ کیا ہر سطر کو ہٹانے سے غلطی ہوگی۔ زیادہ تر لوگ پہلے پاس پر ڈھیر کے ایک تہائی اور نصف کے درمیان کاٹتے ہیں اور دیکھتے ہیں کہ ایجنٹ باقی کی زیادہ قابل اعتماد طریقے سے پیروی کرتا ہے۔
پھر دستاویزات کو مہنگا کیے بغیر قابل رسائی بنانے کے لیے پوائنٹر شامل کریں، اور اپنے CI میں ایک لنٹر لگائیں تاکہ یہ یقینی بنایا جا سکے کہ سب کچھ ایماندار رہے کیونکہ کوڈ بیس اس کے نیچے چلتا ہے۔
مکمل سیٹ اپ، بشمول لنٹرز، سنک اسکرپٹس، ہکس، اور CI ورک فلو، github.com/Adeniyikayodee/MCF پر ہے۔ کلون اور چلائیں. npm run lint:context اسے دیکھنے کے لیے آگے بڑھیں اور پھر کچھ توڑ دیں۔ AGENTS.md اور اسے ناکام ہوتے دیکھیں۔
صرف لنٹر کو کاپی کرنے کے بجائے، آپ اسے اپنے اصولوں کے مطابق ڈھال سکتے ہیں۔ کیونکہ چلانے کے قابل ٹیسٹ وہ ہوتے ہیں جو اس بات سے میل کھاتے ہیں کہ ایک مخصوص ذخیرہ کس طرح بڑھتا ہے۔
اگر آپ اپنی کاپی کے ساتھ تجربہ کرنا چاہتے ہیں تو ایک ذخیرہ کو فورک کریں، کیونکہ کانٹا آپ کو ایک برانچ فراہم کرتا ہے جسے آپ بعد میں اپنی تبدیلیوں کو دوبارہ کھینچنے کی صلاحیت کو کھوئے بغیر آزادانہ طور پر ترمیم کرسکتے ہیں۔ اگر آپ ان تبدیلیوں کے لائیو ہونے پر مطلع کرنا چاہتے ہیں، تو فورک کے آگے واچ بٹن استعمال کریں اور ریلیز یا تمام سرگرمیاں منتخب کریں۔ اس کی وجہ یہ ہے کہ جب کانٹا صرف کوڈ کو اسی طرح کیپچر کرتا ہے جیسا کہ اسے درآمد کیا گیا تھا، یہ وہ کنٹرول ہے جو حقیقت میں اطلاع بھیجتا ہے۔