📜 פרק 8

חוקים, חוקי צוות ו-AGENTS.md

מודלי שפה אינם שומרים זיכרון בין פעולות שונות. חוקים (Rules) מספקים הקשר קבוע לשימוש חוזר ברמת הפרומפט. כאשר חוק מופעל, התוכן שלו נכלל בתחילת ההקשר של המודל, וכך מספק ל-Agent הנחיות עקביות ליצירת קוד, להבנת שינויים ולתמיכה בתהליכי עבודה.

Cursor תומך בארבעה סוגי חוקים:

1. חוקי פרויקט (Project Rules): מאוחסנים בתיקיית .cursor/rules, מנוהלים ב-Git ותחומים לקוד של הפרויקט.
2. חוקי משתמש (User Rules): הגדרות גלובליות לסביבת Cursor שלכם, המשמשות את Agent בצ'אט.
3. חוקי צוות (Team Rules): חוקים כלל-ארגוניים המנוהלים מלוח הבקרה (dashboard), וזמינים במסלולי Team ו-Enterprise.
4. קובץ AGENTS.md: הנחיות סוכן בפורמט Markdown פשוט, המהוות חלופה קלה ל-.cursor/rules.

#חוקי פרויקט (Project Rules)

חוקי פרויקט יושבים בתיקיית .cursor/rules כקובצי .mdc ונשמרים בניהול גרסאות ב-Git. התחולה שלהם נקבעת לפי תבניות נתיבים, הפעלה ידנית, או התאמה להקשר לפי רלוונטיות.

שימושים מרכזיים בחוקי פרויקט:

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

#מבנה קובץ חוק

כל חוק מוגדר בקובץ .mdc שניתן לתת לו כל שם. חוקי פרויקט חייבים להשתמש בסיומת .mdc. מערכת החוקים מתעלמת מקובצי .md רגילים שמונחים בתיקיית .cursor/rules, מכיוון שאין להם בלוק Frontmatter להגדרת description, globs ו-alwaysApply. אם אתם מעדיפים Markdown רגיל, השתמשו ב-AGENTS.md.

ניתן לארגן את הקבצים גם בתוך תיקיות פנימיות:

.cursor/rules/
  react-patterns.mdc       
# Recognized as a project rule
  api-guidelines.md        
# Ignored (wrong extension)
  frontend/                
# Organize rules in folders
    components.mdc

#אנטומיית החוק ואופני הפעלה

כל חוק הוא קובץ Markdown הכולל מטא-דאטה ב-Frontmatter ותוכן. בחירת סוג החוק בתפריט משנה את המאפיינים description, globs ו-alwaysApply.

מאחורי הקלעים, שלושת השדות ב-Frontmatter פועלים יחד וקובעים כיצד החוק ייכלל:

#דוגמה לחוק שחל תמיד (Always applied)

---
alwaysApply: true
---

- All source files must include the company copyright header
- When you are unsure about implementation details, read the relevant
  source files before proposing changes
- Never modify generated files in the `dist/` or `build/` directories

#דוגמה לחוק המצורף אוטומטית לפי תבנית קבצים (Auto-attached by file pattern)

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports
- Co-locate styles in a module CSS file next to the component
- Keep components under 200 lines. Extract subcomponents into the same
  directory when a file grows beyond that
- Prefer composition over prop drilling. Pass children or render props
  instead of threading data through multiple layers

#דוגמה לחוק שנבחר על ידי הסוכן לפי תיאור (Agent-selected based on description)

---
description: RPC service conventions and patterns for the backend
alwaysApply: false
---

- Define each service in its own file under `src/services/`
- Always validate inputs at the service boundary before passing data
  to internal functions
- Return structured error objects with a `code` and `message` field,
  never throw raw strings
- Add a `@service-template.ts` reference file when creating a new
  service for the standard boilerplate

#דוגמה לחוק ידני שמופעל רק באמצעות תיוג @ (Manual)

---
alwaysApply: false
---

- Every database migration must have both `up` and `down` functions
  so it can be fully reversed
- Never alter a column type in-place. Add a new column, backfill,
  then drop the old one in a separate migration
- Reference the template for the expected file structure

@migration-template.sql

#דוגמאות לתבניות Glob

השתמשו ב-globs כדי להגדיר את תחולת החוק לקבצים או לתיקיות מסוימות. ניתן להגדיר מספר תבניות מופרדות בפסיקים:

#יצירת חוק

קיימות שתי דרכים ליצירת חוקים:

• באמצעות פקודת /create-rule בצ'אט: מקלידים /create-rule ב-Agent ומתארים את החוק המבוקש. ה-Agent מייצר את קובץ החוק עם ה-Frontmatter הנדרש ושומר אותו ב-.cursor/rules.
• מתוך מסך Customize: פותחים את Customize בסרגל הצד, עוברים אל Rules, ולוחצים על Add Rule. פעולה זו יוצרת קובץ חוק חדש ב-.cursor/rules. מתוך מסך זה ניתן לראות את כל החוקים ואת הסטטוס שלהם.

#שיטות מומלצות וממה להימנע

חוקים יעילים הם חוקים ממוקדים, מעשיים ותחומים היטב:

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

#ממה להימנע בכתיבת חוקים

• העתקת מדריכי סגנון שלמים: השתמשו ב-linter. ה-Agent כבר מכיר מוסכמות סגנון נפוצות.
• תיעוד כל פקודה אפשרית: ה-Agent מכיר כלים מוכרים כמו npm, git ו-pytest.
• הוספת הנחיות למקרי קצה נדירים: שמרו את החוקים ממוקדים בדפוסים שנמצאים בשימוש תדיר.
• שכפול קוד שכבר קיים בפרויקט: הפנו לדוגמאות קנוניות במקום להעתיק קוד.

התחילו בפשטות. הוסיפו חוק רק כאשר אתם מבחינים שה-Agent חוזר על אותה טעות מספר פעמים, ואל תבצעו אופטימיזציית יתר מראש.

שמרו את החוקים ב-Git כדי שכל הצוות ייהנה מהם. כאשר אתם מזהים טעות של הסוכן, עדכנו את החוק. ניתן גם לתייג את @cursor ב-Issue או ב-Pull Request ב-GitHub כדי שהסוכן יעדכן את החוק בעצמו.

#מבנה תוכן קובץ החוק

כל חוק מורכב ממטא-דאטה ב-Frontmatter ומגוף החוק:

---
description: "This rule provides standards for frontend components and API validation"
alwaysApply: false
---

...rest of the rule content

כאשר alwaysApply מוגדר כ-true, החוק יופעל בכל שיחת צ'אט. אחרת, התיאור (description) יוצג ל-Agent כדי שיחליט האם להפעיל אותו.

#דוגמאות מהתיעוד

#סטנדרטים לרכיבי צד לקוח ואימות API

כלל זה מגדיר סטנדרטים לרכיבי Frontend:

When working in components directory:

- Always use Tailwind for styling
- Use Framer Motion for animations
- Follow component naming conventions

וכלל זה אוכף ולידציה עבור נקודות קצה ב-API:

In API directory:

- Use zod for all validation
- Define return types with zod schemas
- Export types generated from schemas

#תבניות לשירותי Express ורכיבי React

תבנית ליצירת שירות Express:

Use this template when creating Express service:

- Follow RESTful principles
- Include error handling middleware
- Set up proper logging

@express-service-template.ts

מבנה רכיב React:

React components should follow this layout:

- Props interface at top
- Component as named export
- Styles at bottom

@component-template.tsx

#אוטומציה של תהליכי פיתוח ויצירת תיעוד

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

When asked to analyze the app:

1. Run dev server with `npm run dev`
2. Fetch logs from console
3. Suggest performance improvements

יצירת טיוטת תיעוד:

Help draft documentation by:

- Extracting code comments
- Analyzing README.md
- Generating markdown documentation

#הוספת הגדרה חדשה בתוך Cursor

הליך הוספת הגדרה לפי התיעוד הרשמי:

1. תחילה יוצרים מאפיין מתאים בקובץ @reactiveStorageTypes.ts.
2. מוסיפים ערך ברירת מחדל בתוך INIT_APPLICATION_USER_PERSISTENT_STORAGE בקובץ @reactiveStorageService.tsx.
3. עבור תכונות בטא, מוסיפים מתג ב-@settingsBetaTab.tsx. עבור תכונות רגילות, מוסיפים ב-@settingsGeneralTab.tsx. ניתן להוסיף מתגים כרכיב <SettingsSubSection> עבור תיבות סימון כלליות:

<SettingsSubSection
  label="Your feature name"
  description="Your feature description"
  value={
    vsContext.reactiveStorageService.applicationUserPersistentStorage
      .myNewProperty ?? false
  }
  onChange={(newVal) => {
    vsContext.reactiveStorageService.setApplicationUserPersistentStorage(
      "myNewProperty",
      newVal,
    );
  }}
/>

כדי להשתמש בהגדרה באפליקציה, מייבאים את reactiveStorageService ומשתמשים במאפיין:

const flagIsEnabled =
  vsContext.reactiveStorageService.applicationUserPersistentStorage
    .myNewProperty;

#חוקי צוות (Team Rules)

מנויי תוכניות Team ו-Enterprise יכולים להגדיר ולאכוף חוקים עבור כלל הארגון ישירות מלוח הבקרה של Cursor בכתובת cursor.com/dashboard/team-content. מנהלי מערכת (Admins) יכולים לקבוע האם כל חוק הוא חובה עבור חברי הצוות.

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

#הפעלה ואכיפה

• Enable this rule immediately: כאשר אפשרות זו מסומנת, החוק פעיל מיד עם יצירתו. כאשר אינה מסומנת, החוק נשמר כטיוטה ולא חל עד שתפעילו אותו מאוחר יותר.
• Enforce this rule: כאשר אפשרות זו מופעלת, החוק הופך לחובה עבור כל חברי הצוות ולא ניתן לכבות אותו במסך Customize. כאשר אינה מופעלת, חברי צוות יכולים לכבות את החוק תחת Team Rules במסך Customize. כברירת מחדל, חוקי צוות שאינם נאכפים ניתנים לכיבוי על ידי המשתמש.

#פורמט ואופן החלת חוקי צוות

• מבנה התוכן: חוקי צוות נכתבים כטקסט חופשי ואינם דורשים את מבנה התיקיות של חוקי פרויקט.
• תבניות Glob: חוקי צוות תומכים בתבניות glob לצורך הגדרת תחולה לקבצים מסוימים (למשל **/*.py). כאשר מוגדרת תבנית glob, החוק יחול רק כשקבצים תואמים נמצאים בהקשר. חוקים ללא תבנית glob חלים על כל שיחה.
• מיקום ההחלה: כאשר חוק צוות פעיל (ולא כובה על ידי המשתמש, אלא אם הוא נאכף), הוא נכלל בהקשר המודל עבור Agent בצ'אט בכל המאגרים והפרויקטים של אותו צוות.
• סדר קדימות: חוקים מוחלים לפי הסדר הבא: חוקי צוות -> חוקי פרויקט -> חוקי משתמש (Team Rules -> Project Rules -> User Rules). כל החוקים הרלוונטיים ממוזגים יחד, ובמקרה של הנחיות סותרות, המקור המוקדם יותר בסדר הקדימות קובע.
• אבטחה ותאימות: צוותים מסוימים משתמשים בחוקים נאכפים כחלק מתהליכי compliance פנימיים, אך הנחיות AI אינן מהוות בקרת אבטחה בלעדית.

#ייבוא חוקים ממאגר (Importing rules from a repository)

חוקים אינם מיובאים באופן עצמאי. כדי לייבא חוקים ממאגר GitHub, אורזים אותם בתוסף (plugin) ומפרסמים אותו דרך marketplace לפי השלבים הבאים:

1. מייבאים את המאגר במסך Customize באמצעות האפשרות From GitHub Repository (המאגר נדרש לכלול קובץ .cursor-plugin/marketplace.json), או מוסיפים אותו כ-team marketplace.
2. מתקינים את התוסף. החוקים מגיעים יחד עם התוסף ומוצגים במסך Customize לצד שאר החוקים שלכם.

#קובץ AGENTS.md

קובץ AGENTS.md הוא קובץ Markdown פשוט להגדרת הנחיות סוכן. מניחים אותו בשורש הפרויקט כחלופה ישירה ל-.cursor/rules במקרים שאינם דורשים תצורה מורכבת. הקובץ אינו כולל מטא-דאטה ב-Frontmatter וקריא לחלוטין לבני אדם.

# Project Instructions

## Code Style

- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture

- Follow the repository pattern
- Keep business logic in service layers

#תמיכה ב-AGENTS.md מקונן (Nested AGENTS.md support)

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

project/
  AGENTS.md              
# Global instructions
  frontend/
    AGENTS.md            
# Frontend-specific instructions
    components/
      AGENTS.md          
# Component-specific instructions
  backend/
    AGENTS.md            
# Backend-specific instructions

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

#חוקי משתמש (User Rules)

חוקי משתמש הם העדפות גלובליות המוגדרות תחת Customize -> Rules וחלות על כל הפרויקטים. הם משמשים את Agent בצ'אט ומתאימים לקביעת סגנון תקשורת או מוסכמות עבודה אישיות:

Please reply in a concise style. Avoid unnecessary repetition or filler language.

#שאלות נפוצות ומלכודות (FAQ)

#מדוע החוק שלי אינו מופעל?

בדקו את סוג החוק. עבור Apply Intelligently, ודאו שהוגדר שדה description. עבור Apply to Specific Files, ודאו שתבנית הקבצים תואמת לקבצים שנמצאים בהקשר.

#האם חוקים יכולים להפנות לקבצים או לחוקים אחרים?

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

#האם ניתן ליצור חוק מתוך הצ'אט?

כן, ניתן לבקש ישירות מהסוכן ליצור חוק חדש עבורכם.

#האם חוקים משפיעים על Cursor Tab או יכולות AI אחרות?

לא. חוקים אינם משפיעים על Cursor Tab ואינם משפיעים על תכונות AI אחרות.

#האם חוקי משתמש (User Rules) חלים על Inline Edit באמצעות Cmd/Ctrl+K?

לא. חוקי משתמש אינם חלים על Inline Edit (Cmd+K או Ctrl+K), אלא מיועדים אך ורק לשימוש על ידי Agent בצ'אט.