ארכיטקטורת Workspace: 7 תיקיות ו-CLAUDE.md שמשמרים את הריכוז של הסוכן
בלי מבנה נכון, Claude — וכל סוכן AI אחר — "שוכח" מה הוא עושה אחרי כ-25 הודעות. עם המבנה שתלמדו כאן, הסוכן זוכר מי אתם, מה הפרויקט, ואיך לעבוד — לאורך כל הפרויקט.
1. הבעיה: Claude שוכח מה דיברנו
נניח שהתחלתם לבנות אתר Landing Page עם Claude. הסברתם לו מי קהל היעד, איזה סגנון עיצוב אתם רוצים, ואיזה קבצים אסור לגעת בהם. Claude עבד מצוין — בהודעות הראשונות.
אחרי 20–25 הודעות, משהו מתחיל להשתבש. Claude מציע שינויים שסתרתם קודם. הוא שוכח שכבר הגדרתם צבעים. הוא מוסיף קוד שמפר כלל שקבעתם. לא מפני שהוא "שוטה" — אלא מפני שהוא עובד בתוך חלון הקשר (context window), שהוא כמו לוח לבן שנמחק חלקית מדי כמה הודעות. ככל שהשיחה ארוכה יותר, ההיסטוריה הרחוקה דוחקת החוצה.
זו לא בעיה של Claude בלבד — Codex, Cursor ו-Copilot Workspace סובלים מאותה מגבלה. ה-7 תיקיות ו-CLAUDE.md שנסביר כאן עובדים עם כל אחד מהם.
הודעה 5: Claude מבין את הפרויקט.
הודעה 15: הוא עדיין מכיר את כל ההחלטות.
הודעה 25: הוא כבר לא זוכר שיש קובץ CSS נפרד, שסגנון הכפתורים נקבע, ושמותר לו לשנות רק את קבצי ה-components.
הוא מתחיל להמציא מחדש — ולפעמים לשבור דברים שעבדו.
בתחילת כל שיחה Claude Code טוען אוטומטית את קובץ CLAUDE.md מהפרויקט. הוא יודע מיד: מי אתם, מה המטרה, אילו כלים בשימוש, מה כבר הוחלט, ומה אסור לגעת בו. אין צורך להסביר מחדש — לא בהתחלת שיחה, לא בשיחה הבאה.
/agent-onboarding-wizard.
2. שבע התיקיות — הפרויקט כמו משרד מסודר
במשרד פיזי יש מגירות ברורות: תיקייה לחוזים, תיקייה לתקציבים, תיקייה לחומרי שיווק. Claude צריך אותו הדבר — מבנה שאומר לו איפה לחפש ואיפה לשמור.
שבע התיקיות האלה הן קונבנציה שעובדת — לא דוגמה מתוך תיעוד רשמי. המפתח הוא העקביות: ברגע שגם אתם וגם Claude מסכימים שהמפרטים תמיד ב-02-specs/ וההחלטות תמיד ב-05-decisions/, הסוכן מפסיק לשאול ומתחיל לדעת.
| תיקייה | מטרה | מי מוסיף | מתי להוסיף |
|---|---|---|---|
| 01-context/ | זהות הפרויקט: מי קהל היעד, מה הבעיה שנפתרת, מה החזון. Claude קורא מכאן בתחילת כל שיחה. | אתם (פעם אחת, בהתחלה) | לפני שמתחילים לבנות. עדכנו אם הכיוון משתנה. |
| 02-specs/ | PRD (מסמך דרישות מוצר), SPEC טכנית, החלטות עיצוב. Claude מתייחס לכאן כ"מה שסוכם". | אתם + Claude | כשמחליטים מה לבנות ואיך. לפני שמתחילים לממש. |
| 03-src/ | קוד המקור עצמו. כל מה ש-Claude כותב ומשנה. | Claude (בעיקר) | תמיד — זה הלב הפועם של הפרויקט. |
| 04-tasks/ | רשימות משימות, תוכניות ספרינט (sprint — מחזור עבודה קצר), סטטוס מה פעיל ומה הושלם. | אתם + Claude | בתחילת כל ספרינט. Claude מעדכן תוך כדי עבודה. |
| 05-decisions/ | יומן החלטות: מה הוחלט, למה, ומה הדחינו. Claude לא שואל שוב שאלות שהוכרעו כבר. | אתם + Claude | בכל פעם שמתקבלת החלטה משמעותית — לא רק טכנית. |
| 06-assets/ | תמונות, פונטים, נתוני דוגמה, מסמכי רפרנס. Claude יודע לאן לפנות כשצריך חומרים. | אתם | כשמייבאים חומרי עיצוב או מסמכי רקע. |
| 07-output/ | פלטים מוגמרים: קבצים מוכנים לפרסום, דוחות שנוצרו, ייצוא נתונים. ברור מה "גמור" ומה "בתהליך". | Claude (בעיקר) | כשמשהו מגיע לשלב סיום. לא לאחסן טיוטות כאן. |
אילו תיקיות להעלות ל-GitHub
לא כל התיקיות צריכות להיות ב-repo. הנחיה כללית:
- כן להעלות:
01-context/,02-specs/,03-src/,04-tasks/,05-decisions/ - לשקול:
06-assets/— תלוי בגודל הקבצים (תמונות כבדות → השתמשו ב-Git LFS או שמרו בענן) - בדרך כלל לא:
07-output/— קבצי פלט נוצרים מחדש בכל פרסום
הוסיפו לקובץ .gitignore בשורש הפרויקט:
07-output/ 06-assets/large-files/ .env .env.local
3. CLAUDE.md — ה-Briefing שהסוכן קורא בכל בוקר
CLAUDE.md הוא קובץ טקסט פשוט (בפורמט Markdown — טקסט עם כותרות וכוכביות לעיצוב) שיושב בשורש הפרויקט. Claude Code טוען אותו אוטומטית בתחילת כל שיחה — בלי שתצטרכו לבקש. זה כאילו נתתם לסוכן "תדריך" מלא לפני כל פגישת עבודה.
בלי CLAUDE.md, כל שיחה חדשה היא כמו לשכור עובד חדש ולהסביר לו מאפס מי הקהל, מה הסגנון, ומה אסור לגעת בו. עם CLAUDE.md — העובד קרא את כל זה לפני שהגיע.
מה כוללים ב-CLAUDE.md
CLAUDE.md טוב מכסה חמישה נושאים:
- זהות הפרויקט — מי בונה, בשביל מי, ומה המטרה
- כלים וסביבה — שפות תכנות, frameworks, שירותים חיצוניים
- כללי עבודה — פקודות נפוצות שמריצים, סגנון קוד, naming conventions
- מגבלות — מה אסור לשנות בלי לשאול
- טון ורוח — אם יוצרים תוכן (טקסטים, עיצוב), מה הסגנון הרצוי
CLAUDE.md לפרויקט אתר קורס
# הקשר הפרויקט ## מי אני בעל עסק קטן, לא מפתח. מנהל קורסי אונליין ב-Teachable. ## מה הפרויקט אתר Landing Page לקורס AI לסטארטאפים. מבוסס Next.js 15. הקהל: מייסדים לא-טכניים, גיל 28–45, עברית בעיקר. ## כלים וסביבה - GitHub repo: my-org/landing-ai (branch ראשי: main) - Supabase: לאחסון leads (רשומות אנשי קשר) - Netlify: פרסום אוטומטי מה-main branch - TypeScript, Tailwind CSS ## פקודות נפוצות - npm run dev — שרת פיתוח מקומי - npm run build — build לייצור - npm run lint — בדיקת קוד ## כללים חשובים - אל תשנה את עיצוב הקובץ globals.css בלי לשאול - כל קובץ חדש → ספר לי מה יצרת ולמה - שמות קבצים תמיד באנגלית, kebab-case (לדוגמה: hero-section.tsx) - אל תשנה את schema של Supabase בלי אישור מפורש ## טון ותוכן כשכותבים טקסטים לאתר: ישיר, חם, ללא ז'רגון טכני. הקהל לא מכיר מונחי תכנות.
איך יוצרים CLAUDE.md בפועל
- פתחו את תיקיית הפרויקט ב-VS Code (או ב-Cursor)
- בסרגל הצד, לחצו ימין על שם הפרויקט ← בחרו New File
- הקלידו
CLAUDE.mdולחצו Enter - הדביקו את התוכן לפי התבנית למעלה, התאימו למצבכם, ושמרו (
Ctrl+S)
חשוב: הקובץ חייב להיות בשורש הפרויקט — ממש לצד תיקיות ה-01 עד 07 — לא בתוך אחת מהן.
אם יש לכם CLAUDE.md גם בספרייה הגלובלית (~/.claude/CLAUDE.md), הוא ייטען נוסף — כלומר יש לכם שכבת "כללים ארגוניים" שחלים על כל הפרויקטים, ושכבת "כללי הפרויקט הספציפי" מעליה.
/new-project-from-prd בתוך Claude Code. המדריך הזה עדיין שווה לקרוא — כדי שתבינו למה הסקיל יצר מה שיצר, ותוכלו לשנות אם צריך.
4. Slash Commands — הפקודות שחוסכות את ההסברים החוזרים
Slash command (פקודת קו נטוי) הוא קובץ Markdown קטן שאתם כותבים פעם אחת, ואז מריצים בכל פעם שצריך באמצעות /שם-הפקודה. Claude מחליף את הפקודה בתוכן הקובץ — ומבצע אותו.
למה זה חשוב? מפני שחלק גדול מהעבודה עם AI הוא הוראות שחוזרות על עצמן. "בדוק את הקוד שכתבת. בדוק edge cases. בדוק שאין קוד כפול. דווח לי לפי חומרה." אם כותבים את זה כל פעם מחדש — מבזבזים זמן וסיכוי שמשהו יפול. אם שומרים כ-slash command — הפרוטוקול שלכם הוא קובץ בשורש הפרויקט.
Slash Commands ברמת הפרויקט מול רמה גלובלית
פקודות ב-.claude/commands/ פנימיים לפרויקט הספציפי. פקודות ב-~/.claude/commands/ (בתיקיית הבית שלכם) זמינות בכל פרויקט — שימושי להוראות כלליות כמו "כתוב commit message בסגנון X".
יצירת slash command: שלב אחר שלב
- בסרגל הצד ב-VS Code, לחצו ימין על שם הפרויקט ← New Folder ← הקלידו
.claude← Enter - לחצו ימין על
.claude← New Folder ← הקלידוcommands← Enter - לחצו ימין על
commands← New File ← הקלידוreview.md← Enter
שימו לב: תיקיות שמתחילות בנקודה (.claude) הן נסתרות ב-File Explorer רגיל. VS Code מציג אותן תמיד.
קובץ .claude/commands/review.md לדוגמה
זהו הפרוטוקול שירוץ בכל פעם שתקלידו /review בשיחה:
סקור את הקוד שכתבת בשיחה הזו. בדוק את הנושאים הבאים בסדר הזה: 1. נכונות לוגית — האם הקוד עושה מה שהתבקש? 2. טיפול בשגיאות — האם מקרי קצה (edge cases) מכוסים? 3. קוד כפול — האם יש לוגיקה שחוזרת ואפשר לאחד? 4. עקביות סגנון — האם עולה בקנה אחד עם שאר הפרויקט? פלט: רשימה ממוינת לפי חומרה. קריטי → גבוה → בינוני → נמוך. אם אין ממצאים בקטגוריה — כתוב "נקי".
מעכשיו, /review מריץ את כל הפרוטוקול הזה — לא צריך לחזור עליו.
/plan — לפני שמתחילים משימה, בקש מ-Claude לפרק אותה לצעדים ולרשום ב-04-tasks. /commit — יצור commit message מסודר לפי השינויים שנעשו. /decision — יתעד החלטה חדשה ב-05-decisions בפורמט אחיד.
5. דפוסים נפוצים — שאלות שעולות בפועל
מה שמים ב-CLAUDE.md לעומת ב-05-decisions?
CLAUDE.md הוא לדברים שנכונים תמיד — זהות, סגנון, מגבלות קבועות. אם משהו לא אמור להשתנות בין שיחה לשיחה, הוא שייך ל-CLAUDE.md.
05-decisions/ הוא לדברים שהיה להם הקשר בזמן — "ביום X החלטנו Y בגלל Z". זה מועיל כשרוצים להבין בעוד שלושה חודשים למה הפרויקט בנוי כך ולא אחרת. Claude יכול לקרוא משם, אבל הוא לא טוען את כל הקובץ אוטומטית כמו CLAUDE.md.
מה קורה כש-slash command ו-05-decisions סותרים?
Claude מעדיף את ההוראות הישירות בשיחה — כלומר את מה שבפקודה שרצה עכשיו — על פני קבצים שהוא קורא ברקע. אם יש סתירה, פתרו אותה: עדכנו את הפקודה, או הוסיפו הבהרה ל-CLAUDE.md. אל תסמכו על Claude שיפתור סתירות לוגיות לבד.
מה עם פרויקטים שכוללים כמה repo-ים?
מודל שבע התיקיות עובד טוב גם כאן — עם כלל אחד: CLAUDE.md אחד לכל repo. אם יש לכם repo לפרונטאנד ו-repo לבקאנד, לכל אחד CLAUDE.md משלו שמתאר את ההקשר הספציפי שלו. כללים משותפים לשניהם — שמרו ב-CLAUDE.md הגלובלי.
האם מבנה זה עובד עם Codex / Cursor?
כן. Codex קורא קבצי AGENTS.md (מקביל ל-CLAUDE.md). Cursor קורא קבצי .cursorrules. המבנה הלוגי — 7 תיקיות + קובץ briefing — עובד עם כל הסוכנים. רק שם הקובץ שונה.
6. פתרון בעיות נפוצות
Claude לא מתנהג לפי CLAUDE.md
בדקו ראשית: האם הקובץ נמצא בשורש הפרויקט? פתחו terminal (שורת פקודה) ורשמו ls -la (Mac/Linux) או dir (Windows) — CLAUDE.md צריך להופיע ישירות, לא בתת-תיקייה.
בדקו שנית: האם Claude Code נפתח מהתיקייה הנכונה? Claude Code עוקב אחרי CLAUDE.md של תיקיית העבודה הנוכחית. אם פתחתם אותו מתיקייה אחרת — הוא לא ימצא את הקובץ.
בדקו שלישית: האם שמרתם את הקובץ? נשמע טריוויאלי — אבל Ctrl+S אחד נשכח שכיח יותר ממה שנדמה.
הפקודה /review לא עובדת
בדקו את המבנה: הקובץ חייב להיות ב-.claude/commands/review.md — כן עם הנקודה בהתחלה, כן בתוך commands/.
בדקו את שם הקובץ: שם הקובץ (ללא סיומת .md) הוא שם הפקודה. review.md ← /review. אם שמרתם אותו בשם אחר, הפקודה תהיה שונה.
נסו לרענן: אם שיניתם את הקובץ בזמן שהשיחה פתוחה, Claude לא תמיד מרענן. פתחו שיחה חדשה.
שיניתי CLAUDE.md באמצע שיחה ו-Claude לא מתנהג לפיו
Claude טוען את CLAUDE.md פעם אחת — בתחילת השיחה. שינויים שנעשו אחרי שהשיחה כבר פתוחה לא נטענים מחדש.
הפתרון: פתחו שיחה חדשה. אם עיבדתם שינוי חשוב ב-CLAUDE.md וצריכים שיחול מיד — לחצו Ctrl+W לסגור את השיחה הנוכחית ופתחו חדשה.
7. המשך הסדרה
עכשיו שיש לכם מבנה workspace ו-CLAUDE.md — Claude יודע מי אתם ומה הפרויקט. השלב הבא הוא לחבר לו ידיים: לתת לו גישה לכלים חיצוניים כמו GitHub, Notion, Gmail, ואחרים.
זה בדיוק מה שמדריך 4 מכסה: Composio MCP — שכבת חיבור שמאפשרת ל-Claude לפעול בתוך הכלים שאתם כבר משתמשים בהם. הגדרת הקישור נעשית עם פקודת claude mcp add בשורת הפקודה — נכסה את זה שלב אחר שלב.
מדריך 5 לאחר מכן סוגר את המעגל: איך הופכים את ה-repo שלכם ליועץ אוטומטי — סוכן שסורק את הקוד באופן שוטף ומציע שיפורים לפני שבעיות הופכות לתקלות.