האנטומיה של coding harness: מה באמת מפעיל סוכני קידוד
סקירה מעשית של החלקים המרכזיים ב-coding harness, העקרונות שמאחורי לולאת agent אמינה, ואיך Goose, Pi, OpenCode ו-DeepSeek Harness משתלבים בתמונה.
בדרך כלל אנחנו אומרים “סוכן קידוד”, אבל מי שבאמת עושה את העבודה הוא לרוב coding harness: שכבת התזמור שמסביב למודל השפה, זו שהופכת חיזויי טקסט ללולאה שימושית. המודל מציע, וה-harness מחליט איזה הקשר המודל רואה, אילו כלים זמינים, מתי פעולה מותרת, איך מתעדים תוצאות ומתי לעצור.
ההבחנה הזו חשובה. שני מוצרים יכולים להשתמש במודלים דומים ועדיין להרגיש שונים לגמרי, כי ה-harness שלהם מקבל החלטות אחרות לגבי state, כלים, הרשאות ומשוב. אם רוצים להבין למה סוכן מהיר, זהיר, שביר או גמיש, בדרך כלל צריך להסתכל מתחת לשכבת המודל.
הפוסט הזה פותח סדרה. כאן אני רוצה למפות קודם את האנטומיה והעקרונות המשותפים, ואז להשתמש בעדשה הזו בפוסטים נפרדים על ארבעה harnesses בקוד פתוח:
מה זה בעצם coding harness
coding harness הוא לא רק ממשק צ’אט ולא רק prompt. זו המערכת שמתווכת בין מודל לבין סביבה: קבצים, shell, טסטים, קומפיילרים, APIs, עורכים ואנשים.
ברמה הבסיסית, harness צריך לעשות ארבעה דברים:
- להרכיב הקשר לקריאת המודל הבאה (הוראות, היסטוריה, תוצאות כלים, עובדות על הסביבה).
- לחשוף יכולות שהמודל יכול לבקש להשתמש בהן (כלים, פקודות, תתי-סוכנים, שירותים חיצוניים).
- להריץ ולתווך את הבקשות האלה (dispatch, הרשאות, sandboxing, ניסיונות חוזרים, טיפול בשגיאות).
- לשמור state כדי שהאינטראקציה תישאר עקבית לאורך צעדים, סשנים או ממשקים שונים.
כל השאר - TUI מלוטש, אינטגרציה ל-IDE, תזמור של כמה סוכנים, מערכות plugins - נבנה על היסודות האלה.
לולאת הליבה
רוב ה-harnesses מצטמצמים ללולאת agent: לקרוא למודל, לפרש את הפלט, להריץ פעולות מבוקשות, להזין בחזרה תצפיות ולחזור על התהליך. הפרטים משתנים, אבל דרך שימושית לקרוא כל מימוש היא לשאול תמיד את אותן שאלות:
- מה נחשב לצעד או לתור? בקשת מודל אחת? בקשה אחת ועוד כל קריאות הכלים? האם הלולאה ממשיכה גם אחרי “stop” אם עדיין יש כלים שממתינים?
- איך הלולאה מסתיימת? המודל מחליט, המשתמש מבטל, מגיעים לתקרת צעדים, hook עוצר, או שיש שגיאה שלא מטופלת.
- מה מנוסה שוב אוטומטית? כשלי ספק/רשת, קריאות כלים פגומות, גלישת הקשר, או בכלל לא.
- איפה יושב מנגנון הבקרה? בלולאת
whileפשוטה, במכונת מצבים, או בצינור של effects ואירועים.
הבחירות האלה משפיעות ישירות על ההתנהגות שהמשתמש מרגיש. harness עם ניסיונות חוזרים ו-compaction אגרסיביים עשוי להתאושש מסשנים ארוכים ומבולגנים. harness עם מגבלות צעדים קשיחות ואישורים מפורשים עשוי להרגיש איטי יותר, אבל צפוי יותר. harness שמתייחס לקריאות כלים פגומות כמידע שאפשר להתאושש ממנו נותן למודל הזדמנות נוספת; harness שזורק חריגה עלול להפיל את כל הריצה.
ההקשר הוא המוצר האמיתי
איכות המודל קובעת תקרה, אבל הרכבת ההקשר היא לרוב מה שקובע אם הסוכן באמת מגיע אליה. harness טיפוסי בונה כל בקשה מכמה שכבות:
- הוראות מערכת ומוצר: התנהגות הבסיס, עמדת הבטיחות והכללים הספציפיים לממשק.
- הוראות פרויקט: קבצים כמו
AGENTS.md,CLAUDE.mdאו הנחיות ייעודיות לריפו שמסבירות איך הקוד מתנהג. - היסטוריית שיחה וסשן: הודעות קודמות, קריאות לכלים, תוצאות, סיכומים, ולעיתים גם ענפים או forks.
- תיאורים וסכמות של כלים: אילו פעולות זמינות כרגע, עם אילוצים על פרמטרים שהמודל יכול לכוון אליהם.
- עובדות על הסביבה: תיקיית עבודה, מצב git, קבצים פתוחים, דיאגנוסטיקה, זמן, מודל נבחר ומגבלות ריצה.
harness טוב הוא דעהן לגבי ההרכבה הזו. הוא מחליט מה תמיד נכנס, מה מתגלה לפי צורך ומה נדחס כשהחלון מתמלא. compaction, זיכרון, prompt templates ו-skills הם כולם תשובות לאותה בעיה: המודל צריך את המידע הנכון ברגע הנכון, לא את כל המידע כל הזמן.
כלים הופכים טקסט לעבודה
כלים הם הנקודה שבה harness פוגש את המציאות. גבול הכלי מגדיר מה המשמעות של “לבצע פעולה”: לקרוא קבצים, לערוך קוד, להריץ פקודות shell, לשאול LSP, לקרוא לשרת MCP, לחפש בדוקומנטציה, לפתוח דפדפן או להאציל עבודה לסוכן אחר.
שאלות העיצוב החשובות כאן הן פחות “כמה כלים יש” ויותר “מה החוזה”:
- ממשק: האם הכלים הם פונקציות native, שרתי MCP, plugins, או הכול מאחורי אבסטרקציה אחת?
- בחירה: האם סט הכלים קבוע, או נבנה מחדש לכל סשן/מודל/סוכן?
- ולידציה: האם הארגומנטים מאומתים מול schema, מתוקנים, או מועברים כמו שהם?
- הרצה: האם כלים רצים inline, במקביל, בתהליכים נפרדים, מרחוק או בסביבות מבודדות?
- משוב: האם ה-harness מחזיר פלט גולמי, שגיאות מובנות, קבצי spill לקלט גדול, דיאגנוסטיקה או רמזים להמשך?
כאן גם חיים הרבה מההתנהגויות שנראות “חכמות”. למשל, harness יכול להזין דיאגנוסטיקה של קומפיילר או linter בחזרה לצעד הבא אחרי עריכה, להפוך פלט גדול לקובץ במקום להציף את ההקשר, או לנרמל שמות כלים שהמודל שיבש קלות כדי שהקריאה עדיין תתפוס. אלה לא טריקים של המודל; זו מכניקה של ה-harness.
הרשאות ובטיחות הן חלק מהריצה
סוכן קידוד הוא שימושי במיוחד כשהוא יכול לפעול, ומסוכן במיוחד מאותה סיבה. harnesses מטפלים במתח הזה עם שכבות מדיניות: כללי allow, ask ו-deny, בקשות אישור, גבולות sandbox, סינון משתני סביבה, הגבלות על נתיבים ו-hooks שיכולים לבדוק או לחסום פעולות.
מודל הרשאות פרקטי בדרך כלל עונה על השאלות האלה:
- מה מותר כברירת מחדל? קריאת קבצים, כתיבה, גישה לרשת, הרצת shell.
- מה ההיקף של החלטה? פעם אחת, לסשן הנוכחי, לפרויקט, או תמיד.
- מי יכול לעקוף את מי? בחירת משתמש, הגדרות פרויקט, מצב סוכן, מדיניות ארגונית.
- האם האכיפה מרכזית? שער אחד לפני הרצה קל יותר להבנה מאשר בדיקות מפוזרות.
עיצוב הרשאות אי אפשר להפריד מחוויית שימוש. אם הכול מבקש אישור, אנשים מפסיקים לקרוא. אם שום דבר לא מבקש, אנשים מפסיקים לסמוך. ה-harness צריך להפוך סיכון למשהו קריא.
state, התמדה ותצפיתיות
זוג אחד של prompt ותגובה הוא פשוט; עבודה ארוכת טווח היא המקום שבו harness באמת מוכיח את עצמו. סשנים צריכים לפעמים לשרוד הפעלה מחדש, לתמוך ב-undo/redo, להתפצל או להתפצל לענפים, להזרים התקדמות למספר ממשקים, או להעביר עבודה לתת-סוכנים.
דפוסי התמדה נפוצים כוללים:
- מצב שיחה בזיכרון להרצות קצרות.
- קבצי סשן או מסדי נתונים להיסטוריה שאפשר להמשיך.
- יומני אירועים append-only שמאפשרים replay, ביקורת ו-projection.
- snapshots וסיכומים ל-compaction, checkpoints או התאוששות.
תצפיתיות נובעת מאותו עיצוב. אם harness מתעד אירועים מובנים (הודעות, קריאות לכלים, תוצאות, הרשאות, ניסיונות חוזרים, compaction), הרבה יותר קל לנפות תקלות, לרנדר ממשקי live ולבנות אוטומציה ברמה גבוהה יותר מעליו.
הרחבה: איפה harnesses באמת נבדלים
ההבדלים הגדולים בין harnesses לרוב מתגלים במודל ההרחבה שלהם:
- Configuration-first: משתמשים מתאימים prompts, כללים, ספקים ושרתי כלים.
- APIs של plugins/extensions: משתמשים מוסיפים התנהגות בקוד (hooks, פקודות, UI, כלים מותאמים).
- Protocol-first: יכולות מגיעות דרך פרוטוקול סטנדרטי כמו MCP, והסוכן מתנהג בעיקר כלקוח.
- Composition-first: כל האפליקציה מורכבת מחלקים או bundles שאפשר להחליף.
אין כאן בחירה אחת נכונה תמיד. ליבה מינימלית יכולה להיות קלה יותר להבנה ולכיוונון. מערכת שמרוכזת סביב פרוטוקול יכולה להיות ניתנת יותר לחיבור. runtime מובנה לעומק יכול לאכוף invariants חזקים יותר. כל גישה מחליפה פשטות, כוח וניידות ביחס אחר.
עקרונות שגורמים ל-harness לעבוד
על פני מימושים שונים, כמה עקרונות חוזרים שוב ושוב:
- לסגור את לולאת המשוב: תוצאות כלים, פלט של טסטים ודיאגנוסטיקה צריכים לחזור מהר להחלטה הבאה.
- להשאיר פעולות קריאות: המערכת צריכה להבהיר מה הסוכן עשה, מה הוא רוצה לעשות עכשיו ולמה.
- לתחום אוטונומיה: timeouts, מגבלות צעדים, אישורים והרשאות בהיקף נכון מגבילים נזק כשמשהו משתבש.
- להעדיף שגיאות שאפשר להתאושש מהן: כשאפשר, עדיף להפוך כשל למידע שהלולאה יכולה להשתמש בו במקום לקריסה קשה.
- להתייחס להקשר כתקציב: בוחרים, מסכמים ומבנים מידע בכוונה.
- להפריד אחריויות: כשחשיבה של מודל, הרצת כלים, התמדה וממשק לא מעורבבים, קל יותר לפתח כל חלק בנפרד.
מה מחכה בהמשך הסדרה
עם האנטומיה הזו בראש, הפוסטים הבאים יפרקו כל harness דרך אותה עדשה:
- Goose: harness מבוסס MCP ומונחה הרחבות, עם מודל אישורים חזק ולולאת agent שנמצאת בתהליך מעבר למכונת מצבים מבוססת effects.
- Pi: harness מינימלי וגמיש במיוחד, שמתייחס למשטחי התאמה אישית (extensions, skills, packages, RPC/SDK) כחלק מרכזי בעיצוב.
- OpenCode: סוכן קידוד עם dual runtime, התמדה של סשנים, בחירת כלים מותאמת מודל ומשוב LSP משולב בלולאת העריכה.
- DeepSeek Harness: מערכת של “הכול plugin” שנבנתה על Cordis, שבה קומפוזיציה, אירועי סשן עמידים ו-capability seams מגדירים את הארכיטקטורה.
המטרה היא לא להכתיר מנצח. המטרה היא להפוך את מרחב העיצוב לגלוי: ברגע שאפשר לתת שמות לחלקים, הרבה יותר קל להעריך כלי agents, לנפות אותם ולבחור את ה-tradeoffs שמתאימים לאופן העבודה שלכם.
מקורות
- הריפו של Goose ו-מסמכי הארכיטקטורה של Goose
- הריפו של Pi, How Pi Works ו-הדוקומנטציה של Pi
- הריפו של OpenCode, הדוקומנטציה של OpenCode ו-Agent Harness Anatomy: OpenCode
- הריפו של DeepSeek Harness ו-מסמכי הארכיטקטורה
סדרה שבועית
אפשר לקרוא את הפוסטים לפי הסדר:
- הוספתי בלוג לאתר האישי (בלי לבנות הכול מחדש) - 2026-11-11
- למה PostHog הוא אחד הכלים הראשונים שאני מוסיף למוצר חדש - 2026-11-18
- האנטומיה של coding harness: מה באמת מפעיל סוכני קידוד (הפוסט הזה) - 2026-11-11
- ניהול context ב-coding harnesses: מה באמת נשלח למודל ולמה זה חשוב - 2026-11-18
- Goose מבפנים: harness מבוסס MCP עם פרוטוקול במרכז - 2026-11-11
- Pi מבפנים: harness מינימלי שנבנה סביב עץ סשנים ופרימיטיבים - 2026-11-18
- OpenCode מבפנים: לולאה אחת, מודלים רבים, ומשוב אמיתי מהסביבה - 2026-11-11
- DeepSeek Harness מבפנים: הכול plugin, והלוג הוא החוזה - 2026-11-18
הקודם: למה PostHog הוא אחד הכלים הראשונים שאני מוסיף למוצר חדש הבא: ניהול context ב-coding harnesses: מה באמת נשלח למודל ולמה זה חשוב