הכאב: למה AI תמיד מפשל קוד באותו מקום

כל מי שכותב פרויקטים עם Cursor, Windsurf או Claude Code חווה את אותו שבירה: ה-AI פולט פיסת קוד שלמה, אתה מדביק ומריץ — בילד נכשל, טסטים אדומים, תלויות מותקנות במקום הלא נכון. הבעיה לא באינטליגנציה של ה-AI, אלא שהוא פשוט לא מכיר את “החוקים השקטים” של הפרויקט שלך.

AGENTS.md הוא קובץ Markdown בתיקיית השורש של הפרויקט, כתוב במיוחד עבור ה-AI. הוא אומר לו איך לבנות, איך לבדוק, איזה קונבנציות לשמור. README.md מיועד לבני אדם — מלא בהצגת הפרויקט, הנחיות תרומה וסיפורי מותג. כשה-AI קורא את זה, זה כמו עובד חדש ביום הראשון שמקבל חוברת שיווק של החברה ומיד מתבקש לכתוב קוד — הוא יודע מה החברה עושה, אבל לא יודע מה פקודת הבילד, איך מריצים טסטים, מה הם חוקי ה-ESLint. התוצאה: כל פעם צריך לתקן בצ’אט שוב ושוב — “תשתמש ב-pnpm ולא ב-npm”, “הטסטים ב-packages/web”, “אל תשכח להריץ lint”. אחרי מאה תיקונים כאלה, הפרויקט עדיין הפוך.

בעבודה על פרויקטים עם לקוחות ההפסד ישיר יותר: לקחתם פרויקט חוץ של Next.js + Prisma, אתם מאיצים עם Cursor, וה-AI מתקין תלויות עם npm install — קונפיג ה-workspace של pnpm הושמד. הוא לא יודע איפה ה-schema של הדאטהבייס, קובץ ה-migration שהוא יוצר זורק שגיאה. הלקוח לוחץ לדליברי, אתם מבלים שלוש שעות בדיבאג של קוד שה-Aי יצר — הכסף הזה מרגיש רע.

3 תרחישי התרסקות קלאסיים כשה-AI לא מכיר את החוקים השקטים: ① מנהל חבילות שגוי (הפרויקט ב-pnpm, ה-AI ברירת מחדל עם npm install), תלויות מותקנות במקום הלא נכון, ה-workspace קורס; ② כניסה לטסטים לא נמצאת (הטסטים ב-packages/web, ה-AI מריץ pnpm test בשורש ומקבל “קובץ טסט לא נמצא”); ③ סגנון קוד לא עקבי (הפרויקט עם ESLint + Prettier, הקוד של ה-AI עם הזחה וגרשיים שגויים, ה-CI נופל).

ההזדמנות: AGENTS.md מפריד בין “תיעוד לבני אדם” ל”תיעוד למכונה”

הפרויקט הפתוח AGENTS.md ב-GitHub (כתובת המאגר github.com/agentsmd/agents.md, נכון ל-25.08.2026 כ-24 אלף כוכבים) פותר בדיוק את הבעיה הזו. הרעיון המרכזי פשוט ביותר: קובץ Markdown בתיקיית השורש, שמסביר ל-AI איך לבנות, איך לבדוק, איזה סגנון קוד לשמור.

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

לפי הפוסט המקורי, AGENTS.md אומץ על ידי עשרות אלפי פרויקטים פתוחים (המספר המדויק טעון אימות), ומכסה את הכלים המובילים VS Code, Cursor, Windsurf, Aider, GitHub Copilot (אומת); בנוסף לפי משוב קהילה, גם OpenAI Codex ו-Google Jules תומכים (⚠️ לא אומת). אם לא תלמדו את זה עכשיו, אתם בעצם מדברים עם ה-AI בניב זר.

מסלול 1: כתיבת AGENTS.md מינימלי בכתב יד

עלות אפסית. צרו קובץ חדש, כתבו שלוש פסקאות וזהו.

הקדמה טכנית: הדוגמאות הבאות משתמשות ב-pnpm (חסכוני יותר בדיסק מ-npm, תומך ב-monorepo workspace), turbo הוא כלי תזמור משימות ל-monorepo, הפרמטר --filter מגביל פעולה לתת-חבילה מסוימת ומונע השפעה על שאר המאגר.

פסקה ראשונה “Dev environment tips”: מסבירה ל-AI באיזה מנהל חבילות להשתמש, איך לקפוץ לתת-חבילה, איך ליצור מודול חדש. למשל מהתבנית הרשמית:

• pnpm dlx turbo run where <project_name> — קפיצה ישירה לתת-חבילה מסוימת, בלי ls ארוך
• pnpm install --filter <project_name> — התקנת תלויות רק לתת-חבילה אחת, בלי לגעת בשאר ה-monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — יצירת תת-חבילה חדשה של React + Vite עם בדיקת TypeScript

הפקודות האלה ה-AI לא ינחש לבד, אבל ברגע שתכתבו אותן — הוא יבצע.

פסקה שנייה “Testing instructions”: מסבירה איך מריצים טסטים, איפה תוכנית ה-CI, אילו בדיקות חובה לפני commit. התבנית הרשמית כוללת:

• pnpm turbo run test --filter <project_name> — הרצת כל הבדיקות של תת-חבילה מסוימת
• pnpm vitest run -t "<test name>" — הרצת טסט בודד שתואם לשם מסוים
• “Fix any test or type errors until the whole suite is green” — לא לעצור עד שהכל ירוק
• “Add or update tests for the code you change, even if nobody asked” — המשפט הזה קריטי, בלעדיו ה-AI מתחמק מכתיבת טסטים

פסקה שלישית “PR instructions”: קובעת פורמט לכותרת commit, מחייבת הרצת lint ו-test. התבנית הרשמית: Title format: [<project_name>] <Title>, וגם “Always run pnpm lint and pnpm test before committing”.

שלוש הפסקאות האלה ביחד פחות מ-50 שורות, אבל מעלות משמעותית את אחוז ההצלחה של הקוד שה-AI מייצר (לפי משוב קהילה, המספר המדויק טעון אימות).

מסלול 2: שימוש מקונן ב-monorepo גדול

אם אתם עובדים על פרויקט ארגוני עם מבנה monorepo (מספר פרויקטים קשורים באותו מאגר Git, למשל תיקיות נפרדות לפרונטאנד, בקאנד וקוד משותף), AGENTS.md יחיד לא מספיק. AGENTS.md תומך בקינון: בכל תת-תיקייה שמים קובץ AGENTS.md ייעודי, וה-AI טוען אוטומטית את “הקרוב ביותר”.

איך עושים את זה בפועל: ב-AGENTS.md של השורש רושמים חוקים גלובליים (מנהל חבילות, תהליך CI, הנחיות אבטחה), ואז ב-packages/web/, packages/api/, packages/shared/ שמים קובץ נפרד עם פקודות בילד, כניסות טסט ותלויות מיוחדות לתת-החבילה. למשל חבילת הפרונטאנד צריכה לציין “ספריית קומפוננטות shadcn, עיצוב Tailwind, אייקונים lucide-react”; חבילת הבקאנד צריכה לציין “migrations של דאטהבייס ב-Prisma, נתיבי API תחת src/routes, אימות ב-JWT”.

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

מסלול 3: הפיכת זה ליתרון תחרותי בעבודה עם לקוחות

שוק עבודות ה-AI כבר אדום — כולם יודעים להשתמש ב-Cursor, אבל איכות הדליברי לא אחידה. אם תכתבו בהצעת המחיר “הפרויקט הזה כולל תצורת AGENTS.md תקנית, פיתוח מואץ AI תוך שמירה על קונבנציות הפרויקט”, שיעור הזכייה יהיה גבוה משמעותית ממתחרים שאומרים רק “אני כותב קוד עם AI”.

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

תמחור שירות התצורה של AGENTS.md בנפרד (התאמה לשוק המקומי): גרסה בסיסית כ-450 ש”ח (קובץ תצורה יחיד + הסבר ב-README), גרסה ארגונית כ-2,700 ש”ח (קינון monorepo + הנחיות אבטחה + הדרכת צוות). רשימת דליברי: ① קובץ AGENTS.md מותאם ② מענה במשך 30 יום בוואטסאפ ③ סרטון הדרכה של 10 דקות. מתאים ל: לקוחות שכבר יש להם מנוי Cursor/Windsurf אבל לא מצליחים להוציא תוצאות. לא מתאים ל: לקוחות שעדיין עובדים ידני לגמרי בלי כלי AI.

מקרה בוחן: חומת התאימות של AGENTS.md

AGENTS.md מופץ תחת רישיון MIT (אומת בחבילת החומרים), מתוחזק על ידי הקהילה (מבנה הניהול המדויק טעון אימות), האתר הרשמי הוא agents.md.

התאימות היא חומת ההגנה הגדולה ביותר שלו: אומת ש-VS Code, Cursor, Windsurf, Aider ו-GitHub Copilot כולם תומכים בקריאת AGENTS.md; לפי משוב קהילה, גם OpenAI Codex, Claude Code, Gemini CLI ו-Google Jules תומכים (⚠️ לא אומת). זה אומר שקובץ אחד משרת את כל הכלים המובילים — בלי צורך לכתוב תצורה נפרדת לכל אחד.

השוואה לחלופות: .cursorrules של Cursor עובד רק ב-Cursor, עוברים ל-Windsurf והוא מת; CLAUDE.md של Claude Code משרת רק את Claude; מערכת ההוראות של GitHub Copilot היא עולם נפרד. העיקרון של AGENTS.md — “כותבים פעם אחת, רץ בכל מקום” — הוא הסיבה האמיתית לאימוץ המהיר שלו.

עלות המעבר בין כלים מתאפסת. היום אתם ב-Cursor, מחר עוברים ל-Windsurf — ה-AGENTS.md עובד מיד, בלי לכתוב מחדש את החוקים.

קריאה לפעולה: הוסיפו הלילה מדריך הפעלה למכונה לפרויקט

רשימת פעולה של 5 דקות: ① פתחו את תיקיית השורש של הפרויקט ② צרו AGENTS.md ③ העתיקו את התבנית הרשמית (github.com/agentsmd/agents.md) ④ מלאו שלוש פקודות (בילד, טסטים, lint) ⑤ בקשה הבאה ל-AI — תראו את ההבדל.

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

AGENTS.md הוא תצורת ה-AI לתכנות עם ה-ROI הגבוה ביותר כרגע — 30 דקות השקעה חוסכות מספר שעות דיבאג בחודש.