Tutorial 2 How the Code Works he

מדריך 2 · איך הקוד עובד

מטרה: להבין את קומץ החלטות העיצוב שהופכות את הפרויקט הזה לקל — ובטוח — לשינוי עם סוכן AI. אינכם צריכים לשנן את הקוד; אתם צריכים את המודל המנטלי, כדי שתוכלו לכוון את הסוכן במדויק.

← הקודם: מדריך 1 התמצאות · הבא: מדריך 3 משימת הסוכן הראשונה שלכם

---

המפה

lockedin-cli/
├── bin/lockedin.js      # נקודת הכניסה — החלק היחיד שעושה קלט/פלט
├── src/lockedin.js      # הליבה — פונקציות טהורות שמחזירות מחרוזות
├── test/
│   ├── unit.test.js     # בודק ישירות את פונקציות הליבה
│   └── cli.test.js      # מפעיל את הבינארי האמיתי ובודק את הפלט שלו
├── tools/screenshot.js  # יוצר את קובצי ה-SVG שב-docs/
└── package.json         # מטא-נתונים + הסקריפט `npm test`

ארבעה רעיונות גורמים לזה לעבוד. למדו אותם ותוכלו לבקש מהסוכן כמעט כל שינוי בביטחון.

רעיון 1 — ליבה טהורה שמחזירה מחרוזות

פתחו את src/lockedin.js. שימו לב שפונקציות הרינדור אינן מדפיסות — הן מחזירות מחרוזות:

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...בונה מערך של שורות...
  return out.join('\n');   // מחזיר טקסט; לא מדפיס דבר
}

כל ההדפסה בפועל (וקריאת ההקשות שלכם) קורית ב-bin/lockedin.js. הפרדת "הליבה מחזירה נתונים, הקצה עושה I/O" הזו היא הדבר החשוב ביותר כאן, כי פונקציה שרק מחזירה מחרוזת היא טריוויאלית לבדיקה:

const out = app.renderConnect();
assert.ok(out.includes("״אשמח להוסיף אותך לרשת המקצועית שלי.״ — נשלח ל-"));

ללא הדמיית טרמינל, ללא לכידת stdout. כשאתם מבקשים מהסוכן להוסיף תכונה, זו הסיבה שהוא יכול גם להוסיף לה בדיקה מהירה ואמינה.

רעיון 2 — מאגרי תוכן

הבדיחות חיות במערכים פשוטים בראש src/lockedin.js:

const HOOKS = [ 'דעה לא פופולרית:', 'תנו לזה לשקוע.', /* ...~25 total... */ ];
const LESSONS = [ '→ הרשת שלך היא השווי הנקי שלך.', /* ... */ ];

המחוללים בוחרים מהמאגרים האלה. ב-v1.2.0 כל מאגר גדל ל-~25 וריאציות, ושכבה שנייה של מאגרי תבנית נוספה (דברים כמו POST_REVEALS ו-REFLECT_TAGSETS) כך שה_מבנה_ של כל פלט משתנה, לא רק המילים. הוספת תוכן היא לרוב פשוטה כמו הוספת מחרוזות למערך — משימה ראשונה מושלמת למסור לסוכן.

רעיון 3 — אקראיות עם זרע = בדיקות דטרמיניסטיות

פלט אקראי ובדיקות אוטומטיות נשמעים לא תואמים. הפרויקט הזה מרבע את המעגל הזה עם מחולל מספרים אקראיים ניתן לזריעה:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → אותו seed, אותו פוסט

כל בחירה אקראית עוברת דרך פונקציות העזר המשותפות pick() / shuffle(), ששואבות מאותו מחולל בעל זרע. הגדירו LOCKEDIN_SEED=42 וה-CLI ניתן לשחזור מלא. כלל הזהב לכל שינוי: אקראיות חדשה חייבת להשתמש ב-pick / shuffle, לעולם לא ב-Math.random ישירות — אחרת הדטרמיניזם (והבדיקות) נשברים. שמרו את זה בכיס האחורי; תזכירו את זה לסוכן בפרק 3.

רעיון 4 — שתי שכבות של בדיקות

• test/unit.test.js קורא לפונקציות הליבה ומוודא על המחרוזות שהן מחזירות (מהיר, מדויק).
• test/cli.test.js למעשה מפעיל את bin/lockedin.js ובודק את ה-stdout וקוד היציאה האמיתיים שלו (מוכיח שכל הדבר עובד מקצה לקצה).

יחד הם המחסום. הם גם מקודדים אינווריאנטים — הבטחות שהאפליקציה נותנת. למשל, פוסט תמיד נפתח ב-hook ידוע ותמיד מכיל לפחות שלושה שיעורי →; מסך ה-"connect" תמיד אומר incalculable. כשסוכן משנה קוד, הבדיקות האלה תופסות כל דבר ששבר הבטחה בשקט.

---

למה זה חשוב לעבודה עם סוכן

חברו את ארבעת הרעיונות יחד ותקבלו בסיס קוד שבו סוכן יכול:

1. להוסיף תכונה כפונקציה טהורה שמחזירה מחרוזת,
2. להוסיף בדיקה לה ללא שום התעמלות I/O,
3. לשמור על הפלט ניתן לשחזור דרך ה-RNG בעל הזרע, ו-
4. להוכיח שלא שבר כלום על ידי הרצת המחסום הקיים.

זו הלולאה שתריצו בפרק הבא.

✅ נסו עם הסוכן שלכם

בקשו מהסוכן שלכם לוודא את ההבנה שלכם — קריאה, לא עריכה:

1. "רשום כל מאגר תוכן ב-src/lockedin.js וכמה ערכים יש בכל אחד."
2. "הראה לי אינווריאנט אחד ש-test/unit.test.js אוכף לגבי generatePost, והסבר מה ישבור אותו."
3. "היכן מוגדר ה-RNG בעל הזרע, ואילו פונקציות חייבות להשתמש בו במקום ב-Math.random? אל תשנה כלום — רק הסבר."

כשתשובות הסוכן תואמות את הפרק הזה, אתם מוכנים לבנות.

הבא: מדריך 3 משימת הסוכן הראשונה שלכם