כתבו את CLAUDE.md כמו חוקה: איסורים, כללי התנהגות, החלטות ברירת מחדל. 92 קומיטים ב-5 ימים, בלי סטייה.
ב-5 ימים דחפתי 92 commits והעליתי מוצר לפרודקשן (github.com/defi-io/smarts). בלי תאונות, בלי rollbacks, בלי refactor גדול. הסיבה היא לא ש-Claude גאון. הסיבה היא 565 השורות של CLAUDE.md שיושבות בשורש הפרויקט.
הפוסט הזה הוא על איך לכתוב CLAUDE.md שעובד כמו חוקה, ומה קורה אחרי.
הרבה אנשים כותבים CLAUDE.md כמו README — מהו הפרויקט, איך מריצים אותו. זה בזבוז.
ה-README הוא לבני אדם. ה-CLAUDE.md הוא ל-Claude. Claude טוען אותו אוטומטית בתחילת כל session. כלומר כל שורה שאתם שמים שם הופכת לתנאי מקדים לכל החלטה שהוא יקבל בהמשך.
תכתבו בסגנון README, ותקבלו: Claude יודע פחות או יותר מהו הפרויקט, יודע איך להריץ את הבדיקות, אבל מקבל כל החלטה טכנית מאפס.
תכתבו בסגנון חוקה, ותקבלו: Claude יודע אילו דרכים סגורות, אילו קונבנציות הן חובה, לאן להטות כברירת מחדל בכל פרשת דרכים, ומתי לעצור ולשאול.
ההבדל: הראשון "אגב הדרך" יכניס תלות חדשה, יוסיף שכבת הפשטה, יגע ב-Gemfile. השני לא.
הפרויקט שאני בונה לאחרונה נקרא smarts.md — פלטפורמה שמייצרת live docs ושרתי MCP עבור smart contracts. ה-CLAUDE.md שלו באורך 565 שורות, בחלוקה כזו:
1. זהות הפרויקט (5 שורות)
2. ליבת המוצר (הגדרה במשפט אחד + הבדלים מבניים מול מתחרים)
3. מחסנית טכנולוגית (אילוצים קשים, פורמט YAML)
4. רשימת איסורים (פריטי ❌ מפורשים)
5. היקף (גבולות קשים של ה-MVP)
6. ארכיטקטורה (כולל דיאגרמת ASCII)
7. מבנה תיקיות (אחריות לכל קובץ)
8. קונבנציות קוד Ruby (כולל קטעי "עשה / אל תעשה")
9. אסטרטגיית cache (בטבלה)
10. דרישות טסטים
11. פרטי deployment
12. תהליך Git
13. כללי שימוש ב-Claude Code (הוראות התנהגות)
14. אבני דרך ל-90 ימים
15. עקרונות ליבה
אף סעיף הוא לא קישוט. למטה אבחר כמה ואסביר למה הם כתובים ככה.
שלי נראית ככה:
❌ בלי שירותי TypeScript / Node.js
❌ בלי ethers.js / web3.js
❌ בלי Sidekiq (משתמשים ב-Solid Queue)
❌ בלי React / Vue / Svelte (משתמשים ב-Hotwire)
❌ בלי Redis (Solid Cache / Solid Queue / Solid Cable מכסים הכול)
❌ בלי חוזים שלא עברו verification (רק מאומתים ב-Etherscan)
❌ בלי Solana / Bitcoin / Move (רק EVM)
זה פרויקט Web3. ברירת המחדל בעולם ה-Web3 היא TypeScript + ethers.js + Redis + React. אני הולך נגד הזרם. יש לי סיבות, אבל Claude לא מכיר אותן. בלי רשימת איסורים, Claude מבסס המלצות על "ההיגיון התעשייתי" שטמון בנתוני האימון שלו — וזה כמעט בוודאות הנתיב של TypeScript.
עם רשימת האיסורים, Claude מפסיק לשאול "להוסיף שירות Node להריץ web3.js?". הדרך הזו סגורה בברירת מחדל.
המפתח: כל פריט חייב להיות מפורש ומוחלט. אל תכתבו "השתדל להימנע מ-TypeScript". כתבו "בלי TypeScript". כל מה שמעורפל, Claude יקרא כניתן למשא ומתן.
הבלוק הגדול האחרון של CLAUDE.md הוא "כללי שימוש ב-Claude Code":
### כשאני אומר "תתחיל עם X"
1. בדוק קודם אם האילוצים של CLAUDE.md מתירים את הגישה
2. בדוק אם בקוד הקיים יש כבר מימוש קשור (אל תמציא את הגלגל)
3. לפני כתיבת קוד, פתח branch חדש
4. אחרי המימוש, הרץ טסטים
5. אל תעשה commit אוטומטי — כשהקוד נכתב והטסטים ירוקים, עצור ודווח.
חכה עד שאומר "commit" במפורש
### כשאני אומר "יש לי רעיון"
אל תכתוב קוד מיד. קודם:
1. אשר הבנה (פרפראזה)
2. הערך מול האילוצים של CLAUDE.md
3. הצבע על בעיות פוטנציאליות או חלופות טובות יותר
4. חכה לאישור שלי לפני שתפעל
### כשנתקלים בצומת טכני
כשה-CLAUDE.md לא מציין:
1. ברירת מחדל: האפשרות "יותר Rails-native"
2. ברירת מחדל: האפשרות עם פחות תלויות
3. ברירת מחדל: האפשרות שמאפשרת ל-solo dev לעשות איטרציות מהר יותר
4. בספק — עצור ושאל
החלק הזה חשוב פי עשרה מ"השתמש ב-snake_case".
סגנון קוד Claude לומד בקריאת הקוד. אבל "מתי לעצור ולשאול", "כששומע 'יש לי רעיון', לעשות פרפראזה לפני שכותבים קוד" — אלה דפוסי התנהגות. קוד לבדו לא מלמד אותם.
השורה הכי חשובה: לאן להטות בברירת מחדל בצומת. כלל יחיד זה מחליט מה Claude עושה כשאתם לא בחדר (כשאתם רק אומרים "תתחיל עם X" ויוצאים). תכתבו את זה ברור, ותוכלו לתת לו לעבוד בלי השגחה.
בראש ה-CLAUDE.md כתוב:
מסמך זה הוא "המקור הראשי" של הפרויקט. נטען אוטומטית בתחילת כל session של Claude Code. כשמשנים החלטות טכניות, שנו כאן קודם; הקוד נגרר אחר כך.
זה חוזה של workflow. כשאני מחליט לשנות בחירה טכנית — נניח, להעלות את מודל ה-AI הראשי מ-gpt-5-mini ל-gpt-5 — הצעד הראשון הוא לא לגעת ב-initializer. הצעד הראשון הוא לערוך את הקטע הזה ב-CLAUDE.md:
ai:
fast: gpt-5-mini # לפני
fast: gpt-5 # אחרי
אחר כך אני נותן ל-Claude לקרוא מחדש את CLAUDE.md וליישר את הקוד.
למה? כי אם תשנו ערך בקוד וה-CLAUDE.md לא מתעדכן, בפעם הבאה ש-Claude קורא את CLAUDE.md הוא רואה את הערך הישן ו"מטוב לבו" מחזיר את הקוד שלכם אחורה. שורש הקונפליקט הוא נקודת כשל יחידה — ה-CLAUDE.md מפגר. חוקה שמפגרת אחרי המציאות — כך פורצות מלחמות אזרחים.
להתייחס ל-CLAUDE.md כאל חוקה משמעו: הוא תמיד רץ לפני הקוד.
smarts.md, 5 ימים, 92 commits:
חיי PR ממוצעים: 30 דקות. בלי refactor גדולים. בלי "רגע, הכיוון לא נכון, rollback".
לא בגלל ש-Claude קסם. בגלל שכל session הוא רץ על מסילה של 565 שורות. הוא ידע שלא להכניס TypeScript, ידע ש-Solid Queue היא תור ברירת המחדל, ידע שפונקציות view בקאש ל-60 שניות, ידע שכל service צריך לממש מתודת מחלקה call, ידע לחכות לאישור שלי לפני commit.
תורידו חצי מהאילוצים האלה ותקבלו: 30 דקות ביום הסבר "למה אנחנו לא משתמשים ב-X", 5 דקות review לתלות שהוא הכניס "אגב", ו-Gemfile שמתפרק לאט.
אל תתחילו מקובץ ריק. תתחילו מההחלטה האחרונה שכאבה.
אם לאחרונה Claude "מכניס תלויות חדשות כל הזמן", כתבו את רשימת האיסורים.
אם הוא "מבכל פעם משנה ארכיטקטורה", כתבו את דיאגרמת הארכיטקטורה + "הוספת מיקרו-שירות, החלפת DB וכו' דורשת אישור".
אם הוא "לא כותב טסטים", כתבו "מה חייב להיות מכוסה בטסטי יחידה".
אם הוא "עושה commit אגרסיבי מדי", כתבו "בלי commit אוטומטי, חכה להוראה מפורשת".
לכל כאב — סעיף אחד. שאר הדברים, לעת עתה, אל תכתבו.
אחרי שלושה חודשים יהיה לכם CLAUDE.md באורך 500 שורות, ומאחורי כל שורה ניצב "אני לא רוצה שיעשה את זה שוב" קונקרטי. המסמך הזה גובר על כל תבנית, כי הוא מכוון בדיוק לפרויקט שלכם, ל-workflow שלכם, לצוות שלכם (גם אם זה רק אתם).
חוקה לא נכתבת בבת אחת. היא מתגבשת מקונפליקטים קונקרטיים, אחד אחר השני.
קוד מקור: github.com/defi-io/smarts