Ponytail: AI coding agent کو کم کوڈ لکھوائیں

Ponytail کیا ہے

Ponytail قواعد کا ایک مجموعہ ہے جو AI coding agent کو کم کوڈ لکھنے پر مجبور کرتا ہے۔ یہ project اپنی وضاحت ایک جملے میں یوں کرتا ہے: "آپ کے AI agent کو کمرے میں موجود سب سے سست senior dev کی طرح سوچنے پر مجبور کرتا ہے۔ بہترین code وہ ہے جو آپ نے کبھی لکھا ہی نہ ہو۔" یہ MIT license کے تحت ہے۔ اس کا اپنا کوئی runtime نہیں، اور اس میں کوئی چیز execute نہیں ہوتی۔ یہ وہ text ہے جو agent کی instructions میں شامل کیا جاتا ہے۔ اسے ان hosts کے لیے skill کے طور پر package کیا گیا ہے جو skills load کرتے ہیں، اور ان hosts کے لیے plain rule files کے طور پر جو skills load نہیں کرتے۔

repository DietrichGebert/ponytail ہے۔ اسے 12 June 2026 کو بنایا گیا تھا، اور 1 August 2026 تک اسے 90,000 stars مل چکے تھے۔ 1 August 2026 کو latest tagged release v4.8.4 ہے، جو 29 June 2026 کو publish ہوا تھا۔ releases page پر صرف 14 سے 29 June کے درمیان دس tags درج ہیں۔ اس رفتار سے تبدیل ہونے والے project میں آپ کے یہ متن پڑھنے تک تبدیلی آ چکی ہو گی، اس لیے اس پر کچھ بھی build کرنے سے پہلے ایک tag pin کریں۔

آلے سے پہلے خیال: پہلی قابلِ عمل سیڑھی پر رک جائیں

Ponytail کی بنیاد ایک فیصلہ جاتی سیڑھی ہے۔ ایجنٹ کچھ بھی لکھنے سے پہلے اس پر چڑھتا ہے اور پہلی قابلِ عمل سیڑھی پر رک جاتا ہے۔

1. کیا یہ چیز سرے سے موجود ہونی بھی چاہیے؟ یہ YAGNI (آپ کو اس کی ضرورت نہیں پڑنے والی) ہے۔ اگر جواب نہیں ہے تو اسے چھوڑ دیں۔
2. کیا یہ پہلے ہی اس codebase میں موجود ہے؟ پہلے سے موجود helper یا pattern دوبارہ استعمال کریں۔
3. کیا standard library یہ کام کرتی ہے؟ اسے استعمال کریں۔
4. کیا native platform feature اس ضرورت کو پورا کرتا ہے؟ اسے استعمال کریں۔
5. کیا پہلے سے نصب dependency یہ مسئلہ حل کرتی ہے؟ اسے استعمال کریں۔
6. کیا یہ ایک سطر میں ہو سکتا ہے؟ اسے ایک سطر میں لکھیں۔
7. صرف اس کے بعد، کم سے کم ایسا code لکھیں جو کام کرے۔

کام کسی ایک سیڑھی سے نہیں بلکہ ترتیب سے ہوتا ہے۔ اگر ایجنٹ سے date picker مانگا جائے تو وہ date picker ہی لکھے گا، کیونکہ اسے یہی کرنے کو کہا گیا ہے۔ یہ سیڑھی اسے پہلے سیڑھی 4 چیک کرنے پر مجبور کرتی ہے، اور سیڑھی 4 بتاتی ہے کہ browser میں پہلے ہی <input type="date"> موجود ہے۔ پروجیکٹ کے اپنے benchmark notes میں عین یہی مثال دی گئی ہے: اس اصول کے بغیر تیار ہونے والا date picker 404 سطروں کا تھا، جبکہ اس اصول کے ساتھ 23 سطروں کا رہا، کیونکہ ایجنٹ نے component بنانے کے بجائے native input استعمال کیا۔ اسی وجہ سے colour picker بھی 287 سطروں سے کم ہو کر 23 سطروں کا رہ گیا۔

یہاں lazy ہونے کا مطلب لاپرواہ ہونا نہیں ہے، اور ruleset میں یہ بات براہِ راست بیان کی گئی ہے۔ اس کی "never lazy about" فہرست میں فیصلہ کرنے سے پہلے مسئلے کو سمجھنا، trust boundaries پر input validation، data loss روکنے والی error handling، security، accessibility، اور وہ ہر چیز شامل ہے جس کے لیے آپ نے نام لے کر کہا ہو۔ یہ ہر non-trivial logic کے حصے کے لیے ایک چھوٹا runnable check بھی طلب کرتی ہے۔ یہ اصول نئی چیزیں ایجاد کرنے کو کم کرتا ہے۔ یہ correctness کو کم نہیں کرتا۔

ریپوزٹری دراصل کیا فراہم کرتی ہے

• AGENTS.md، مستقل طور پر فعال ruleset، جو پورا تصور ایک ایسی فائل میں پیش کرتا ہے جسے آپ پانچ منٹ میں پڑھ سکتے ہیں۔
• skills/ponytail/SKILL.md، skill definition، جس میں argument hint lite، full یا ultra ہے۔
• editor-specific directories کے اندر موجود rule files، جیسے .cursor/rules/ اور .windsurf/rules/، ان hosts کے لیے جو rules پڑھتے ہیں لیکن skills لوڈ نہیں کرتے۔
• hooks/، benchmarks/، examples/ اور scripts/۔

intensity argument یہ طے کرتا ہے کہ rule کتنی سختی سے نافذ ہو۔ lite آپ کی مطلوبہ چیز تیار کرتا ہے اور ایک سست تر option کا نام ایک ہی سطر میں دیتا ہے۔ full default ہے اور ladder نافذ کرتا ہے۔ ultra YAGNI کا انتہائی سخت setting ہے: یہ addition کے بجائے deletion کو ترجیح دیتا ہے اور خود requirement سے بھی اختلاف کرے گا۔

Skill-capable hosts کو slash commands بھی ملتے ہیں۔ /ponytail level مقرر کرتا ہے، /ponytail-review over-engineering کے لیے diff چیک کرتا ہے، /ponytail-audit پوری repository چیک کرتا ہے، /ponytail-debt ان shortcuts کو جمع کرتا ہے جنہیں آپ نے مؤخر کیا، اور /ponytail-gain benchmark scorecard دکھاتا ہے۔ جو hosts صرف rule files پڑھتے ہیں، انہیں commands کے بغیر ruleset ملتا ہے۔

ماخذ پر اعتماد کرنے سے پہلے اسے پڑھنے کے لیے branch کے بجائے tag کو clone کریں:

git clone --depth 1 --branch v4.8.4 https://github.com/DietrichGebert/ponytail.git

Claude Code پر project اس کے بجائے plugin install کی دستاویز فراہم کرتا ہے، اور یہ دو سطریں 1 August 2026 کو درج دستاویز کے مطابق ہیں:

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

plugin path tag کے بجائے default branch کی پیروی کرتا ہے، اس لیے آپ کے agent کو ہدایات دینے والا مواد sessions کے درمیان آپ کی توقع کے بغیر تبدیل ہو سکتا ہے۔ update command کی سہولت کے بدلے آپ یہی trade قبول کرتے ہیں۔

VPS پر کم کام کرنے والا agent کیوں سستا ہوتا ہے

Agent کی لکھی ہوئی diff گفتگو سے باہر نہیں جاتی۔ اگلی باری میں model اسے دوبارہ پڑھتا ہے، ساتھ ہی وہ تمام files بھی پڑھتا ہے جنہیں اس نے diff بنانے کے لیے کھولا تھا۔ اس لیے 500 لائنوں کی تبدیلی صرف اسے بنانے والی باری پر نہیں، بلکہ session کی ہر بعد والی باری پر بھی اضافی بوجھ ڈالتی ہے۔ اسی وجہ سے مسلسل پھیلتی ہوئی refactor سے session آگے بڑھنے کے ساتھ agent زیادہ سست اور کم مؤثر محسوس ہوتا ہے: window agent کے اپنے output سے بھر جاتی ہے، اس لیے آپ کے اصل code کے لیے کم جگہ بچتی ہے۔ اس کو قابو میں رکھنا ہی coding agent کی context window کو منظم کرنا کا مکمل موضوع ہے۔

Tokens اندر آنے اور باہر جانے، دونوں پر شمار کیے جاتے ہیں۔ اس لیے نصف سائز کی diff دو مرتبہ سستی ہوتی ہے: ایک بار لکھے جاتے وقت، اور پھر ہر اس باری میں جب اسے دوبارہ پڑھا جاتا ہے۔ اگر آپ self-hosted setup کا bill دیکھ رہے ہیں تو instruction file ایسا lever ہے جسے استعمال کرنے کی کوئی لاگت نہیں۔ AI agent کی لاگت کو قابو میں رکھنا output volume سے شروع ہوتا ہے، جبکہ coding agent اپنے tokens کیسے خرچ کرتا ہے یہ واضح کرتا ہے کہ دوبارہ پڑھنے کی اہمیت توقع سے زیادہ کیوں ہے۔

انسان پھر بھی diff پڑھتا ہے۔ 400 لائنوں کی ایسی تبدیلی جو 20 لائنوں کی ہونی چاہیے تھی، reviewer کی توجہ خرچ کرتی ہے، اور توجہ وہ resource ہے جو سب سے پہلے ختم ہوتی ہے۔ کوئی بھی شخص دن کی چوتھی طویل diff کا اسی احتیاط سے review نہیں کرتا جس سے پہلی diff کا کیا تھا۔ اس لیے ضرورت سے زیادہ code بنانا صرف وقت ضائع نہیں کرتا۔ یہ خاموشی سے اس review کے معیار کو کم کر دیتا ہے جس کا مقصد غلطیوں کو پکڑنا ہوتا ہے۔

Server پر خطرہ بدل جاتا ہے، کیونکہ agent اکثر اس وقت چل رہا ہوتا ہے جب کوئی اسے دیکھ نہیں رہا ہوتا۔ tmux session یا timer پر کام کرنے والے agent کے پاس آپ کے دیکھنے سے پہلے کسی غلط فیصلے کو آگے بڑھانے کے لیے کئی گھنٹے ہوتے ہیں۔ یہی VPS پر coding agent چلانے کا عملی خطرہ ہے، اور اسی لیے loop engineering کرنے والے لوگ انفرادی prompts کے بجائے مستقل ہدایات پر اتنی توجہ دیتے ہیں۔ ہمیشہ فعال file میں موجود rule باری 200 پر بھی لاگو ہوتا ہے۔ chat میں لکھی ہوئی rule صرف باری 3 پر لاگو ہوتی ہے۔

نئی dependencies ایک اور خاموش لاگت ہیں۔ Rung 5 کہتا ہے کہ جو چیز installed ہے، اسے استعمال کریں۔ Agent کی اپنی initiative پر شامل کیا گیا ہر package ایسی چیز ہے جسے آپ بعد میں patch کریں گے، اور جو اس repository سے بننے والی ہر container image میں شامل ہو جائے گا۔

Ponytail کے اپنے benchmark اعداد و شمار کیا بتاتے ہیں

پروجیکٹ نتائج کے دو مجموعے شائع کرتا ہے، اور دونوں میں خاصا بڑا فرق ہے۔ دونوں اعداد و شمار خود پروجیکٹ کے شائع کردہ ہیں۔ ان میں سے کوئی بھی آزادانہ ٹیسٹ نہیں ہے۔

[
  {
    "label": "Lines of code",
    "single_shot_pct": 93,
    "agentic_pct": 54
  },
  {
    "label": "Cost per run",
    "single_shot_pct": 63,
    "agentic_pct": 20
  },
  {
    "label": "Wall clock time",
    "single_shot_pct": 74,
    "agentic_pct": 27
  }
]

single shot کالم ایک bare model سے حاصل کیا گیا ہے، جس نے ایک مختصر prompt set کا جواب rule کے ساتھ اور اس کے بغیر دیا۔ یہ نتائج 13 اور 17 June 2026 کو کی گئی repeated runs کے median ہیں۔ agentic کالم ایک headless Claude Code session سے حاصل کیا گیا ہے، جس نے tiangolo کے full-stack-fastapi-template، یعنی ایک حقیقی FastAPI اور React repository، میں بارہ feature tickets پر ترمیم کی۔ ہر ticket کے لیے Haiku 4.5 پر چار runs کیے گئے اور پیچھے رہ جانے والے git diff کی بنیاد پر اسکور دیا گیا۔

دوسرا کالم دیکھیں۔ agentic نتیجے میں code کی لائنیں 54 فیصد کم، لاگت 20 فیصد کم، اور wall clock time 27 فیصد کم ہے۔ single shot setup میں انہی پیمانوں کے لیے یہ اعداد بالترتیب 93 فیصد اور 74 فیصد ہیں۔ README اس کی وجہ واضح طور پر بتاتا ہے: single shot baseline ایک bare model ہے جو "کئی options کے ساتھ commentary بھی دیتا ہے"، اور اسے شکست دینا آسان ہے۔ جب موازنہ ایک حقیقی agent کے ساتھ کیا جاتا ہے جو حقیقی کام کر رہا ہو، تو فائدہ کم ہو جاتا ہے۔ یہ نتیجہ پھر بھی برقرار رہتا ہے، اور یہی زیادہ مفید حقیقت ہے۔

ایک caveat خود پروجیکٹ نے بیان کیا ہے، اور یہی طے کرتا ہے کہ یہ آپ کے لیے مفید ہوگا یا نہیں۔ بچت وہاں سب سے زیادہ ہوتی ہے جہاں غیر ضروری طور پر زیادہ code بنانے کا حقیقی خطرہ ہو، اور اس code میں تقریباً صفر ہوتی ہے جو پہلے ہی minimal ہو۔ ایک Python اور TypeScript repository کے بارہ tickets آپ کی repository کے نتائج کی پیش گوئی نہیں کرتے۔ اگر یہ عدد آپ کے لیے اہم ہے تو اپنے tickets پر، rule کے ساتھ اور اس کے بغیر، یہ موازنہ خود چلائیں اور لائنیں خود گنیں۔

وہ نمونہ جسے آپ آج کچھ انسٹال کیے بغیر نقل کر سکتے ہیں

یہ ترتیب متن پر مشتمل ہے، اس لیے اس خیال کو استعمال کرنے کے لیے آپ کو plugin کی ضرورت نہیں۔ اس طرح کا ایک block اس instruction file میں شامل کریں جسے آپ کا agent پہلے ہی پڑھتا ہے، خواہ وہ AGENTS.md، CLAUDE.md یا آپ کے editor کی rules file ہو۔

## Before you write code

Climb this list in order. Stop at the first line that applies.

1. Does this need to exist? If not, say so and stop.
2. Does this repo already have it? Reuse the helper.
3. Does the standard library do it? Use it.
4. Does the platform do it natively? Use it.
5. Does an installed dependency do it? Use it.
6. Can it be one line? Write one line.
7. Otherwise write the minimum that works.

Never take the shortcut on: reading the code before changing it, validating
input that crosses a trust boundary, error handling that would otherwise lose
data, security, accessibility, or anything I asked for by name.

Do not add an abstraction I did not ask for. Do not add a dependency without
saying why in one line. Prefer deleting code to adding it.

Mark a deliberate simplification with a comment naming its ceiling and the
upgrade path.

یہ آخری rule الگ سے قابلِ توجہ ہے۔ Ponytail کا convention ایک ایسا comment ہے جس پر tool کا نام درج ہوتا ہے:

# ponytail: global lock, per-account locks if throughput matters

یہ comment کام کی دو سطروں پر مشتمل ہے اور اس سوال کو واضح کر دیتا ہے جس کے لیے بصورتِ دیگر review cycle درکار ہوتی۔ یہ اگلے قاری کو بتاتا ہے کہ سادہ version ایک سوچا سمجھا فیصلہ تھا، اور یہ بھی واضح کرتا ہے کہ وہ فیصلہ کن حالت میں قابلِ اطلاق نہیں رہتا۔ اس کے بغیر reviewer یہ نہیں جان سکتا کہ یہ سوچا سمجھا shortcut ہے یا agent اسے بھول گیا، اس لیے اسے سوال کرنا پڑتا ہے۔

آپ block کہاں رکھتے ہیں، یہ اتنا ہی اہم ہے جتنا اس میں لکھی ہوئی بات۔ وہ file جسے agent ہر run پر load کرتا ہے، ہر run کی سمت متعین کرتی ہے، ان run کی بھی جن کی آپ نگرانی نہیں کر رہے ہوتے۔ اس فرق کی وضاحت ایسی AGENTS.md لکھنا جس پر آپ کا agent واقعی عمل کرے میں کی گئی ہے، اور اسی وجہ سے یہ pattern آپ کی shell history کے بجائے committed file میں ہونا چاہیے۔

جہاں اصول درست نہیں رہتا

یہ درجہ بندی ایسے codebase میں feature work کے لیے بنائی گئی ہے جو پہلے سے موجود ہو، جہاں دوبارہ استعمال عموماً ممکن اور درست ہوتا ہے۔ یہ greenfield project کے لیے موزوں نہیں، کیونکہ rung 2 پر دوبارہ استعمال کرنے کے لیے کچھ نہیں ہوتا اور rung 5 پر کچھ installed نہیں ہوتا، اس لیے agent ہر بار rung 7 تک پہنچ جاتا ہے۔ یہ اس وقت بھی موزوں نہیں رہتی جب آپ واقعی abstraction چاہتے ہوں۔ اگر آپ اسی copied block کے چوتھے caller کو شامل کرنے والے ہیں، تو "shortest diff" آپ کو پانچویں copy فراہم کرتا ہے۔

ultra level آپ کے requirements کو چیلنج کرے گا۔ یہی اس level کا مقصد ہے، اور جب آپ فیصلہ کر چکے ہوں اور صرف کام مکمل کرانا چاہتے ہوں، تو یہ ایک حقیقی cost ہے۔ معمول کے کام کے لیے full استعمال کریں، اور جب آپ کو شبہ ہو کہ feature request ہی مسئلہ ہے تو ultra اختیار کریں۔

کوئی instruction block آپ کو مسئلے کی غلط تشریح سے محفوظ نہیں رکھتا۔ ruleset کا پہلا item بھی فیصلہ کرنے سے پہلے code کو سمجھنے پر مبنی ہے۔ یہی مہنگا حصہ ہے، اور یہی وہ حصہ ہے جو متن آپ کے لیے انجام نہیں دے سکتا۔ غلط function میں minimal diff پھر بھی غلط fix ہوتا ہے، اور اب یہ ایک چھوٹا غلط fix ہے جسے approve کرنا آسان ہے۔

دیانت دارانہ خلاصہ یہ ہے کہ Ponytail ایک احتیاط سے لکھا گیا prompt ہے جسے اچھی طرح distributed کیا گیا ہے اور جس کے ساتھ numbers منسلک ہیں۔ اس میں plugin کی کوئی لازمی ضرورت نہیں۔ project آپ کو یہ فراہم کرتا ہے کہ کسی نے list درست طور پر لکھی، اسے ایک حقیقی repository کے خلاف test کیا، اور method کو result کے ساتھ شائع کیا۔

FAQ

کیا Ponytail، Claude Code کے علاوہ دیگر agents کے ساتھ بھی کام کرتا ہے؟

جی ہاں۔ یہ ایسے hosts کے لیے skill کے طور پر جاری کیا جاتا ہے جو skills لوڈ کرتے ہیں۔ اس فہرست میں Claude Code، Codex، OpenCode، Gemini اور README میں درج کئی دیگر hosts شامل ہیں۔ ایسے editors جو rule files پڑھتے ہیں لیکن skills لوڈ نہیں کرتے، مثلاً Cursor، Windsurf، Cline اور Copilot، متعلقہ rules directory سے always-on ruleset لیتے ہیں اور انہیں slash commands نہیں ملتیں۔ دونوں صورتوں میں متن یکساں رہتا ہے۔ اصل فرق یہ ہے کہ آپ کا host ہر turn پر اس متن کو context میں رکھتا ہے یا صرف skill trigger ہونے پر۔

کیا کوئی سست agent tests، validation یا security کو چھوڑ دے گا؟

نہیں، اور ruleset میں یہ بات براہِ راست لکھی ہے۔ اس کی "never lazy about" فہرست میں trust boundaries پر input validation، data loss روکنے والی error handling، security اور accessibility شامل ہیں۔ یہ ہر non-trivial logic کے حصے کے لیے ایک چھوٹا runnable check بھی طلب کرتی ہے۔ یہ rule جس چیز کو ختم کرتا ہے وہ من گھڑت structure ہے: ایسی abstractions جن کی کسی نے درخواست نہیں کی، اور ایسی dependencies جن کی کسی کو ضرورت نہیں تھی۔ اگر اسے install کرنے کے بعد آپ کا agent tests چھوڑنے لگے تو اس کی وجہ آپ کے اپنے config میں موجود کوئی دوسری instruction ہے جو اس rule پر فوقیت رکھتی ہے۔ اس لیے وہ file پڑھیں جسے agent سب سے آخر میں load کرتا ہے۔

کیا شائع کردہ speed اور cost کے اعداد و شمار قابلِ اعتماد ہیں؟

یہ project کی اپنی پیمائشیں ہیں، جو اس کے طریقۂ کار کے ساتھ شائع کی گئی ہیں۔ انہیں اسی تناظر میں پڑھنا چاہیے۔ single shot کے اعداد و شمار کا موازنہ ایسے bare model سے کیا گیا ہے جو options اور commentary کے ساتھ جواب دیتا ہے۔ README خود اسے کمزور baseline قرار دیتا ہے۔ agentic اعداد و شمار ایک repository پر headless Claude Code session سے حاصل کیے گئے ہیں۔ یہ repository FastAPI اور React استعمال کرتی ہے، اس میں twelve tickets تھے، اور Haiku 4.5 پر ہر ticket کے لیے four runs کیے گئے۔ یہ اعداد و شمار اس setup کے لیے درست ہیں۔ یہ آپ کے codebase کی پیش گوئی نہیں کرتے، کیونکہ project یہ بھی کہتا ہے کہ جو code پہلے ہی minimal ہو، اس میں saving تقریباً zero تک پہنچ جاتی ہے۔

کیا فائدہ حاصل کرنے کے لیے مجھے کچھ install کرنا ہوگا؟

نہیں۔ یہ ladder متن پر مشتمل ہے۔ اسی کے مساوی block کو اس instruction file میں paste کرنے سے، جسے آپ کا agent پہلے ہی پڑھتا ہے، زیادہ تر اثر حاصل ہو جاتا ہے۔ plugin آپ کو maintained wording، intensity levels، review commands اور update path فراہم کرتا ہے۔ پہلے copied block آزمانا اس سوال کا rung 1 جواب ہے کہ install کا موجود ہونا ضروری بھی ہے یا نہیں۔

میں unattended agent کو رات بھر ضرورت سے زیادہ code بنانے سے کیسے روکوں؟

rule کو chat message کے بجائے always-on instruction file میں رکھیں، تاکہ یہ طویل run کے turn 200 پر بھی لاگو ہو، صرف turn 3 پر نہیں۔ پھر نقصان کو الگ سے محدود کریں: agent کو ایسا checkout دیں جسے خراب کرنے کی اجازت ہو، اپنی واحد copy نہیں، اور merge سے پہلے human diff review لازم کریں۔ minimal diff rule اس code کی مقدار کم کرتا ہے جسے آپ کو پڑھنا ہوگا۔ یہ فیصلہ نہیں کرتا کہ کیا merge ہوگا، اور اسے ایسا کرنا بھی نہیں چاہیے۔