📘 תיעוד 31

התאמה אישית של Code Review

כוונון של מה ש Code Review מסמן בבקשות המשיכה באמצעות REVIEW.md ו CLAUDE.md: כיול מחדש של חומרה, דילוג על נתיבים, הוספת בדיקות, וראייה איזה עותק חל.

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

• CLAUDE.md: הוראות פרויקט ש Claude Code קורא לכל משימה, כולל סקירות. Code Review קורא אותן כהקשר הפרויקט ומסמן שינויים שמפרים אותן.
• REVIEW.md: הוראות לסקירות בלבד. משתמשים בו כדי לומר מה הצוות רוצה שיסומן, באיזו חומרה, ועל מה לדלג.

הוסיפו את REVIEW.md בשורש המאגר ומזגו אותו. אחר כך הגנו על ענף ברירת המחדל.

[!NOTE]

כדי לשנות עד כמה הסקירות יסודיות או מתי הן רצות, בקשו מ Owner לשנות את רמת הסקירה או את ההגדרה Review runs.

#שימוש ב CLAUDE.md לכללי הפרויקט כולו

Code Review קורא את קבצי CLAUDE.md של המאגר כהקשר הפרויקט. שינוי שמפר אחד מהכללים שלהם הופך לממצא ברמת החומרה שמתאימה לבעיה.

סקירה קוראת את CLAUDE.md בשורש המאגר ואת קבצי CLAUDE.md בתיקיות האב של כל קובץ שהשתנה. CLAUDE.md של תת תיקייה נקרא כשבקשת המשיכה משנה קובץ תחת הנתיב הזה.

#שימוש ב REVIEW.md לכללי סקירה בלבד

REVIEW.md הוא קובץ בשורש המאגר שמתאים את Code Review למאגר. בענף מוגן אפשר גם להוסיף REVIEW.md ברוב תתי התיקיות כדי להוסיף בדיקות לשינויים תחת תת התיקייה הזו, בנוסף לקובץ השורש.

הסוכנים שמוצאים בעיות והסוכנים שמאמתים אותן מקבלים את התוכן שלו כהוראות הסקירה של המאגר, לצד הנחיית הסקירה של ברירת המחדל של Code Review. השלב שכותב את הסקירה הסופית מתייעץ בו לפני קביעת החומרה וכתיבת הסיכום.

פריסת הדוגמה הזו כוללת קובץ שורש וקובץ אחד בתת תיקייה:

your-repo/
├── REVIEW.md            # Root file
├── services/
│   └── billing/
│       └── REVIEW.md    # Adds checks for changes under services/billing/
└── src/

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

[!NOTE]

שירות Code Review והפקודה המקומית /code-review הם שני כלים נפרדים, והם קוראים קבצים שונים. השירות קורא גם את CLAUDE.md וגם את REVIEW.md. הפקודה /code-review, שמריצים אותה בתוך סשן של Claude Code במחשב שלכם, קוראת את קבצי CLAUDE.md ולא את REVIEW.md. שימו הנחיה שרוצים שתחול בשני המקומות ב CLAUDE.md, ושמרו את REVIEW.md לכללים ייחודיים לסקירת בקשות משיכה.

#מתי REVIEW.md בתת תיקייה לא חל

Code Review לא מחיל REVIEW.md שנמצא בתוך תת תיקייה או מתחתיה כשלתת התיקייה אחד מהשמות האלה, בלי קשר לתוכן התת תיקייה. שם של תת תיקייה תואם רק כשם שלם, בכל מצב אותיות ובכל עומק, כך ש Tests תואם ו integration-tests לא:

• בדיקות: test, tests, __tests__, testdata, fixtures, __fixtures__, golden, corpus, snapshots, __snapshots__
• דוגמאות: example, examples, sample, samples, demo, demos
• קוד שנוצר: generated
• קוד של צד שלישי: vendor, third_party, third-party, thirdparty, node_modules, bower_components, external, extern, deps, godeps, pods, carthage, site-packages, contrib

שימו בדיקות לתתי התיקיות האלה ב REVIEW.md של השורש, או ב REVIEW.md של תת תיקיית אב כאשר לא ההורה הזה ולא שום דבר מעליו נמצאים ברשימה.

שאר קבצי REVIEW.md בתתי התיקיות, בנתיבים שבקשת המשיכה משנה, חולקים מגבלה של 150,000 בתים, בלי לספור את קובץ השורש. אם ריצת הבדיקה מדווחת שחלק מהם לא נכנסו, קצרו את הקבצים כדי להיכנס למגבלה הזו.

#דוגמה ל REVIEW.md

REVIEW.md הזה מכייל מחדש את החומרה עבור שירות צד שרת, מגביל הערות Nit, מדלג על קבצים שנוצרו, ומוסיף בדיקות ייחודיות למאגר.

# Review instructions

## What Important means here

Reserve Important for findings that would break behavior, leak data,
or block a rollback: incorrect logic, unscoped database queries, PII
in logs or error messages, and migrations that aren't backward
compatible. Style, naming, and refactoring suggestions are Nit at
most.

## Cap the nits

Report at most five Nits per review.

## Do not report

- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file
- Test-only code that intentionally violates production rules

## Always check

- New API routes have an integration test
- Log lines don't include email addresses, user IDs, or request bodies
- Database queries are scoped to the caller's tenant

#בחירה מה לכתוב ב REVIEW.md

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

• דברים לא נכונים מסומנים כ Important: הגדירו מחדש מה 🔴 Important אומר במאגר. כיול ברירת המחדל מכוון לקוד ייצור, ומאגר תיעוד, מאגר הגדרות, או אב טיפוס עשויים לרצות הגדרה צרה הרבה יותר. ציינו אילו סוגים של ממצאים הם Important ואילו הם Nit לכל היותר. אפשר גם להעלות חומרה, למשל להתייחס לכל הפרה של CLAUDE.md כ Important.
• יותר מדי הערות Nit: הגבילו כמה הערות 🟡 Nit סקירה אחת מפרסמת. מגבלה כמו "לדווח על לכל היותר חמש הערות Nit" שומרת על סקירות שאפשר לפעול לפיהן.
• הערות על קבצים שנוצרו או על מה ש CI כבר בודק: פרטו נתיבים וסוגי ממצאים שבהם Claude צריך לדלג על ממצאים. מועמדים נפוצים הם קוד שנוצר, קובצי נעילה, ותלויות vendored, וגם כל מה ש CI כבר אוכף כמו lint או בדיקת איות. לנתיבים שמצדיקים סקירה חלקית אבל לא בדיקה מלאה, הציבו רף גבוה יותר: "ב scripts/, דווחו רק אם זה כמעט ודאי וחמור."
• כלל צוות לא נבדק: הוסיפו כללים שרוצים שיסומנו בכל בקשת משיכה, כמו "לנתיבי API חדשים חייב להיות מבחן אינטגרציה."
• ממצאים שמתבררים כשגויים: דרשו ראיה לפני שמפרסמים סוג של ממצא. לדוגמה, "טענות על התנהגות צריכות ציטוט file:line במקור, לא הסקה משמות" מצמצם תוצאות חיוביות שגויות שאחרת היו עולות למחבר סבב נוסף.

חלק מההוראות האלה דורשות את קובץ השורש בענף ברירת מחדל מוגן.

השאירו ב REVIEW.md הוראות שמשנות את התנהגות הסקירה, והשאירו הקשר כללי של הפרויקט ב CLAUDE.md.

#הכללת קבצים אחרים ב REVIEW.md

אפשר לפצל הוראות סקירה בין כמה קבצים ולמשוך אותן אל REVIEW.md של השורש. השתמשו בזה כש REVIEW.md מתארך, או כשכללי הסקירה כבר נשמרים בקובץ אחר.

כדי לכלול קובץ, הוסיפו ל REVIEW.md של השורש שורה שעליה רק @ ושם הקובץ. Code Review שם את תוכן הקובץ במקום השורה הזו, כך שהתוכן חל כחלק מ REVIEW.md. בדוגמה הזו קובץ השורש נותן הוראה אחת משלו ואז כולל שני קבצי כללים:

# Review instructions

Report at most five Nits per review.

@review-security.md
@review-api.md

שמרו את הקבצים הכלולים בשורש המאגר, ליד REVIEW.md:

your-repo/
├── REVIEW.md
├── review-security.md
└── review-api.md

Code Review כולל את הקבצים כשהוא קורא את REVIEW.md מענף מוגן, לכן בדקו איזה ענף סקירה קוראת עבור המאגר:

• ענף מוגן: Code Review שם את הקובץ הכלול במקום שורת ה @ שלו
• ענף ברירת מחדל לא מוגן: שורת ה @ נשארת ב REVIEW.md כטקסט רגיל. אם בקשת המשיכה משנה את הקובץ ששמו מופיע בשורה, השורה מושמטת.

כשסקירה לא מחילה קובץ כלול, בדקו כל אחד מאלה:

• מיקום: העבירו את הקובץ לשורש המאגר. מלבד קובץ skill, נתיב אל תת תיקייה כמו @docs/review-rules.md לא נכלל.
• שם: התאימו את שם הקובץ בדיוק, כולל מצב האותיות, והשתמשו בשם בלי רווחים. שורה ששמה לא תואם לאף קובץ ליד REVIEW.md נשארת ב REVIEW.md כטקסט רגיל, וריצת הבדיקה לא מדווחת עליה כהכללה שדולגה.
• רמה אחת: פרטו כל קובץ ב REVIEW.md של השורש. שורת @ בקובץ כלול או ב REVIEW.md של תת תיקייה נשארת כטקסט רגיל (קבצי skill שונים), וקישור Markdown לקובץ אחר אינו הכללה.
• מגבלות: כללו לכל היותר שמונה קבצים שונים, ושמרו את REVIEW.md ואת הקבצים שהוא כולל מתחת ל 150,000 בתים יחד. קובץ שהיה מגיע למגבלת הבתים מדולג בשלמותו, בלי קיצור. ריצת הבדיקה מדווחת כמה שורות הכללה דולגו בגלל אחת מהמגבלות.
• קישורים: שמרו על 64 קישורי Markdown או פחות ב REVIEW.md ובקבצים שהוא כולל. קישורים לכתובות http, https או mailto ולעוגני # לא נספרים, וגם קישורים בקובץ skill לא נספרים. מעבר למגבלה הזו, הסקירה מדלגת על כל REVIEW.md של השורש, לא רק על הקבצים הכלולים. ריצת הבדיקה אז מציינת שההוראות לא הוחלו.
• עותק ממוזג: מזגו את הקובץ הכלול אל הענף שממנו נקרא REVIEW.md. הסקירה קוראת את שניהם מאותו קומיט, אף פעם לא מהשינויים של בקשת המשיכה עצמה.

#הכללת קובץ skill

כדי שסקירות יעקבו אחרי הנחיה ששומרים בskill, כללו את SKILL.md של ה skill ב REVIEW.md של השורש. Code Review לא מריץ skills.

הוסיפו @ ואת הנתיב אל SKILL.md, בצורה .claude/skills/<folder>/SKILL.md, בשורה נפרדת:

# Review instructions

Report at most five Nits per review.

@.claude/skills/api-review/SKILL.md

Treat any change under `migrations/` as Important.

הגנו על הענף שממנו נקרא REVIEW.md, כי Code Review כולל קובץ skill רק כשהוא קורא את REVIEW.md מענף מוגן. קובץ ה skill נספר במגבלות של שמונה קבצים ו 150,000 בתים, ויש לו מגבלה משלו של 30,000 בתים.

#כתיבת שורת skill ש Code Review כולל

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

אם שורת ה @ של skill מפרה אחד מהכללים למטה, Code Review לא כולל את ה skill מהשורה הזו:

• נתיב: כתבו את הנתיב כ .claude/skills/<folder>/SKILL.md משורש המאגר, כשתיקיית ה skill נמצאת ישירות תחת skills/. בניגוד לשם קובץ בשורש, נתיב בצורה הזו שלא תואם לאף קובץ מדולג ונספר.
• מקור: העתיקו הנחיה מכל קובץ אחר תחת .claude/, או מskill ארוז, אישי, או של תוסף, אל קובץ ליד REVIEW.md. אי אפשר לכלול אותם ישירות.
• קובץ: בצעו קומיט ל SKILL.md כקובץ טקסט רגיל. Code Review לא עוקב אחרי קישור סמלי, בין שהקישור הוא הקובץ ובין שהוא תיקייה בנתיב שלו.
• גודל: שמרו את SKILL.md על 30,000 בתים או פחות, כולל frontmatter
• מניין: כתבו לכל היותר שמונה שורות skill. שורה שחוזרת נספרת שוב לתוך השמונה.
• בלוקים ב REVIEW.md: השאירו את שורת ה @ מחוץ לגדרות קוד. סגרו כל הערת HTML וכל בלוק <pre>, <script>, <style> או <textarea> שמעליה.

כש Code Review מדלג על שורת skill כי היא מפרה את כלל הקובץ, הגודל, המניין או הבלוקים, ההודעה על שורות הכללה שדולגו בריצת הבדיקה סופרת אותה. ההודעה מופיעה רק כשהסקירה מחילה את REVIEW.md מענף מוגן.

#בדיקה מה סקירה מקבלת מ skill

כשה skill נכלל, סקירה מקבלת את גוף SKILL.md ושום דבר אחר מה skill, לכן בדקו את ה skill מול הרשימה למטה.

• frontmatter: חזרו בגוף על כל מה שסקירה צריכה מתוך הfrontmatter, למשל התנאים ש description נותן לשימוש ב skill
• פקודות מוזרקות: כתבו במפורש מה פקודת ! הייתה מספקת. Code Review לא מריץ את הפקודה, ומחליף את כל השורה או הבלוק שמחזיק אותה במציין מקום.
• החלפות: החליפו את $ARGUMENTS והחלפות אחרות בטקסט קבוע, כי סקירה לא מעבירה ארגומנטים ומשאירה אותם כפי שנכתבו
• קבצים תומכים: העתיקו אל SKILL.md את מה שסקירה צריכה, כי Code Review לא טוען סקריפטים, קבצים מקושרים, או הפניות @file
• החרגות ומגבלות Nit: כתבו הוראות שמחריגות ממצאים או מגבילות Nits ב REVIEW.md או בקובץ לידו, לא ב skill. Code Review לא מקבל את טקסט ה skill כנימוק לאף אחד מהשניים.
• קישורים לקבצי המאגר: נסחו במילים לאן קישור או הפניית @file מצביעים. הסקירה רואה את הנתיב כטקסט רגיל או כמציין מקום.

אם עורכים את פקודות ה ! של ה skill, את $ARGUMENTS, או קישורים, משנים גם את אופן הפעולה שלו ב Claude Code. אם הצוות נשען על אלה, העתיקו את ההנחיה לקובץ ליד REVIEW.md וכללו את הקובץ הזה במקום ה skill.

#תווים ש Code Review משנה בטקסט של skill

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

In SKILL.md:       Use `items[0]`, never `List<String>`.
The review reads:  Use ˋitems(0)ˋ, never ˋList< String>ˋ.

In SKILL.md:       Run `ps | grep api` and ask @alice.
The review reads:  Run ˋps ¦ grep apiˋ and ask @ alice.

כשכלל תלוי באחד מהתווים האלה, נסחו אותו גם במילים.

#מאיזה ענף נקרא REVIEW.md

Code Review קורא את REVIEW.md מענף הבסיס של בקשת המשיכה או מענף ברירת המחדל, אף פעם לא מהשינויים של בקשת המשיכה עצמה. כדי לשנות את התנהגות הסקירה, מזגו קודם את השינוי ב REVIEW.md.

החזיקו את REVIEW.md בענף ברירת המחדל והגנו על הענף הזה. כשסקירה קוראת את העותק שבענף ברירת מחדל מוגן, השורה הראשונה בטבלה למטה, היא מכבדת את ההוראות האלה מקובץ השורש:

• הורדת חומרה של ממצא
• החרגת נתיבים, קבצים, או סוגים של בעיות
• הגבלת הערות Nit

כתבו החרגות ומגבלות Nit ב REVIEW.md או בקובץ לידו, לא בskill כלול.

#מה נחשב להגנה על ענף

Code Review סופר את ההגדרות האלה כהגנה:

• ענף ברירת מחדל: כלל הגנה קלאסי על ענף, או ruleset
• כל ענף אחר: ruleset בלבד

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

#מה סקירה קוראת לכל הגדרת ענף

מצאו את מצב המאגר בעמודה הראשונה של הטבלה למטה.

אם ריצת הבדיקה מזכירה את REVIEW.md, ראו ריצת הבדיקה מזכירה את REVIEW.md.

#משאבים קשורים

• Code Review: מה השירות ואיך סקירה רצה
• קריאה ובקשה של סקירות בבקשת משיכה: מה כל רמת חומרה אומרת ואיך ממצאים מופיעים
• הגדרת Code Review: רמת הסקירה ומתי סקירות רצות, ואת זה קובע Owner
• סקירה מקומית עם /code-review: הפקודה /code-review, הארגומנטים שלה, ורמות המאמץ
• זיכרון: איך קבצי CLAUDE.md עובדים ברחבי Claude Code