מהו קובץ 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

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

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

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

חלופות שנדחו (Rejected Alternatives)

• שימוש במערכת ניהול ידע חיצונית (כמו Confluence): נדחה מכיוון שהוא מנתק את התיעוד מהקוד ומונע בקרת גרסאות משותפת.
• שמירת כל ההחלטות בקובץ יחיד בשורש הפרויקט: נדחה עבור פרויקטים מרובי חבילות כדי למנוע קובץ גדול מדי וקונפליקטים ב-Git.
• שימוש בפורמט Wiki בתוך ה-Repository: נדחה כי הוא אינו נגיש בקלות לסקריפטים של אוטומציה ואינו עובר Code Review כחלק מה-Pull Request.

תהליך קבלת החלטות

מבנה המסמך

קריטריונים להערכת חלופות

תהליך עדכון ושינוי החלטות

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

למידע נוסף על ניהול החלטות ברמת ה-repository, עיינו ב-קבצי AGENTS.md מקוננים ב-monorepo.

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

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