סוכני קוד AI כותבים קוד JavaScript מיושן לעיתים קרובות יותר ממה שנדמה. כלים כמו Cursor ו-Claude Code מייצרים היום חלק ניכר מהקוד בפרויקטים של Next.js ו-React, אבל יש להם הרגל מוכר: ספרייה ייעודית למודאל, חישובי מיקום ידניים ל-tooltip, קרוסלה עם עשרות שורות JS, במקום HTML, CSS ו-API נייטיביים שכבר קיימים בדפדפן. הסיבה פשוטה: פלטפורמת הווב משתנה מהר יותר מנתוני האימון של המודלים.
זו לא בעיה אסתטית. כל תלות מיותרת מוסיפה משקל לבאנדל, שטח תקיפה בשרשרת האספקה וקוד שמישהו יצטרך לתחזק. מעבר לזה, Google מציינת שהמודלים הנוכחיים עדיין חלשים בנגישות, ב-security headers ובתעדוף טעינה של סקריפטים ותמונות. אלה בדיוק התחומים שבהם קוד שנוצר אוטומטית עובר Code Review בלי שאיש שם לב.
המדריך הזה מציג את Modern Web Guidance, פרויקט של צוות Chrome שמזריק ידע עדכני על פלטפורמת הווב לתוך סוכני קוד, ומראה צעד אחר צעד איך לשלב אותו עם AGENTS.md, CLAUDE.md וכללים ל-Cursor בפרויקט Next.js. המטרה: לשפר בפועל את איכות הקוד שנוצר ב-AI, ולמדוד את השיפור במקום להניח אותו.
למה סוכני קוד AI כותבים קוד JavaScript מיושן
נתוני אימון עם תאריך תפוגה
כל מודל שפה מאומן על קורפוס שנחתך בנקודת זמן מסוימת, ורוב הקוד בקורפוס הזה נכתב שנים לפני החיתוך. התוצאה היא שהסוכן "זוכר" היטב את הדרך שבה בנו ממשקים לפני כמה שנים, ופחות את מה שנכנס לדפדפנים מאז.
לפי LogRocket, יש שני מצבי כשל עיקריים:
- הסוכן לא יודע שהיכולת קיימת. הוא פשוט לא מכיר API נייטיבי חדש, ולכן מתקין ספרייה או כותב מימוש ידני.
- הסוכן מכיר את היכולת אבל טועה בפרטים. תחביר לא נכון, או הנחות שגויות לגבי תמיכת הדפדפנים.
המצב השני מסוכן יותר, כי הקוד נראה מודרני ומשכנע אבל נשבר בדפדפן מסוים או מתנהג אחרת ממה שהמפתח ציפה.
איך נראה "JavaScript של 2019"
הדפוסים חוזרים על עצמם. Reptile Haus מונה כמה תחליפים נייטיביים לספריות JavaScript נפוצות:
דפוס ישן שסוכנים מייצרים | חלופה נייטיבית בפלטפורמת הווב המודרנית |
|---|---|
ספריית מודאל + Portal + מלכודת פוקוס ידנית | אלמנט |
ספריית מיקום ל-tooltip ותפריטים צפים | Popover API יחד עם CSS Anchor Positioning |
ספריית קרוסלה מבוססת JS | CSS scroll snap |
| |
ספריות אנימציה בשיטת FLIP | View Transitions |
לשם המחשה של המשקל: ספריות מיקום כמו Floating UI או Popper.js מוערכות בין 12KB ל-35KB אחרי minify ו-gzip, לפי טענת המקור. זה לא אסון בפני עצמו, אבל כשהסוכן מוסיף תלות כזו לכל רכיב שצריך מיקום, זה מצטבר. עבור משתמשים בישראל שגולשים בסלולר, באנדל קטן יותר מתורגם ישירות לזמן טעינה, נושא שנדון בהרחבה במאמר למה מהירות האתר קריטית.
גם חיפוש בתיעוד לא תמיד עוזר
אפשר היה לצפות שסוכן עם גישה לאינטרנט או לתיעוד פשוט יבדוק לפני שהוא כותב קוד. בפועל, סוכנים לא תמיד יודעים מתי לחפש. כותב אחד מדווח שבמבחנים של Vercel, קונטקסט שנמצא תמיד בחלון (AGENTS.md) ניצח חיפוש תיעוד לפי דרישה דרך skill, בדיוק מהסיבה הזו. חשוב לציין שזו טענה מיד שנייה מבלוג אישי ולא נתון מאומת, אבל היא מתיישבת עם החוויה של רבים: אם לא אומרים לסוכן לבדוק, הוא לא בודק.
Modern Web Guidance: מה זה ואיך זה עובד
Modern Web Guidance הוא אוסף של skills מצוות Chrome שמטמיע בסוכני קוד מומחיות בפלטפורמת הווב, best practices ונתוני תאימות דפדפנים, במטרה להרחיק אותם מדפוסים ישנים. הוא עובד עם כל סוכן שתומך ב-skills.
העיקרון: לפני שהסוכן כותב HTML, CSS או JavaScript בצד הלקוח, הוא מחפש במדריכים המאומתים ומקבל הנחיה ממוקדת לבעיה הספציפית. במקום להסתמך על זיכרון האימון, הוא נשען על מקור שמתעדכן.
קוד פתוח ומבנה הריפו
הפרויקט מופץ ברישיון Apache-2.0, כך שאין עלות שימוש ואין שאלה של תמחור מקומי. בריפו יש תיקיות פלאגין ל-Claude, Codex, Cursor ו-Grok, לצד תיקיית skills משותפת. בזמן הבדיקה, הריפו הציג כ-2.6 אלף כוכבים, 103 forks ו-215 commits, נתונים שכמובן משתנים מיום ליום.
מ-Early Preview לגרסה 1.0
Chrome השיקה את הפרויקט כ-early preview ב-Google I/O בחודש מאי. לפי סיכום של Pasquale Pillitteri מאותה תקופה, הגרסה המוקדמת כיסתה 128 יכולות ווב ודווח על שיפור של 37 נקודות אחוז בעמידה ב-best practices.
גרסה 1.0 הוסיפה כמה דברים משמעותיים, לפי Search Engine Journal:
- Audit לקוד קיים שסורק את הפרויקט ומציע שדרוגים בטוחים.
- הצטרפות של Firefox ו-Edge לפרויקט.
- מבנה ממשל עם שישה מושבי owners: שניים ל-Chrome, אחד ל-Edge, אחד ל-Mozilla ושניים לגורמים עצמאיים, כשאחד מהם עדיין פנוי. ל-Apple אין מושב.
הערה על תאריכים: המקורות לא עקביים לגבי מועד השחרור המדויק של 1.0, ובזמן הכתיבה עמוד התיעוד הרשמי של Chrome עדיין הציג באנר של early preview. כדאי לבדוק את מצב הפרויקט ישירות בריפו.
מה המספרים אומרים
Google מפעילה דשבורד evals ציבורי שמריץ בכל לילה סוכנים של Anthropic, OpenAI ו-Google, עם ובלי ההנחיות. בצילום המצב שפרסם SEJ מתוך הדשבורד, מ-8 בנובמבר, הרצות עם הנחיה עברו 88% מהבדיקות האוטומטיות, לעומת 56% בלי הנחיה. כל סוכן הורץ על 199 עד 215 משימות.
חשוב לזכור: מדובר בקריאה של SEJ בדשבורד שמתעדכן מדי לילה. המספרים משתנים מהרצה להרצה, ולכן כדאי לבדוק את הנתונים העדכניים ישירות בדשבורד עצמו לפני שמסתמכים עליהם.
שני המספרים (37 נקודות אחוז ו-88% מול 56%) מודדים דברים שונים בשלבים שונים של הפרויקט, ולכן לא נכון להשוות ביניהם ישירות. מה שכן עקבי: הנחיה מפורשת משפרת את התוצאות בצורה ניכרת.
לגבי איכות התוכן עצמו: לפי SEJ, כל מדריך עובר ביקורת של tech lead מהתחום הרלוונטי, ומדריכים שנוגעים בממשק משתמש עוברים ביקורת נגישות נוספת.
התקנה ותצוגה מקדימה: CLI, Claude Code ו-Cursor
דרישות מקדימות
המדריך של LogRocket מניח:
- Node.js בגרסה 18 ומעלה.
- סוכן שתומך ב-skills, למשל Antigravity, Gemini CLI, Claude Code או Copilot CLI.
- פרויקט קיים. LogRocket משתמשים בפרויקט React/Next.js, אבל מדגישים שההנחיות אינן ספציפיות ל-React.
התקנה דרך ה-CLI (הדרך המומלצת)
לפי התיעוד של Chrome, הדרך המומלצת היא דרך ה-CLI של modern-web-guidance, כי היא מאפשרת עדכונים אוטומטיים. רוב אפשרויות ההתקנה הידנית הייעודיות לכל סוכן לא תומכות בעדכון אוטומטי.
מתוך תיקיית הפרויקט, לפי SEJ:
npx modern-web-guidance@latest installההבדל בין התקנה עם עדכונים לבין התקנה ידנית חשוב יותר ממה שנראה. כל הרעיון של הפרויקט הוא לסגור את הפער בין הסוכן לבין מצב הפלטפורמה. התקנה שלא מתעדכנת פשוט יוצרת פער חדש, רק מאוחר יותר.
Claude Code: הוראות התקנה דרך ה-Marketplace
ב-Claude Code ההתקנה היא שלושה צעדים בתוך הסשן:
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/reload-pluginsהפקודה הראשונה מוסיפה את הריפו כ-marketplace, השנייה מתקינה את הפלאגין, והשלישית טוענת מחדש את הפלאגינים כדי שה-skill יהיה זמין מיד.
Cursor: פלאגין מה-Marketplace
ל-Cursor יש פלאגין Modern Web Guidance ב-marketplace. הוא כולל שני skills:
- chrome-extensions לפיתוח תוספים לדפדפן.
- modern-web-guidance שמתואר כ-MANDATORY, כלומר כזה שחובה להריץ ראשון בכל משימה של HTML, CSS ו-JavaScript בצד הלקוח.
הניסוח "MANDATORY" בתיאור ה-skill אינו מקרי. הוא נועד להתמודד בדיוק עם הבעיה שתוארה קודם: סוכנים שלא יודעים מתי להפעיל כלי עזר.
תצוגה מקדימה עם פקודת search
לפני ההתקנה, או כדי להבין מה הסוכן יקבל, ה-CLI כולל פקודת search שמחזירה את המדריכים הרלוונטיים לבקשה. התחביר המדויק לא הופיע בחילוץ התיעוד, ולכן כדאי לאמת מול --help, אבל הצורה הכללית היא:
npx modern-web-guidance@latest search "animate a dialog modal backdrop"הפלט הוא JSON עם מזהה המדריך, הקטגוריה, היכולות שבהן הוא משתמש וכמות הטוקנים. מבנה להמחשה בלבד:
[
{
"id": "<guide-id>",
"category": "<category>",
"featuresUsed": ["<feature>"],
"tokenCount": 0
}
]השדה tokenCount שימושי במיוחד. הוא מאפשר להעריך כמה קונטקסט כל מדריך יצרוך, שיקול שחשוב בכל סוכן. העיקרון של פחות קונטקסט אבל ממוקד יותר נדון בהרחבה במאמר על עלות טוקנים ב-MCP.
AGENTS.md וכללים ל-Cursor בפרויקט Next.js
שתי שכבות משלימות
בפרויקט Next.js או React יש שני סוגי סחיפה שהסוכן צריך להתגבר עליהם: סחיפה של ה-framework (API של Next.js שהשתנה בין גרסאות) וסחיפה של פלטפורמת הווב (יכולות דפדפן חדשות). לכל אחת מתאים כלי אחר:
| AGENTS.md / קובצי כללים | Modern Web Guidance skill |
|---|---|---|
מתי פעיל | תמיד בקונטקסט | לפי דרישה, כשהסוכן מפעיל את ה-skill |
מה מכסה | כללי פרויקט, הפניה לתיעוד Next.js לפי גרסה | ידע על פלטפורמת הווב ותאימות דפדפנים |
יתרון מרכזי | הסוכן לא צריך להחליט לחפש | מדריכים מאומתים עם evals ציבוריים |
חולשה מרכזית | עלול להתיישן ולגבור על הקוד | תלוי בכך שהסוכן יפעיל אותו |
תאימות | Cursor, Claude Code, Codex, Copilot | כל סוכן שתומך ב-skills |
הנתונים בטבלה מבוססים על ההשוואה של Kuldeep Modi ועל SEJ. אף מקור לא בדק את השילוב של השניים באופן מבוקר, אבל ההיגיון ברור: AGENTS.md דואג שהסוכן יידע להפעיל את ה-skill, וה-skill מספק את התוכן. זו דוגמה קלאסית להנדסת קונטקסט: לא רק מה נמצא בחלון, אלא גם מתי ולמה.
התיעוד המובנה של Next.js
נקודה שמפתחים רבים מפספסים: Next.js מגיע עם תיעוד שתואם לגרסה המותקנת, בתיקייה node_modules/next/dist/docs/. קובץ AGENTS.md בשורש הפרויקט יכול להורות לסוכן לקרוא את התיעוד הזה לפני שהוא כותב קוד, וכך הוא מקבל את ה-API הנכון לגרסה שבאמת מותקנת, ולא את מה שזכר מהאימון.
בגרסאות עדכניות, create-next-app יכול לייצר AGENTS.md (ולעיתים קרובות גם CLAUDE.md) כבר בהקמת הפרויקט.
הבלוק המנוהל: לא לגעת
עוד פרט חשוב מאותו מקור: Next.js עשוי לנהל אוטומטית את התוכן שבין הסמנים BEGIN:nextjs-agent-rules ו-END:nextjs-agent-rules. כללים מותאמים של הפרויקט צריכים להיכתב מחוץ לבלוק הזה, אחרת שדרוג של Next.js עלול לדרוס אותם.
תבנית AGENTS.md לפרויקט Next.js
התבנית הבאה משלבת את כל העקרונות: הפניה לתיעוד הגרסה, הפעלת ה-skill, העדפת פרימיטיבים נייטיביים, כללי RTL, ומשפט קדימות שמונע מהקובץ לגבור על הקוד (על החשיבות שלו בהמשך).
הסתייגות חשובה לפני השימוש בתבנית: המקורות מזכירים רק את שמות הסמנים, ולא מציגים את התחביר המדויק שלהם. התחביר בצורת הערת HTML שמופיע כאן הוא להמחשה בלבד. אם הבלוק כבר קיים בקובץ שנוצר בפרויקט, אין לערוך אותו ואין להחליף אותו בגרסה הזו, רק להוסיף כללים מתחתיו.
<!-- NOTE: Illustrative marker syntax only. The sources name the markers
but do not show their exact format. If create-next-app already generated
this block, keep it as is and add your rules below it. -->
<!-- BEGIN:nextjs-agent-rules -->
(managed by Next.js – do not edit)
<!-- END:nextjs-agent-rules -->
# Project rules
## Source of truth
- If this file conflicts with the existing code, the code takes precedence.
Point out the conflict instead of following this file.
## Framework
- Before writing Next.js code, read the version-matched docs in
node_modules/next/dist/docs/.
## Web platform
- Before writing HTML, CSS or client-side JS, run the modern-web-guidance skill.
- Prefer native primitives:
- <dialog> for modals
- Popover API for menus and tooltips
- CSS scroll snap for carousels
- structuredClone() instead of cloneDeep
- View Transitions instead of FLIP animation libraries
- When replacing an existing component, preserve its behavior
(e.g. backdrop click to close) or flag the difference.
- Do not add a UI dependency for something the platform already provides
without asking first.
## RTL / Hebrew
- The UI is RTL (dir="rtl"). Use CSS logical properties
(margin-inline-start, padding-inline, inset-inline-end), not left/right.
## Browser support
- Support target: <fill in your project's policy>.
- Check Baseline status before using newer features. Ask before adding polyfills.כמה הערות על התבנית:
- קצר עדיף. לפי אותו מקור, כללים קצרים עובדים טוב יותר, וחיבורים ארוכים מקבלים פחות ציות.
- כללי RTL. הסעיף על logical properties הוא המלצה מעשית לממשקים בעברית. מאפיינים לוגיים חוסכים כפילויות של סגנונות ל-LTR ול-RTL. המקורות שנבדקו לא בחנו זאת ישירות בהקשר של סוכנים, אבל זה דפוס שסוכנים נוטים לפספס בלי הנחיה.
- שימור התנהגות. השורה על שמירת ההתנהגות הקיימת נועדה למנוע מצב שבו החלפה לפרימיטיב נייטיבי משנה בשקט את חוויית המשתמש. הדוגמה של המודאל בהמשך ממחישה בדיוק את המקרה הזה.
- מדיניות תמיכה. ההעדפה לפרימיטיבים נייטיביים חייבת להיות מעוגנת ביעד תמיכה מוגדר. בלי זה, הסוכן עלול להשתמש ביכולת שעדיין לא נתמכת אצל חלק מהקהל.
CLAUDE.md: הפניה במקום שכפול
Claude Code קורא את CLAUDE.md. כדי לא לתחזק שני קבצים עם אותם כללים, שעם הזמן יתחילו לסתור זה את זה, אפשר להשאיר ב-CLAUDE.md הפניה קצרה:
# CLAUDE.md
Read AGENTS.md at the repository root before every task.
It is the single source of truth for project rules.כללים ל-Cursor
AGENTS.md עובד גם ב-Cursor, לצד Claude Code, Codex ו-Copilot. העיקרון זהה גם לכללים ל-Cursor: אם הצוות כבר מחזיק קובצי כללים ייעודיים לכלי, עדיף שיפנו ל-AGENTS.md במקום לשכפל את התוכן. מקור אמת אחד הוא הדרך הבטוחה ביותר למנוע סתירות. המקורות שנבדקו לא הציגו פורמט מדויק לקובצי הכללים של Cursor, ולכן כדאי לאמת את הפורמט מול התיעוד של Cursor לגרסה שבשימוש.
דוגמה מעשית: מודאל ב-React, לפני ואחרי
כך נראה מודאל טיפוסי שסוכן מייצר בלי הנחיה. Portal, האזנה ידנית ל-Escape, נעילת גלילה ידנית, סגירה בלחיצה על הרקע ו-role="dialog" שמנסה לחקות את מה שהדפדפן כבר יודע לעשות:
// הדפוס המיושן
import { useEffect, useRef } from "react";
import { createPortal } from "react-dom";
export function Modal({ open, onClose, children }) {
const ref = useRef(null);
useEffect(() => {
if (!open) return;
const onKey = (e) => e.key === "Escape" && onClose();
document.addEventListener("keydown", onKey);
document.body.style.overflow = "hidden";
ref.current?.focus();
return () => {
document.removeEventListener("keydown", onKey);
document.body.style.overflow = "";
};
}, [open, onClose]);
if (!open) return null;
return createPortal(
<div className="backdrop" onClick={onClose}>
<div
ref={ref}
tabIndex={-1}
role="dialog"
aria-modal="true"
onClick={(e) => e.stopPropagation()}
>
{children}
</div>
</div>,
document.body
);
}וכך נראית הגרסה הבסיסית עם האלמנט הנייטיבי <dialog>. הקריאה ל-showModal() מציבה את הדיאלוג ב-top layer, ומקש Escape סוגר אותו ומפעיל את אירוע close:
"use client";
import { useEffect, useRef, type ReactNode } from "react";
type Props = { open: boolean; onClose: () => void; children: ReactNode };
export function Modal({ open, onClose, children }: Props) {
const ref = useRef<HTMLDialogElement>(null);
useEffect(() => {
const dialog = ref.current;
if (!dialog) return;
if (open && !dialog.open) dialog.showModal();
if (!open && dialog.open) dialog.close();
}, [open]);
return (
<dialog ref={ref} onClose={onClose}>
{children}
</dialog>
);
}שינוי התנהגות: סגירה בלחיצה על הרקע
חשוב לשים לב שהגרסה הבסיסית הזו אינה תחליף אחד-לאחד. הגרסה הישנה נסגרה בלחיצה על הרקע, ואילו <dialog> שנפתח עם showModal() נסגר כברירת מחדל רק דרך Escape או קריאה מפורשת ל-close(). מי שמחליף רכיב קיים בגרסה הבסיסית עלול לקבל דיווחים על רגרסיה מצד משתמשים שהתרגלו לסגור את החלון בלחיצה מחוץ לו.
יש שתי דרכים לשמר את ההתנהגות:
- התכונה
closedby="any"על האלמנט מאפשרת light-dismiss באופן הצהרתי. זו תכונה חדשה יחסית שאינה נתמכת בכל הדפדפנים, ולכן יש לבדוק את מצב ה-Baseline שלה מול יעד התמיכה של הפרויקט לפני שמסתמכים עליה. - מאזין לחיצה על האלמנט עצמו, שעובד בכל הדפדפנים שתומכים ב-
<dialog>. לחיצה על ה-::backdropנרשמת כלחיצה על אלמנט ה-dialogעצמו, ולכן אפשר לבדוק אםe.targetהוא הדיאלוג. כדי שלחיצה על הריפוד הפנימי לא תסגור את החלון בטעות, התוכן עטוף באלמנט פנימי והריפוד עובר אליו:
<dialog
ref={ref}
onClose={onClose}
onClick={(e) => {
// לחיצה על הרקע מגיעה ישירות לאלמנט ה-dialog
if (e.target === e.currentTarget) e.currentTarget.close();
}}
>
<div className="dialog-body">{children}</div>
</dialog>וה-CSS, כולל עיצוב הרקע:
dialog {
padding: 0;
}
.dialog-body {
padding: 1.5rem;
}
dialog::backdrop {
background: rgb(0 0 0 / 0.5);
}הלקח רחב יותר מהמודאל עצמו: כשסוכן מחליף רכיב קיים בפרימיטיב נייטיבי, כדאי לבקש ממנו לפרט אילו התנהגויות השתנו, ולבדוק אותן ידנית.
Popover API לתפריטים צפים
אותו עיקרון חל על תפריטים צפים. במקום ספריית מיקום, Popover API מספק top layer ו-light-dismiss (סגירה בלחיצה מחוץ לאלמנט) מובנים. Reptile Haus מציינים באופן כללי שפרימיטיבים נייטיביים מגיעים עם טיפול מובנה בפוקוס, אבל זה לא פוטר מבדיקה: ניווט מקלדת, סדר הפוקוס וההתנהגות מול קוראי מסך צריכים להיבדק בפועל בכל רכיב.
<button popovertarget="user-menu">תפריט משתמש</button>
<div id="user-menu" popover>
<a href="/profile">פרופיל</a>
<a href="/settings">הגדרות</a>
</div>ודוגמה קטנה שמופיעה כמעט בכל פרויקט, שכפול עמוק של אובייקט:
// לפני: תלות ב-lodash
import cloneDeep from "lodash/cloneDeep";
const copy = cloneDeep(state);
// אחרי: API מובנה
const copy2 = structuredClone(state);Audit ומדידה: לבדוק שהסוכן באמת השתפר
Audit לקוד קיים
ההנחיות משפיעות על קוד חדש, אבל רוב הפרויקטים כבר מכילים לא מעט קוד ישן. כאן נכנס ה-audit של גרסה 1.0. לפי SEJ, הוא סורק קובצי HTML, CSS, JavaScript ואת package.json, מאתר שדרוגים בטוחים ואז מוביל את הסוכן דרך השינויים.
חשוב להבין את המגבלה: מדובר בניתוח סטטי על מספר מוגבל של דפוסי קוד. כלומר, ה-audit יתפוס מקרים מוכרים, כמו תלות שיש לה תחליף נייטיבי ידוע, אבל לא יחליף Code Review. הפקודה המדויקת להפעלת ה-audit לא הופיעה במקורות שנבדקו, ולכן כדאי לבדוק אותה בתיעוד או דרך --help של ה-CLI.
תהליך עבודה מומלץ עם ה-audit:
- לעבוד על branch נפרד.
- להריץ את ה-audit ולסקור את רשימת ההצעות לפני שהסוכן מתחיל לשנות קוד.
- לאשר שינויים בקבוצות קטנות, למשל רכיב אחד או תלות אחת בכל פעם.
- להריץ בדיקות ולבדוק ידנית את הרכיבים שהשתנו, במיוחד במצב RTL ובהתנהגויות כמו סגירה בלחיצה על הרקע.
- להסיר תלויות שהתייתרו מ-
package.jsonולוודא שהבאנדל באמת קטן.
הסרת תלויות היא גם רווח אבטחתי. כל חבילה שיוצאת מהפרויקט היא חבילה אחת פחות לעקוב אחריה, כפי שמפורט בצ'קליסט אבטחת שרשרת אספקה לצוותים קטנים.
בדיקת לפני/אחרי משלכם
הדשבורד הציבורי של Google מראה מגמה, אבל הוא לא מכיר את הפרויקט שלכם. בדיקה פשוטה ופנימית נותנת תמונה אמינה יותר:
- לבחור 5 עד 10 משימות טיפוסיות מהפרויקט: מודאל, תפריט נפתח, קרוסלה, טופס, אנימציית מעבר.
- להריץ כל משימה פעמיים, פעם בלי ה-skill וה-AGENTS.md ופעם איתם, באותו מודל.
- לשמור את התוצרים ב-branches נפרדים.
- להשוות לפי קריטריונים קבועים מראש.
קריטריונים להשוואה
- תלויות חדשות: האם הסוכן הוסיף חבילה ל-
package.json? - גודל באנדל: ההפרש בגודל ה-JavaScript שנשלח ללקוח.
- שימוש בפרימיטיבים נייטיביים:
<dialog>,popover, scroll snap,structuredClone(). - שימור התנהגות: האם הרכיב החדש מתנהג כמו הישן, או שהשינויים מתועדים.
- נגישות: ניווט מקלדת, ניהול פוקוס ותוויות. זהו אחד התחומים שGoogle מציינת כחלשים אצל המודלים.
- תעדוף טעינה: האם תמונות וסקריפטים מקבלים עדיפות טעינה מתאימה.
- תאימות ל-RTL: האם הסוכן השתמש במאפיינים לוגיים או ב-left/right קשיחים.
לפי LogRocket, גם המדריך שלהם בנוי סביב השוואת לפני/אחרי על פרויקט React/Next.js. התוצאות המפורטות לא נכללו בחומר שנבדק, ולכן ההמלצה היא להריץ את ההשוואה בעצמכם.
מלכודות: קבצי הוראות מיושנים ומתי ספרייה עדיין נכונה
קובץ הוראות מיושן גובר על הקוד
זו המלכודת המשמעותית ביותר, והיא מגובה במחקר. מחקר שפורסם ב-arXiv בחן 320 הרצות על פני 40 פרויקטים, ומצא שכאשר קובץ הוראות כמו CLAUDE.md או AGENTS.md התיישן, הסוכנים העדיפו את הקובץ על פני הקוד הקיים ב-90.1% מההחלטות.
המשמעות: AGENTS.md שכתוב בו "משתמשים בספריית X" אחרי שהצוות כבר עבר ל-<dialog> יגרום לסוכן להחזיר את הספרייה. אותו כלי שנועד לעצור קוד מיושן הופך למקור שלו.
החדשות הטובות מאותו מחקר: משפט אחד שקובע שהקוד גובר על הקובץ העלה את שיעור ההיצמדות לקוד מ-4.2% ל-91.4%, ואת שיעור הבדיקות שעברו מ-89.4% ל-100%. לכן משפט הקדימות מופיע בראש התבנית שלמעלה.
בנוסף למשפט הקדימות, כדאי:
- לעדכן את AGENTS.md באותו PR שמשנה ארכיטקטורה או מחליף ספרייה.
- לכלול את קובצי ההוראות ב-Code Review כמו כל קוד אחר.
- להעדיף כללים שמתארים עקרונות ("העדף פרימיטיבים נייטיביים") על פני כללים שמזכירים קבצים או גרסאות ספציפיות, שמתיישנים מהר.
Skill שלא מופעל לא עוזר
ה-skill תלוי בכך שהסוכן יפעיל אותו. זו בדיוק הסיבה לשורה "Before writing HTML, CSS or client-side JS, run the modern-web-guidance skill" ב-AGENTS.md. שווה לבדוק מדי פעם בלוג של הסוכן אם ה-skill באמת הופעל במשימות רלוונטיות.
מתי ספרייה עדיין הבחירה הנכונה
העדפה לפרימיטיבים נייטיביים אינה כלל נוקשה. Reptile Haus מציינים כמה מגבלות:
- CSS Anchor Positioning עדיין לא אוניברסלי. ייתכן שיידרשו polyfills, ומצב התמיכה צריך להיבדק מול Baseline בזמן ההחלטה.
- יעדי תמיכה הם החלטה של הפרויקט. אתר שחלק משמעותי מהקהל שלו משתמש בדפדפנים ישנים צריך כללים שונים מאפליקציה פנימית.
- לפעמים הספרייה היא הטרייד-אוף הנכון, למשל כשמערכת עיצוב קיימת כבר בנויה סביבה, או כשנדרשת התנהגות מורכבת שהפלטפורמה עדיין לא מספקת.
הכלל המעשי: הסוכן לא צריך להחליט לבד להוסיף או להסיר ספרייה. זו הסיבה לשורה "ask first" בתבנית.
Skills ופלאגינים הם קוד צד שלישי
כל skill או פלאגין מכניס טקסט והוראות לקונטקסט של הסוכן. Modern Web Guidance מגיע ממקור מוכר ועובר ביקורת, אבל ההרגל של התקנת פלאגינים בלי בדיקה מסוכן באופן כללי. כדאי להכיר את הסיכונים שמתוארים במאמר על הזרקת פרומפט עקיפה לסוכני קוד, ולהתקין רק מה-marketplace הרשמי או מהריפו המקורי.
שאלות נפוצות
איך מתקינים את Modern Web Guidance?
הדרך המומלצת היא להריץ npx modern-web-guidance@latest install בתיקיית הפרויקט, שמאפשרת עדכונים אוטומטיים. ב-Claude Code מוסיפים את ה-marketplace GoogleChrome/modern-web-guidance, מתקינים את modern-web-guidance@googlechrome ומריצים /reload-plugins. ב-Cursor יש פלאגין ב-marketplace.
האם זה מתאים רק ל-React או ל-Next.js?
לא. LogRocket מציינים שההנחיות אינן ספציפיות ל-React, גם אם המדריך שלהם משתמש בפרויקט React/Next.js. ההנחיות עוסקות ב-HTML, CSS ו-JavaScript בצד הלקוח, ולכן רלוונטיות לכל framework.
אפשר להריץ בדיקה על פרויקט קיים?
כן. גרסה 1.0 הוסיפה audit שסורק HTML, CSS, JavaScript ו-package.json ומחפש שדרוגים בטוחים. הוא מבוסס על ניתוח סטטי של מספר מוגבל של דפוסים, ולכן הוא נקודת התחלה ולא תחליף ל-Code Review.
אם מתקינים את ה-skill, עדיין צריך AGENTS.md?
לשניהם תפקידים שונים. AGENTS.md נותן כללי פרויקט שנמצאים תמיד בקונטקסט ומפנה לתיעוד המובנה של Next.js, וה-skill מספק ידע על פלטפורמת הווב לפי דרישה. השימוש בשניהם הגיוני, אם כי אף מקור לא בדק את השילוב באופן מבוקר.
מה קורה אם AGENTS.md לא מעודכן?
הסוכן כנראה יעדיף אותו על פני הקוד. מחקר ב-arXiv מצא שבמצב כזה 90.1% מההחלטות תאמו את הקובץ המיושן. הוספת משפט אחד שקובע שהקוד גובר העלתה את ההיצמדות לקוד ל-91.4%.
אפשר לראות את המדריכים לפני ההתקנה?
כן. פקודת search של ה-CLI מקבלת תיאור משימה ומחזירה JSON עם מזהי המדריכים, הקטגוריות, היכולות שבשימוש וכמות הטוקנים של כל מדריך.
סיכום
הנטייה של סוכני קוד AI לכתוב קוד JavaScript מיושן אינה באג של כלי מסוים. היא תוצאה ישירה של נתוני אימון שמפגרים אחרי הפלטפורמה. הפתרון שעובד הוא שילוב של שתי שכבות:
- שכבה קבועה: AGENTS.md קצר ועדכני שמפנה לתיעוד הגרסה של Next.js, מורה להפעיל את ה-skill, מגדיר יעדי תמיכה וכללי RTL, וכולל משפט שקובע שהקוד גובר על הקובץ.
- שכבה לפי דרישה: Modern Web Guidance, שמספק מדריכים מאומתים עם נתוני תאימות, מותקן דרך ה-CLI כדי לקבל עדכונים.
הנתונים הציבוריים מעודדים, 88% מול 56% בבדיקות האוטומטיות בצילום מצב אחד מתוך דשבורד שמשתנה מדי לילה, אבל המבחן האמיתי הוא בפרויקט עצמו. הרצת ה-audit על הקוד הקיים, השוואת לפני/אחרי על משימות אמיתיות, בדיקה שהתנהגות הרכיבים נשמרה ותחזוקה שוטפת של קובצי ההוראות הם מה שהופך את הכלים האלה משיפור תיאורטי לשיפור מדיד באיכות הקוד שנוצר ב-AI.
מקורות
- Get started with Modern Web Guidance – Chrome for Developers
- Google Releases Modern Web Guidance 1.0 For AI Coding Agents – Search Engine Journal
- GoogleChrome/modern-web-guidance – GitHub
- How to use Chrome's Modern Web Guidance – LogRocket
- Modern Web Guidance – Cursor Plugins
- AGENTS.md for Next.js: Stop AI Agents From Writing Outdated Code
- Stale Instruction Files Override the Code in Coding Agents – arXiv
- The Web Platform in 2026: Browser APIs That Replace Your JavaScript Libraries
- Modern Web Guidance: Chrome Ships Verified Skills for AI Coding Agents – Pasquale Pillitteri
- CSS Anchor Positioning and Popover API Guide – SnippetCrafted






