برد واقعی Next.js 16.2 برای ایجنت، API غلط کمتر است

عدد «شروع خیلی سریع‌تر» را حوالی سومین پست وبلاگی که با آن شروع می‌شد کنار گذاشتم. اگر شروع سرد بهتر شده باشد، خوشا به حالش. چیزی که PR را می‌شکند این نیست.

چیزی که می‌شکند آرام‌تر است. مدل یک API مربوط به App Router را اختراع می‌کند که دو نسخه عمده قبل وجود داشت. کش را با مدل ذهنی پارسال مهاجرت می‌کند. یا خطای کلاینت را «درست» می‌کند در حالی که پشته فقط در DevTools مرورگر بوده. Next.js 16.2 از این جهت جالب است که این شکل شکست را مسئله محصول دیده، نه سرگرمی پرامپت.

فایل کسل‌کننده‌ای که واقعاً مهم است

`create-next-app` حالا یک `AGENTS.md` می‌گذارد که ایجنت را به سند داخل خود پکیج `next` ارجاع می‌دهد. مارک‌داون ساده زیر `node_modules/next/dist/docs/`. فایل کوتاه است و دستورش تند: قبل از نوشتن کد Next.js، سند همین نصب را بخوان. داده آموزشی‌ات غلط است. پکیج منبع حقیقت است.

این تقریباً بیش از حد کوچک به نظر می‌رسد. ایجنت وقتی کمتر اشتباه می‌کند که سند همیشه در دسترس و هم‌نسخه با نصب، از مهارتی که مدل یادش می‌رود صدا بزند قوی‌تر باشد. ارزیابی خود Vercel این رویکرد را در مجموعه Next.js خودشان نسبت به بهترین تنظیم skill جلوتر نشان داده. ارزیابی فروشنده را وحی نمی‌گیرم. جهتش با چیزی که در ریپو می‌بینم می‌خواند: ایجنتی که سند محلی را می‌خواند، API شبح کمتری اختراع می‌کند.

برای اپ موجود روی 16.2 به بعد، بلوک مدیریت‌شده را خودت اضافه می‌کنی یا ابزار جدیدتر آن را upsert می‌کند. خط‌های قدیمی‌تر هنوز از codemod به نام `agents-md` استفاده می‌کنند که درخت `.next-docs` می‌سازد. ناوردای مهم یکی است: سند با پین وابستگی سفر می‌کند. ارتقای `next`، مرجع ایجنت را هم ارتقا می‌دهد.

اگر `AGENTS.md` را به ریپو اضافه کردی و بعد نسخه Next را بی‌صدا عقب یا جلو بردی، مطمئن شو مرجع همان نصب است. سند کپی‌شده در ویکی تیم، هفته بعد دروغ می‌شود.

حقیقت ترمینال به‌جای فولکلور مرورگر

دو تکه دیگر به ایجنتی که در شل زندگی می‌کند کمک می‌کنند.

خطای مرورگر در dev به‌طور پیش‌فرض به ترمینال فوروارد می‌شود. ایجنتی که کنسول را باز نمی‌کند، استثنای کلاینت را کنار لاگ سرور می‌بیند. در `next.config` می‌توانی این را به هشدار یا کل خروجی کنسول باز کنی، یا اگر نویز سیگنال را خورد خاموش کنی. پیش‌فرض سطح خطا معمولاً نقطه شروع درست است. ریختن هر `console.log` دیباگ داخل رونوشت ایجنت، زمینه را ارزان و شلوغ می‌کند.

یک فایل قفل زیر `.next/dev/lock` هست با PID و پورت و URL. وقتی `next dev` دوم بالا می‌آید، کاری که ایجنت‌ها دوست دارند بکنند، خطا آن‌قدر ساخت‌یافته است که بشود فرآیند درست را کشت یا به فرآیند موجود وصل شد. کمتر «چرا پورت اشغال است» در رونوشت جلسه.

`@vercel/next-browser` آزمایشی جلوتر می‌رود. فرمان شل که درخت کامپوننت، فعالیت شبکه، لاگ کنسول، تحلیل پوسته، و نماگرفت برمی‌گرداند. مدل به پنل DevTools خیره نمی‌شود. می‌تواند خروجی را ببیند و کاوش بعدی را انتخاب کند. این را وقتی مفید می‌دانم که از قبل به ایجنت روی یک شاخه اعتماد داری، نه مجوز رد کردن بازبینی.

معامله‌ای که نادیده نمی‌گیرم

عادت کهنه مدل با یک فایل مارک‌داون غیبش نمی‌زند. هنوز آموزش قدیمی داخل گفتگو را الگو می‌گیرد. هنوز `getServerSideProps` را در اپ App Router کپی می‌کند. هنوز با حذف مرز Suspense «بهینه» می‌کند و پوسته ایستا را می‌شکند. `AGENTS.md` کف را بالا می‌آورد. جایگزین انسانی که diff مهاجرت را می‌خواند نیست.

اعتماد بیش از حد به همین فایل، شکست بعدی است. بلوک مدیریت‌شده اشاره‌گر است نه موتور سیاست. اگر قانون واقعی ریپو فقط در یک رشته گفتگوی تیمی باشد، احراز هویت چطور است، کدام متغیر محیط دست‌نخورده است، بازتولید کی مجاز است، ایجنت یک جواب تمیز Next.js می‌دهد که برای استقرار تو غلط است. محدودیت پروژه را بیرون نشانگرهای مدیریت‌شده بنویس و آن‌قدر کوتاه که خوانده شود.

مهاجرت تولیدشده هنوز بازبینی انسان می‌خواهد. کش، Route Handler، middleware، و مسیر پیش‌نویس و پیش‌نمایش جاهایی‌اند که کد «درست طبق سند» هنوز می‌تواند در پروداکشن غلط باشد. ایجنت حالا می‌تواند صفحه درست سند را نشان بدهد. شعاع انفجار هنوز مال توست.

این هفته در یک ریپوی واقعی

به خطی برو که سند را باندل می‌کند. `AGENTS.md` یا `CLAUDE.md` را با نشانگر Next.js سالم کامیت کن و یک پاراگراف قانون تیم را بیرون آن نشانگر بگذار. اگر ایجنت را مقابل `next dev` می‌دوانی، فوروارد خطا به ترمینال را روشن بگذار. `next-browser` را روی یک باگ UI که ایجنت مدام حدس می‌زند امتحان کن، بعد تصمیم بگیر تشریفاتش می‌ارزد یا نه.

کل پشته ایجنت را دور تیتر سرعت شروع بازنویسی نکن. برد پایدار 16.2 باریک‌تر و راست‌گوتر است: API فریمورک غلط کمتر در PR، خطای کلاینت نامرئی کمتر، و کمی آشوب کمتر وقتی ایجنت سرور توسعه دوم را بالا می‌آورد. برای ریپوی شلوغ همین کافی است که مهم باشد. کافی نیست که diff را نخوانی.

یک جزئیات اجرایی که در بازبینی گم می‌شود: نشانگر مدیریت‌شده را با دست «تمیز» نکن. ابزار ارتقا همان بلوک را upsert می‌کند. اگر داخلش قانون تیم نوشته باشی، ارتقای بعدی یا قانونت را پاک می‌کند یا بلوک را تکراری می‌سازد. قانون خودتان بیرون نشانگر بماند، کوتاه، و نزدیک همان فایل تا مدل هر دو را در یک خواندن ببیند.

پرسش‌های کوتاه

روی نسخه قبل از 16.2 چه کار کنم؟ اگر codemod سند محلی را می‌سازد همان ناوردای «سند با نسخه نصب» را بگیر. اگر نه، حداقل یک پاراگراف کوتاه در ریپو بگذار که بگوید کدام APIها در این اپ ممنوع‌اند. سکوت یعنی مدل از حافظه‌اش کد می‌نویسد.

خروجی کنسول را کامل به ترمینال بریزم؟ فقط وقتی دنبال یک باگ مشخصی. سطح خطا را پیش‌فرض نگه دار تا رونوشت ایجنت تبدیل به سطل لاگ نشود.

اگر AGENTS.md باشد دیگر بازبینی لازم نیست؟ نه. سند درست هنوز با قانون استقرار تو یکی نیست. کش و پیش‌نمایش و middleware را انسان باید ببیند.