📘 תיעוד 52

הגדרת Claude Code במונוריפו או בבסיס קוד גדול

הגדר את Claude Code עבור מונוריפואים ובסיסי קוד גדולים בעלי עץ יחיד עם קובצי CLAUDE.md מקוננים, עצי עבודה דלילים (sparse worktrees), אינטליגנציית קוד (code intelligence) וכישורים (skills) לכל חבילה, כך ש-Claude יישאר ממוקד בקוד שבו אתה עובד.

בסיס קוד גדול יכול להיות מאגר יחיד עם מיליוני שורות או מונוריפו עם חבילות רבות. Claude Code עובד בכל גודל, אך ככל שבסיס הקוד גדל, הגדרות ברירת המחדל המותאמות לפרויקטים קטנים יותר עלולות למלא את חלון ההקשר בהוראות ובקריאות קבצים שאינן קשורות למשימה, מה שמבזבז אסימונים (tokens) ופוגע בביצועים של Claude.

מדריך זה מראה למפתחים בודדים ולצוותי הנדסה כיצד לתחום את Claude לחלק של בסיס הקוד שבו המשימה נוגעת. כל סעיף מציין האם הגדרה מסוימת היא אישית למחשב שלך או נשמרת במאגר (committed).

#מה המדריך הזה מכסה

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

#הגדרות בדף זה

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

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

#המונוריפו לדוגמה

הדוגמאות לכל אורך דף זה מתייחסות למונוריפו עם שלוש חבילות. אותם דפוסים פועלים בבסיס קוד גדול בעל עץ יחיד: כאשר דוגמה משתמשת ב-packages/api/, החלף אותה בתיקיית תת-המערכת שלך, כגון src/backend/ או lib/core/.

monorepo/
  CLAUDE.md                     
# root instructions
  packages/
    api/
      CLAUDE.md                 
# API-specific instructions
      .claude/skills/
      src/
    web/
      CLAUDE.md                 
# frontend-specific instructions
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 
# shared library instructions
      src/

#בחירת המקום שממנו מפעילים את Claude

המקום שממנו אתה מפעיל את claude קובע באילו קבצים Claude יכול לקרוא ולערוך ללא מתן הרשאה נוספת, אילו קובצי CLAUDE.md נטענים להקשר בעת ההפעלה, ואילו הגדרות פרויקט חלות.

הגדרות פרויקט ב-.claude/settings.json אינן עוברות בירושה מתיקיות אב כפי שקובצי CLAUDE.md עוברים. לגבי השאלה איזה קובץ .claude/settings.json של איזו תיקייה הפעלה מסוימת קוראת, ראה היכן Claude Code מחפש כל קובץ.

כל סעיף למטה מציין האם קובץ ההגדרות שלו שייך לשורש המאגר או לתת-התיקייה שממנה אתה מתחיל, והאם הוא נשמר במאגר (committed) או נשמר מקומית.

#פריסת קובצי CLAUDE.md בשכבות לפי תיקייה

בבסיס קוד גדול, קובץ CLAUDE.md יחיד בשורש המאגר נוטה לגדול כדי לכסות את המוסכמות של כל תת-מערכת, מה שעולה בהקשר על הוראות שאינן קשורות למשימה הנוכחית, או להישאר כללי מדי מכדי להיות שימושי. פיצול הוראות בין קבצים לפי תיקייה גורם לכך ש-Claude טוען כללים כלל-מאגריים ובנוסף רק את המוסכמות עבור הקוד שבו אתה עובד.

Claude Code טוען בהפעלה כל קובץ CLAUDE.md מתיקיית העבודה שלך ומכל תיקיית אב, ולאחר מכן טוען את הקובץ של כל תת-תיקייה לפי דרישה כאשר הוא קורא קבצים שם. קובץ שורש קובע כללים כלל-מאגריים וכל תת-תיקייה מוסיפה את הכללים שלה.

פיצול נפוץ הוא לשתי רמות:

• קובץ CLAUDE.md שורשי: הוראות שחלות בכל מקום, כגון תקני קידוד ומוסכמות commit.
• קובץ CLAUDE.md לכל תת-תיקייה: מוסכמות ספציפיות למחסנית הטכנולוגית של אותו אזור. במונוריפו זהו קובץ אחד לכל חבילה. בעץ יחיד גדול זהו קובץ אחד לכל תת-מערכת כגון src/db/ או src/api/.

שמור קבצים אלה במאגר כדי שחברי הצוות יירשו אותם. הבעלים של כל תיקייה מתחזק בדרך כלל את הקובץ שלה.

כדי לצמצם קובץ שכבר נשמר במאגר, הרץ את בדיקת /doctor. קובץ ה-CLAUDE.md השורשי מחזיק את הכללים שחלים בכל חבילה:

Run package scripts from the package directory, not the monorepo root.
Prefix commit subjects with the package name, for example `api: add rate limiting`.
Never edit files under packages/*/generated/. Run `npm run codegen` in the package instead.

קובץ ה-CLAUDE.md של כל תת-תיקייה, כאן packages/api/CLAUDE.md, מוסיף את המוסכמות הספציפיות לאותו אזור:

Copy `.env.example` to `.env` before running anything. Tests and the dev server fail without it.
Write database queries with the Knex query builder. Never put raw SQL strings in route handlers.
Never edit a migration after it has merged. Add a new migration instead.

כאשר אתה מפעיל את Claude מ-packages/api/, הוא טוען הן את packages/api/CLAUDE.md והן את CLAUDE.md השורשי. Claude רואה את ההוראות המקומיות לצד הכללים הכלל-מאגריים, בלי שאף הוראה מ-packages/web/ תהיה בהקשר. אותו הדבר נכון עבור כל תת-תיקייה בעץ שאינו מונוריפו. כדי לאשר אילו קבצים נטענו, הרץ /context ובדוק את הרשימה תחת Memory files.

מספר דרכים לשמור על הקבצים מעודכנים ככל שבסיס הקוד והמודלים משתנים:

• סקירה ב-pull requests: התייחס לעריכות CLAUDE.md כמו לכל שינוי תיעוד אחר, כך שהמוסכמות יעקבו אחר הקוד.
• בחינה מחדש לאחר גרסאות מודל עיקריות: הוראות שעקפו מגבלה של מודל ישן יותר עשויות להפוך לתקורה מיותרת ברגע שמודל חדש יותר מטפל במקרה בעצמו. לדוגמה, כלל שמחייב שינויי קוד (refactors) בקובץ בודד בלבד ניתן למחיקה ברגע שהמגבלה נעלמה.
• הוספת hook מסוג Stop שמציע עדכונים: hook מסוג Stop מקבל את הנתיב לתמליל ההפעלה כאשר Claude מסיים להגיב, כך שסקריפט יכול לסקור את ההפעלה ולהציע עדכוני CLAUDE.md בעוד הפער שהיא חשפה עדיין טרי.

למידע נוסף על האופן שבו קובצי CLAUDE.md נטענים ומקיימים אינטראקציה, ראה זיכרון והוראות פרויקט.

#בחירה בין CLAUDE.md לפי תיקייה לבין כללים תחומים לפי נתיב

קובצי CLAUDE.md לפי תיקייה וכללים תחומים לפי נתיב תחת .claude/rules/ מאפשרים שניהם לכוון הוראות לחלק מהעץ. הם נבדלים במקום שבו הקובץ נמצא ומתי הוא נטען.

להשוואה שמכסה גם כישורים (skills), ראה השוואת תכונות דומות.

#החרגת קובצי CLAUDE.md שאינם רלוונטיים

כאשר אתה מפעיל את Claude משורש המאגר, ה-CLAUDE.md של כל תת-תיקייה נטען ברגע ש-Claude קורא קובץ באותה תיקייה. ההגדרה claudeMdExcludes מדלגת על קבצים ספציפיים לפי נתיב או תבנית glob כך שהם לעולם אינם נטענים.

השתמש בזה עבור תיקיות שבהן אינך עובד לעולם, כגון חבילות של צוותים אחרים, קוד ישן (legacy), או עצי משנה חיצוניים (vendored). רשימת ההחרגה היא סטטית, ולא מתג לכל משימה. כדי להתמקד בחבילה אחת היום ובאחרת מחר, הפעל את Claude מתיקיית אותה חבילה במקום לערוך החרגות.

אם אתה רוצה החרגות אלה רק עבור עצמך, שים את ההגדרה ב-.claude/settings.local.json. Claude Code מוסיף קובץ זה ל-gitignore הגלובלי שלך כאשר הוא שומר הגדרה שם. מכיוון שאתה יוצר אותו ידנית כאן, הוסף אותו ל-gitignore שלך בעצמך. תבניות משתמשות בתחביר glob המושווה מול נתיבי קבצים מוחלטים, לכן התחל תבניות בסגנון יחסי עם **/ כדי להתאים לכל מקום בעץ. הדוגמה למטה מחריגה חבילה שבבעלות צוות אחר:

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

פעולה זו מדלגת על כל CLAUDE.md וקובץ כללים תחת אותה חבילה. קובץ ה-CLAUDE.md השורשי והחבילות שבהן אתה כן עובד עדיין נטענים כרגיל.

תבניות אלה מכסות מקרים נפוצים נוספים:

• "**/packages/*/CLAUDE.md": מחריג את ה-CLAUDE.md של כל חבילה תוך שמירה על קובץ השורש
• "**/packages/legacy-*/**": מחריג כל חבילה ששמה תואם ל-glob, כולל כללים
• "/home/user/monorepo/legacy/CLAUDE.md": מחריג קובץ ספציפי אחד לפי נתיב מוחלט

לא ניתן להחריג קובצי מדיניות מנוהלים של CLAUDE.md, כך שהוראות כלל-ארגוניות חלות תמיד. ניתן להגדיר את claudeMdExcludes בכל טווח הגדרות: משתמש (user), פרויקט (project), מקומי (local) או מנוהל (managed). מערכים מתמזגים בין טווחים שונים, כך שצוות יכול להגדיר ברירות מחדל ברמת הפרויקט בעוד שאנשים בודדים מוסיפים דריסות מקומיות.

לתיעוד ההחרגה המלא, ראה החרגת קובצי CLAUDE.md ספציפיים.

#צמצום מה ש-Claude קורא

הוראות הן רק חלק ממה שמגיע להקשר של Claude. קריאות קבצים הן עלות נוספת שגדלה יחד עם בסיס הקוד. ההגדרות למטה חוסמות קריאות של נתיבים שאינם רלוונטיים ומחליפות סריקות קבצים מקיפות בחיפושים באמצעות שרת שפה (language server).

#חסימת קריאות של קוד שנוצר אוטומטית וקוד חיצוני

חיפושי התוכן של Claude מכבדים את .gitignore כברירת מחדל, כך שנתיבים שכבר רשומים שם, כגון node_modules/, dist/ ו-build/, נשארים מחוץ לתוצאות החיפוש ללא הגדרה נוספת.

עבור נתיבים שנשמרים במאגר, כגון ערכת SDK חיצונית (vendored) או קוד שנוצר אוטומטית ושמור במאגר, הוסף כללי דחיית Read ב-permissions.deny כדי לחסום את Claude מפתיחת קבצים אלה.

כללי הדחייה יכולים לכסות את כל מי שעובד במאגר, רק אותך, או כל הפעלה במחשב, בהתאם לקובץ ההגדרות שבו אתה שם אותם:

• כל מי שעובד במאגר: שמור את הכללים ב-.claude/settings.json, בשורש המאגר אם אתה מפעיל את Claude משם, או ב-.claude/ של כל חבילה אם אתה מתחיל מתת-תיקיות. בדומה להגדרות פרויקט אחרות בדף זה, קובץ זה אינו עובר בירושה מתיקיות אב.
• רק אתה בעצמך: השתמש ב-.claude/settings.local.json בשורש המאגר, אשר נטען בכל הפעלת CLI בתוך המאגר ללא קשר לתיקיית ההתחלה, למעט במקרים שבהם Claude Code אינו משתמש בשורש המאגר, כגון ב-Windows. תבניות יחסיות כמו Read(./vendor/**) שבדוגמה עדיין מעוגנות בתיקיית העבודה הנוכחית של ההפעלה ולא בשורש המאגר, לכן אם אתה מתחיל הפעלות מתת-תיקיות, כתוב את הכללים בקובץ זה כנתיבים מוחלטים עם //, כגון Read(//absolute/path/to/repo/vendor/**). לפני גרסה v2.1.211, הקובץ .claude/settings.local.json נטען גם הוא רק מתיקיית ההתחלה.
• כולם, נאכף בכל הפעלה: הגדר את הכללים בהגדרות מנוהלות, שהגדרות משתמש ופרויקט אינן יכולות לדרוס.

הדוגמה למטה חוסמת תוצרי בנייה וערכת SDK חיצונית:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)",
      "Read(./**/*.generated.*)",
      "Read(./vendor/**)"
    ]
  }
}

כללי דחייה מכסים את כלי הקבצים המובנים של Claude. ב-Bash, הם מכסים את פקודות הקבצים ש-Claude Code מזהה, כגון cat, head, grep ו-find, כאשר נתיב שנדחה מופיע כארגומנט, ואת היעד של הפניה מחדש (redirection) כגון < file. בנוסף, Claude Code מבצע ניסיון מיטבי להשאיר נתיבים שנדחו מחוץ לתוצאות של כלי ה-Grep וה-Glob המובנים. חיפוש Bash כגון grep -r או find על תיקייה שמכילה קבצים שנדחו עדיין יכלול אותם בפלט שלו.

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

#צמצום קריאות קבצים באמצעות אינטליגנציית קוד

בבסיס קוד גדול, מציאת המקום שבו סמל מוגדר או נמצא בשימוש יכולה לעלות בקריאות קבצים רבות ובקריאות grep. תוספי אינטליגנציית קוד מחברים את Claude לשרת שפה כדי שהוא יוכל לקפוץ להגדרות, למצוא הפניות ולהציף שגיאות טיפוסים ישירות במקום לסרוק את העץ.

ה-marketplace הרשמי כולל תוספים עבור TypeScript, Python, Go, Rust ושפות נפוצות אחרות. הרץ את הפקודה למטה בתוך הפעלת Claude Code כדי להתקין את התוסף של TypeScript:

/plugin install typescript-lsp@claude-plugins-official

אם ההתקנה נכשלת, התאם את הפעולה לפי ההודעה ש-Claude Code מדווח:

• Marketplace "claude-plugins-official" not found: הוסף את ה-marketplace באמצעות /plugin marketplace add anthropics/claude-plugins-official, ולאחר מכן נסה שוב את ההתקנה.
• התוסף לא נמצא ב-marketplace: בדוק את שם התוסף.

כדי להפעיל תוסף עבור כולם במאגר במקום להתקין אותו בעצמך, הוסף אותו להגדרת הפרויקט enabledPlugins.

תוספי אינטליגנציית קוד דורשים את הקובץ הבינארי של שרת השפה עבור אותה שפה במחשב של כל מפתח. ראה איזה קובץ בינארי כל שפה דורשת. התקנה מה-marketplace הרשמי דורשת גישת רשת אל GitHub, שבו ה-marketplace מתארח. ברשת מוגבלת, הוסף את ה-marketplace ממארח Git פנימי או מנתיב מקומי במקום זאת.

זה משתלב היטב עם claudeMdExcludes ועם כללי דחיית Read שלמעלה. אלה שומרים על תוכן שאינו רלוונטי מחוץ להקשר, ואינטליגנציית קוד מונעת מ-Claude לקרוא את מה שנותר כדי לאתר הגדרה.

#תחימת עצי עבודה (worktrees) וגישה לקבצים

הגדרות אלה שולטות במה שנמצא על הדיסק בעצי עבודה ובאילו תיקיות Claude יכול לקרוא ולכתוב מעבר לנקודת ההתחלה שלך.

#ביצוע checkout רק לתיקיות שאתה צריך

הדגל --worktree מתחיל הפעלה בעץ עבודה חדש של git, כך ששינויים נשארים מבודדים מעותק העבודה הראשי שלך. כברירת מחדל הוא מבצע checkout למאגר כולו. במאגר גדול, ההגדרה worktree.sparsePaths משתמשת ב-git sparse-checkout כדי לכתוב לדיסק רק את התיקיות המפורטות בתוספת קבצים ברמת השורש, כך שעצי עבודה מתחילים מהר יותר וצורכים פחות מקום.

אם כל מי שעובד בתיקייה זו זקוק לאותם נתיבים, שמור את ההגדרה ב-.claude/settings.json. כדי להוסיף נתיבים עבור עצמך, השתמש ב-.claude/settings.local.json: הרשימות מתמזגות בין טווחים שונים, כך שקובץ מקומי יכול להוסיף נתיבים לרשימה השמורה במאגר אך לא להסיר מהם.

דוגמאות ה-JSON בדף זה מציגות הגדרה אחת בכל פעם. אם ה-.claude/settings.json שלך כבר מכיל מפתחות אחרים, כגון כללי permissions.deny שלמעלה, הוסף את המפתח worktree לצדם במקום להחליף את הקובץ. הסעיף שילוב הכל יחד מציג את התוצאה המשולבת.

הדוגמה למטה מציגה את הקובץ השמור במאגר:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

כאשר Claude יוצר עץ עבודה, הוא מבצע checkout רק ל-.claude/, packages/api/ ו-packages/shared/ במקום לעץ המלא. נתיבים ב-sparsePaths הם יחסיים לשורש המאגר, ללא קשר לתת-התיקייה שממנה אתה מפעיל את Claude. כל נתיבי התיקיות עובדים כאן, לא רק שורשי חבילות.

זה שימושי במיוחד עבור בידוד עצי עבודה של סוכני משנה. סוכני משנה הם מופעים מקבילים של Claude שנוצרים עבור משימות משנה, וכל אחד מהם שרץ בעץ עבודה מקבל checkout קל משקל במקום את העץ המלא. כל עצי העבודה בהפעלה חולקים את אותם sparsePaths, כך שאם סוכן משנה אחד זקוק ל-packages/api/ ואחר זקוק ל-packages/web/, רשום את שניהם.

רשום תיקיות ב-sparsePaths, לא קבצים בודדים. קבצים ברמת השורש כמו package.json, tsconfig.base.json וקובצי נעילה תמיד עוברים checkout לצד התיקיות שאתה מציין. תיקיות ברמת השורש אינן נכללות, לכן כלול את .claude ברשימה אם אתה רוצה שקובצי .claude/settings.json, .claude/rules/ או .claude/skills/ של שורש המאגר יהיו זמינים בתוך עץ העבודה.

Sparse checkout דורש מ-git להפעיל את extensions.worktreeConfig בקובץ .git/config המשותף של המאגר כל עוד עץ עבודה דליל קיים. Claude Code מסיר ערך זה לאחר הסרת עץ העבודה האחרון, אך רק אם Claude Code הוסיף אותו. הוא לעולם אינו מסיר ערך שהגדרת בעצמך. לפני גרסה v2.1.207, הערך נשאר לאחר הסרת עץ העבודה האחרון, וכלים מבוססי go-git כגון tea נכשלו בפתיחת המאגר עד שהרצת git config --unset extensions.worktreeConfig.

כדי למנוע שכפול של תיקיות גדולות כמו node_modules בין עצי עבודה, שלב את sparsePaths עם symlinkDirectories באותו .claude/settings.json:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

פעולה זו יוצרת קישור סימבולי (symlink) מ-node_modules/ של כל עץ עבודה בחזרה לעותק של המאגר הראשי במקום לשכפל אותו על הדיסק.

הערה: ההגדרות sparsePaths ו-symlinkDirectories נקראות מתיקיית ההתחלה שלך לפני יצירת עץ העבודה. לאחר היצירה, תיקיית העבודה של ההפעלה היא שורש עץ העבודה, ולא תת-התיקייה שממנה הפעלת. לכן, הגדרות פרויקט בתוך עץ העבודה נטענות מ-.claude/settings.json שבשורש עץ העבודה, העותק שנמשך (checked-out) של קובץ שורש המאגר. שים כל הגדרה אחרת שאתה צריך בתוך עצי עבודה, כגון כללי הרשאות או hooks, ב-.claude/settings.json של שורש המאגר.

לעיון מלא בהגדרות עצי עבודה, ראה הגדרות עץ עבודה.

#הענקת גישה בין חבילות או מאגרים

סעיף זה חל כאשר אתה מפעיל את Claude מתת-תיקייה, או כאשר משימה מתפרסת על פני מספר עותקי checkout. אם אתה מתחיל משורש המאגר בעץ יחיד גדול, ל-Claude כבר יש גישה לכל קובץ ותוכל לדלג על זה.

כאשר אתה מפעיל את Claude מ-packages/api/, הוא יכול לקרוא ולכתוב קבצים בתוך תיקייה זו. אם משימה דורשת שינויים בין חבילות, כגון עדכון טיפוס משותף שגם api וגם web מייבאים, עליך להעניק גישה לתיקייה השכנה. אותו מנגנון מעניק גישה למאגר שנמצא ב-checkout נפרד.

ההגדרה additionalDirectories ב-.claude/settings.json מעניקה ל-Claude גישה לתיקיות מחוץ לתיקיית העבודה. הדוגמה למטה מעניקה גישה לשתי חבילות שכנות:

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

נתיבים יחסיים נפתרים ביחס לתיקייה שממנה אתה מפעיל את Claude. בתצורה זו, Claude יכול לקרוא ולערוך קבצים ב-packages/shared/ וב-packages/web/ בזמן שהוא עובד מ-packages/api/.

תוכל גם להעניק גישה בזמן ריצה ללא עריכת הגדרות על ידי העברת הדגל --add-dir בעת הפעלת Claude:

claude --add-dir ../shared

בכל דרך שבה תוסיף תיקייה, Claude יכול לקרוא ולערוך קבצים בה. השאלה האם קובצי CLAUDE.md, קובצי .claude/rules/ וכישורים של התיקייה נטענים גם כן תלויה באופן שבו הוספת אותה:

כדי לטעון קובצי CLAUDE.md וקובצי כללים מתיקייה שנוספה באמצעות --add-dir או /add-dir, הגדר את משתנה הסביבה CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

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

עבור תיקיות שכנות שכל מי שעובד באזור זה זקוק להן, שמור את additionalDirectories ב-.claude/settings.json. עבור בחירה אישית או גישה חד-פעמית, השתמש ב-.claude/settings.local.json או העבר --add-dir בעת ההפעלה.

#הוספת כישורים (skills) לפי תיקייה

כל תת-תיקייה יכולה להגדיר כישורים (skills) התחומים למחסנית הטכנולוגית שלה. כישור נטען לפי דרישה כאשר Claude קובע שהוא רלוונטי, כך שכלי עבודה ספציפיים ל-API אינם צורכים הקשר במהלך עבודה בצד הלקוח (frontend).

כישורים נמצאים תחת .claude/skills/ בתוך התיקייה. שמור אותם במאגר לצד הקוד של אותו אזור כך שכל מי שמשכפל את המאגר יקבל אותם. במונוריפו זו יכולה להיות קבוצת כישורים אחת לכל חבילה. בבסיס קוד גדול בעל עץ יחיד זו קבוצה אחת לכל תת-מערכת כגון src/db/.claude/skills/.

צור תיקיית כישור בתוך תת-התיקייה:

mkdir -p packages/api/.claude/skills/api-testing

לאחר מכן כתוב את SKILL.md בתוך אותה תיקייה, כאן packages/api/.claude/skills/api-testing/SKILL.md. דוגמה זו מלמדת את Claude את דפוסי הבדיקות של חבילת ה-API:

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---

## Test structure

Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.

## Running tests

- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`

## Test utilities

- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints

## Patterns

- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

תת-תיקייה אחרת מחזיקה כישורים שונים באותו אופן: packages/web/.claude/skills/component-patterns/ מתאר את מוסכמות הרכיבים של צד הלקוח במקום בדיקות. כאשר Claude עובד על קובץ ב-packages/api/, הוא טוען את הכישור api-testing. כאשר הוא עובד ב-packages/web/, הוא טוען את component-patterns במקום זאת. הכישורים של אף אחת מהתיקיות אינם נטענים במהלך משימות של התיקייה האחרת.

תוכל גם לתחום כישור לפי תבנית קובץ במקום לפי מיקום. שדה ה-frontmatter בשם paths מקבל תבניות glob, ו-Claude טוען את הכישור אוטומטית רק כאשר הוא עובד עם קבצים תואמים. השתמש בזה עבור כישור שנמצא ב-.claude/skills/ של שורש המאגר אך חל רק על קבצים מסוימים בכל מקום שבו הם מופיעים, כגון כישור מסוג מיגרציית מסד נתונים התחום ל-**/migrations/**.

למידע נוסף על יצירה וארגון של כישורים, ראה כישורים (skills).

#שמירה על כישורים הניתנים לגילוי

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

אילו כישורים נמצאים בטווח תלוי במקום שממנו אתה מפעיל את Claude:

• מתת-תיקייה כגון packages/api/: כישורים מאותה תיקייה, מכל תיקיית אב עד לשורש המאגר, וברמות המשתמש והארגון.
• משורש המאגר: כישורי שורש, בתוספת כישורים מכל תת-תיקייה ש-Claude נוגע בה במהלך ההפעלה, מה שיכול להצטבר למאות.
• לאחר הוספת תיקייה שכנה באמצעות --add-dir: הכישורים של אותה תיקייה שכנה נטענים גם כן. ההגדרה additionalDirectories מעניקה גישה לקבצים בלבד ואינה טוענת כישורים.

שמות נטענים תמיד, אך תיאורים מתקצרים כאשר יש רבים, מה שעלול להסיר את מילות המפתח שבהן Claude משתמש כדי להחליט האם כישור מתאים. שמור על תיאורים קצרים והתחל במילים שבקשה תכיל, כמו "writing or modifying tests in packages/api/".

עבור כישורים שתיקיות רבות חולקות, כגון מוסכמות PR או רשימת תיוג לפריסה, מקם אותם ב-.claude/skills/ של שורש המאגר כך שייטענו מכל תיקיית הפעלה. כאשר כישורים משותפים זקוקים להיסטוריית גרסאות משלהם או חייבים לעבוד על פני מאגרים שונים, ארוז אותם כתוסף (plugin) במקום זאת. כישורי תוסף משתמשים במרחב שמות בתבנית plugin-name:skill-name, כך שהם לעולם אינם מתנגשים עם כישורים לפי תיקייה. צוות פלטפורמה יכול לנהל גרסאות ולעדכן אותם במקום אחד.

כדי למצוא אילו כישורים אינם בשימוש, הפעל את יצואן היומנים (logs exporter) של OpenTelemetry והגדר OTEL_LOG_TOOL_DETAILS=1 כך ששמות כישורים יתועדו כלשונם במקום לעבור השחרה (redacted). האירוע skill_activated מתעד כל הפעלה במאפיין skill.name שלו, והמאפיין invocation_trigger מתעד האם פקודה, Claude או כישור מקונן הפעילו אותו, מה שמלמד אותך מה לאחד או להוציא משימוש.

#ריכוז מוסכמות כאשר פריסה בשכבות מפסיקה להתרחב ביעילות

קובצי CLAUDE.md לפי תיקייה עלולים להפוך לקשים לשליטה וניהול ככל שבסיס הקוד גדל. מוסכמות מתרחקות מהמקור, קבצים מתיישנים, ואף אחד אינו הבעלים של קובץ השורש. פתרון הבעיה הזו מוטל בדרך כלל על הצוות שמתחזק את הגדרות ה-Claude Code של המאגר, ולא על כל מפתח שעובד באזור שלו.

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

• כישורים (skills): חומר עזר ש-Claude טוען רק כאשר הוא רלוונטי למשימה.
• תוספים (plugins): חבילות בעלות גרסאות של כישורים, hooks ופקודות שצוות פלטפורמה מחזיק בבעלות מרכזית.
• שרתי MCP: אם הארגון שלך כבר מפעיל חיפוש קוד או אינדקס RAG על גבי המאגר, חשוף אותו ככלי MCP כך ש-Claude יתשאל אותו במקום לקרוא קבצים ישירות.

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

#המלצה על התוסף הנכון בתחילת ההפעלה

ברגע שמוסכמות חיות בתוספים, לחבר צוות שמפעיל את Claude בחלק לא מוכר של העץ אין סימן המעיד איזה תוסף בעלי אותו אזור מתחזקים. hook מסוג SessionStart יכול לגשר על פער זה, מכיוון ש-Claude Code מוסיף טקסט רגיל שה-hook מדפיס ל-stdout ישירות להקשר של Claude לפני הבקשה הראשונה.

לדוגמה, תוכל לכתוב סקריפט שקורא את תיקיית ההפעלה מתוך קלט ה-hook, מחפש אותה במיפוי של נתיב לתוסף השמור במאגר, ומדפיס את ההמלצה כדי ש-Claude יעביר אותה בתשובתו הראשונה. ראה אוטומציה של פעולות עם hooks כדי לכתוב ולרשום את ה-hook.

#שילוב הכל יחד

התצורה המשולבת למטה משתמשת במבנה המונוריפו. אותם קבצים פועלים עבור כל תת-תיקייה בעץ יחיד גדול. קובץ ה-.claude/settings.json של כל תת-תיקייה חייב להיות עצמאי (self-contained) ולא מבוסס על שכבות על גבי קובץ שורש.

הדוגמה שומרת במאגר את worktree, additionalDirectories וכללי דחיית Read ב-.claude/settings.json, כך שכל מפתח ב-packages/api/ מקבל את אותה גישה לשכנים, נתיבים דלילים והחרגות. הקובץ למטה הוא ההגדרות השמורות במאגר לפי אזור עבור packages/api/:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)"
    ]
  }
}

מכיוון שהפעלה זו מתחילה מ-packages/api/, קובצי ה-CLAUDE.md של חבילות שכנות כבר נמצאים מחוץ לטווח, כך ש-claudeMdExcludes אינו נחוץ כאן. הוסף אותו במקום זאת ל-.claude/settings.local.json של שורש המאגר אם אתה מפעיל הפעלות גם מהשורש.

הערך additionalDirectories חל כאשר אתה מפעיל את Claude ישירות מ-packages/api/. בתוך עץ עבודה שנוצר מהפעלה זו, תיקיית העבודה היא שורש עץ העבודה, ולכן קובץ הגדרות זה אינו נטען. החבילות השכנות כבר נגישות בתוך עץ העבודה בלעדיו, אך כללי הדחייה זקוקים לעותק שני ב-.claude/settings.json של שורש המאגר כדי שהפעלות עץ עבודה יקלטו אותם, כפי שמתארת ההערה לגבי הגדרות עץ עבודה:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)"
    ]
  }
}

לאחר ההגדרה, למאגר יש מבנה זה:

monorepo/
  CLAUDE.md
  .claude/settings.json                           
# deny rules for worktree sessions
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       
# worktree, additionalDirectories, deny rules
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

עם הגדרה זו, הפעלת Claude מ-packages/api/:

• טוענת את CLAUDE.md השורשי ואת packages/api/CLAUDE.md, ומדלגת על packages/web/CLAUDE.md
• יכולה לקרוא ולערוך קבצים ב-packages/api/ וב-packages/shared/
• מדלגת על קריאות של תוצרי בנייה תחת dist/ ו-build/ ב-packages/api/
• כוללת את הכישור api-testing הזמין לפי דרישה
• יוצרת עצי עבודה המכילים את .claude/, packages/api/, packages/shared/ וקבצים ברמת השורש, כאשר כללי הדחייה מוחלים על פני כל עץ העבודה מקובץ הגדרות השורש

#תחימה ותכנון של שינויים המתפרסים על פני חבילות

התצורה שלמעלה שולטת במה ש-Claude רואה. כאשר שינוי בודד נוגע במספר חבילות, כגון עדכון טיפוס משותף יחד עם כל מקום קריאה שמשתמש בו, האופן שבו אתה תוחם ומסדר ברצף את המשימה משפיע גם הוא על התוצאה.

שתי טכניקות מסייעות לשמור על עקביות בשינוי חוצה חבילות:

• מסירת השינוי כולו ל-Claude בהפעלה אחת: מסירת העריכה המשותפת ומקומות הקריאה שלה יחד שומרת על עקביות בהחלטות שמאחורי כל עריכה, במקום לגזור אותן מחדש לכל חבילה.
• תכנון לפני עריכה: תכנן תחילה במצב תוכנית (plan mode), ו-Claude יכתוב את התוכנית לקובץ. הפעלה ארוכה חוצת חבילות דוחסת את ההקשר שלה לאורך הדרך. Claude Code מזריק מחדש את קובץ התוכנית לאחר כל דחיסה, כך שהתוכנית שורדת במקום שבו היסטוריית השיחה עלולה שלא לשרוד.

#השלבים הבאים

ברגע שתצורה זו קיימת, תוכל לשפר אותה:

• השתמש ב-hooks כדי להריץ בודקי סגנון (linters) או בודקי טיפוסים (type-checkers) לפי תיקייה לאחר ש-Claude עורך קבצים.
• עיין במדריך ניהול עלויות ביעילות כדי להבין כיצד גודל בסיס הקוד משפיע על השימוש באסימונים (tokens) וכיצד להגדיר מגבלות הוצאה לפני פריסה רחבה יותר.
• קרא את כיצד Claude Code עובד בבסיסי קוד גדולים בבלוג של Claude לקבלת דפוסי פריסה ארגוניים ומודלים של בעלות שנמצאים מעל התצורה לפי מאגר שבדף זה.