📘 תיעוד 57

הגדרת Claude Code ב-monorepo או בבסיס קוד גדול

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

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

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

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

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

#הגדרות בעמוד הזה

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

[!TIP]

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

#ה-monorepo לדוגמה

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

monorepo/
  CLAUDE.md                     # הוראות שורש
  packages/
    api/
      CLAUDE.md                 # הוראות ספציפיות ל-API
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # הוראות ספציפיות לפרונטאנד
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # הוראות לספרייה המשותפת
      src/

#בחר מאיפה להפעיל את Claude

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

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

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

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

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

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

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

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

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

כדי לקצר קובץ שכבר נמצא ב-commit, הרץ את בדיקת /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/ בהקשר. אותו דבר נכון לכל תת-ספרייה בעץ שאינו monorepo. כדי לאשר אילו קבצים נטענו, הרץ /context all ובדוק את הרשימה תחת Memory files.

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

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

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

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

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

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

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

כשאתה מפעיל את Claude משורש המאגר, קובץ CLAUDE.md של כל תת-ספרייה יכול להיטען לפי דרישה במהלך הסשן. ההגדרה 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": מחריג קובץ מסוים אחד לפי נתיב מוחלט

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

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

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

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

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

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

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

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

• כל מי שעובד במאגר: הכנס את הכללים ב-commit לקובץ .claude/settings.json, בשורש המאגר אם אתה מפעיל את Claude משם, או ב-.claude/ של כל חבילה אם אתה מתחיל מתת-ספריות. כמו שאר הגדרות הפרויקט בעמוד הזה, הקובץ הזה לא עובר בירושה מספריות אב.

• רק אתה: השתמש ב-.claude/settings.local.json בשורש המאגר. הוא נטען בכל סשן CLI בתוך המאגר בלי קשר לספריית ההתחלה, חוץ מהמקרים שבהם Claude Code לא משתמש בשורש המאגר, למשל ב-Windows.

  תבניות יחסיות כמו Read(./**/vendor/**/*) שבדוגמה עדיין מעוגנות בתיקיית העבודה הנוכחית של הסשן ולא בשורש המאגר. אם אתה מתחיל סשנים מתת-ספריות, כתוב את הכללים בקובץ הזה כנתיבים מוחלטים עם //, למשל Read(//absolute/path/to/repo/**/vendor/**/*).

• כולם, באכיפה בכל סשן: הגדר את הכללים ב-הגדרות מנוהלות, שאותן הגדרות משתמש ופרויקט לא יכולות לדרוס.

הדוגמה למטה חוסמת ארטיפקטים של בנייה ו-SDK שהוא vendored. תבניות הספריות שלה מסתיימות ב-/**/* ולא ב-/**, כדי שכל כלל יכסה את כל מה שבתוך הספרייה אבל לא את הספרייה עצמה. Claude עדיין יכול להציג את הספריות האלה או להיכנס אליהן, למשל עם ls dist או cd build.

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

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

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

#צמצום קריאות קבצים עם code intelligence

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

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

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

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

• Marketplace "claude-plugins-official" not found: הוסף את ה-marketplace עם /plugin marketplace add anthropics/claude-plugins-official, ואז נסה שוב את ההתקנה.
• Plugin "<name>" not found in marketplace "claude-plugins-official": העותק המקומי שלך של קטלוג ה-marketplace אולי לא מעודכן. רענן אותו עם /plugin marketplace update claude-plugins-official, ואז נסה שוב את ההתקנה. אם הניסיון החוזר מדפיס את אותה הודעה, ראה Plugin not found in marketplace.

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

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

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

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

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

#הוצא רק את הספריות שאתה צריך

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

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

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

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

.claude/settings.json

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

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

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

רשום ב-sparsePaths ספריות, ולא קבצים בודדים. קבצים ברמת השורש כמו package.json, tsconfig.base.json, וקבצי lock תמיד נמשכים לצד הספריות שרשמת. ספריות ברמת השורש לא נמשכות, לכן כלול את .claude ברשימה אם אתה רוצה ש-.claude/settings.json או .claude/rules/ של שורש המאגר יהיו זמינים בתוך ה-worktree. עבור skills, agents ופקודות של הפרויקט, ראה מה worktrees חולקים עם ה-checkout הראשי.

sparse checkout דורש ש-git יפעיל את extensions.worktreeConfig ב-.git/config המשותף של המאגר בזמן שקיים worktree מסוג sparse. Claude Code מסיר את הרשומה הזו אחרי שה-worktree האחרון מוסר, ורק אם Claude Code הוסיף אותה. Claude Code אף פעם לא מסיר ערך שהגדרת בעצמך.

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

.claude/settings.json

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

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

[!NOTE]

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

למדריך המלא של הגדרות worktree, ראה הגדרות Worktree.

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

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

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

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

packages/api/.claude/settings.json

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

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

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

claude --add-dir ../shared

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

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

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

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

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

#הוסף skills לפי ספריה

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

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

צור ספריית skill בתוך תת-הספריה:

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

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

packages/api/.claude/skills/api-testing/SKILL.md

---
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/`

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

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

למידע נוסף על יצירה וארגון של skills, ראה Skills.

#שמור על skills שניתן לגלות

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

אילו skills נמצאים בתחום תלוי במקום שממנו מתחילים את Claude:

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

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

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

כדי לגלות אילו skills לא בשימוש, הפעל את מייצא הלוגים של OpenTelemetry והגדר OTEL_LOG_TOOL_DETAILS=1 כדי ששמות skills יירשמו כלשונם ולא יוסתרו. אירוע skill_activated רושם כל הפעלה במאפיין skill.name שלו, ו-invocation_trigger רושם אם פקודה, Claude, או skill מקונן הפעילו אותו, וזה אומר לך מה לאחד או להוציא משימוש.

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

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

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

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

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

#המלץ על ה-plugin הנכון בתחילת הסשן

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

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

#חבר את הכל

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

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

packages/api/.claude/settings.json

{
  "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/ ישירות. בתוך worktree שנוצר מהסשן הזה, ספריית העבודה היא שורש ה-worktree, ולכן קובץ ההגדרות הזה לא נטען. חבילות האחים כבר נגישות בתוך ה-worktree בלעדיו, אבל כללי הדחייה צריכים עותק שני ב-.claude/settings.json של שורש המאגר כדי שסשנים של worktree יקלטו אותם, כפי שהערת הגדרות ה-worktree מתארת:

.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/
• ה-skill api-testing זמין לפי דרישה
• יוצר worktrees שמכילים את .claude/, packages/api/, packages/shared/, וקבצים ברמת השורש, עם כללי הדחייה שחלים על כל ה-worktree מקובץ ההגדרות של השורש

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

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

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

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

#הצעדים הבאים

אחרי שההגדרה הזו במקום, אפשר לחדד אותה:

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