Tutorial 4 Prompting and Reviewing fa

آموزش ۴ · اعلان‌نویسی و بازبینی

🌎 زبان: فارسی — مشاهدهٔ هر ۳۳ زبان

هدف: فرا-مهارت. اکنون می‌توانید یک ویژگی را با یک عامل بسازید — این فصل درباره‌ی انجامِ آن به‌شکلِ روان و تکرارپذیر است: نوشتنِ اعلان‌هایی که بارِ اول به هدف می‌خورند، بازبینیِ کارآمدِ diffها، تکرار وقتی اوضاع به‌هم می‌ریزد، و حفظِ شتاب در طول نشست‌ها.

← قبلی: آموزش ۳ نخستین کارِ عاملِ شما · بعدی: آموزش ۵ بومی‌سازی

---

مانند یک سرگروه اعلان بنویسید، نه مانند یک جعبه‌ی جست‌وجو

عامل یک مهندسِ جوانِ سریع، تحت‌اللفظی و مشتاق است. آن را همان‌گونه هدایت کنید که یک مهندسِ خوب را:

• هدف و محدودیت‌ها را بیان کنید. «endorse را اضافه کن» ضعیف است. «endorse را با پیروی از الگوی connect، فقط مولدِ بذردار، همراه با آزمون‌ها، در حالی که دروازه سبز می‌ماند اضافه کن» قوی است. محدودیت‌ها همان راهی هستند که کدِ متناسب می‌گیرید.
• به مثال‌ها اشاره کنید. «از الگوی به‌کاررفته توسط renderConnect پیروی کن» بر یک پاراگراف توصیف می‌چربد. کدِ موجود بهترین مشخصات است.
• پیش از ویرایش‌ها یک برنامه بخواهید روی هر چیزِ غیرِ پیش‌پاافتاده. تغییرِ مسیرِ یک برنامه ارزان است؛ بازکردنِ ده فایلِ ویرایش‌شده گران است.
• هر اعلان یک کار. بسته‌بندیِ «endorse را اضافه کن، مولد را هم بازآرایی کن، README را هم به‌روزرسانی کن» یک diff درهم‌تنیده می‌سازد که بازبینی‌اش سخت است.
• دروازهٔ آزمون را به آن بدهید. «npm test را اجرا کن و تا سبز نشده آن را تمام‌شده نشمار» عامل را به چیزی بدل می‌کند که کارِ خودش را بررسی می‌کند.

هر بار diff را بازبینی کنید

سرعت کلِ هدفِ یک عامل است — اما سرعتِ نخوانده راهی است که باگ‌ها عرضه می‌شوند. یک واکنشِ بازبینیِ سریع و ثابت بسازید:

1. دامنه: آیا فقط آنچه را که باید تغییر داد؟ خطوطِ نامرتبطِ جابه‌جاشده یک بوی بد هستند.
2. الگوها: آیا با کدِ پیرامون هماهنگ است، بدون وابستگیِ جدید و بدون ورودی/خروجی درونِ src/؟
3. قواعدِ پروژه: برای این مخزن، آن‌ها فقط مولدِ بذردار (diff را برای Math.random grep کنید)، متنِ قابل‌مشاهده برای کاربر در بسته‌های زبانی (نه کدسختِ درون‌خطی)، و خطوطِ کارت که هرگز از عرضی که چیدمان تا آن لایه‌گذاری می‌کند فراتر نمی‌روند هستند.
4. دسترس‌پذیری: آیا خروجیِ جدید از --accessible جانِ سالم به در می‌برد؟ lockedin --accessible <your command> را اجرا کنید و بررسی کنید که به‌صورت متنِ ساده‌ی تمیز خوانده می‌شود — بدون نگاره‌ی تزئینیِ تازه‌ای که از a11yFilter بگذرد.
5. آزمون‌ها: آیا یک آزمونِ جدید هست، و آیا واقعاً اگر ویژگی می‌شکست شکست می‌خورد؟ بپرسید: «کدام خط را عوض کنم تا این آزمونِ جدید شکست بخورد؟»
6. اجرایش کنید: npm test، سپس فرمان را اجرا کنید و به خروجی نگاه کنید.

لازم نیست هر نویسه را بفهمید — اما باید هر تصمیم را بفهمید. اگر نمی‌توانید یک تغییر را توضیح دهید، پیش از پذیرش از عامل بخواهید آن را توضیح دهد.

وقتی سبز نیست تکرار کنید

یک دروازه‌ی قرمز یک گامِ عادی است، نه یک شکست. راه‌حل، بازخوردِ دقیق است:

«npm test با این شکست می‌خورد: [paste the exact error]. آزمونِ عرضِ renderEndorse انتظار دارد هر خطِ کارت ≤ ۶۰ ستونِ مرئی باشد. بدون تضعیفِ آزمون اصلاحش کن.»

متنِ واقعیِ خطا را بچسبانید. «خراب است» عامل را به حدس می‌اندازد؛ ردیابیِ پشته‌ای آن را به اصلاح می‌کشاند. و ترجیح دهید همان گفت‌وگو را ادامه دهید به‌جای شروعِ تازه — عامل پیشاپیش زمینه‌ی آنچه را که به‌تازگی نوشت دارد. اگر دو یا سه تکرار همگرا نشد، یک گام عقب بروید و دوباره دامنه را تعیین کنید: کار ممکن است برای یک اعلان بیش‌ازحد بزرگ باشد.

حفظ شتاب در طول نشست‌ها

کارِ واقعی بیش از یک نشست طول می‌کشد. دو عادت یک عامل را در طول زمان کارآمد نگه می‌دارد:

• حافظه / قراردادها. اگر عامل شما از حافظه‌ی پایدار یا یک فایلِ دستورالعملِ پروژه پشتیبانی می‌کند، قواعدی را که همیشه باید پیروی کند این‌جا ثبت کنید (مثلاً «همه‌ی تصادفی‌سازی باید از pick/shuffle استفاده کند»، «پیش از اعلامِ اتمام npm test را اجرا کن»). یک قرارداد را یک بار بیان می‌کنید به‌جای هر اعلان.
• یک یادداشتِ واگذاری. این مخزن یک سندِ وضعیتِ کوتاه و پاکیزه در docs/HANDOFF.md نگه می‌دارد: پروژه چیست، چگونه ساخته شده، چگونه آزموده می‌شود و بعدی چیست. وقتی برمی‌گردید (یا به یک هم‌تیمی — یا عاملی دیگر — واگذار می‌کنید)، آن یادداشت زمینه را در چند ثانیه بازمی‌سازد. از عامل خود بخواهید به‌عنوان بخشی از یک تغییر آن را به‌روز نگه دارد.

نرده‌های محافظِ ارزشمند

• دروازه غیرقابل‌مذاکره است. آزمون‌های سبز پیش از عرضه‌ی هر چیز. همان چیزی است که به شما اجازه می‌دهد سریع حرکت کنید و به خروجی اعتماد کنید.
• شما بازبینِ ثبت‌شده هستید. عامل می‌نویسد؛ شما تصمیم می‌گیرید. پذیرشِ یک diff یعنی ضمانتش می‌کنید.
• گام‌های کوچک و قابل‌راستی‌آزمایی بر یک جهشِ غول‌آسا می‌چربند. هر تغییرِ پذیرفته‌شده باید اپلیکیشن را در حال کار رها کند.

---

✅ با عامل خود امتحان کن

1. یک مشخصاتِ یک‌پاراگرافی برای یک فرمانِ mentor («توصیه‌ی ناخواسته پخش می‌کند») بنویسید، شاملِ محدودیت‌ها، و عامل را وادار کنید آن را آزمون‌محور بسازد — برنامه، آزمون‌ها، کد، دروازه — با بازبینی در هر گام.
2. از عامل بخواهید docs/HANDOFF.md را به‌روزرسانی کند تا از فرمانِ جدید یاد کند.
3. عمداً چیزی را بشکنید (مثلاً یک ورودیِ مخزن را حذف کنید)، npm test را اجرا کنید، و تمرین کنید که شکستِ دقیق را برای اصلاح به عامل بدهید.

---

به کجا برویم

• کدِ واقعی در src/lockedin.js را مرور کنید — اکنون شکلِ آن را می‌دانید.
• docs/HANDOFF.md را برای یادداشت‌های وضعیت و معماریِ خودِ پروژه بخوانید.
• از شوخی‌ها در مرجع فرمان‌ها لذت ببرید.

آموزش همین است. اکنون می‌توانید یک عامل هوش مصنوعی را هدایت کنید تا نرم‌افزارِ واقعی را پشتِ یک دروازهٔ آزمون بسازد و تغییر دهد — با به‌کارگیریِ پرنخوت‌ترین نمونه‌ی قابل‌تصور. موافقید؟ 👇