📘 תיעוד 5

כללים

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

Cursor תומך בארבעה סוגי כללים:

#כללי פרויקט

מאוחסנים ב-.cursor/rules, מנוהלים בבקרת גרסאות ומוגבלים לבסיס הקוד שלך.

#כללי משתמש

גלובליים לסביבת Cursor שלך. בשימוש על ידי Agent (Chat).

#כללי צוות

כללים לכלל הצוות המנוהלים מתוך לוח הבקרה. זמינים בתוכניות Team ו-Enterprise.

#AGENTS.md

הוראות ל-Agent בפורמט markdown. חלופה פשוטה ל-.cursor/rules.

#כיצד כללים עובדים

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

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

#כללי פרויקט

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

השתמש בכללי פרויקט כדי:

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

#מבנה קובץ כלל

כל כלל הוא קובץ .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 פועלים יחד כדי לקבוע מתי כלל ייכלל:

---
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

---
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

---
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

---
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. מתוך Customize תוכל לראות את כל הכללים ואת הסטטוס שלהם.

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

כללים טובים הם ממוקדים, ישימים ומוגדרים היטב בהיקפם.

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

#ממה להימנע בכללים

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

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

בצע שמירה של הכללים שלך ב-git כדי שכל הצוות שלך ירוויח. כשאתה רואה ש-Agent עושה טעות, עדכן את הכלל. אתה יכול אפילו לתייג את @cursor ב-issue או PR ב-GitHub כדי שה-Agent יעדכן את הכלל עבורך.

#פורמט קובץ כלל

כל כלל הוא קובץ markdown עם מטא-נתונים של frontmatter ותוכן. מטא-נתוני ה-frontmatter משמשים לשליטה באופן החלת הכלל. התוכן הוא הכלל עצמו.

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

...rest of the rule content

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

#דוגמאות

#תקנים עבור רכיבי frontend ואימות API

כלל זה מספק תקנים עבור רכיבי frontend:

בעת עבודה בספריית components:

• השתמש תמיד ב-Tailwind לעיצוב
• השתמש ב-Framer Motion לאנימציות
• פעל לפי מוסכמות שיום רכיבים

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

בספריית API:

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

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

כלל זה מספק תבנית עבור שירותי Express:

השתמש בתבנית זו בעת יצירת שירות Express:

• פעל לפי עקרונות RESTful
• כלול middleware לטיפול בשגיאות
• הגדר רישום יומנים מתאים

@express-service-template.ts

כלל זה מגדיר את מבנה רכיבי React:

רכיבי React צריכים לפעול לפי מבנה זה:

• ממשק props בחלק העליון
• רכיב כ-named export
• סגנונות בחלק התחתון

@component-template.tsx

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

כלל זה הופך ניתוח אפליקציה לאוטומטי:

כאשר מתבקש ניתוח של האפליקציה:

1. הפעל את שרת הפיתוח באמצעות npm run dev
2. משוך יומנים מהקונסולה
3. הצע שיפורי ביצועים

כלל זה מסייע ביצירת תיעוד:

עזור בניסוח תיעוד על ידי:

• חילוץ הערות קוד
• ניתוח README.md
• יצירת תיעוד markdown

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

תחילה צור מאפיין למיתוג ב-@reactiveStorageTypes.ts.

הוסף ערך ברירת מחדל ב-INIT_APPLICATION_USER_PERSISTENT_STORAGE ב-@reactiveStorageService.tsx.

עבור תכונות בטא, הוסף מתג ב-@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 ו-Enterprise יכולות ליצור ולאכוף כללים ברחבי הארגון כולו מתוך לוח הבקרה של Cursor. מנהלים יכולים להגדיר אם כל כלל הוא חובה עבור חברי הצוות או לא.

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

#ניהול כללי צוות

מנהלי צוות יכולים ליצור ולנהל כללים ישירות מלוח הבקרה של Cursor:

לאחר יצירת כללי צוות, הם מוחלים אוטומטית על כל חברי הצוות וגלויים בלוח הבקרה:

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

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

כברירת מחדל, כללי צוות שאינם נאכפים ניתנים להשבתה על ידי משתמשים. השתמש ב-Enforce this rule כדי למנוע זאת.

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

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

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

#ייבוא כללים ממאגר

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

#AGENTS.md

AGENTS.md הוא קובץ markdown פשוט להגדרת הוראות עבור Agent. מקם אותו בתיקיית השורש של הפרויקט שלך כחלופה ל-.cursor/rules עבור מקרי שימוש פשוטים.

בשונה מכללי פרויקט, AGENTS.md הוא קובץ markdown פשוט ללא מטא-נתונים או הגדרות מורכבות. הוא מושלם עבור פרויקטים הזקוקים להוראות פשוטות וקריאות ללא התקורה של כללים מובנים.

Cursor תומך ב-AGENTS.md בתיקיית השורש של הפרויקט ובספריות משנה.

# 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 מקונן

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

דבר זה מאפשר שליטה מדויקת יותר בהוראות ה-Agent בהתאם לאזור בבסיס הקוד שבו אתה עובד:

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

#כללי משתמש

כללי משתמש הם העדפות גלובליות המוגדרות ב-Customize → Rules אשר חלות על כל הפרויקטים. הם בשימוש על ידי Agent (Chat) ומתאימים לקביעת סגנון תקשורת מועדף או מוסכמות קידוד:

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

#שאלות נפוצות

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

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

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

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

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

כן, אתה יכול לבקש מה-Agent ליצור כלל חדש עבורך.

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

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

#האם כללי משתמש חלים על עריכה בתוך השורה (Cmd/Ctrl+K)?

לא. כללי משתמש אינם מוחלים על עריכה בתוך השורה (Cmd/Ctrl+K). הם בשימוש רק על ידי Agent (Chat).

#נושאים קשורים

• Rules help

#מפת האתר

סקירה של כל דפי התיעוד