Ponytail؛ قانون نوشتن کمترین کد برای عامل هوش مصنوعی

Ponytail چیست

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

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

ابزار مهم نیست؛ در اولین سطح قابل‌اتکا متوقف شوید

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

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

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

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

آنچه مخزن واقعاً منتشر می‌کند

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

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

میزبان‌های پشتیبان مهارت، فرمان‌های slash را نیز دریافت می‌کنند. /ponytail سطح را تنظیم می‌کند، /ponytail-review یک diff را از نظر مهندسی بیش‌ازحد بررسی می‌کند، /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، پروژه به‌جای آن نصب plugin را مستند کرده است و این دو خط، مطابق مستندات در 1 August 2026، به شکل زیر هستند:

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

مسیر plugin از branch پیش‌فرض پیروی می‌کند، نه از tag. بنابراین دستورالعمل‌هایی که agent شما را هدایت می‌کنند ممکن است بین نشست‌ها بدون اطلاع شما تغییر کنند. این هزینه‌ای است که برای راحتی استفاده از فرمان update می‌پذیرید.

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

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

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

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

در یک سرور، شرایط متفاوت است، زیرا عامل اغلب بدون نظارت اجرا می‌شود. عاملی که در یک نشست tmux یا بر اساس زمان‌بندی کار می‌کند، پیش از آنکه متوجه شوید، ساعت‌ها فرصت دارد یک تصمیم نادرست را مبنا قرار دهد. این خطر عملی در اجرای یک عامل کدنویسی روی VPS است و به همین دلیل افرادی که مهندسی حلقه‌ای انجام می‌دهند، به دستورالعمل‌های دائمی بسیار بیشتر از promptهای منفرد توجه می‌کنند. یک قاعده در فایل همیشه‌فعال در نوبت 200 اعمال می‌شود. قاعده‌ای که در chat وارد کرده‌اید، فقط در نوبت 3 اعمال می‌شود.

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

اعداد معیارسنجی خود 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 از پاسخ‌گویی یک مدل خام به مجموعه‌ای کوچک از promptها، با و بدون این rule، به دست آمده است. این نتایج به‌صورت median در اجرای تکرارشده در تاریخ‌های 13 و 17 June 2026 محاسبه شده‌اند. ستون agentic از یک نشست headless Claude Code به دست آمده است که در آن، full-stack-fastapi-template متعلق به tiangolo، یعنی یک repository واقعی FastAPI و React، در دوازده feature ticket و با 4 اجرا برای هر ticket روی Haiku 4.5 ویرایش شده است. امتیازدهی بر اساس git diff باقی‌مانده انجام شده است.

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

یک نکته احتیاطی نیز خود پروژه مطرح کرده است؛ همین نکته تعیین می‌کند که این روش برای شما مفید است یا نه. صرفه‌جویی در جایی بیشترین مقدار را دارد که واقعاً خطر over-build وجود داشته باشد، و برای کدی که از ابتدا minimal بوده است تقریباً صفر است. دوازده ticket در یک repository شامل Python و TypeScript، عملکرد repository شما را پیش‌بینی نمی‌کند. اگر این عدد برایتان مهم است، مقایسه را روی ticketهای خودتان، با و بدون این rule، اجرا کنید و خطوط را خودتان بشمارید.

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

این نردبان متنی است؛ بنابراین برای استفاده از این ایده به افزونه نیاز ندارید. بلوکی مانند بلوک زیر را در فایل دستورالعملی قرار دهید که 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

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

محل قرار دادن این بلوک، به‌اندازه محتوای آن اهمیت دارد. فایلی که agent در هر اجرا بارگیری می‌کند، بر هر اجرا اثر می‌گذارد؛ حتی اجراهایی که شما نظارت نمی‌کنید. موضوع نوشتن یک AGENTS.md که agent شما واقعاً از آن پیروی کند همین تفاوت است و به همین دلیل این الگو باید در فایلی ثبت‌شده در مخزن قرار گیرد، نه در سابقه shell شما.

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

این نردبان برای کار روی قابلیت‌ها در یک codebase موجود تنظیم شده است؛ جایی که استفادهٔ مجدد معمولاً امکان‌پذیر و معمولاً درست است. این روش برای یک پروژهٔ greenfield مناسب نیست، چون در پلهٔ 2 چیزی برای استفادهٔ مجدد وجود ندارد و در پلهٔ 5 نیز چیزی نصب نشده است؛ بنابراین agent هر بار به پلهٔ 7 می‌رسد. این روش زمانی هم مناسب نیست که واقعاً بخواهید آن abstraction را ایجاد کنید. اگر در آستانهٔ اضافه‌کردن چهارمین caller برای همان block کپی‌شده هستید، «کوتاه‌ترین diff» یک کپی پنجم به شما می‌دهد.

سطح ultra الزامات شما را به چالش می‌کشد. هدف این سطح همین است و زمانی که تصمیم را قبلاً گرفته‌اید و می‌خواهید کار انجام شود، هزینهٔ واقعی دارد. برای کارهای معمول از full استفاده کنید و زمانی به ultra روی بیاورید که احتمال می‌دهید درخواست قابلیت، خودِ مسئله باشد.

هیچ instruction blockی شما را از برداشت نادرست از مسئله مصون نمی‌کند. نخستین مورد در ruleset نیز درک code پیش از تصمیم‌گیری است؛ این بخش پرهزینه است و متنی که در اختیار دارید نمی‌تواند آن را برای شما انجام دهد. یک diff حداقلی در function نادرست همچنان اصلاحی نادرست است و اکنون به اصلاحی کوچک و نادرست تبدیل شده که تأیید آن آسان است.

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

FAQ

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

بله. این ابزار به‌صورت یک skill برای hostهایی ارائه می‌شود که skillها را بارگذاری می‌کنند؛ این فهرست شامل Claude Code، Codex، OpenCode، Gemini و چند گزینه دیگر است که در README نام برده شده‌اند. ویرایشگرهایی که فایل‌های rule را می‌خوانند اما skillها را بارگذاری نمی‌کنند، مانند Cursor، Windsurf، Cline و Copilot، ruleset همیشه‌فعال را از دایرکتوری rule متناظر دریافت می‌کنند و هیچ slash commandی ندارند. متن در هر دو حالت یکسان است. تفاوت اصلی این است که host شما این متن را در هر نوبت در context نگه می‌دارد یا فقط هنگام فعال‌شدن یک skill آن را وارد context می‌کند.

آیا یک agent تنبل، testها، اعتبارسنجی یا امنیت را نادیده می‌گیرد؟

خیر، و ruleset این موضوع را مستقیماً بیان می‌کند. فهرست «هرگز درباره این موارد تنبل نباش» شامل اعتبارسنجی ورودی در مرزهای اعتماد، مدیریت خطا برای جلوگیری از ازدست‌رفتن داده، امنیت و دسترس‌پذیری است. همچنین برای هر بخش از منطق غیرساده، وجود یک بررسی کوچک و قابل‌اجرا را درخواست می‌کند. این rule ساختارهای ابداعی را حذف می‌کند: abstractionهایی که کسی درخواست نکرده و dependencyهایی که کسی به آن‌ها نیاز ندارد. اگر agent شما پس از نصب آن شروع به حذف testها کرد، علت احتمالاً دستور دیگری در config خودتان است که نسبت به این rule اولویت بالاتری دارد. بنابراین فایلی را بخوانید که agent در آخر بارگذاری می‌کند.

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

این اعداد، اندازه‌گیری‌های خود پروژه هستند که همراه با روش اندازه‌گیری منتشر شده‌اند و باید در همین چارچوب خوانده شوند. اعداد مربوط به اجرای منفرد، با یک model ساده مقایسه می‌شوند که در پاسخ خود optionها و توضیحات ارائه می‌کند؛ خود README نیز این معیار پایه را ضعیف می‌داند. اعداد agentic از یک session بدون رابط گرافیکی Claude Code به دست آمده‌اند که روی یک repository شامل FastAPI و React، با 12 ticket و 4 اجرا برای هر ticket، با Haiku 4.5 انجام شده است. این اعداد برای همان setup معتبر هستند. آن‌ها پیش‌بینی‌ای برای codebase شما نیستند، زیرا پروژه همچنین می‌گوید میزان صرفه‌جویی در کدی که از ابتدا حداقلی بوده است، به نزدیک صفر کاهش می‌یابد.

آیا برای بهره‌مندی از این قابلیت باید چیزی نصب کنم؟

خیر. این ladder متنی است و با چسباندن یک block معادل در فایل instructionای که agent شما از قبل می‌خواند، بیشتر اثر آن را دریافت می‌کنید. plugin، متن نگهداری‌شده، سطح‌های شدت، commandهای review و مسیر update را در اختیار شما می‌گذارد. ابتدا امتحان‌کردن block کپی‌شده، پاسخ مربوط به rung 1 به این پرسش است که آیا نصب آن اصلاً باید انجام شود یا نه.

چگونه از over-build کردن یک agent بدون نظارت در طول شب جلوگیری کنم؟

rule را به‌جای پیام chat، در فایل instruction همیشه‌فعال قرار دهید تا در turn 200 از یک اجرای طولانی نیز اعمال شود، نه فقط در turn 3. سپس دامنه خسارت را جداگانه محدود کنید: به‌جای تنها copy خود، checkoutای در اختیار agent بگذارید که مجاز باشد آن را خراب کند، و پیش از merge شدن هر چیزی، review انسانی diff را الزامی کنید. یک rule برای حداقل‌بودن diff، مقدار متنی را که باید بخوانید کاهش می‌دهد. این rule تعیین نمی‌کند چه چیزی وارد محصول شود و نباید هم چنین کاری انجام دهد.