📘 תיעוד 36

כללי פרויקט (AGENTS.md)

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

#מהם כללי פרויקט?

כללי פרויקט הם קובצי Markdown שGrok קורא ומוסיף להקשר שלו. Grok פועל לפי התוכן שלהם בכל אינטראקציה בעץ תיקיות זה.

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

#שמות קבצים נתמכים

Grok בודק את שמות הקבצים הבאים (בסדר הזה) בתוך כל תיקייה:

• Agents.md
• Claude.md
• CLAUDE.md
• CLAUDE.local.md
• AGENT.md
• AGENTS.md

Grok טוען כל קובץ תואם בתיקייה, כך שתיקייה המכילה גם את AGENTS.md וגם את CLAUDE.md תורמת את שניהם. במערכות קבצים שאינן רגישות לאותיות גדולות וקטנות, שמות שמפנים לאותו קובץ (כגון Agents.md וAGENTS.md) עוברים הסרת כפילויות ונספרים פעם אחת. Claude.md, CLAUDE.md וCLAUDE.local.md נתמכים לצורך תאימות עם תהליכי עבודה של Claude Code. כאשר תאימות לClaude מופעלת (ברירת המחדל), Grok סורק גם את תיקיית הבית ~/.claude/ עבור שמות קבצים אלה, ובכל רמת תיקייה בודק את .claude/CLAUDE.md ואת .claude/CLAUDE.local.md, המיקומים שבהם Claude Code משתמש עבור זיכרון פרויקט. כאשר תאימות לCursor מופעלת, תיקיית הבית ~/.cursor/ נסרקת באותו אופן.

#תיקיות כללים

בנוסף לקובצי AGENTS.md, Grok סורק קובצי *.md בתיקיות כללים בכל רמה (<dir>) משורש המאגר ועד לתיקיית העבודה הנוכחית:

Grok סורק גם כללים ברמת תיקיית הבית, ללא קשר למקום שבו הוא מתחיל. שורשים אלה כבר ספציפיים לספק, ולכן כללים נמצאים ישירות תחת rules/:

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

[paths]
extra_rule_dirs = ["~/team-rules", "/opt/company/grok-rules"]

כל קובץ *.md ישירות בתוך תיקייה שברשימה נטען ככלל (תיקיות משנה אינן נסרקות), בכל פרויקט וללא קשר למתן אמון בתיקייה, ל.gitignore של המאגר או לתאי התאימות: המודל מקבל אותם כuser rules וgrok inspect מציג אותם כglobal. רשומות חייבות להיות מוחלטות או להתחיל ב~/, רשומה יחסית או חסרה אינה טוענת דבר. הפקודה /import-claude כותבת את ~/.claude/rules/ הקיים שלך לכאן כדי שימשיך להיטען לאחר כיבוי סריקת התאימות לClaude. תאי rules של הספק שולטים הן בכללי בית והן בכללי פרויקט, ללא תלות בתאי agents התואמים. תא agents של Claude שולט בקבצים בעלי שמות תחת ~/.claude/ ובקובצי <dir>/.claude/CLAUDE*.md של הפרויקט, שמות כלליים ברמה העליונה כגון Claude.md, CLAUDE.md וCLAUDE.local.md נשארים מזוהים. ראה Configuration.

#כיצד פועל תהליך הגילוי

Grok סורק כללי פרויקט בסדר זה:

1. כללי בית: $GROK_HOME, לאחר מכן מקורות ~/.claude/ ו~/.cursor/ שמופעלים, ולאחר מכן [paths] extra_rule_dirs
2. כללי מאגר: אם נמצאים בתוך מאגר git, כל תיקייה משורש המאגר ומטה עד לתיקיית העבודה הנוכחית (כולל)
3. תיקיית עבודה נוכחית בלבד: אם לא נמצאים בתוך מאגר git, רק תיקיית העבודה הנוכחית

#דוגמה

בהינתן מבנה פרויקט זה:

~/projects/my-app/
  AGENTS.md              
# "Use TypeScript. Follow ESLint rules."
  src/
    AGENTS.md            
# "Prefer functional components."
    components/
      AGENTS.md          
# "Use CSS modules for styling."

כאשר Grok רץ ב~/projects/my-app/src/components/, הוא טוען את כל שלושת הקבצים. ההוראות מצטברות, כך שGrok רואה את כולן.

#קבצים עמוקים יותר מקבלים עדיפות

Grok מסדר את הקבצים משורש המאגר ועד לתיקיית העבודה הנוכחית, כך שקבצים בתיקיות עמוקות יותר מופיעים מאוחר יותר בהקשר שלו ומקבלים עדיפות כאשר הוראות מתנגשות. בדוגמה שלעיל, אם קובץ השורש מציין "Use styled-components" אך components/AGENTS.md מציין "Use CSS modules", ההוראה של CSS modules מנצחת מכיוון שהיא מופיעה מאוחר יותר.

#התנהגות טעינה אוטומטית

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

#מה לשים בכללי פרויקט

#מוסכמות קידוד

# Coding Standards

- Use TypeScript for all new code
- Prefer functional components with hooks over class components
- Use `const` by default; only use `let` when reassignment is needed
- Maximum line length: 100 characters

#הוראות בנייה ובדיקה

# Build & Test

- Run `npm test` before committing
- Use `npm run lint` to check code style
- Build with `npm run build` -- ensure no TypeScript errors
- Integration tests: `npm run test:e2e` (requires Docker)

#מדריכי סגנון

# Style Guide

- Follow the Airbnb JavaScript Style Guide
- Use 2-space indentation
- Always use trailing commas in multi-line arrays/objects
- Prefer template literals over string concatenation

#דרישות PR ו-Commit

# Version Control

- Write commit messages in conventional commits format
- Prefix branch names with `feature/`, `fix/`, or `chore/`
- All PRs require at least one approval before merge
- Squash-merge feature branches

#הערות ארכיטקטורה

# Architecture

- API routes go in `src/routes/` with one file per resource
- Business logic goes in `src/services/`
- Database queries go in `src/repositories/`
- Never import from `src/routes/` in `src/services/`

#הגבלת היקף כללים לתיקיות משנה

קובצי AGENTS.md חלים על כל עץ התיקיות ששורשו בתיקייה שלהם. השתמש בכך כדי לספק הוראות שונות לחלקים שונים של בסיס הקוד שלך:

my-monorepo/
  AGENTS.md                    
# Monorepo-wide rules
  packages/
    frontend/
      AGENTS.md                
# "Use React. Prefer CSS modules."
    backend/
      AGENTS.md                
# "Use Express. Follow REST conventions."
    shared/
      AGENTS.md                
# "No framework-specific code in this package."

#דגלי כללים להפעלה

כדי להוסיף כללים עבור הפעלה בודדת בלי לערוך קבצים, העבר את --rules (כינוי נוסף: --append-system-prompt):

grok --rules "Always use TypeScript. Prefer functional components."

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

כדי להחליף את הנחיית המערכת לחלוטין, העבר את --system-prompt-override (כינוי נוסף: --system-prompt). Grok משתמש בטקסט כלשונו ומדלג הן על הנחיית המערכת המוגדרת כברירת מחדל והן על --rules. (לעומת זאת, טקסט המועבר עם --rules נעטף בתוך בלוק <human_rules> ומצורף להנחיית ברירת המחדל).

#גודל קובץ

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

#סינון לפי Gitignore

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

# .gitignore
CLAUDE.local.md

כקובצי הוראות ברמה העליונה, Grok מגלה רק את שמות הקבצים המוכרים הרשומים תחת שמות קבצים נתמכים, ולא שמות מותאמים אישית כגון AGENTS.local.md או notes.md. (בתוך תיקיית כללים כגון .grok/rules/, כל קובץ *.md נטען ללא קשר לשמו).

#תיקיית הפרויקט .grok/

מעבר לקובצי AGENTS.md, תיקיית .grok/ בשורש הפרויקט שלך יכולה להכיל תצורה נוספת ברמת הפרויקט:

כל אלה אופציונליים. ראה את המדריכים המתאימים לפרטים על כל אחד מהם.

#בדיקת כללים שנטענו

השתמש בgrok inspect כדי לראות את כל הוראות הפרויקט שנטענו:

grok inspect

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

#שיטות מומלצות

1. התחל בשורש. שים את הכללים החשובים ביותר שחלים על כל הפרויקט בקובץ AGENTS.md בשורש המאגר.

2. היה ספציפי. "Use TypeScript" עדיף על "Use modern JavaScript". "Run cargo fmt before committing" עדיף על "Format your code".

3. שמור על זה קצר. יש סבירות גבוהה יותר שGrok יפעל לפי הוראות תמציתיות מאשר לפי הוראות ארוכות.

4. השתמש בהגבלת היקף לתיקיות משנה עבור מאגרים גדולים. לחלקים שונים ב-monorepo עשויות להיות מוסכמות שונות. השתמש בAGENTS.md לכל תיקייה כדי להגדיר את היקף הכללים כראוי.

5. נהל גרסאות לכללים שלך. בצע commit לקובץ AGENTS.md לתוך המאגר כדי שכל הצוות יפיק תועלת. עקיפות ספציפיות למשתמש שייכות ל~/.grok/ (כללים גלובליים).

6. אל תשכפל תיעוד. AGENTS.md צריך להכיל הוראות בנות ביצוע, ולא עותק של ה-README של הפרויקט שלך. קשר לתיעוד חיצוני במידת הצורך.

7. סקור מעת לעת. ככל שהפרויקט שלך מתפתח, עדכן את הכללים שלך כך שיתאימו למוסכמות הנוכחיות.