Skip to content

CLAUDE.md

Latest commit

 

History

History
387 lines (264 loc) · 15.8 KB

CLAUDE.md

File metadata and controls

387 lines (264 loc) · 15.8 KB
Raw

Android & AI Style Rules

מתי להשתמש: בכל שינוי/PR – כללי סגנון ותשובות ראו גם: Commit/PR

כללי כתיבה

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

תהליך עבודה

  1. קודם מתכננים – לפני כל מימוש, יש להציג תוכנית עבודה ברורה (עם הסברים בשפה פשוטה ומובנת לכל)
  2. אחר כך מממשים – המימוש מתחיל רק לאחר אישור התוכנית.
  3. אין רשות לדלג בשלב המימוש על חלקים כלשהם מתוך תוכניות מימוש שנמסרות לך, יש לממש את כל מה שבתכניות/מסמכי מימוש.

כלל חשוב:

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

שפה

  • תקשורת בצ'אט — בעברית
  • המחשבות (thinking / reasoning) — גם בעברית.
  • סיכומי PR, תיאורי commit — בעברית
  • הערות בקוד ℹ️ (comments) — בעברית
  • שמות משתנים, פונקציות, וטבלאות — באנגלית (כמקובל)

פורמטור HTML/Jinja

מתי להשתמש: בעת עבודה עם קבצי תבניות Jinja ב־webapp/templates/**/*.html

  • אל תריצו Prettier (או כל פורמטור אוטומטי אחר) על קבצי Jinja, כי הוא שובר בלוקים של {% ... %}/{{ ... }}. אם צריך יישור קוסמטי – ערכו ידנית.
  • אם חייבים להריץ Prettier על קבצים אחרים, הוסיפו את התיקייה webapp/templates/ לקובץ .prettierignore כדי למנוע הרצה בטעות.

הימנעות ממחיקות קבצים בטסטים ובסקריפטים

מתי להשתמש: טסטים/סקריפטים שנוגעים לקבצים או ניקוי ראו גם: CI / Required Checks, מעטפת Bash למחיקה בטוחה

1. עבוד רק על תיקיות זמניות

  • השתמש ב-tmp לכל קלט/פלט בטסטים (pytest: tmp_path)
  • אל תכתוב או תמחק ב-root של הפרויקט או בתיקיות קוד מקור

2. קבע ENV/קונפיג למסלולי tmp בלבד

  • ודא ש-ENV כמו OUTPUT_DIR/WORKDIR מוגדרים לתיקיות tmp
  • בדוק שהם לא ריקים לפני שימוש (assert ולא default ל-".")

3. אל תשתמש בגלובים גורפים

  • הימנע מ-rm -rf */* או תבניות כמו build*
  • העדף allowlist שמיועד לתת-תיקיה אחת ספציפית

4. סורגי בטיחות לפני מחיקה

  • אל תמחק אם הנתיב לא מתחת ל-allowlist
  • אל תמחק נתיבים מסוכנים: /, ., ספריית הפרויקט

דוגמת Python למחיקה בטוחה

from pathlib import Path
import shutil

def safe_rmtree(path: Path, allow_under: Path) -> None:
    p = path.resolve()
    base = allow_under.resolve()
    if not str(p).startswith(str(base)) or p in (Path('/'), base.parent, Path.cwd()):
        raise RuntimeError(f"Refusing to delete unsafe path: {p}")
    shutil.rmtree(p)

5. הימנע משינוי cwd

  • אם חייב, שמור/שחזר cwd, והשתמש בנתיבים מוחלטים למחיקה

6. נטרל ניקוי מסוכן ב-CI

  • הימנע מ-git clean/reset על ה-workspace
  • אם חייב, עבוד על clone זמני בלבד

7. במקביליות – הפרד תיקיות עבודה

  • לכל טסט UUID ייחודי (לדוגמה: /tmp/app-test-<uuid>)
  • או סדר טסטים שנוגעים לקבצים לריצה סריאלית

8. בדוק תקלות מוקדם

  • הרחק הרשאות כתיבה מ-src בתקופת הטסטים (chmod -w)
  • כרוך קריאות מחיקה ב-wrapper בטוח כדי להעלות חריגה מוקדם

בדיקת קוד לאיתור מחיקות לא בטוחות

rg -n "(shutil.rmtree|os.remove|Path.unlink|rm -rf|rimraf)" -S

שחזור לאחר מחיקה בטעות

  • אל תבצע merge/PR כדי לא לדרוס היסטוריה
  • בצע git restore/git checkout לקבצים או git revert לקומיטים
  • אם אין היסטוריה מקומית: שחזר מ-CI artifacts/ענף גיבוי/מכונה אחרת

קישור לתיעוד והקשר

מתי להשתמש: בכל PR/מסמך – מדיניות וקישורים רלוונטיים

  • קרא והסתמך על התיעוד: CodeBot – Project Docs
  • קובץ זה הוא מדיניות מחייבת לצוות; יש להפנות אליו ב-PRs ובתיעוד
  • ⚠️ לפני כל תיקון טסטים פתח את CodeBot Docs וקרא את הנחיות הטסטים הרלוונטיות (async, aiohttp, cleanup וכו') לפני ביצוע שינוי

ChatOps – מודעות ושילוב

מתי להשתמש: בכל משימה שדורשת מידע בזמן אמת (request_id, מצב שירות, תקלות פעילות, דיוק חיזוי)

  • קיימת מערכת ChatOps פעילה עם פקודות כמו /triage, /predict, /status, /errors ועוד
  • כשנדרש מידע כזה: אל תסיק מתוך הקוד. בקש מהמשתמש להריץ את הפקודה המתאימה בבוט ושתף את הפלט
  • פלט הבוט הוא מקור האמת (Source of Truth) עבור החלטות ותשובות

דוגמה כהנחיה פורמלית

# 🤖 ChatOps Awareness
- name: ChatOps Integration
  description: |
    דע כי קיימת מערכת ChatOps פעילה עם פקודות כמו /triage, /predict, /status, /errors ועוד.
    כאשר נדרש מידע בזמן אמת (כגון request_id, מצב שירות, תקלות פעילות, או דיוק חיזוי),
    **אל תסיק מתוך הקוד** – התייעץ עם המשתמש ובקש ממנו להריץ את הפקודה המתאימה בבוט ושתף את הפלט.
    המידע שיחזור מהבוט נחשב למקור האמת.

כללי שימוש ב-AI/CodeBot

מתי להשתמש: בכל שימוש ב-AI/אוטומציה בקוד וב-PRים

  • כל שינוי שמוצע על ידי AI עובר code review אנושי לפני merge
  • אין להזין סודות, מפתחות או PII לפרומפטים או קבצי הקשר
  • פקודות שמורצות אוטומטית: ללא sudo, לא אינטראקטיביות, ורק בתיקיות tmp
  • תעד ב-PR החלטות אוטומציה: מקור ההצעה, שיקולים ובדיקות שבוצעו

Android/Kotlin/Compose

מתי להשתמש: בפיתוח Android/Kotlin/Compose – סגנון, ארכיטקטורה וטסטים ראו גם: CI / Required Checks

Kotlin

  • העדף val על var, אי-שינוי, data/sealed classes
  • Null-safety ברורה

Concurrency

  • Coroutines עם Structured Concurrency
  • שימוש ב-viewModelScope/CoroutineScope נכון

זרימות נתונים

  • העדף Flow
  • מיפוי ב-Repository
  • Dispatchers מתאימים (IO/Default)

ארכיטקטורה

  • MVVM
  • Single Source of Truth
  • Repository/UseCases
  • DI עם Hilt

Compose

  • State hoisting
  • remember/derivedStateOf
  • הימנע מ-side effects בתוך Composables
  • שימוש ב-LaunchedEffect/DisposableEffect
  • בדיקות עם compose-ui-test

Commit/PR

מתי להשתמש: כשכותבים קומיטים או פותחים Pull Request ראו גם: CI / Required Checks, קישור לתיעוד והקשר

שמות ענפים

fix/..., chore/..., feat/...

Conventional Commits

feat/fix/chore/docs/refactor/test/build

תיאור PR

  • תיאור קצר ב-HTML: What / Why / Tests
  • כולל לינק ל-RTD build/preview אם יש
  • מלא PR לפי התבנית שב-.github/pull_request_template.md
  • צרף Docs Preview, בדיקות, צ'קליסט ו-Rollback
  • ציין מפורשות האם עיינת ב-CodeBot – Project Docs

לפני merge

  • תיאור ברור
  • תוכנית בדיקות
  • סיכוני Rollback
  • עדכון docs

UI

צרף צילום/וידאו תוצאות אם רלוונטי

הערה: טבלת דוגמאות ל-Conventional Commits והצ'קליסט לפני merge נשמרים בתבנית ה-PR

CI / Required Checks

מתי להשתמש: לפני merge ובבדיקת סטטוסי CI ראו גם: הימנעות ממחיקות קבצים בטסטים ובסקריפטים

חובות

  • מעבר ירוק: ./gradlew test detekt ktlintCheck
  • אין להריץ git clean/reset על ה-workspace
  • עבודה רק על תיקיות זמניות
  • טסטים שנוגעים לקבצים ירוצו בסביבה מבודדת לכל טסט

סטטוסים נדרשים ב-PR

  • "🔍 Code Quality & Security"
  • "Unit Tests (3.11)"
  • "Unit Tests (3.12)"

נוספים

  • אין paths-ignore על .cursorrules – שינוי בו מריץ CI
  • שמור דיווח סטטוסים גם בגרסת legacy/plain אם נדרש למדיניות

סודות ולוגים

מתי להשתמש: בעת לוגים/קונפיג/אינטגרציות – מניעת דליפת מידע רגיש

  • אין לשמור סודות בקוד או בלוגים; השתמש ב-ENV/Secret Manager
  • אל תרשום PII; בצע השחרה (redaction) לערכים רגישים בלוגים

מעטפת Bash למחיקה בטוחה

מתי להשתמש: כשכותבים סקריפטי Bash שמבצעים מחיקות/ניקוי

set -euo pipefail
IFS=$'\n\t'

safe_rmrf() {
  local target="${1:-}"
  local allow_under="${2:-}"

  [[ -z "$target" || -z "$allow_under" ]] && { echo "empty path"; exit 1; }

  local rp_target rp_base
  rp_target="$(readlink -f -- "$target")"
  rp_base="$(readlink -f -- "$allow_under")"

  [[ "$rp_target" == "/" || "$rp_target" == "$HOME" || "$rp_target" == "$PWD" ]] && {
    echo "unsafe"; exit 1;
  }

  [[ "$rp_target" != "$rp_base"/* ]] && { echo "outside allowlist"; exit 1; }

  rm -rf -- "$rp_target"
}

Sphinx/RTD (תיעוד)

מתי להשתמש: בעת בנייה/עדכון תיעוד Sphinx/RTD

כללים

  • אין להריץ קוד בטופ-לבל בזמן build (importים חייבים להיות בטוחים)
  • RTD נחשב נכשל על אזהרות (fail_on_warning: true) – שמור 0 warnings
  • כל עמוד חדש חייב להירשם ב-docs/index.rst (ה-master document) בתוך toctree מתאים. עמוד שלא רשום מייצר אזהרת document isn't included in any toctree – ומכיוון ש-RTD נכשל על אזהרות, זה מפיל את הבילד. אם עמוד לא אמור להתפרסם – הוסף אותו ל-exclude_patterns ב-docs/conf.py במקום להשאיר אותו "יתום"
  • השתמש ב-:noindex: בעמודי סקירה חופפים: api, database, handlers, services, configuration

הגדרות

  • autodoc_mock_imports: cairosvg, aiohttp, textstat, langdetect, pytest, search_engine, code_processor, integrations
  • exclude_patterns (ב-docs/conf.py) מרכז את העמודים שאינם ב-toctree בכוונה (למשל כפילויות .md/.rst). לפני שמוסיפים החרגה – ודא שהעמוד באמת לא אמור להיות בתוכן העניינים

Telegram Bot – מניעת "Message is not modified"

מתי להשתמש: בפיתוח/תחזוקת בוט Telegram בעת עריכת הודעות

כללים

  • כשנערכת רק המקלדת: השתמש ב-safe_edit_message_reply_markup (אותו טיפול חריגים)
  • תמיד קרא query.answer() לפני עריכה
  • עטוף edit_message_text/edit_message_reply_markup ב-wrapper שמתעלם מהשגיאה הזו בלבד
  • לא משתיקים BadRequest אחרים; רק המקרה "message is not modified" נבלם

דוגמה

import telegram.error

async def safe_edit(query, text, reply_markup=None, parse_mode=None):
    try:
        await query.edit_message_text(
            text=text,
            reply_markup=reply_markup,
            parse_mode=parse_mode
        )
    except telegram.error.BadRequest as e:
        if "message is not modified" in str(e).lower():
            return
        raise

GitHub – "📥 הורד קובץ מריפו"

מתי להשתמש: בפלואו הורדת קבצים מהריפו – התנהגות UI בטוחה

כללים

  • בכניסה לפלואו: browse_action=download, אפס multi_mode/safe_delete
  • במצב הורדה לא מציגים כפתורי מחיקה או מצב מחיקה
  • חזרה לתפריט בלבד מחזירה את המצב לעריכה/מחיקה (אם נדרש)

Gists/קישורים חיצוניים בהנחיות משתמש

מתי להשתמש: כשהמשתמש מצרף Gist/קישור בבקשה הנדסית

כללים

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

Performance & Optimization Architecture

מתי להשתמש: בכל פיתוח של Endpoint חדש, שאילתת DB, או דף ב־Webapp

1. חוק ה־Smart Projection (החרגת שדות כבדים)

  • לעולם אל תמשוך את השדות code, content, או raw_data בשאילתות שמחזירות רשימה/אוסף של קבצים.

  • השתמש תמיד בקבוע HEAVY_FIELDS_EXCLUDE_PROJECTION (מתוך database/repository.py).

  • משיכת תוכן מלא תתבצע רק בבקשה מפורשת (Explicit Fetch) עבור צפייה או עריכה של קובץ בודד.

2. מטא־דאטה במקום חישובים בזיכרון

  • העדף שימוש בשדות מחושבים ב־DB כמו file_size ו־lines_count.

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

3. אופטימיזציית חיפוש (The Snippet Pattern)

  • בחיפוש קוד, אל תחזיר את כל הקובץ מה־API.

  • השתמש ב־Aggregation של MongoDB ($regexFind) כדי לחתוך רק את קטע הקוד הרלוונטי (Snippet) כבר ברמת בסיס הנתונים.

4. אינדקסים כחלק מהפיתוח

  • כל שאילתה חדשה חייבת לעבור בדיקת אינדקסים ב־database/repository.py.

  • העדף אינדקסים מורכבים (Compound Indexes) הכוללים את ה־user_id יחד עם סטטוס המחיקה/מועדפים.

5. טעינה אסינכרונית ב־Webapp (Lazy Loading)

  • דפים כבדים ב־Webapp צריכים להחזיר HTML ראשוני מהר (< 200ms).

  • השתמש ב־Skeleton Loaders ובשליפת נתונים מה־API דרך JavaScript ברקע.

  • עטוף חישובים כבדים ב־await asyncio.to_thread(...) כדי לא לחסום את ה־Event Loop.