‏ایجنت‌های کدنویسی از خطای ابزارهای CLI چی لازم دارن؟

ایجنت کدنویسی وقتی یه ابزار CLI رو اجرا می‌کنه فقط دو چیز رو می‌خونه: exit code (عددی که برنامه موقع تموم شدن برمی‌گردونه) و خروجی stdout. تیم debuff تو این مقاله رفتار ۱۲ ابزار معروف جاوااسکریپت مثل ESLint، webpack، npm، Jest، Biome، Vitest، tsc، Vite، esbuild، Prettier و Rollup رو موقع خطا یکسان اندازه گرفته؛ روی ویندوز ۱۱ و Node 24.15.0.

به گفته نویسنده‌ها ایجنت باید بین چهار حالت فرق بذاره: کار درست انجام شده، چیزی که چک شده شکست خورده (مثلاً تست یا خطای تایپ)، خود دستور اشتباه بوده، یا پروژه و سیستم آماده نیست. اشتباه گرفتن این‌ها گرونه؛ ایجنتی که یه flag غلط رو با تست شکست‌خورده قاطی کنه، دنبال باگ تو کدی می‌گرده که سالمه. ایجنتی هم که نبودن فایل config رو دوباره امتحان کنه، تو حلقه می‌افته.

نتایج جالبی داره. ۱۰ ابزار از ۱۲ تا گزینه ناشناخته رو رد می‌کنن و ESLint از همه بهتره، چون نزدیک‌ترین گزینه درست رو هم پیشنهاد می‌ده. Prettier و Rollup با یه هشدار ادامه می‌دن که ایجنت ممکنه نبینه. Vitest، Vite و esbuild (روی ویندوز) به‌جای پیام ساده stack trace چاپ می‌کنن. فقط ESLint و webpack برای خطای استفاده کد ۲ و برای شکست واقعی کد ۱ برمی‌گردونن؛ بقیه برای هر دو ۱ می‌دن.

حالت JSON هم کامل نیست. از ۷ ابزاری که حالت JSON دارن، ۶ تا موقع شکست واقعی یه JSON قابل parse می‌دن، ولی وقتی فایل config نیست و ابزار اصلاً اجرا نمی‌شه، ۵ تاشون هیچی رو stdout نمی‌نویسن. فقط npm تو این حالت هم JSON با یه کد خطا مثل E404 می‌ده. هیچ ابزاری هم تو یه فیلد مشخص نمی‌گه تکرار دستور فایده داره یا نه.

debuff از نسخه 0.20 یه قرارداد ثابت گذاشته: کد ۰ یعنی موفقیت، ۱ یعنی گزارش شکست، ۲ یعنی سیستم یا پروژه باید درست بشه و تکرار فایده نداره، و ۳ یعنی ورودی اشتباه. با --json هم stdout دقیقاً یه سند JSON داره و اگه دستور اجرا نشه، این شکلی خطا می‌ده:

{ "error": { "code": "browser_not_found", "message": "…", "fix": "Install Chrome or Edge, or set DEBUFF_BROWSER…", "transient": false } }

فیلد code از یه لیست ثابت میاد و بین نسخه‌ها معنیش عوض نمی‌شه و transient: true یعنی ممکنه اجرای دوباره جواب بده. پیشنهاد نویسنده‌ها به سازنده‌های CLI اینه: گزینه ناشناخته رو رد کنن، برای خطای استفاده کد خروج جدا بذارن، تو حالت JSON همیشه یه سند بدن، خطا رو با کد ثابت و اطلاعات retry گزارش کنن و برای اشتباه کاربر stack trace چاپ نکنن.

نکات کلیدی:

• از ۱۲ ابزار، ۱۰ تا گزینه ناشناخته رو رد می‌کنن؛ Prettier و Rollup فقط هشدار می‌دن.
• فقط ESLint و webpack برای خطای استفاده (۲) و شکست واقعی (۱) کد خروج جدا دارن.
• از ۷ ابزار با حالت JSON، فقط npm وقتی ابزار اجرا نمی‌شه هم JSON با کد خطا می‌ده.
• هیچ ابزاری صریحاً نمی‌گه تکرار دستور کمک می‌کنه یا نه.
• debuff 0.20 کدهای خروج ۰ تا ۳ و یه JSON خطا با فیلدهای code، fix و transient تعریف کرده.
• آزمایش فقط روی ویندوز ۱۱ و Node 24.15.0 با یه دستور برای هر ابزار انجام شده.