📘 תיעוד 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 של המאגר, או לתאי התאימות. המודל מקבל אותם ככללי משתמש, ו-grok inspect מציג אותם כ-global. רשומות חייבות להיות מוחלטות או להתחיל ב-~/. רשומה יחסית או חסרה לא טוענת דבר. /import-claude כותב את ~/.claude/rules/ הקיים לכאן, כדי שהטעינה תימשך אחרי שסריקת התאימות ל-Claude כבויה. תאי rules של הספק שולטים גם בכללי הבית וגם בכללי הפרויקט, בנפרד מתאי agents התואמים. תא agents של Claude שולט בקבצים בעלי שם תחת ~/.claude/ וב-<dir>/.claude/CLAUDE*.md של הפרויקט. שמות כלליים ברמה העליונה, כמו Claude.md, CLAUDE.md ו-CLAUDE.local.md, ממשיכים להיות מזוהים. ראה הגדרות.

#איך הגילוי עובד

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

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

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

• Grok טוען את הקבצים משורש המאגר עד תיקיית העבודה הנוכחית באופן אוטומטי בתחילת הסשן.
• בתחילת הסשן, קובץ פרויקט או כלל שהוא symlink נטען רק כשהיעד שלו נמצא בתוך המאגר. Grok משתמש בתיקיית העבודה הנוכחית במקום זאת כשאין מאגר, כשהגדרת core.worktree מזיזה את עץ העבודה מהתיקייה שמחזיקה את .git שלו, או כשהתיקייה הזו היא תיקיית הבית או שורש מערכת הקבצים. כללי בית ו-extra_rule_dirs עוקבים אחרי symlinks בכל מקום.
• כש-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 עטוף בבלוק <human_rules> ומצורף, אחרי הנחיית ברירת המחדל או אחרי הטקסט של --system-prompt-override כששניהם ניתנים.

#גודל קובץ

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. שמור על קיצור. הוראות תמציתיות צפויות יותר להיות במעקב מהוראות ארוכות.

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

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

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

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