Tutorial 3 Your First Agent Task fa

آموزش ۳ · نخستین کارِ عاملِ شما

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

هدف: افزودن یک فرمانِ کاملاً نو به CLI — سرتاسری — با هدایتِ عاملِ خود. فرمانِ lockedin endorse را اضافه می‌کنیم: غریبه‌های کاملاً ناشناس را برای مهارت‌هایی که تقریباً به‌یقین ندارند تأیید مهارت می‌کند. کاملاً هماهنگ با برند.

این قلبِ آموزش است. حلقه‌ی واقعی را تمرین می‌کنید: مشخصات → آزمون‌ها → پیاده‌سازی → دروازه‌ی سبز → بازبینی.

← قبلی: آموزش ۲ کد چگونه کار می‌کند · بعدی: آموزش ۴ اعلان‌نویسی و بازبینی

---

گام ۰ — تصمیم بگیرید «انجام‌شده» چه شکلی است

پیش از هر اعلانی، مشخصات را خودتان به زبان ساده بنویسید. درخواست‌های مبهم کدِ مبهم می‌گیرند — از یک انسان یا یک عامل.

endorse پنج تا هفت خط چاپ می‌کند، هر خط یک فردِ تصادفی‌انتخاب‌شده (با استفاده‌ی دوباره از مخزنِ موجودِ NAMES) را برای یک مهارتِ پرطمطراقِ تصادفی‌انتخاب‌شده (یک مخزنِ جدید) تأیید مهارت می‌کند. با یک تک‌خطیِ طنزآمیز پایان می‌یابد. باید به‌عنوان lockedin endorse، به‌عنوان /endorse درون‌نشست و در help قابل‌دسترس باشد. همه‌ی تصادفی‌سازی باید از کمک‌کننده‌های بذردارِ pick/shuffle استفاده کند تا خروجی قطعی بماند. npm test باید سبز بماند و باید یک آزمونِ جدید باشد که دستِ‌کم یک ناوردا را میخکوب کند.

آن پاراگراف چیزی است که به عامل خواهید سپرد. توجه کنید که محدودیت‌های فصل ۲ را نام می‌برد (مولدِ بذردار، دروازهٔ آزمون، عادتِ ناوردا‌ها).

گام ۱ — از عامل بخواهید برنامه‌ریزی کند، نه کدنویسی

با درخواستِ یک برنامه شروع کنید. این فرصتِ شماست که یک رویکردِ بد را پیش از تغییرِ هر فایلی بگیرید.

«می‌خواهم یک فرمانِ endorse به LockedIn CLI اضافه کنم. مشخصات این است: [paste your spec]. پیش از نوشتن کد، به من بگو کدام فایل‌ها را تغییر می‌دهی و رویکردت چیست، تا تأییدش کنم. برای فرمانی مانند connect از الگوهای موجود پیروی کن.»

یک برنامه‌ی خوب به این‌ها اشاره می‌کند: یک مخزنِ جدیدِ SKILLS + یک renderEndorse() در src/lockedin.js، سیم‌کشیِ آن به dispatch() و handleSlash()، افزودن یک ردیف به renderHelp()، صادرکردنِ تابع/مخزنِ جدید، و افزودن آزمون‌ها در هر دو فایلِ آزمون. اگر برنامه قاعده‌ی مولدِ بذردار یا آزمون‌ها را از قلم انداخت، همین حالا بگویید.

گام ۲ — آزمون‌محور

از عامل بخواهید آزمون‌ها را پیش از پیاده‌سازی بنویسد. آزمون‌محوری مشخصاتِ شما را به چیزی اجراپذیر بدل می‌کند و عامل را درستکار نگه می‌دارد.

«عالی. نخست، فقط آزمون‌های شکست‌خورده اضافه کن: یک آزمونِ واحد که renderEndorse() متنی برمی‌گرداند که یک مهارتِ شناخته‌شده و دستِ‌کم ۵ تأیید مهارت را نام می‌برد، و یک آزمونِ cli.test.js که lockedin endorse با کد ۰ خارج می‌شود و یک تأیید مهارت چاپ می‌کند. از یک بذرِ ثابت استفاده کن. هنوز renderEndorse را پیاده نکن — بگذار نخست شکستِ آزمون‌ها را ببینیم.»

آن‌ها را اجرا کنید و تماشا کنید که به دلیلِ درست شکست می‌خورند (تابع هنوز وجود ندارد):

npm test

گام ۳ — بگذارید عامل پیاده‌سازی کند

اکنون به پیاده‌سازی چراغ سبز بدهید:

«حالا آن را پیاده کن تا آن آزمون‌ها سبز شوند، با پیروی از الگوی connect. یک مخزنِ SKILLS از حدود ۲۵ مهارتِ پرطمطراق، یک renderEndorse() که یک رشته برمی‌گرداند اضافه کن، dispatch و handleSlash را سیم‌کشی کن، یک ردیفِ help اضافه کن، و آنچه افزودی را صادر کن. برای تصادفی‌سازی فقط از pick/shuffle استفاده کن.»

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

const SKILLS = [
  'رهبری فکری', 'هم‌افزایی', 'قصه‌گویی', 'حال‌وهوا',
  'چرت‌زدن راهبردی', 'هم‌راستایی ذی‌نفعان', 'صراحت رادیکال', /* ...~25 total... */
];

function renderEndorse() {
  const people = shuffle(NAMES).slice(0, 5 + Math.floor(rand() * 3)); // 5–7
  const skills = shuffle(SKILLS);
  const out = [''];
  people.forEach((n, i) =>
    out.push('  ✔ ' + n + ' را برای ' + skills[i % skills.length] + ' تأیید کردید'));
  out.push('', '  شما ۶ غریبه را برای مهارت‌هایی تأیید کردید که نمی‌توانید راستی‌آزمایی کنید. آن‌ها ظرف یک ساعت شما را هم تأیید می‌کنند.');
  return out.join('\n');
}

…به‌علاوه‌ی یک خط در هر یک از dispatch() و handleSlash()، یک ردیف در renderHelp()، و افزودنِ SKILLS, renderEndorse به module.exports.

گام ۴ — دروازه

npm test

سبز؟ همین‌حالا یک ویژگی را با یک عامل و به‌صورت آزمون‌محور عرضه کردید. سبز نیست؟ این عادی است — به حلقه‌ی تکرارِ فصل ۴ بروید و دقیقاً به عامل بگویید چه شکست خورد.

سپس به چیزِ واقعی نگاه کنید (آزمون‌ها متن را بررسی می‌کنند، اما شما همچنان باید نگاه کنید):

node bin/lockedin.js endorse
LOCKEDIN_SEED=1 node bin/lockedin.js endorse   # reproducible

گام ۵ — پیش از پذیرش بازبینی کنید

هرگز یک diff را که نخوانده‌اید نپذیرید. به‌ویژه این‌ها را مرور کنید:

• آیا از الگو پیروی کرد؟ فرمانِ جدید باید آینه‌ی connect باشد — بدون وابستگیِ جدید، بدون console.log درونِ src/.
• فقط مولدِ بذردار؟ diff را برای Math.random بگردید. هیچ‌کدام نباید باشد.
• آیا چیزی را که نباید دست زد؟ تغییر باید افزایشی باشد؛ خطوطِ نامرتبط نباید جابه‌جا شوند.
• آیا آزمونِ جدید معنادار است؟ باید شکست بخورد اگر کسی بعداً ویژگی را بشکند — نه اینکه فقط true را ادعا کند.

اگر چیزی سرِ جایش نبود، بخواهید اصلاحش کند (فصل ۴). اگر خوب بود، کارتان تمام است.

---

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

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

• «کاری کن endorse یک نامِ اختیاری بپذیرد: lockedin endorse Ada باید به‌طور خاص Ada را تأیید مهارت کند. یک آزمون اضافه کن، دروازه را سبز نگه دار.»

اکنون یک ویژگی را سرتاسری ساخته‌اید. فصلِ آخر درباره‌ی انجامِ روانِ این کار است — اعلان‌نویسی و بازبینی مانند یک مهندسِ سرگروه.

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