WISHGOODS

למפתחים שבונים עם סוכני קוד · zoe-coding-skills by WISHGOODS

כך מוצר נבנה בידי סוכני קוד — בלי להיסחף

ריפו שנבנה בידי סוכנים, לאורך הרבה סשנים, מתפרק בדרך צפויה. zoe-coding-skills הוא שלושה דברים שמתקינים בריפו: סקיל שמכוון סוכן בקריאה אחת ומסרב למערכת שנייה, guard שהופך כלל לכשל build, ואינדקס שהסוכן יכול לשאול. קבצים, hook ו־CI — לא שרת, לא חשבון, לא מפתח.

  • אפס תלויות ב־guard
  • עובד עם כל סוכן קוד
  • שום דבר לא יוצא מהמכונה
  • Apache-2.0
  • Node 22+

למה ריפו של סוכנים מתפרק

לא בגלל הוראות גרועות. הוראות הן החומר הקטן ביותר. זה קורה כי אין מי שזוכר, ואין מה שאוכף.

עותק שני של תת־מערכת

הראשון לא היה ניתן למציאה, אז סוכן בנה אותו שוב. עכשיו יש שניים, ושניהם חצי נכונים.

תיעוד שמתאר את החודש שעבר

הקוד השתנה, המסמך לא. הסשן הבא קורא "בוצע: שלבים 1–2" ויוצא לדרך הלא נכונה.

שכבה "בצל" שאף אחד לא קורא

דגל שרץ וכותב ושותק, שבועות. בלי תאריך קריאה, צל הוא דליפה.

טסט בהסגר שהאריך ימים מהסיבה

הטסט הושתק כדי להיות ירוק. הסיבה נשכחה. ההסגר רק גדל.

ממה זה מורכב

שלושה דברים מותקנים אצלכם ונשארים שלכם. הרביעי הוא שירות מארח, והוא לעולם לא נשלח.

skills/zoe-codingמותקן אצלכם

הסקיל

פרוטוקול סשן בשמונה צעדים: להתמצא, למצוא עוגן קונקרטי, לבדוק את המפה לפני שבונים, היפותזה אחת שאפשר להפריך, העריכה הקטנה ביותר, הבדיקה הצרה ביותר, תיעוד באותו שינוי, commit עם הסיבה. פלוס חוקים קשיחים, ז׳אנרים של מסמכים עם בעלים אחד לכל עובדה, ושתים־עשרה תבניות. עשר שיטות בדוקות בלבד, כל אחת עם המקור שלה.

@zoe-coding-skills/guardמותקן אצלכם

ה־guard

אחד־עשר כללי מדיניות שרצים ב־pre-commit וב־CI. כל כלל נולד מתקרית ונושא אותה: zoe-guard list מדפיס לכל כלל את ה־why. הוא קורא את אינדקס git ואת הקבצים שנאמר לו, ומדפיס. לא מריץ תוכן מהריפו, לא נוגע ברשת, לא כותב אלא כשמבקשים. אפס תלויות.

@zoe-coding-skills/mcpמותקן אצלכם

האינדקס

שרת MCP על stdio שעונה על שש שאלות: מה לקרוא למשימה הזאת, מי הבעלים של קובץ, איזה מסמך לעדכן, אילו צללים פתוחים, מה מצב ה־guard, ורישום הכרעה אחת. הוא מספק חומר, לעולם לא מסקנה — כל תשובה אומרת "קראו את המסמך הבעלים".

stewardמארח, לא נשלח

השיפוט

מה לקדם, מה למחוק, מתי להזכיר ומתי לשתוק, הביקורת שסומכת על המימוש ולא על המסמכים, הכיול שמצטבר בין ריפואים. זה מה שהמייסד עושה היום ביד. הוא יהיה שירות מארח שמקבל מבנה בלבד — מפת בעלות, מצבי checkpoint, תאריכי צל, הכרעות, דוחות guard — ולעולם לא קוד. הגבול נאכף ב־guard: ייבוא מ־steward/ מפיל build.

התקנה בחמישה שלבים

הכל קבצים בריפו שלכם. ביום ההתקנה ה־guard עובר; מאמצים כלל אחד בכל פעם. כלל שלא הוגדר מדווח SKIP, לעולם לא כשל.

1. מתקינים את שתי החבילות

ה־guard וה־MCP הם חבילות npm רגילות, devDependencies. הן דורשות Node 22 ומעלה ולא מוסיפות תלויות לפרויקט.

shell
npm install --save-dev @zoe-coding-skills/guard @zoe-coding-skills/mcp

עדיין לא ב־npm — ראו "איפה זה עומד". בגישה מוקדמת מתקינים מהריפו עם npm link, ואותן פקודות בדיוק עובדות.

2. מאתחלים את ה־guard

init כותב את guard.config.json, הסגר ריק, רשימת dials ריקה, ובייסליין לכל glob — מה שקיים בעץ היום. הוא לעולם לא דורס קובץ קיים. אחר כך עורכים את ה־globs לפי הריפו: תיקיית השירותים, המודלים, מסמכי התוכניות.

shell
npx zoe-guard init          # guard.config.json, empty quarantine and dials, baselines from today's tree
npx zoe-guard               # passes on the day of adoption; unconfigured rules report SKIP
npx zoe-guard list          # every rule, with the incident behind it

3. מוסיפים את הסקיל ואת התבניות

הסקיל והתבניות חיים בריפו, לא בחבילת npm: משכפלים אותו פעם אחת (אותו checkout שמשמש ל־npm link בגישה מוקדמת), מעתיקים את הסקיל לתיקיית הסקילים של הסוכן, ומתחילים מתבנית CLAUDE.md: סדר קריאה, פקודות אימות שבאמת קיימות, חוקים קשיחים, ואיזה מסמך מתעדכן על איזה שינוי. כותבים arc/code-architecture.md מהרשימה שה־guard מדפיס כלא־מתועדת, ומריצים עד שהוא עובר. רושמים את האימוץ כ־ADR הראשון.

shell
git clone https://github.com/wishgoods/zoe-coding-skills ../zoe-coding-skills
mkdir -p .claude/skills
cp -r ../zoe-coding-skills/skills/zoe-coding .claude/skills/zoe-coding
cp .claude/skills/zoe-coding/templates/CLAUDE.md ./CLAUDE.md   # then fill the read order and the validation commands

הסקיל הוא Markdown בתבנית של Claude Code. סוכן אחר קורא את אותו קובץ; רק המיקום משתנה.

4. מחברים hook ו־CI

ה־hook הוא מה שהמפתח רואה; ה־CI הוא מה שאף אחד לא יכול לדלג עליו. ה־guard רץ ראשון ב־CI ובלי תלויות, ואחריו typecheck, build וטסטים — לפי תבנית ה־CI שהגיעה עם הסקיל בשלב הקודם.

shell
npx zoe-guard install-hook  # pre-commit runs `zoe-guard --staged`
mkdir -p .github/workflows
cp .claude/skills/zoe-coding/templates/ci.yml .github/workflows/guard.yml

האכיפה לעולם לא תלויה בסוכן. כלי MCP הוא נוחות שהסוכן רשאי לדלג עליה; hook — לא.

5. מחברים את האינדקס לסוכן

שורה אחת בקובץ ה־MCP של הסוכן. ב־Claude Code זה .mcp.json בשורש הפרויקט; בכל לקוח MCP אחר — אותה פקודת stdio. השרת קורא את הריפו ועונה; הוא לא מאזין ברשת ואין לו אימות, כי הוא שייך למכונה של המפתח, צמוד לריפו אחד.

.mcp.json
{
  "mcpServers": {
    "zoe-coding": { "command": "npx", "args": ["zoe-coding-mcp", "--root", "."] }
  }
}

מה עוד צריך לחבר, חוץ מהספרייה

ארבעה חיבורים, כולם בתוך הריפו והמכונה שלכם. ואז — כלום.

git hook

pre-commit שמריץ zoe-guard --staged. install-hook כותב אותו; מפתח שמעדיף husky או lefthook מוסיף את אותה שורה שם.

CI

job אחד של GitHub Actions מהתבנית: guard על כל קובץ עוקב, ועל השינוי מול ענף הבסיס ב־pull request.

שרת MCP בסוכן

רשומת stdio אחת בקונפיגורציית ה־MCP של הסוכן. Claude Code, Cursor, או כל לקוח MCP אחר — אותה פקודה.

הסקיל בתיקיית הסקילים

תיקייה אחת של Markdown ותבניות. ב־Claude Code: .claude/skills/zoe-coding. כשהפלאגין ייצא מצל — התקנה אחת מהמרקטפלייס במקום ההעתקה.

אין חשבון, אין API key, אין שרת שלנו, אין רשת. שום דבר לא יוצא מהמכונה. הדבר היחיד שיהיה מארח הוא ה־steward — והוא עדיין לא קיים.

אחד־עשר הכללים

ארבעה עובדים בלי שום הגדרה. השאר מחכים ל־globs שלכם ב־guard.config.json, ועד אז מדווחים SKIP.

  • no-tracked-envקובץ .env שאינו דוגמה עוקב ב־git.
  • no-tracked-credentialsמפתחות, קבצי service-account, או .npmrc עם טוקן — עוקבים.
  • no-tracked-build-outputdist/, build/, node_modules/, coverage ודומיהם — עוקבים.
  • no-tracked-email-listקובץ עוקב שרובו כתובות אימייל.
  • ownership-map-completeקובץ שמתאים ל־glob של תת־מערכת ואף מסמך לא מזכיר אותו.
  • baseline-is-a-line-in-timeקובץ בייסליין (למשל מודל) שאינו ברשימה ואינו מוזכר במסמך.
  • plan-names-its-predecessorמסמך תוכנית חדש שאינו מפנה לשום מסמך אחר.
  • quarantine-only-shrinksההסגר עבר את התקרה, או שרשומה חסרה סיבה ותאריך.
  • shadow-has-a-read-dateדגל בצל בלי בעלים, בלי מסמך, בלי תאריך קריאה — או שהתאריך עבר.
  • docs-in-same-changeשינוי staged או PR נוגע בתת־מערכת ולא באף מסמך.
  • import-boundaryקובץ בתוך גבול מייבא משהו שאסור לו.

שש השאלות שהאינדקס עונה עליהן

קריאה בלבד, חוץ מכתיבת ADR אחת שהיא create-only. חפיפת מילים והשוואת תאריכים הן התקרה; שום דירוג, שום המלצה.

  • orient(task)סדר הקריאה מ־CLAUDE.md, תת־מערכות ומסמכים שחולקים מילה עם המשימה, שורות checkpoint פתוחות, צללים שעבר תאריכם, ההכרעות האחרונות.
  • owner_of(name)כל שורת תיעוד שמזכירה קובץ, שירות או מודל.
  • docs_to_update(files)לכל קובץ ששונה: תת־המערכת שלו והמסמכים שמזכירים אותו. לא־מתועד נאמר במפורש.
  • open_shadows()כל dial בצל, עם בעלים, מסמך, תאריך קריאה ודגל איחור.
  • record_decision(…)ADR חדש אחד תחת arc/decisions/, ההכרעה כלשונה, לעולם לא דורס.
  • guard_status(mode)דוח ה־guard, עם התקרית מאחורי כל כלל שנכשל.

מה נבנה כדי שאפשר יהיה לסמוך על זה

כלי שרץ בכל commit ובכל סשן של סוכן צריך להיות משעמם. אלה הגבולות, בקוד ולא בהבטחה.

ה־guard טיפש בכוונה

קורא קבצים, מריץ אחד־עשר בדיקות טהורות, מדפיס. לא מריץ תוכן מהריפו, לא נוגע ברשת, לא כותב אלא ב־init וב־install-hook. אפס תלויות — אין מה לתקוף בשרשרת האספקה.

stdio בלבד

לשרת ה־MCP אין transport של HTTP ולא יהיה. אין אימות כי אין רשת; הוא שייך למכונה של המפתח, צמוד לריפו אחד.

נתיבים כלואים לשורש

השורש נפתר דרך symlinks פעם אחת בהפעלה; כל נתיב שהשרת נוגע בו נפתר מולו ונדחה אם יצא החוצה — ב־.. או ב־symlink בתוך העץ.

כתיבה אחת

record_decision יוצר קובץ ADR חדש בשם מסונן, ב־create-only. אין עדכון ואין מחיקה. תהליך חיצוני יחיד: git ls-files.

קלט חסום

טקסט משימה עד 2,000 תווים, שדות הכרעה עד 20,000, עד 200 קבצים לקריאה אחת.

הסוד לא בריפו, ולא במסמך

ארבעה כללים נעולים תופסים את הצורות הברורות: .env, מפתחות, פלט build, רשימות אימייל. הסקיל אוסר על השאר — שום מזהה אמיתי, שם או כתובת במסמך כדי שדוגמה תהיה קונקרטית.

איפה זה עומד — בכנות

המוצר בנוי ונבדק בריפו זר. מה שעדיין לא נכון כתוב כאן, כי תגלו את זה ביום הראשון בכל מקרה.

  • עובד: ה־guard — אחד־עשר כללים, תשעה־עשר טסטים על ריפואים זמניים אמיתיים, init שמעביר את הריפו ביום האימוץ.
  • עובד: האינדקס — שישה כלים, שבעה טסטים כולל סיבוב מלא של לקוח MCP על stdio.
  • עובד: הסקיל, שתים־עשרה תבניות, עשר שיטות בדוקות עם המקור של כל אחת.
  • עובד: מבחן קבלה שמתקין את החבילות בריפו שמעולם לא שמע על Zoe ומוכיח שהן רצות שם בלי שום דבר מהמקור.
  • עדיין לא: פרסום ל־npm. שתי החבילות מוכנות (publishConfig, CHANGELOG, SECURITY, ‏npm pack נבדק) והפרסום עצמו ממתין.
  • עדיין לא: התקנת הפלאגין ממרקטפלייס. המניפסט כתוב ובצל עד התקנה אמיתית אחת.
  • עדיין לא: המספר. כמה זמן לוקח לסוכן חדש להגיע לשינוי נכון ראשון בריפו זר, עם הסקיל ובלעדיו. הפרוטוקול כתוב; בלי המספר הזה אין פרסום פומבי.
  • עדיין לא: ה־steward. הוא נבנה אחרי המספר, בריפו אחר, ומקבל מבנה בלבד.
  • גישה מוקדמת: הריפו פרטי היום. רוצים לנסות על ריפו שלכם? דברו איתנו ותקבלו גישה.

שאלות

זה עובד רק עם Claude Code?

לא. הקבצים, ה־hook וה־CI לא יודעים איזה סוכן כותב את הקוד. שרת ה־MCP עובד עם כל לקוח MCP. הסקיל הוא Markdown בתבנית של Claude Code — סוכן אחר קורא את אותו קובץ ממקום אחר.

משהו מהקוד שלי יוצא החוצה?

לא. שום דבר לא נוגע ברשת: ה־guard קורא ומדפיס, ה־MCP מדבר על stdio עם הסוכן על המכונה שלכם. כשה־steward יגיע, הוא יקבל מבנה בלבד — שמות, מצבים, תאריכים — ולעולם לא מקור, diff או תוכן קובץ. הרשימה המדויקת היא מסמך בריפו.

זה ישבור לי את ה־build ביום הראשון?

לא. init מייצר בייסליין ממה שקיים בעץ היום, וכלל שלא הוגדר מדווח SKIP. ה־guard מתחיל לנשוך רק כשאתם עורכים את ה־globs — כלל אחד בכל פעם.

אפשר לכתוב כללים משלי?

הכללים מוגדרים, לא נכתבים: כל אחד מקבל את ה־globs והרשימות שלכם ב־guard.config.json. כלל חדש נכנס רק עם התקרית שמאחוריו — כלל בלי תקרית הוא דעה. אם נתקלתם במשהו שאין לו כלל, זה בדיוק מה שאנחנו רוצים לשמוע.

זה מוגבל ל־TypeScript?

ה־guard עובד על globs של קבצים ועל מסמכי Markdown — השפה לא משנה לו. שתי החבילות עצמן דורשות Node 22 להרצה, ותבנית ה־CI מניחה npm; מחליפים את השלב הזה בכלי שלכם.

מה עולה?

החבילות והסקיל הם Apache-2.0: מותקנים אצלכם, שלכם. ה־steward יהיה החלק המשולם, והמחיר שלו עוד לא נקבע — הוא נבנה אחרי שיש מספר.

מה הקשר לזואי?

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

למה לתת את הכלים חינם?

כי מה שמותקן אצל המפתח ניתן לקריאה ולהעתקה בכל מקרה. מה שלא ניתן להעתקה הוא השיפוט שמצטבר בין ריפואים — וזה נשאר מארח. ההגנה היא להיות ראשונים עם מה שמצטבר, לא נעילה.

רוצים לנסות על ריפו שלכם?

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