Ponytail: AI coding agent کو کم سے کم code لکھوائیں

Ponytail کیا ہے

Ponytail قواعد کا ایک مجموعہ ہے جو AI coding agent کو کم code لکھنے کی ہدایت دیتا ہے۔ یہ project اپنے آپ کو ایک جملے میں یوں بیان کرتا ہے: "آپ کے AI agent کو کمرے میں موجود سب سے سست senior dev کی طرح سوچنے پر مجبور کرتا ہے۔ بہترین code وہ ہے جو آپ نے کبھی لکھا ہی نہ ہو۔" یہ MIT licensed ہے۔ اس کا اپنا کوئی 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 (you are not going to need it) ہے۔ اگر جواب نہیں ہے تو اسے چھوڑ دیں۔
2. کیا یہ اس codebase میں پہلے سے موجود ہے؟ پہلے سے موجود helper یا pattern دوبارہ استعمال کریں۔
3. کیا standard library یہ کام کر سکتی ہے؟ اسے استعمال کریں۔
4. کیا native platform feature اس ضرورت کو پورا کرتا ہے؟ اسے استعمال کریں۔
5. کیا پہلے سے installed dependency اس مسئلے کو حل کرتی ہے؟ اسے استعمال کریں۔
6. کیا یہ ایک line میں ہو سکتا ہے؟ اسے ایک line میں کریں۔
7. اس کے بعد ہی کم سے کم ایسا code لکھیں جو کام کرے۔

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

یہاں سستی کا مطلب لاپروائی نہیں ہے، اور 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 load نہیں کرتے۔
• hooks/، benchmarks/، examples/ اور scripts/۔

intensity argument یہ طے کرتا ہے کہ rule کتنی سختی سے لاگو ہوگا۔ lite آپ کی مطلوبہ چیز بناتا ہے اور ایک ہی سطر میں کم محنت والا متبادل بھی بتاتا ہے۔ 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 ملتا ہے۔

source پر اعتماد کرنے سے پہلے اسے پڑھنے کے لیے 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 کو ہدایات دینے والی configuration سیشنز کے درمیان آپ کی توقع کے بغیر تبدیل ہو سکتی ہے۔ یہ update command کی سہولت کے بدلے قبول کیا جانے والا trade-off ہے۔

VPS پر سست ایجنٹ کیوں کم خرچ ہوتا ہے

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

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

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

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

نئی dependencies دوسری خاموش لاگت ہیں۔ Rung 5 کہتا ہے کہ جو پہلے سے installed ہے اسے استعمال کریں۔ ایجنٹ کی اپنی 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 کے نتائج سے حاصل کیا گیا ہے۔ model نے rule کے ساتھ اور اس کے بغیر prompts کے ایک مختصر مجموعے کے جوابات دیے۔ یہ نتائج 13 اور 17 June 2026 کو دہرائے گئے runs کے median کے طور پر لیے گئے ہیں۔ agentic کالم headless Claude Code session سے حاصل کیا گیا ہے۔ اس 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 بنانے کا حقیقی خطرہ ہو، جبکہ پہلے سے minimal code میں یہ بچت تقریباً صفر ہوتی ہے۔ ایک Python اور TypeScript repository میں کیے گئے بارہ tickets آپ کی repository کے نتائج کی پیش گوئی نہیں کرتے۔ اگر یہ عدد آپ کے لیے اہم ہے تو اپنے tickets پر، rule کے ساتھ اور اس کے بغیر، موازنہ چلائیں اور لائنیں خود شمار کریں۔

وہ pattern جسے آپ آج ہی کچھ install کیے بغیر اپنا سکتے ہیں

یہ ladder صرف text پر مشتمل ہے، اس لیے اس idea کو استعمال کرنے کے لیے plugin کی ضرورت نہیں۔ اس طرح کا block اس instruction file میں paste کریں جسے آپ کا agent پہلے ہی read کرتا ہے، خواہ وہ 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 کا نام tag کیا جاتا ہے:

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

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

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

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

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

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

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

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

FAQ

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

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

کیا lazy 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 numbers قابل اعتماد ہیں؟

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

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

نہیں۔ یہ ladder صرف text پر مشتمل ہے، اور اسی کے مساوی 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 آپ کے پڑھنے کے کام کو کم کرتا ہے۔ یہ فیصلہ نہیں کرتا کہ کیا merge ہوگا، اور اسے ایسا کرنا بھی نہیں چاہیے۔