‏چرا توضیح pull request رو باید خودمون بنویسیم، نه agent

تو این پست از وبلاگ لاراول، نویسنده استدلال می‌کنه که برنامه‌نویس‌ها باید توضیح pull request رو خودشون بنویسن، حتی وقتی یه agent مثل Claude یا Codex بیشتر پیاده‌سازی رو انجام داده. حرفش این نیست که agentها نمی‌تونن، اتفاقاً معمولاً توضیحی خیلی کامل‌تر می‌نویسن. دو دلیل داره: نوشتن توضیح مجبورت می‌کنه تغییر رو بفهمی و توضیحش بدی، و reviewer به context از طرف تو نیاز داره، نه خلاصهٔ diff از طرف همون agentی که کد رو نوشته.

به گفتهٔ نویسنده، وقتی کد و تست و پیام commit و توضیح PR همه رو agent نوشته باشه، دیگه هیچ جایی نیست که خودمون رو مجبور به فهمیدن تغییر کنیم. نوشتن توضیح یه checkpoint طبیعی می‌سازه: چی عوض شد؟ چرا؟ عواقبی هست که از diff معلوم نباشه؟ reviewer چی باید بدونه؟ اگه بدون اینکه از agent بپرسی نتونی جواب بدی، یعنی باید یه کم بیشتر با تغییر وقت بذاری.

نویسنده اسم یه پدیده رو گذاشته «Claude confidence»: Claude یه تغییر می‌ده، تست‌ها رو اجرا می‌کنه و با اطمینان کامل می‌گه همه‌چی درست و backward compatible و آمادهٔ ship هست. خیلی وقت‌ها هم درست می‌گه، ولی «Claude مطمئنه» با «من این تغییر رو می‌فهمم» فرق داره. خیلی راحت اعتمادبه‌نفس agent به آدم منتقل می‌شه، مخصوصاً وقتی هم کد رو نوشته هم توضیح اینکه چرا درسته.

نویسنده می‌گه توضیح PR جای همهٔ جزئیات نیست، اون کار diff هست. توضیح برای یه آدم دیگه نوشته می‌شه و باید بگه این PR چرا وجود داره، چی رو عوض می‌کنه، کجای کار بزرگ‌تر قرار می‌گیره، چه چیز عجیب یا پرریسکی داره و دوست داری نظر reviewer رو دربارهٔ چی بدونی. یه مثال هم می‌زنه: توضیح agent برای جلوگیری از حذف workspace با deployment فعال، پر از بخش‌های Changes و Testing و Backward compatibility بود، ولی بیشترش به review کمکی نمی‌کرد. نسخهٔ انسانی سه خط بود: چرا (حذف workspace اون deploymentها رو خراب می‌کنه)، چه گزینه‌ای رد شد (پاک‌کردن خودکار)، و اینکه نویسنده مطمئن نیست 409 پاسخ درستی باشه.

نویسنده اضافه می‌کنه که با agentها همزمان روی کارهای بیشتری کار می‌کنیم و دنبال کردن اینکه کی داره چی کار می‌کنه سخت‌تر شده. برای همین وقتی PR یه هم‌تیمی رو باز می‌کنه، نمی‌خواد ۱۵۰۰ کلمهٔ رباتی بخونه. جمع‌بندیش اینه: بذار agentها کد بنویسن، ولی اگه صاحب تغییری، صاحب توضیحش هم باش.

نکات کلیدی:

• نوشتن توضیح PR یه checkpoint برای فهمیدن تغییره، مخصوصاً وقتی agent کد رو نوشته.
• «Claude confidence» یعنی اعتمادبه‌نفس agent رو با فهم خودت اشتباه گرفتن.
• توضیح خوب PR می‌گه چرا، چه context و trade-offی داره، کجا شک داری و reviewer کجا رو دقیق‌تر ببینه.
• جزئیات پیاده‌سازی و لیست تست‌ها جاشون تو diff هست، نه توضیح PR.
• ادعای «کاملاً backward compatible» از طرف agent چیزیه که reviewer به هر حال باید خودش چک کنه.