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

Ponytail چیست

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

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

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

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

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

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

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

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

• 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) شما را هدایت می‌کنند، ممکن است بین جلسات مختلف تغییر کنند. این هزینه‌ای است که برای راحتیِ داشتن یک دستور به‌روزرسانی می‌پذیرید.

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

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

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

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

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

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

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

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

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

این نردبان متنی است، بنابراین برای استفاده از این ایده نیازی به افزونه ندارید. بلوکی مانند این را در فایل دستورالعملی که عامل (agent) شما از قبل می‌خواند جای‌گذاری کنید؛ فرقی نمی‌کند این فایل 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 شما، متعلق به یک فایلِ commit شده است.

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

این نردبان برای توسعهٔ قابلیت‌ها در یک 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 مینیمال، حجم متنی که باید بخوانید را کاهش می‌دهد. این قانون تصمیم نمی‌گیرد چه چیزی نهایی شود و نباید هم چنین کاری انجام دهد.