איך לעדכן את AGENTS.md באופן אוטומטי בעזרת dox

מדוע הקובץ AGENTS.md שלכם הופך ללא רלוונטי כעבור שלושה שבועות

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

הסוכן (agent) קורא את הקובץ ומאמין לתוכנו. זה החלק שעולה לכם ביוקר. מאגר ללא AGENTS.md גורם לסוכן תכנות לבחון את השטח לפני שהוא פועל. מאגר עם AGENTS.md שגוי גורם לו להפסיק לחפש, כי כבר יש לו תשובה. הוא מריץ את הפקודה שהקובץ שלכם מציין, ה-shell עונה Missing script: "test", וכעת הסוכן מתחיל לנחש. לעיתים קרובות הוא עורך את package.json כדי להוסיף את הסקריפט שהתיעוד שלכם הבטיח. הקובץ המיושן לא נכשל בשקט. הוא גרם לעריכה שלא רציתם.

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

מהו dox, ומה הוא אינו

dox הוא קובץ Markdown יחיד. המאגר נמצא ב-agent0ai/dox, הוא מופץ תחת רישיון MIT, ונכון ל-11 באוגוסט 2026, הפרויקט כולו הוא AGENTS.md בגודל 3906 בתים, הכולל קובץ README, קובץ LICENSE ושתי תמונות. אין חבילה להתקנה ואין סביבת הרצה (runtime).

זה משמעותי, כיוון שהמילה "מחולל" (generator) מרמזת על תוכנה שמנתחת את הקוד שלכם. שום דבר לא מנתח את הקוד שלכם. dox הוא חוזה שסוכן הקידוד שלכם קורא: הסוכן שלכם הוא המחולל, ו-dox הוא סט ההוראות שמורה לו מתי לקרוא את התיעוד, מתי לשכתב אותו, ומהי הצורה שכל מסמך מקבל.

הקובץ מכיל עשרה סעיפים, ושניים מהם מבצעים את העבודה. הסעיף "Read Before Editing" מורה לסוכן לעבור משורש המאגר לכל נתיב שהוא מתכנן לשנות, ולקרוא כל קובץ AGENTS.md לאורך כל נתיב, בסשן הנוכחי, מבלי להסתמך על זיכרון. הסעיף "Update After Editing" מורה לו שכל שינוי משמעותי דורש מעבר DOX, כלומר שלב עדכון תיעוד שמתבצע לפני שהמשימה נחשבת כהושלמה. המעבר מעדכן את המסמך הקרוב ביותר שבבעלותו כאשר המטרה, המבנה, זרימת העבודה, ההרשאות או העדפות המשתמש השתנו.

שאר הקובץ עוסק במבנה. לקובץ AGENTS.md צאצא יש סדר סעיפים ברירת מחדל: מטרה (Purpose), בעלות (Ownership), חוזים מקומיים (Local Contracts), הנחיות עבודה (Work Guidance), אימות (Verification), ואינדקס DOX של צאצאים (Child DOX Index). קובץ השורש מכיל חוקים כלל-פרויקטיביים בתוספת אינדקס DOX של צאצאים ברמה העליונה, וזו הדרך שבה סוכן מגלה את מסמכי הצאצאים. "Closeout" הוא רשימת התיוג שהסוכן מריץ בסוף משימה: בדיקה חוזרת של הנתיבים ששונו מול השרשרת, עדכון המסמכים הקרובים ביותר שבבעלותו, רענון כל אינדקס מושפע, מחיקת סתירות, הרצת אימות קיים, ודיווח על אילו מסמכים הוא השאיר ללא שינוי במכוון.

קיבוע התיעוד ל-commit ספציפי, לא ל-main

במאגר אין תגיות (tags) או גרסאות (releases), לכן אין מספר גרסה שאפשר לקבע. במקום זאת, יש לקבע את ה-commit. הקובץ AGENTS.md הנוכחי הוא ב-commit מספר f34ec7ad1055d3393887e5a2670e8cb7320c9165, מתאריך 1 באוגוסט 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

הפקודה wc -c אמורה להדפיס 3906. מספר שונה מעיד על כך שלא משכת את הקובץ המתואר במדריך זה, לכן עליך לקרוא אותו לפני שתסתמך עליו. אם תקליד בטעות hash שגוי של commit, הפקודה -f תגרום ל-curl לעצור עם curl: (22) The requested URL returned error: 404 ולא לכתוב תוכן, והפקודה wc -c תדפיס לאחר מכן 0. קובץ קטוע גרוע יותר מקובץ חסר, כיוון שהסוכן יפעל לפי חצי חוזה מבלי לדעת זאת.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

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

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

Initialize DOX tree for this project now.

פעולה זו יוצרת את קובצי ה-AGENTS.md המשניים ואת האינדקסים המפנים אליהם. בדוק מה התבצע לפני שתסתמך על התוצאה:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

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

מה dox יכול לראות, ומה הוא אינו יכול לדעת

הסוכן שבונה את העץ שלך קורא את ה-repository, לכן כל מה שנמצא ב-repository יכול להיכנס ל-inventory: מבנה הספריות, קובצי ה-manifest של החבילות וקובצי ה-lock, הסקריפטים ב-package.json או ב-Makefile או ב-pyproject.toml, קובצי ה-workflow של ה-CI, ה-Dockerfiles, נקודות הכניסה (entry points), ו-CODEOWNERS אם קיים כזה. inventory שנבנה מתוך אלו הוא באמת בעל תחזוקה עצמית. כאשר חבילה עוברת מיקום, הסבב הבא מעדכן את השורה שמתארת אותה.

כל מה שמופיע להלן הוא באחריותך להצהיר, כיוון שהוא אינו נמצא ב-repository כדי שניתן יהיה לקרוא אותו:

• הסיבה לקיומו של כלל מסוים, מה שמונע מהסוכן להסיר אותו כמורכבות מיותרת.
• איזה מבין שני נתיבי עבודה נתמך, ואיזה מהם ממתין למחיקה.
• כל דבר שנמצא מחוץ ל-repository, כגון סביבת ה-staging או הסיבה לכך שתלות מסוימת מקובעת (pinned) שתי גרסאות אחורה.
• מה התוכניות שלך לשבוע הבא, מה שמהווה את ההבדל בין קובץ עדכני לבין קובץ שימושי.

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

הפרדת כוונת הכותב מהמלאי המופק אוטומטית

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

ישנם שני מנגנונים, ואתם זקוקים לשניהם.

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

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

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

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

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

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

ביצוע רענון ב־pull request, ולא לפי תזמון

הרגע הטוב ביותר לרענן מסמך הוא בעת ה־commit שגורם לו להיות שגוי. כללו את פעולת ה־DOX באותו ה־pull request שבו בוצע השינוי המבני; כך ה־diff יישאר קטן מספיק כדי שיהיה ניתן לקרוא אותו בפועל.

בדיקה חוסמת שמבצעת אכיפה של הנושא:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

התאימו את הנתיבים למאגר שלכם. הערך המוסף הוא שהבדיקה נכשלת בענף (branch), שם התיקון זול, והיא נכשלת מסיבה שסוקר יכול לפעול לפיה.

לוח זמנים הוא גיבוי, לא המנגנון העיקרי. משימה שבועית תופסת את מה שאף אחד לא הבחין בו בענף: קבצים שהועברו ב־rebase, חבילה שנמחקה ב־merge, או מסמך שמפנה לספרייה שכבר אינה קיימת. הריצו זאת על שרת קטן, אותו שרת שבו אתם עשויים להשתמש כדי להריץ סוכן תכנות על גבי VPS, והגדירו שהמשימה תפתח pull request במקום לבצע push ישירות ל־main.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

הערה זו היא מציין מיקום מכוון. לכל סוכן יש CLI (ממשק שורת פקודה) משלו ודגל (flag) ייעודי להרצה לא אינטראקטיבית. פקודה שמועתקת מדף אינטרנט ואינה תואמת לגרסה שלכם תיכשל בתוך cron, שם איש לא יראה את השגיאה. מלאו את הפרטים והריצו את הסקריפט ידנית פעם אחת לפני שאתם מתזמנים אותו. ה־|| exit 0 חשוב גם הוא: git commit מסיים את הפעולה עם קוד יציאה שאינו אפס עם nothing to commit, working tree clean כאשר העץ כבר מעודכן, ותחת set -e זה ידווח על הרצה תקינה כעל כשל.

כל הרצה עולה ב־tokens, כיוון שפעולת "קריאה לפני עריכה" גורמת לסוכן לקרוא את כל השרשרת בכל משימה. זהו המחיר, וכדאי לעקוב אחריו אם אתם כבר מחשבים את עלות ההרצות של הסוכן שלכם.

Monorepos: חוזים רבים, אינדקס אחד

קובץ AGENTS.md שורשי יחיד במאגר המכיל ארבעים חבילות מייצר diff של יצירה מחדש שאף אחד לא קורא, ומסמך שרובו אינו רלוונטי למה שהסוכן עושה כרגע. הפתרון של dox הוא אינדקס DOX לילדים (Child DOX Index): השורש מכיל כללים החלים על כל המאגר ומפנה לילדיו, וכל גבול בר-קיימא מחזיק קובץ משלו. כיצד להגדיר את מבנה העץ הזה, ואילו כלים קוראים קבצים מקוננים בכלל, מוסבר ב-קבצי AGENTS.md מקוננים עבור monorepos.

מה ש-dox משנה הוא שטח הפנים של הסקירה. בקשת משיכה (pull request) שנוגעת ב-packages/api צריכה לייצר diff של תיעוד בתוך packages/api ולא בשום מקום אחר:

git diff --stat -- '*AGENTS.md'

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

סקירת ה-diff כמו קוד

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

• פקודה שהקובץ מציין כעת, שעליכם להריץ בעצמכם לפני ה-merge. הוראות בנייה מומצאות הן הכשל הנפוץ ביותר.
• שורה שנמחקה והכילה כוונה מסוימת. הוספות הן זולות; מחיקות הן המקום שבו אובדן מידע מתרחש.
• נתיב אבסולוטי, שם מארח (hostname), כתובת URL פנימית, או כל דבר שנראה כמו פרטי הזדהות.
• רשומה במלאי (inventory) עבור משהו שכבר אינו קיים, עניין ש-ls פותר בשנייה.

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

כאשר מתרחשת תקלה

התהליך מחק את בלוק הכוונה שלך. הבדיקה diff לעיל מדפיסה את השורות שהוסרו. שחזר את הקובץ מנקודת ה-branch באמצעות git restore --source=origin/main AGENTS.md, ולאחר מכן הרץ שוב את התהליך עם הוראה ממוקדת יותר המציינת את הסעיפים שניתן לשנות.

שני ענפים עברו יצירה מחדש. אתה מקבל CONFLICT (content): Merge conflict in AGENTS.md וסימני התנגשות <<<<<<< HEAD בתוך הקובץ. אל תערוך את הסימנים ידנית. הקובץ נוצר באופן אוטומטי, לכן הפתרון הנכון הוא הרצה מחדש של התהליך על העץ הממוזג.

הסוכן מתעלם מהקובץ לחלוטין. בדוק איזה שם קובץ הכלי שלך קורא בפועל. אם הוא קורא קובץ אחר, הפנה אותו לאותו תוכן באמצעות ln -s AGENTS.md CLAUDE.md ובצע commit לקישור הסימבולי (symlink), כך שתשמור על מקור אחד במקום על שני מסמכים שמתפצלים זה מזה.

העץ הצמיח צאצאים שאף אחד לא אינדקס. השווה את הפלט של find . -name AGENTS.md מול רשומות האינדקס במסמכי האב. צאצא שאינו מוזכר באף אינדקס הוא צאצא שהסוכן ידלג עליו מבלי לעצור.

מתי מחולל הוא מוגזם

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

dox שווה את ההשקעה כאשר ב-repository יש גבולות שאף אדם לא מחזיק בראשו: כמה חבילות עם חוקים שונים, או תורמים שמגיעים ללא הרקע הנדרש. הערך אינו הטקסט שמחולל. הערך הוא שהתיעוד הופך למשהו ש-pull request יכול להיכשל בגללו, וזו הסיבה היחידה לכך שקובץ כלשהו ב-repository נשאר מעודכן.

FAQ

האם עלי להתקין משהו כדי להשתמש ב-dox?

לא. dox הוא קובץ Markdown יחיד, תחת רישיון MIT, ונכון ל-11 באוגוסט 2026 המאגר אינו מפיץ חבילות או גרסאות (releases). עליך להעתיק את תוכנו לתוך הקובץ AGENTS.md בפרויקט שלך, וסוכן הקידוד שלך יפעל לפי הכללים המפורטים שם. קבע (pin) את ה-commit שהעתקת, f34ec7ad1055d3393887e5a2670e8cb7320c9165 בעת כתיבת שורות אלו, וציין אותו בהודעת ה-commit שלך כדי שתוכל לדעת מאוחר יותר באיזו גרסה של הכללים נבנה העץ שלך.

כיצד אוכל למנוע מתהליך יצירה מחדש למחוק את הכללים שכתבתי בעצמי?

הפרד בין כוונה לבין מלאי. הנמקה עמידה צריכה להופיע במסמך נפרד, וכל מה שחייב להישאר בתוך AGENTS.md צריך להיות בתוך בלוק מסומן. לאחר מכן, בדוק את הבלוק ב-CI: חלץ אותו מה-branch ומ-origin/main באמצעות sed, השווה בין השניים בעזרת diff, וגרום ל-build להיכשל בכל מקרה של הבדל. אדם יאשר או יבטל את השינוי, במקום שהוא יעבור ללא הבחנה בתוך diff גדול.

באיזו תדירות עלי ליצור מחדש את AGENTS.md?

בכל פעם שמתבצע pull request שהופך אותו ללא מדויק. שינוי מבני והתיעוד שלו שייכים לאותו diff, כיוון שזהו הרגע היחיד שבו למישהו יש את ההקשר הנדרש כדי לבחון את שניהם. מעבר מתוזמן שבועי הוא גיבוי לסטייה שחמקה מ-branch, ועליו לפתוח pull request במקום לבצע commit ישירות ל-main.

האם פקודות build צריכות להיות ב-AGENTS.md שבשורש או בקובץ בן?

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

האם dox כדאי עבור מאגר קטן?

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