מהו קובץ DESIGN.md ואיך הוא מונע מבינה מלאכותית לשנות קוד

מהו DESIGN.md ומה AGENTS.md אינו מכסה

DESIGN.md הוא קובץ markdown בשורש המאגר שלכם, המסביר לסוכן קידוד מבוסס בינה מלאכותית מדוע הקוד בנוי כפי שהוא בנוי. AGENTS.md עונה על שאלה אחרת: כיצד לעבוד כאן, כלומר מהי פקודת ה-build, פקודת הבדיקות, ה-lint שחייב לעבור, והנתיבים שיש להשאיר ללא שינוי. DESIGN.md מתעד את ההחלטות שכבר התקבלו, ומה נשבר כאשר אחת מהן מבוטלת.

סוכן קידוד, כלומר כלי כמו Claude Code או Cursor שקורא ועורך את המאגר שלכם באופן עצמאי, הוא בעל ביטחון עצמי כברירת מחדל. הוא מוצא תבנית שאינו מזהה ומשפר אותה. מטמון (cache) שנכתב ידנית הופך ל-Redis (מאגר נתונים בזיכרון), כי כך נראה מטמון ברוב הקוד שהמודל קרא. AGENTS.md לא עוצר זאת, כיוון ש-make test עובר בכל מקרה. הכלל שהופר מעולם לא נכתב במקום שהסוכן יכול לקרוא.

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

מה באמת נמצא בתוך קובץ DESIGN.md מפורסם

הדרך המהירה ביותר ללמוד את הפורמט היא לקרוא קבצים שחברות מפרסמות על עצמן. המאגר official-design-md עוקב רק אחרי קבצים אלו. כלל ההכללה שלו מורכב משורה אחת, ושורה זו היא כל המהות של האוסף:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

נכון לאוקטובר 2026 הוא מונה אחד-עשר כאלו: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel ו-VoltAgent. כל קובץ נמצא בכתובת URL ציבורית, רובם בדומיין של המפרסם והשאר במאגר GitHub ציבורי, כך שניתן לקרוא אחד מהם בטרמינל כבר עכשיו.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

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

הקובץ של Nuxt מכיל כ-2,000 מילים נכון ל-27 באוקטובר 2026, ורובו מורכב מכלל והסיבה הנלווית אליו. הוא נפתח בהצהרה ש-dark mode הוא ערכת הנושא המוגדרת כברירת מחדל. הוא מפרט את הצבע הירוק של המותג #00DC82 עם הערה שצבעי המותג מיועדים "ללוגואים, תמונות לרשתות חברתיות והדפסה. אין להשתמש בהם כערכים גולמיים בקוד ה-UI". לקראת הסוף, סעיף תחת הכותרת Reject these כולל:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

הקובץ של Vercel ארוך יותר, כ-6,000 מילים נכון לאוקטובר 2026, והוא הולך צעד אחד רחוק יותר. אחת הכותרות שלו היא Reject generated-design reflexes. תחתיה מופיעה רשימה של מה שמחולל (generator) כשיר ניגש אליו כאשר איש לא הורה לו אחרת:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

המשפט הזה מגדיר את סוג הקובץ. זוהי רשימה כתובה של ברירות המחדל שמודל בטוח בעצמו מייצר, והיא מפורסמת כדי שהמודל יפסיק לייצר אותן. כל קובץ DESIGN.md שראוי לביצוע commit הוא רשימה כזו עבור תחום מסוים.

מדוע חברות מפרסמות קובץ DESIGN.md משלהן?

הקהילה הקדימה אותן. המאגר awesome-design-md מכיל 84 קבצים שחולצו מאתרים ציבוריים, לפי הספירה ב־README נכון ל-27 באוקטובר 2026. כל אחד מהם כתוב באותו פורמט של תשעה סעיפים, כך שניתן להפנות סוכן (agent) לאחד מהם והוא יפיק תוצר הדומה למבנה זה. קבצים אלו שימושיים, אך הם נותרים בגדר ניחוש. איש בחברות אלו לא סקר אותם.

קובץ ממקור ראשון הוא שונה, כיוון שהוא המקור ולא פרשנות של הפלט. כאשר Vercel משנה את סקאלת הטיפוגרפיה שלה, vercel.com/design.md משתנה יחד איתה. עותק שנסרק במרץ ימשיך ללמד את הסוכן שלכם את הסקאלה הישנה, ושום דבר במאגר שלכם לא יתריע שהעותק אינו מעודכן.

אחד-עשר מפרסמים הם עדיין מספר קטן, והמאגר מציין זאת: התקן חדש והאימוץ הרשמי נמצא במגמת עלייה. שני האוספים מתוחזקים על ידי VoltAgent, תשתית סוכנים בקוד פתוח שמפרסמת קובץ משלה גם כן, לכן יש לקרוא את הרשימה כמעקב ולא כמפקד ניטרלי. עם זאת, כדאי לעקוב אחריה בשל זהות המשתתפים. כמה מהן הן החברות שקוד ה-front-end שלהן מועתק בתדירות הגבוהה ביותר על ידי מפתחים אחרים, והערכים החדשים יותר – Ant Design, Microsoft FAST, Juspay ו-Oxide Computer – הם מערכות עיצוב שצוותים אחרים בונים עליהן. הקבצים שלהן הופכים לדוגמה המעשית למה ש-DESIGN.md אמור להיות. השוו זאת למסלול שעבר הקובץ AGENTS.md: agents.md מונה כיום מעל 60,000 פרויקטי קוד פתוח המשתמשים בפורמט זה, והניהול נמצא בידי Agentic AI Foundation תחת ה-Linux Foundation. הקובץ DESIGN.md החל לצעוד באותה דרך. ב-21 באפריל 2026, Google פרסמה בקוד פתוח טיוטת מפרט לפורמט, תחת השם google-labs-code/design.md, הכוללת סכימת אסימונים (token schema) וכלי CLI ברישיון Apache-2.0. נכון לאוקטובר 2026 הפורמט נמצא בגרסת alpha ועדיין בפיתוח פעיל; הוא מתוחזק על ידי Google Labs ולא על ידי קרן ניטרלית, והוא מתאר זהות ויזואלית, כך שהוא אינו מתייחס לאינווריאנטים שקובץ backend דורש. מוסכמות לקבצים קריאים לסוכנים מתגבשות במהירות, והן מתגבשות מלמעלה למטה.

מה לכלול בקובץ DESIGN.md כאשר לפרויקט אין ממשק משתמש

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

אינווריאנטים (Invariants). משפט אחד לכל אינווריאנט, המציין תנאי שחייב להישאר נכון לאחר כל עריכה. "כל פעולת כתיבה עוברת דרך queue.enqueue(). כתיבה ישירה למסד הנתונים מדלגת על לוג הביקורת, והלוג הזה הוא המקור שממנו קורא ייצוא התאימות (compliance export)." אינווריאנט המלווה בהסבר שורד מפגש עם משימה שלא צפית מראש. אינווריאנט ללא הסבר נתפס כהעדפה, והעדפות נוטות להימחק בתהליכי אופטימיזציה.

חלופות שנדחו. האפשרות המובנת מאליה, והסיבה לכך שהיא נפסלה. "אנחנו לא משתמשים ב-Redis עבור מטמון (caching). השירות רץ על גבי VPS בודד, לכן מפה בתוך התהליך (in-process map) מהירה יותר, וזהו daemon אחד פחות שיש לתחזק. יש לבחון זאת מחדש כאשר יתווסף שרת יישומים שני." ללא פסקה זו, סוכן שיתבקש להאיץ את המטמון יוסיף את Redis, והוא יפעל נכון: לא ציינת בפניו את האילוץ. זהו הסעיף שמצדיק את קיומו של הקובץ כולו.

גבולות (Boundaries). המקומות שבהם עריכה קטנה עלולה להוביל להשפעה רחבה. הסכימה של מסד הנתונים. תחילית הניתוב הציבורית שלקוחות כבר כתבו סקריפטים מולה. קובץ התצורה שהתהליך קורא לפני שהיישום עולה. רשומת ה-cron שמניחה שרק עותק אחד שלה רץ. יש לציין אותם ולפרט מה העלות של שינוי בכל אחד מהם. אם הסוכן יכול גם לגשת לרשת הפתוחה, למשל דרך מופע SearXNG מאוחסן עצמית המחובר כ-backend לחיפוש, זהו גבול שראוי לתעד, כיוון שהקובץ צריך להגדיר איזה טקסט שנשאב מותר להשפיע על הקוד ואיזה טקסט מיועד רק לציטוט בחזרה אליך.

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

קובץ DESIGN.md שניתן להעתיק כבר היום

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

מלאו את שני הסעיפים שאתם יכולים לכתוב מהזיכרון כבר היום, אינווריאנטים (invariants) וחלופות שנדחו (rejected alternatives), והשאירו את השאר ככותרות בלבד. קובץ עם ארבע שורות כנות עובד היטב. קובץ עם ארבעים שורות של ניחושים אינו עובד. אם המאגר מכיל כמה חבילות, קובץ שורש אחד לא יתאים לכולן, ואותה חלוקה לפי ספריות שעובדת עבור קובצי AGENTS.md מקוננים ב-monorepo תקפה גם כאן: קובץ שורש קצר עבור ההחלטות המשותפות לכל הפרויקט, וקובץ קטן יותר לצד כל חבילה שיש לה החלטות משלה.

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

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

אנטי-תבנית: קובץ DESIGN.md שחוזר על ה-README

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

הדבר גובה מכם מחיר כפול. המחיר הראשון הוא הקשר (context). קובץ שהסוכן קורא בתחילת כל משימה נצרך בכל משימה, וסעיף התקנה כפול הוא תקורה טהורה על פני חלון זיכרון מוגבל. ניהול החלון הזה הוא מיומנות בפני עצמה, המכוסה ב-ניהול חלון ההקשר ב-Claude Code. הגרסה הקצרה: כל מה שנטען אוטומטית צריך להיות הטקסט בעל הערך הגבוה ביותר במאגר.

המחיר השני גרוע יותר. שני עותקים של אותה הצהרה נוטים להשתנות בנפרד. ה-README מציין שהשירות מאזין בפורט 8080, בעוד ש-DESIGN.md עדיין מציין 3000, ולסוכן אין דרך לדרג אחד על פני השני; הוא בוחר אחד וכותב קוד סביבו. קובץ שלעיתים אינו מדויק זוכה לאותו אמון כמו קובץ שתמיד מדויק.

הבדיקה מהירה. אם פסקה יכולה להשתלב בנוחות ב-README, מחקו אותה מ-DESIGN.md. מה שנותר צריך להיות החלק שהייתם אומרים בקול רם ב-code review, החלק שמתחיל ב-"כבר ניסינו את זה".

איך יודעים שהקובץ עובד?

אין כלי linter לבדיקת העניין הזה. ישנה בדיקה שאפשר להריץ תוך דקה.

תנו לסוכן משימה שנתקלת ישירות באילוץ (invariant). למשל: "הוסף משימת רקע שמסמנת שורות ישנות כפגות תוקף". קובץ שמבצע את עבודתו יבוא לידי ביטוי בתשובה עוד לפני שיופיע קוד כלשהו: הסוכן אמור לציין שהמשימה כותבת דרך queue.enqueue(), כיוון שכתיבה ישירה תעקוף את ה-audit log. אם הוא פותח חיבור למסד נתונים וכותב, אחת משתי אפשרויות נכונה: או שהקובץ כלל לא נקרא, או שהאילוץ מנוסח בצורה רופפת מדי שמאפשרת ויכוח.

עקבו גם אחר ספירת ה-tokens, שכן קובץ זה נטען בכל אינטראקציה. אם השימוש ב-context מזנק לאחר הוספת DESIGN.md והתשובות אינן משתפרות, הקובץ מכיל טקסט שהסוכן כבר הכיר. קריאת מוני ה-tokens ב-Claude Code מראה לאן התקציב הזה הולך.

זה חשוב במיוחד כאשר הסוכן פועל על שרת ולא על המחשב הנייד שלכם. סוכן שעובד בסשן ארוך, כמו ההגדרה ב-סביבת עבודה של Claude Code על גבי VPS עם tmux, אינו זוכר את השיחה מאתמול. ה-repository הוא הזיכרון. כל מה שהסברתם בצ'אט ולא ביצעתם לו commit אובד בסשן הבא, ו-DESIGN.md הוא המקום שבו הסבר זה נשמר כדי שישרוד.

התחילו בהחלטות שאתם מתווכחים עליהן

הגרסה הראשונה לוקחת עשרים דקות. פתחו את ה-pull requests האחרונים שבהם סוקר כתב "לא, אנחנו עושים את זה אחרת כאן". כל הערה כזו היא אינווריאנטה (invariant) שמעולם לא נכתבה, וכל אחת מהן היא נקודה שבה סוכן יבצע את אותה טעות, מהר יותר ובתדירות גבוהה יותר מאדם. הוסיפו לקובץ כאשר הוא נכשל מולכם, לא לפי לוח זמנים. אם אתם עדיין מנסים להבין היכן סוכנים משתלבים בתהליך פיתוח סטנדרטי, המדריך ללימוד סוכני AI לשנת 2026 הוא תחנה הבאה סבירה.

FAQ

האם DESIGN.md הוא תקן רשמי?

לא באותו אופן שבו AGENTS.md הוא תקן. ל-AGENTS.md יש בית בכתובת agents.md, הוא נמצא בשימוש ביותר מ-60,000 פרויקטים של קוד פתוח, והוא מנוהל תחת ה-Agentic AI Foundation, שהיא חלק מה-Linux Foundation. ל-DESIGN.md יש מפרט מפורסם אך אין לו גוף מנהל ניטרלי. גוגל פרסמה טיוטת מפרט בקוד פתוח ב-21 באפריל 2026, והוא נמצא במאגר google-labs-code/design.md תחת רישיון Apache-2.0. נכון לאוקטובר 2026 הוא נמצא בגרסת alpha ועדיין נמצא בפיתוח פעיל, והוא מתאר זהות חזותית: צבעים, טיפוגרפיה, פריסה ורכיבים. ל-DESIGN.md יש גם אימוץ מצד צדדים ראשונים: אחת-עשרה חברות ופרויקטים, כולל Vercel, Nuxt, Atlassian ו-Resend, מפרסמים קובץ כזה, ואוסף קהילתי הכיל 84 נוספים שחולצו מאתרים ציבוריים נכון ל-27 באוקטובר 2026. עבור קובץ backend של אינווריאנטים (invariants) וחלופות שנדחו, התייחסו אליו כאל מוסכמה שניתן לאמץ כעת ולהרחיב בחופשיות, מכיוון שאין מפרט שמכסה את שמות הסעיפים הללו.

האם DESIGN.md צריך להיות פשוט סעיף בתוך AGENTS.md?

עבור מאגר קטן, כן. קובץ אחד שהסוכן (agent) בהחלט קורא עדיף על שני קבצים שבהם אחד מהם מקבל התעלמות. פצלו אותם כאשר AGENTS.md מפסיק להיות קריא לסריקה, או כאשר אתם מבחינים ששני החלקים משתנים בקצבים שונים. AGENTS.md משתנה כאשר ה-build משתנה. DESIGN.md משתנה כאשר החלטה משתנה, וזה קורה לעיתים רחוקות יותר ונושא משקל רב יותר. כאשר אתם מפצלים, הוסיפו שורה אחת ל-AGENTS.md המורה לסוכן לקרוא את DESIGN.md לפני עריכת קוד, מכיוון שלא כל כלי טוען כל קובץ markdown בשורש המאגר.

במה שונה DESIGN.md מתיעוד החלטות ארכיטקטורה (ADR)?

ADR (ר"ת של architecture decision record) הוא תיעוד מתוארך של החלטה אחת, ופרויקט בריא צובר עשרות כאלו בתיקייה. זוהי היסטוריה, והיסטוריה היא יקרה לטעינה, שכן סוכן יצטרך לקרוא את כולם כדי להבין אילו מהם עדיין תקפים. DESIGN.md הוא המצב הנוכחי, שנכתב כדי להיקרא במלואו בכל משימה. שמרו את שניהם אם אתם כבר כותבים ADRs. ה-ADR מציין מה הוחלט ומתי. DESIGN.md מציין מה נכון להיום, והוא הקובץ שאליו תפנו את הסוכן.

מה צריך להיות האורך של DESIGN.md?

קצר מספיק כדי להיטען בכל סבב ללא חרטה. הדוגמאות המפורסמות ארוכות מכיוון שהן מגדירות שפה חזותית שלמה: הקובץ של Nuxt הוא באורך של כ-2,000 מילים והקובץ של Vercel כ-6,000 נכון לאוקטובר 2026. שירות backend בדרך כלל זקוק להרבה פחות. התחילו בעמוד אחד והרחיבו אותו רק כאשר סוכן מבצע טעות שמשפט אחד היה מונע. אורך אינו המדד. כל שורה צריכה להיות דבר שהסוכן היה טועה בו אחרת.