מהו קובץ 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, הוא מונה שבעה כאלה: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel ו-VoltAgent. כל קובץ נמצא בכתובת URL ציבורית קבועה, כך שניתן לקרוא אחד מהם בטרמינל כבר עכשיו.

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

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

הקובץ של Nuxt משתרע על פני כ-2,100 מילים, ורובו מורכב מכלל בצירוף הנימוק שלו:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

הקובץ של Vercel ארוך יותר, כ-6,500 מילים נכון לאוגוסט 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 מכיל 73 קבצים שעברו הנדסה לאחור מאתרים ציבוריים. כל אחד מהם כתוב באותו פורמט של תשעה סעיפים, כך שניתן להפנות סוכן (agent) לאחד מהם כדי להפיק תוצאה הדומה למראה המקורי. הקבצים הללו שימושיים, אך הם נותרים בגדר ניחוש. איש בחברות הללו לא סקר אותם.

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

שבעה מפרסמים הם מספר קטן, והמאגר מציין זאת במפורש: התקן חדש והאימוץ הרשמי נמצא במגמת עלייה. שני האוספים מתוחזקים על ידי VoltAgent, תשתית סוכנים בקוד פתוח שמפרסמת קובץ משלה גם כן, לכן יש לקרוא את הרשימה כמעקב ולא כמפקד ניטרלי. עם זאת, כדאי לעקוב אחריה, בשל זהות שבע החברות הללו. אלו הן החברות שקוד ה-front-end שלהן מועתק בתדירות הגבוהה ביותר על ידי מפתחים אחרים, והקבצים שלהן הופכים לדוגמה המייצגת של מהו DESIGN.md. השוו זאת למסלול שעבר הקובץ AGENTS.md: agents.md מונה כיום מעל 60,000 פרויקטי קוד פתוח המשתמשים בפורמט זה, והניהול שלו נמצא תחת ה-Agentic AI Foundation במסגרת ה-Linux Foundation. מוסכמות לקבצים קריאים עבור סוכנים מתגבשות במהירות, והן מתגבשות מלמעלה למטה.

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

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

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

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

גבולות (Boundaries). המקומות שבהם עריכה קטנה עלולה להוביל להשפעה רחבה. סכימת מסד הנתונים. קידומת הנתיב הציבורי (public route prefix) שלקוחות כבר כתבו סקריפטים עבורה. קובץ התצורה שהפריסה (deploy) קוראת לפני שהיישום עולה. ערך ה-cron שמניח שרק עותק אחד של התוכנית רץ. הגדירו אותם, וציינו מהי העלות של שינוי בכל אחד מהם.

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

עיצוב מסמך 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.

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

כלים מסוימים טוענים כל קובץ 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 עבור זה. יש בדיקה שאפשר להריץ בדקה.

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

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

זה משמעותי במיוחד כאשר ה-agent פועל על שרת ולא על המחשב הנייד שלכם. ל-agent שעובד בסשן ארוך, כמו ההגדרה ב-סביבת עבודה של 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. נכון לאוגוסט 2026, ל-DESIGN.md אין גוף מנהל ואין מפרט מפורסם. מה שיש לו הוא אימוץ מצד חברות מובילות: שבע חברות, בהן Vercel, Nuxt, Atlassian ו-Resend, מפרסמות קובץ כזה בכתובת ציבורית, ואוסף קהילתי מכיל 73 קבצים נוספים שבוצע להם הנדוס לאחור מאתרים ציבוריים. התייחסו אליו כאל מוסכמה שניתן לאמץ כעת ולהרחיב בחופשיות, שכן אין גורם שמתקף את שמות הסעיפים שלכם.

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

עבור מאגר קוד קטן, כן. קובץ אחד שהסוכן קורא בוודאות עדיף על שני קבצים שאחד מהם עלול להתעלם ממנו. פצלו אותם כאשר 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,100 מילים והקובץ של Vercel מכיל כ-6,500 מילים נכון לאוגוסט 2026. שירות backend בדרך כלל זקוק להרבה פחות. התחילו מעמוד אחד והרחיבו אותו רק כאשר סוכן מבצע טעות שמשפט אחד היה יכול למנוע. אורך אינו המדד. כל שורה צריכה להיות דבר שהסוכן היה טועה בו אחרת.