‏AX؛ وقتی کدبیس رو برای ایجنت می‌چینی

نویسنده با یه صحنهٔ آشنا شروع می‌کنه: از ایجنت می‌خوای یه فیلد به صفحهٔ تمدید اشتراک اضافه کنه. کنترلر رو پیدا می‌کنه، فیلد رو می‌ذاره، تست رو آپدیت می‌کنه و تست هم پاس می‌شه. ولی تو production ایمیل تمدید هنوز مقدار قدیمی رو می‌فرسته، چون اون ایمیل رو یه queued job (کاری که می‌ره تو صف و بعداً اجرا می‌شه) می‌سازه که ایجنت هیچ‌وقت پیداش نکرد.

به گفتهٔ نویسنده مشکل این نبود که ایجنت PHP بلد نیست؛ راهی نداشت که کل مسیر تغییر رو کشف کنه و نتیجه رو چک کنه. Agent Experience engineering یا کوتاه AX یعنی همون دقتی که برای developer experience می‌ذاریم، برای محیط کار ایجنت هم بذاریم: ساختار ریپو، دستورهای کوتاه، دسترسی ابزارها، تست و قوانین ریویو. هدف قشنگ شدن ریپو به چشم مدل نیست؛ هدف اینه که کار درست پیدا بشه، کار خطرناک سخت بشه و نتیجه قابل راستی‌آزمایی باشه.

پیشنهاد عملی‌اش سه فایل کوتاه توی .memory/ ـه که هر کدوم به یه سؤال جواب می‌دن: PROJECT_STRUCTURE.md می‌گه هر رفتار کجا زندگی می‌کنه، STANDARDS.md می‌گه تو این پروژه چطور کار و چک می‌کنیم، و MEMORY.md تصمیم‌ها و تله‌های ماندگار رو نگه می‌داره، مثل همین که ایمیل تمدید رو یه job صف‌شده می‌سازه. نویسنده تأکید می‌کنه این فایل‌ها باید کوتاه بمونن؛ سند طولانی هم پیدا کردن چند فکت مهم رو سخت می‌کنه هم زود بیات می‌شه.

بعد یه AGENTS.md به‌عنوان نقطهٔ ورود، این سه فایل رو معرفی می‌کنه و می‌گه کِی سراغشون بره. نویسنده می‌گه این فایل باید قرارداد باشه نه حرف انگیزشی: دامنهٔ مجاز تغییر، تست‌هایی که باید اجرا شن، و تصمیم‌هایی که ایجنت تنهایی حق گرفتنشون رو نداره، مثل migration روی دادهٔ موجود یا دست زدن به .env و تنظیمات deploy. اگه این نوشته‌ها با کد نخوندن، کد مرجعه و نوشتهٔ بیات باید اصلاح شه.

یه هشدار مهم هم می‌ده: دستورهای متنی مرز امنیتی نیستن. یه کامنت مخرب تو سورس یا یه صفحهٔ وب می‌تونه به ایجنت بگه تسکش رو نادیده بگیره، پس هر متنی که از بیرون می‌آد داده‌ست نه دستور، و مجوزها باید بیرون از prompt اعمال شن. کنار این، حلقهٔ بازخورد هم باید خرابی واقعی رو بگیره: یه سوئیت سبز فقط همون چیزی رو ثابت می‌کنه که پوشش داده، و تست کنترلر ثابت نمی‌کنه job صف‌شده از فیلد جدید استفاده کرده.

نویسنده آخرش حد این کار رو هم می‌گه: AX اشتباه‌های قابل‌پیشگیری رو کم می‌کنه، ولی تصمیم نمی‌گیره که مشتری باید بار دوم شارژ شه یا تغییر schema برای deploy بی‌خطره. اون‌ها تصمیم محصول و مهندسی‌ان و آدم مسئولشه. حرف جالبش هم این‌ه که همین تغییرها معمولاً پروژه رو برای خود تیم هم راحت‌تر می‌کنن.

نکات کلیدی:

• سه فایل کوتاه تو .memory/: PROJECT_STRUCTURE.md برای مسیر تغییر، STANDARDS.md برای روش کار، MEMORY.md برای تله‌ها
• AGENTS.md نقطهٔ ورود ـه و باید دامنه، تست‌ها و تصمیم‌های نیازمند تأیید آدم رو مشخص کنه
• تست سبز مدرک کامل نیست؛ رفتار صف و مسیرهای غیر HTTP باید جدا تست شن
• دسترسی ابزار محدود به نیاز تسک باشه؛ ویوی فقط‌خواندنی دادهٔ تست با دسترسی به رکورد مشتری یکی نیست
• معیار سنجش AX تسک واقعی‌ه: تعداد اصلاح‌ها قبل از ریویو و خرابی‌های بعد از «تمام شد»، نه حجم دستورها