آموزش استفاده از Ponytail برای بهینه‌سازی ایجنت

Ponytail چیست

Ponytail مجموعه‌ای از قوانین است که باعث می‌شود ایجنت برنامه‌نویسی هوش مصنوعی، کد کمتری بنویسد. این پروژه خود را در یک جمله این‌گونه توصیف می‌کند: «باعث می‌شود ایجنت هوش مصنوعی شما مانند تنبل‌ترین برنامه‌نویس ارشد در اتاق فکر کند. بهترین کد، کدی است که هرگز ننوشته‌اید.» این پروژه تحت مجوز MIT منتشر شده است. Ponytail هیچ runtime اختصاصی ندارد و هیچ بخشی از آن به صورت مستقل اجرا نمی‌شود. این پروژه در واقع متنی است که در دستورالعمل‌های ایجنت قرار می‌گیرد و به عنوان یک skill برای میزبان‌هایی که از skillها پشتیبانی می‌کنند، یا به عنوان فایل‌های قانون ساده برای میزبان‌هایی که چنین قابلیتی ندارند، بسته‌بندی شده است.

مخزن این پروژه DietrichGebert/ponytail است. این پروژه در تاریخ 12 June 2026 ایجاد شد و تا 1 August 2026 از 90,000 ستاره عبور کرد. آخرین نسخه تگ‌شده در تاریخ 1 August 2026، نسخه v4.8.4 است که در 29 June 2026 منتشر شده و صفحه releases تنها بین 14 تا 29 June، ده تگ مختلف را فهرست کرده است. پروژه‌ای که با این سرعت در حال پیشرفت است، تا زمانی که شما این متن را می‌خوانید تغییر خواهد کرد؛ بنابراین پیش از آنکه هر چیزی بر پایه آن بسازید، حتماً یک تگ خاص را ثابت (pin) کنید.

ایده پیش از ابزار: توقف در نخستین پلهٔ مستحکم

هستهٔ اصلی Ponytail یک نردبان تصمیم‌گیری است. عامل (agent) پیش از نوشتن هر چیزی از این نردبان بالا می‌رود و در نخستین پله‌ای که مستحکم باشد، متوقف می‌شود.

1. آیا این مورد اصلاً نیاز به وجود دارد؟ این همان اصل YAGNI (شما به آن نیاز نخواهید داشت) است. اگر پاسخ منفی است، از آن صرف‌نظر کنید.
2. آیا این مورد قبلاً در این codebase وجود دارد؟ از helper یا الگویی که از قبل موجود است، دوباره استفاده کنید.
3. آیا کتابخانهٔ استاندارد آن را انجام می‌دهد؟ از آن استفاده کنید.
4. آیا یک قابلیت بومی پلتفرم آن را پوشش می‌دهد؟ از آن استفاده کنید.
5. آیا یک dependency که از قبل نصب شده است، مشکل را حل می‌کند؟ از آن استفاده کنید.
6. آیا می‌تواند یک خطی باشد؟ آن را یک خطی کنید.
7. تنها در این صورت، حداقل کدی را بنویسید که کار می‌کند.

این ترتیب است که کار را پیش می‌برد، نه هیچ‌کدام از پله‌ها به تنهایی. عاملی که از او خواسته شود یک date picker بنویسد، آن را می‌نویسد، زیرا به او گفته شده که باید یکی بسازد. نردبان باعث می‌شود او ابتدا پلهٔ 4 را بررسی کند و پلهٔ 4 می‌گوید که مرورگر از قبل <input type="date"> را دارد. بنچمارک خودِ پروژه دقیقاً همین مورد را ثبت کرده است: یک date picker که بدون این قانون 404 خط کد داشت، با وجود آن به 23 خط رسید، زیرا عامل به جای ساختن یک کامپوننت، از input بومی استفاده کرد. یک colour picker نیز به همین دلیل از 287 خط به 23 خط کاهش یافت. پلهٔ 2 همان پله‌ای است که بی‌سروصدا شکست می‌خورد، زیرا عاملی که نمی‌تواند helper موجود شما را ببیند، با خوشحالی دومی را می‌نویسد؛ شکافی که یک نقشهٔ قابل پرس‌وجو از codebase شما برای پر کردن آن طراحی شده است.

تنبلی در اینجا به معنای بی‌دقتی نیست و مجموعه قوانین مستقیماً به این موضوع اشاره دارد. لیست "هرگز در این موارد تنبل نباش" شامل درک مسئله پیش از تصمیم‌گیری، اعتبارسنجی ورودی در مرزهای اعتماد، مدیریت خطایی که از از دست رفتن داده‌ها جلوگیری می‌کند، امنیت، دسترس‌پذیری و هر چیزی است که شما با نام از آن درخواست کرده‌اید. همچنین برای هر بخش از منطق غیربدیهی، یک بررسی کوچک و قابل اجرا درخواست می‌کند. این قانون ابداع و اختراع غیرضروری را حذف می‌کند، نه صحت عملکرد را.

محتویات واقعی مخزن

• AGENTS.md، مجموعه قوانین همیشه فعال، که کل ایده را در یک فایل خلاصه می‌کند و می‌توانید آن را در 5 دقیقه مطالعه کنید.
• skills/ponytail/SKILL.md، تعریف مهارت، با راهنمای آرگومان lite، full یا ultra.
• فایل‌های قانون در دایرکتوری‌های مخصوص ویرایشگر مانند .cursor/rules/ و .windsurf/rules/، برای میزبان‌هایی که قوانین را می‌خوانند اما مهارت‌ها را بارگذاری نمی‌کنند.
• hooks/، benchmarks/، examples/ و scripts/.

آرگومان intensity تعیین می‌کند که قانون تا چه حد سخت‌گیرانه عمل کند. lite آنچه را که درخواست کرده‌اید می‌سازد و یک گزینه تنبل‌تر را در یک خط معرفی می‌کند. full حالت پیش‌فرض است و سلسله‌مراتب را اعمال می‌کند. ultra تنظیمات افراطی YAGNI است: این حالت حذف را به افزودن ترجیح می‌دهد و حتی با خودِ نیازمندی نیز مخالفت می‌کند.

میزبان‌های دارای قابلیت مهارت، دستورات اسلش (slash commands) را نیز دریافت می‌کنند. /ponytail سطح را تنظیم می‌کند، /ponytail-review یک diff را برای بررسی مهندسی بیش‌ازحد (over-engineering) بازبینی می‌کند، /ponytail-audit کل یک مخزن را بررسی می‌کند، /ponytail-debt میان‌برهایی را که به تعویق انداخته‌اید جمع‌آوری می‌کند و /ponytail-gain کارت امتیاز بنچمارک را چاپ می‌کند. میزبان‌هایی که فقط فایل‌های قانون را می‌خوانند، مجموعه قوانین را بدون هیچ دستوری دریافت می‌کنند.

برای مطالعه سورس‌کد پیش از اعتماد به آن، به جای branch، تگ (tag) را clone کنید:

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

در Claude Code، پروژه به جای آن، نصب یک پلاگین را مستند کرده است و این دو خط همان‌طور که در تاریخ 1 August 2026 مستند شده‌اند، عبارتند از:

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

مسیر پلاگین از branch پیش‌فرض پیروی می‌کند و نه یک تگ؛ بنابراین دستورالعمل‌هایی که عامل (agent) شما را هدایت می‌کنند، ممکن است بین جلسات مختلف تغییر کنند. این بهایی است که برای راحتیِ داشتن یک دستور به‌روزرسانی می‌پردازید.

چرا یک agent کم‌کار روی VPS ارزان‌تر است

تغییری (diff) که یک agent می‌نویسد، از گفتگو خارج نمی‌شود. در نوبت بعدی، این تغییر بخشی از context است که مدل دوباره آن را می‌خواند، به همراه تمام فایل‌هایی که برای تولید آن باز کرده بود. بنابراین، یک تغییر 500 خطی، هر نوبت بعدی در نشست را تحت فشار قرار می‌دهد، نه فقط نوبتی که آن را تولید کرده است. به همین دلیل است که یک refactor بی‌رویه باعث می‌شود agent با پیشرفت نشست، کندتر و کم‌هوش‌تر به نظر برسد: پنجره با خروجی‌های خودِ agent پر می‌شود و فضای باقی‌مانده برای کد اصلی شما کاهش می‌یابد. کنترل این موضوع، تمامِ مبحث مدیریت پنجره context یک agent برنامه‌نویسی است.

توکن‌ها هم هنگام ورود و هم هنگام خروج محاسبه می‌شوند، بنابراین یک diff که نصف اندازه باشد، دو بار ارزان‌تر تمام می‌شود: یک بار وقتی نوشته می‌شود و بار دیگر در هر نوبتی که دوباره خوانده می‌شود. اینکه آیا این صرفه‌جویی در صورت‌حساب شما لحاظ می‌شود یا خیر، به نحوه پرداخت شما بستگی دارد، زیرا اشتراک‌های ثابت Pro یا Max توکن‌های اضافی را پوشش می‌دهند، در حالی که در مدل پرداخت per-token API، هزینه تک‌تک آن‌ها از شما دریافت می‌شود. اگر در یک setup خودمیزبان (self-hosted) مراقب هزینه‌ها هستید، فایل دستورالعمل (instruction file) اهرمی است که استفاده از آن هزینه‌ای ندارد. کنترل هزینه‌های یک agent هوش مصنوعی با حجم خروجی شروع می‌شود و نحوه مصرف توکن‌ها توسط یک agent برنامه‌نویسی توضیح می‌دهد که چرا بازخوانی آن‌ها بیش از حد انتظار اهمیت دارد.

انسان همچنان diff را می‌خواند. یک تغییر 400 خطی که باید 20 خط می‌بود، توجه بازبین (reviewer) را هدر می‌دهد و توجه، منبعی است که زودتر از همه تمام می‌شود. هیچ‌کس چهارمین diff طولانی روز را با دقتی که صرف اولی کرده بود، بررسی نمی‌کند؛ بنابراین زیاده‌روی در کدنویسی فقط اتلاف وقت نیست، بلکه به‌طور نامحسوس کیفیت بررسی را که قرار است خطاها را شناسایی کند، کاهش می‌دهد.

روی سرور، شرایط متفاوت است، زیرا agent اغلب بدون نظارت کسی کار می‌کند. agentای که در یک نشست tmux یا بر اساس زمان‌بندی کار می‌کند، ساعت‌ها فرصت دارد تا پیش از آنکه شما متوجه شوید، بر اساس یک تصمیم اشتباه پیش برود. این ریسک عملی در اجرای یک agent برنامه‌نویسی روی VPS است و به همین دلیل است که افرادی که مهندسی حلقه (loop engineering) انجام می‌دهند، به جای promptهای تکی، دقت زیادی صرف دستورالعمل‌های دائمی می‌کنند. قانونی که در فایل همیشه فعال (always-on) قرار دارد، در نوبت 200 نیز اعمال می‌شود. قانونی که در چت تایپ کرده‌اید، فقط در نوبت 3 اعمال می‌شود. این قانون همچنین در نشست دومی که روی همان سیستم شروع می‌کنید اعمال می‌شود؛ نشستی که فایل commit شده را می‌خواند اما هیچ‌کدام از مواردی که در نشست اول تایپ کرده‌اید را به ارث نمی‌برد، حتی زمانی که دو نشست بتوانند با یکدیگر پیام رد و بدل کنند.

وابستگی‌های جدید، هزینه پنهان دیگر هستند. پله 5 می‌گوید از آنچه نصب شده استفاده کنید. هر بسته‌ای که agent با ابتکار خود اضافه می‌کند، چیزی است که بعداً باید آن را patch کنید و چیزی است که در نهایت در هر image کانتینری که از آن مخزن می‌سازید، قرار می‌گیرد.

نتایج بنچمارک رسمی Ponytail چه می‌گویند

این پروژه دو مجموعه نتیجه منتشر کرده است که تفاوت قابل‌توجهی با یکدیگر دارند. هر دو مجموعه، ارقام رسمی منتشرشده توسط خود پروژه هستند و هیچ‌کدام تست مستقل محسوب نمی‌شوند.

[
  {
    "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 از یک مدل خام به‌دست آمده که به مجموعه‌ای کوچک از پرامپت‌ها، با و بدون استفاده از این قاعده پاسخ داده است؛ این اعداد میانگین میانه از اجراهای تکراری در تاریخ‌های 13 و 17 ژوئن 2026 هستند. ستون agentic از یک نشست headless در Claude Code حاصل شده که در حال ویرایش مخزن full-stack-fastapi-template متعلق به tiangolo (یک مخزن واقعی FastAPI و React) بوده است. این تست شامل دوازده تیکت ویژگی با چهار بار اجرا روی Haiku 4.5 بوده و امتیازدهی بر اساس git diff باقی‌مانده انجام شده است.

ستون دوم را بخوانید. نتیجه agentic شامل 54 درصد خطوط کد کمتر، 20 درصد هزینه کمتر و 27 درصد زمان اجرای کمتر (wall clock time) است، در حالی که این مقادیر برای تنظیمات single shot به ترتیب 93 درصد و 74 درصد هستند. فایل README صادقانه دلیل این موضوع را بیان می‌کند: خط مبنای single shot یک مدل خام است که «با چندین گزینه به‌علاوه توضیحات پاسخ می‌دهد» که شکست دادن آن کار ساده‌ای است. اگر عملکرد را در برابر یک ایجنت واقعی که کار واقعی انجام می‌دهد بسنجید، میزان برتری کاهش می‌یابد. با این حال، این نتیجه همچنان واقعی باقی می‌ماند که نکته کاربردی‌تری است.

یک نکته احتیاطی وجود دارد که خود پروژه به آن اشاره کرده و همان عاملی است که تعیین می‌کند آیا این ابزار برای شما مفید است یا خیر. صرفه‌جویی در جایی بیشترین میزان را دارد که تله «ساخت بیش از حد» (over-build) وجود داشته باشد و در کدی که از قبل مینیمال بوده، این صرفه‌جویی نزدیک به صفر است. دوازده تیکت در یک مخزن Python و TypeScript نمی‌توانند وضعیت مخزن شما را پیش‌بینی کنند. اگر این اعداد برای شما اهمیت دارند، مقایسه را روی تیکت‌های خودتان، با و بدون این قاعده اجرا کنید و تعداد خطوط را شخصاً بشمارید.

الگویی که می‌توانید همین امروز بدون نصب هیچ‌چیز کپی کنید

این نردبان (ladder) متنی است، بنابراین برای استفاده از این ایده نیازی به پلاگین ندارید. بلوکی مانند این را در فایل دستورالعملی که ایجنت شما از قبل می‌خواند جای‌گذاری کنید؛ فرقی نمی‌کند آن فایل AGENTS.md باشد، CLAUDE.md یا فایل قوانین ویرایشگر شما.

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

آن قانون آخر به‌تنهایی ارزش توجه دارد. قرارداد Ponytail یک کامنت است که با نام ابزار برچسب‌گذاری شده است:

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

این کامنت دو خط کار است و پرسشی را حل می‌کند که در غیر این صورت یک چرخه بازبینی هزینه می‌برد. این کامنت به خواننده بعدی می‌گوید که نسخه ساده، یک تصمیم آگاهانه بوده است و شرایطی را نام می‌برد که تحت آن، این تصمیم دیگر معتبر نیست. بدون این کامنت، بازبین نمی‌تواند تشخیص دهد که آیا این یک میان‌برِ سنجیده است یا چیزی که ایجنت فراموش کرده، بنابراین مجبور می‌شود سؤال بپرسد.

محل قرارگیری این بلوک به اندازه محتوای آن اهمیت دارد. فایلی که ایجنت در هر اجرا بارگذاری می‌کند، تمام اجراها را هدایت می‌کند، از جمله اجراهایی که شما نظاره‌گر آن‌ها نیستید. این تفاوت، موضوع نوشتن یک AGENTS.md که ایجنت واقعاً از آن پیروی می‌کند است و به همین دلیل است که این الگو به جای تاریخچه شل (shell history)، به یک فایل متعهد (committed file) تعلق دارد. در یک monorepo، این الگو باید در بیش از یک فایل متعهد قرار بگیرد، زیرا یک AGENTS.md برای هر پکیج باعث می‌شود قوانین هر دایرکتوری کوتاه بماند و ایجنت مجبور نباشد در هر اجرا، تمام قراردادهای کل درخت را بخواند. با این حال، محل قرارگیری تضمین‌کننده نیست و ارزش دارد بدانید چرا یک ایجنت از قانونی که قبلاً بارگذاری کرده عبور می‌کند، پیش از آنکه نتیجه بگیرید نردبان به لحن قوی‌تری نیاز دارد.

جایی که این قاعده دیگر کارآمد نیست

این نردبان برای کارهای توسعه‌ای در یک codebase موجود تنظیم شده است، جایی که کدهای قابل استفاده مجدد معمولاً در دسترس و صحیح هستند. این مدل برای پروژه‌های greenfield (پروژه‌های جدید و بدون پیش‌زمینه) مناسب نیست، زیرا در پله 2 چیزی برای استفاده مجدد وجود ندارد و در پله 5 چیزی نصب نشده است، بنابراین عامل (agent) هر بار به پله 7 سقوط می‌کند. همچنین زمانی که واقعاً به انتزاع (abstraction) نیاز دارید، این مدل به خوبی عمل نمی‌کند. اگر قصد دارید چهارمین فراخوان‌کننده (caller) را برای همان بلوک کپی‌شده اضافه کنید، "کوتاه‌ترین diff" به شما یک کپی پنجم تحویل می‌دهد.

سطح ultra الزامات شما را به چالش می‌کشد. هدف این سطح همین است و زمانی که تصمیم خود را گرفته‌اید و می‌خواهید کار انجام شود، این یک هزینه واقعی محسوب می‌شود. برای کارهای عادی از full استفاده کنید و زمانی که شک دارید مشکل از خودِ درخواستِ ویژگی (feature request) است، به سراغ ultra بروید.

هیچ بلوک دستوری شما را از برداشت اشتباه نسبت به مسئله نجات نمی‌دهد. اولین مورد در مجموعه قوانین، درک کد پیش از تصمیم‌گیری است؛ این بخش پرهزینه‌ترین قسمت کار است و بخشی است که متن نمی‌تواند به جای شما انجام دهد. یک diff حداقلی در تابع اشتباه، همچنان یک اصلاح اشتباه است، با این تفاوت که اکنون یک اصلاح اشتباه کوچک است که تأیید آن آسان است.

خلاصه صادقانه این است که Ponytail یک پرامپت با دقت نوشته‌شده است که به خوبی توزیع شده و با اعداد همراه است. هیچ بخشی از آن نیازی به پلاگین ندارد. آنچه این پروژه به شما ارائه می‌دهد این است که شخصی این لیست را به درستی نوشته، آن را روی یک مخزن واقعی تست کرده و روش کار را در کنار نتیجه منتشر کرده است.

FAQ

آیا Ponytail با ایجنت‌هایی غیر از Claude Code کار می‌کند؟

بله. این ابزار به‌عنوان یک skill برای میزبان‌هایی که از skillها پشتیبانی می‌کنند عرضه می‌شود؛ فهرستی که شامل Claude Code، Codex، OpenCode، Gemini و چندین مورد دیگر است که در README نام برده شده‌اند. ویرایشگرهایی که فایل‌های rule را می‌خوانند اما skillها را بارگذاری نمی‌کنند، مانند Cursor، Windsurf، Cline و Copilot، مجموعه قوانین همیشه فعال (always-on) را از دایرکتوری rules مربوطه دریافت می‌کنند و به slash commandها دسترسی ندارند. متن در هر دو حالت یکسان است، بنابراین تفاوت اصلی در این است که آیا میزبان شما آن متن را در هر نوبت در context نگه می‌دارد یا فقط زمانی که یک skill فعال شود.

آیا یک ایجنت تنبل (lazy) از تست‌ها، اعتبارسنجی یا امنیت صرف‌نظر می‌کند؟

خیر، و مجموعه قوانین مستقیماً به این موضوع اشاره دارد. در فهرست «هرگز در این موارد تنبل نباش» (never lazy about)، به اعتبارسنجی ورودی در مرزهای اعتماد (trust boundaries)، مدیریت خطا برای جلوگیری از از دست رفتن داده‌ها، امنیت و دسترس‌پذیری اشاره شده است و برای هر بخش از منطق غیربدیهی، یک بررسی کوچک قابل‌اجرا درخواست می‌شود. آنچه این قانون حذف می‌کند، ساختارهای ابداعی است: انتزاعاتی که کسی درخواست نکرده و وابستگی‌هایی که کسی به آن‌ها نیاز نداشته است. اگر ایجنت شما پس از نصب این ابزار شروع به حذف تست‌ها کرد، علت آن دستور دیگری در پیکربندی شخصی شماست که اولویت بالاتری نسبت به این دستور دارد؛ بنابراین فایلی را که ایجنت در آخرین مرحله بارگذاری می‌کند، بررسی کنید.

آیا اعداد منتشرشده در مورد سرعت و هزینه قابل اعتماد هستند؟

این اعداد اندازه‌گیری‌های خود پروژه هستند که همراه با روش‌شناسی آن‌ها منتشر شده‌اند و باید همان‌طور خوانده شوند. ارقام مربوط به single shot با یک مدل پایه مقایسه شده‌اند که با گزینه‌ها و توضیحات پاسخ می‌دهد؛ موردی که خودِ README آن را به‌عنوان یک baseline ضعیف مشخص کرده است. ارقام مربوط به ایجنت از یک نشست headless در Claude Code روی یک مخزن FastAPI و React، دوازده تیکت و چهار اجرا برای هر کدام، روی مدل Haiku 4.5 به دست آمده‌اند. این‌ها اعداد صادقانه‌ای برای آن تنظیمات هستند. این اعداد پیش‌بینی برای codebase شما نیستند، زیرا پروژه همچنین ذکر کرده است که صرفه‌جویی در کدهایی که از قبل مینیمال بوده‌اند، به نزدیک صفر می‌رسد.

آیا برای بهره‌مندی از این ابزار نیاز به نصب چیزی دارم؟

خیر. این نردبان (ladder) متن است و یک بلوک معادل که در فایل دستوری که ایجنت شما از قبل می‌خواند کپی شود، بیشتر اثر مورد نظر را به شما می‌دهد. این افزونه، متن به‌روزرسانی‌شده، سطوح شدت، دستورات بازبینی و مسیر به‌روزرسانی را در اختیار شما قرار می‌دهد. امتحان کردن بلوک کپی‌شده در ابتدا، پاسخ پله 1 به این پرسش است که آیا اصلاً نیازی به نصب وجود دارد یا خیر.

چگونه از ساخت‌وساز بیش‌ازحد توسط یک ایجنت بدون نظارت در طول شب جلوگیری کنم؟

قانون را به‌جای پیام چت، در فایل دستورات همیشه فعال (always-on) قرار دهید تا در نوبت 200 یک اجرای طولانی نیز اعمال شود، نه فقط در نوبت 3. سپس خسارت احتمالی را جداگانه محدود کنید: به ایجنت یک checkout بدهید که اجازه خراب کردن آن را داشته باشد (به‌جای تنها نسخه اصلی خود) و پیش از هرگونه merge، بازبینی diff توسط انسان را الزامی کنید. یک قانون diff مینیمال، حجم مطالبی که باید بخوانید را کاهش می‌دهد. این قانون تصمیم نمی‌گیرد چه چیزی نهایی شود و نباید هم چنین کاری انجام دهد.