איך לעדכן את AGENTS.md באופן אוטומטי עם dox
קובץ AGENTS.md מיושן גורם לסוכני בינה מלאכותית לבצע פעולות שגויות. השתמשו ב-dox כדי ליצור את התיעוד מתוך הקוד, לבחון את ה-diff ולמנוע שגיאות הרצה כמו Missing script.
מדוע קובץ AGENTS.md שלכם הופך לשגוי לאחר שלושה שבועות
קובץ AGENTS.md מתיישן מכיוון שאין שום דבר שמקשר בינו לבין הקוד. אתם כותבים אותו פעם אחת, ידנית, ביום שבו המאגר נראה בצורה מסוימת. לאחר מכן מריץ הבדיקות משתנה, חבילה עוברת מיתוג מחדש, שירות נמחק, והקובץ עדיין מתאר את המצב של יוני. שום דבר לא נכשל, כי אף שלב ב-build לא קורא אותו.
הסוכן (agent) קורא את הקובץ ומאמין לו. זה החלק שעולה לכם ביוקר. מאגר ללא AGENTS.md גורם לסוכן תכנות לבחון את השטח לפני שהוא פועל. מאגר עם AGENTS.md שגוי גורם לו להפסיק לבדוק, כי כבר יש לו תשובה. הוא מריץ את הפקודה שציינתם בקובץ, ה-shell עונה Missing script: "test", וכעת הסוכן מתחיל לנחש. לעיתים קרובות הוא עורך את package.json כדי להוסיף את הסקריפט שהתיעוד שלכם הבטיח. הקובץ המיושן לא נכשל בשקט. הוא גרם לעריכה שלא רציתם.
dox הוא פתרון אחד לכך. זהו סט חוקים, שנכתב עבור הסוכן, שהופך את עדכון התיעוד לחלק מסיום העבודה, כך שהקובץ משתנה באותו commit שבו השתנה הקוד שהפך אותו לשגוי.
מהו dox, ומה הוא אינו
dox הוא קובץ Markdown יחיד. המאגר נמצא ב-agent0ai/dox, הוא מופץ תחת רישיון MIT, ונכון ל-13 באוקטובר 2026, הפרויקט כולו הוא AGENTS.md בגודל 3965 בתים, הכולל קובץ README, קובץ LICENSE ושתי תמונות. אין חבילה להתקנה ואין סביבת הרצה (runtime).
זה משמעותי, כיוון שהמילה "מחולל" (generator) מרמזת על תוכנית שמנתחת את הקוד שלכם. שום דבר לא מנתח את הקוד שלכם. dox הוא חוזה שסוכן הקידוד שלכם קורא: הסוכן שלכם הוא המחולל, ו-dox הוא מערך ההוראות שמורה לו מתי לקרוא את התיעוד, מתי לשכתב אותו, ומהו המבנה של כל מסמך.
הקובץ כולל תשעה סעיפים, ושניים מהם מבצעים את העבודה. "קרא לפני עריכה" (Read Before Editing) מורה לסוכן לסרוק משורש המאגר ועד לכל נתיב שהוא מתכנן לשנות, ולקרוא כל קובץ AGENTS.md לאורך כל נתיב, בסשן הנוכחי, מבלי להסתמך על זיכרון. "עדכן לאחר עריכה" (Update After Editing) מורה לו שכל שינוי משמעותי מחייב מעבר DOX, כלומר שלב עדכון תיעוד שמתבצע לפני שהמשימה נחשבת כהושלמה. המעבר מעדכן את המסמך הקרוב ביותר שבבעלותו כאשר המטרה, המבנה, זרימת העבודה, ההרשאות או העדפות המשתמש השתנו.
שאר הקובץ עוסק במבנה. לקובץ AGENTS.md צאצא יש סדר סעיפים ברירת מחדל: מטרה, בעלות, חוזים מקומיים, הנחיות עבודה, אימות, ואינדקס DOX צאצאים. קובץ השורש מכיל חוקים כלל-פרויקטיביים בתוספת אינדקס DOX צאצאים ברמה העליונה, שזו הדרך שבה סוכן מגלה את מסמכי הצאצאים. "סגירה" (Closeout) היא רשימת התיוג שהסוכן מריץ בסוף משימה: בדיקה חוזרת של הנתיבים ששונו מול השרשרת, עדכון מסמכי הבעלות הקרובים ביותר, רענון כל אינדקס מושפע, מחיקת סתירות, הרצת אימות קיים, ודיווח על אילו מסמכים הוא השאיר ללא שינוי במכוון.
קיבוע dox ל־commit ספציפי, לא ל-main
במאגר אין תגיות (tags) או גרסאות (releases), לכן אין מספר גרסה שאפשר לקבע. במקום זאת, קבעו את ה-commit. הקובץ AGENTS.md הנוכחי הוא ה-commit שמספרו 765ae4ac02cc884eefcd41a3d0f71941721adb89, מתאריך 1 בספטמבר 2026.
mkdir -p .agent
curl -fsSL -o .agent/dox-765ae4a.md \
https://raw.githubusercontent.com/agent0ai/dox/765ae4ac02cc884eefcd41a3d0f71941721adb89/AGENTS.md
wc -c .agent/dox-765ae4a.mdהפקודה wc -c אמורה להדפיס 3965. מספר שונה מעיד על כך שלא משכתם את הקובץ המתואר במדריך זה, לכן קראו אותו לפני שתסתמכו עליו. אם תקלידו את ה-hash של ה-commit בשגיאה, -f יגרום ל-curl לעצור עם curl: (22) The requested URL returned error: 404 ולא לכתוב תוכן, ו-wc -c ידפיס לאחר מכן 0. קובץ חלקי גרוע יותר מקובץ חסר, כיוון שהסוכן יפעל לפי חצי חוזה מבלי לדעת זאת.
אם קיבעתם את ה-commit המוקדם יותר, f34ec7a מה-1 באוגוסט 2026, בדקו את ה-Child DOX Index שלו. בגרסה ההיא הסעיף מתאר את המאגר של dox עצמו: הוא מציין שאין צורך בקובצי AGENTS.md משניים ומפרט את README.md, LICENSE ושתי התמונות כקבצים בבעלות root. אם תעתיקו אותו לפרויקט שלכם, האינדקס הזה יתאר את המאגר הלא נכון. העדכון מה-1 בספטמבר החליף אותו במציין מיקום (placeholder) המציין שהפרויקט טרם עבר אינדוקס ומורה לסוכן לסרוק את המאגר ולבנות את העץ לפני שימשיך. החליפו את הסעיף הישן באינדקס האמיתי שלכם או במציין המיקום החדש.
cp .agent/dox-765ae4a.md AGENTS.md
git add AGENTS.md .agent/dox-765ae4a.md
git commit -m "Add DOX rules (agent0ai/dox @ 765ae4a)"הפקודה cp מיועדת למאגר שעדיין אין בו AGENTS.md. אם כבר יש לכם אחד כזה, אל תדרסו אותו. הציבו את סעיפי dox מעל התוכן הקיים שלכם, שמרו על הכללים שלכם מתחת, וקראו את התוצאה פעם אחת מההתחלה ועד הסוף. שני מסמכים שסותרים זה את זה יגרמו לסוכן לפעול לפי השורה האחרונה שקרא.
לאחר מכן, בקשו מהסוכן שלכם, בתוך המאגר, לבצע את המעבר הראשון. ה-README מספק את הניסוח המדויק:
Initialize DOX tree for this project now.פעולה זו יוצרת את קובצי ה-AGENTS.md המשניים ואת האינדקסים שמפנים אליהם. כדאי לבקש זאת במפורש, גם אם אינדקס מציין המיקום מורה לסוכן לעשות זאת לפני כל עבודה אחרת: כך תקבלו את כל העץ ב-commit אחד שניתן לבדיקה, במקום כתוצר לוואי של משימה לא קשורה. בדקו מה הוא עשה לפני שתסתמכו על כך:
git status --short
find . -name AGENTS.md -not -path './.git/*' | sortכל קובץ בפלט של find צריך להופיע ב-Child DOX Index כלשהו מעליו. מסמך משני שאף אינדקס לא מציין הוא מסמך שהסוכן עלול לפספס, כיוון שהאינדקס הוא הדרך שלו למצוא מסמכים שלא נמצאים ישירות על הנתיב שבו הוא עובר.
מה dox יכול לראות ומה הוא אינו יכול לדעת
הסוכן שבונה את העץ שלך קורא את ה-repository, לכן כל דבר שנמצא ב-repository יכול להיכנס למלאי: מבנה הספריות, קובצי ה-manifest של החבילות וקובצי ה-lockfile, הסקריפטים ב-package.json או ב-Makefile או ב-pyproject.toml, קובצי ה-workflow של ה-CI, ה-Dockerfiles, נקודות הכניסה (entry points), ו-CODEOWNERS אם קיים כזה. מלאי שנבנה מתוך אלו הוא באמת מתוחזק עצמית. כאשר חבילה עוברת מיקום, המעבר הבא מעדכן את השורה שמתארת אותה.
כל מה שמופיע להלן הוא באחריותך להצהיר, כיוון שהוא אינו נמצא ב-repository כדי שניתן יהיה לקרוא אותו:
- מדוע חוק מסוים קיים; זה מה שמונע מסוכן להסיר אותו כמורכבות מיותרת.
- איזה משני נתיבי עבודה נתמך, ואיזה מהם ממתין למחיקה.
- כל דבר שנמצא מחוץ ל-repository, כגון סביבת ה-staging או הסיבה לכך שתלות מסוימת מקובעת (pinned) שתי גרסאות אחורה.
- מה אתה מתכנן לעשות בשבוע הבא; זה ההבדל בין קובץ שהוא עדכני לבין קובץ שהוא שימושי.
dox יודע זאת על עצמו. הכללים שלו קובעים כי הנחיות עבודה (Work Guidance) חייבות לשקף את הסטנדרטים הנוכחיים של הפרויקט או את ההנחיות של המשתמש, ואם אין כאלו עדיין, עליך להשאיר את הסעיף ריק. אימות (Verification) חייב לשקף בדיקה קיימת, לכן ללא תשתית אימות ב-repo, הסעיף הזה נשאר ריק עד שתהיה כזו. קובץ שנוצר וממציא סטנדרט הוא גרוע יותר מסעיף ריק, כיוון שהסוכן יאכוף לאחר מכן את ההמצאה הזו.
הפרדת הכוונה האנושית מהמלאי המיוצר אוטומטית
זהו הכשל שגורם לאנשים לוותר על תיעוד שנוצר אוטומטית. אתם כותבים פסקה שמסבירה שתור המשימות חייב להישאר עם צרכן יחיד. שלושה שבועות לאחר מכן, תהליך אוטומטי משכתב את הקובץ והפסקה שלכם נעלמת בתוך diff של ארבעים שורות, שרובן בסך הכל שינוי סדר של שמות קבצים, ואף אחד לא מבחין בכך.
ישנם שני מנגנונים, ואתם זקוקים לשניהם.
ראשית, העבירו כוונה (intent) בעלת אופי קבוע לקובץ נפרד. החלטות תכנון והנימוקים מאחוריהן שייכים ל-קובץ 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.headdiff לא מדפיס דבר ומחזיר 0 כאשר הבלוק לא שונה. כל פלט מצביע על כך שהתהליך שכתב מחדש טקסט בבעלות אנושית, ולכן אדם צריך לאשר זאת או לבצע revert. הבדיקה נשמרת מבלי שאיש יצטרך לזכור זאת.
רענון בתוך ה-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, כיוון ש-"Read Before Editing" גורם לסוכן לקרוא את כל השרשרת בכל משימה. זהו מחיר העסקה, וכדאי לעקוב אחריו אם אתם כבר מחשבים את העלות של הרצות הסוכן שלכם.
Monorepos: חוזים רבים, אינדקס אחד
קובץ AGENTS.md שורשי יחיד במאגר המכיל ארבעים חבילות מייצר diff של יצירה מחדש שאף אחד לא קורא, ומסמך שרובו אינו רלוונטי למה שהסוכן מבצע כרגע. הפתרון של dox הוא Child DOX Index: השורש מכיל כללים החלים על כל המאגר ומפנה לצאצאיו, וכל גבול בר-קיימא מחזיק בקובץ משלו. כיצד להגדיר את מבנה העץ הזה, ואילו כלים קוראים קבצים מקוננים, מוסבר ב-קבצי AGENTS.md מקוננים עבור monorepos.
מה ש־dox משנה הוא שטח הפנים של הסקירה. בקשת pull הנוגעת ב-packages/api צריכה להפיק diff של תיעוד בתוך packages/api ולא בשום מקום אחר:
git diff --stat -- '*AGENTS.md'אם פקודה זו מציגה שישה קבצים עבור שינוי בחבילה אחת, העץ שגוי. או שהגבולות גסים מדי, או שכלל השייך לשורש הועתק לכל צאצא. dox מציין את התיקון ישירות: כללים רחבים נכנסים למסמכי ההורה, פרטים קונקרטיים נכנסים למסמכי הצאצא. כללים כפולים הם הגורם לכך ששינוי שגרתי גורם לכתיבה מחדש של הכל. אם אותם כללים חלים באמת על פני מאגרים נפרדים, זו בעיה אחרת, ו-שיתוף כישורי סוכנים בין מאגרים הוא הכלי המתאים יותר לכך.
סקירת ה-diff כקוד
קל לאשר diff של תיעוד שנוצר אוטומטית מבלי לקרוא אותו, וכך משתחרר קובץ שגוי. קראו אותו בחשדנות שבה הייתם בוחנים קוד שנוצר אוטומטית, וחפשו ארבעה דברים:
- פקודה שהקובץ מציין כעת, שעליכם להריץ בעצמכם לפני המיזוג. הוראות בנייה מומצאות הן הכשל הנפוץ ביותר.
- שורה שנמחקה והכילה כוונה מסוימת. הוספות הן זולות. מחיקות הן המקום שבו אובדן מידע מתרחש.
- נתיב אבסולוטי, שם מארח (hostname), כתובת URL פנימית, או כל דבר שנראה כמו פרטי הזדהות.
- רשומה במלאי עבור משהו שכבר אינו קיים, עניין ש-
lsמסדיר בשנייה.
לאחר מכן, בדקו את הגודל באמצעות wc -l AGENTS.md. קובץ root שעובר מאתיים שורות הוא סימן לכך שיש לפצל אותו, כיוון שכל הערך של השרשרת טמון בכך שהסוכן קורא את החלק הרלוונטי הקטן במקום את הכל.
כאשר מתרחשת תקלה
המעבר מחק את בלוק הכוונה שלך. הבדיקה 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 מול ערכי האינדקס במסמכי האב. ילד שאף אינדקס לא מציין הוא ילד שהסוכן יכול לעבור על פניו מבלי להתייחס אליו.
מתי מחולל (generator) הוא מיותר
חבילה אחת, פקודת בדיקה אחת, ושני אנשים שמכירים את ה-repository: כתבו את עשרים השורות ידנית. קובץ AGENTS.md באורך עשרים שורות לא מתיישן מספיק מהר כדי להצדיק עץ, אינדקס, בדיקת CI ומשימה שבועית. קראו אותו מחדש בכל פעם שאתם משנים את ה-build. זוהי כל עלות התחזוקה, והיא קטנה מעלות המנגנון שסביבו.
השימוש ב-dox כדאי כאשר ב-repository יש גבולות שאף אדם לא מחזיק בראשו: כמה חבילות עם חוקים שונים, או תורמים שמגיעים ללא הרקע הנדרש. הערך אינו הטקסט שמחולל. הערך הוא שהתיעוד הופך למשהו ש-pull request יכול להיכשל בגללו, וזו הסיבה היחידה לכך שקובץ כלשהו ב-repository נשאר מעודכן.
FAQ
האם עליי להתקין משהו כדי להשתמש ב-dox?
לא. dox הוא קובץ Markdown יחיד, תחת רישיון MIT, ונכון ל-13 באוקטובר 2026 המאגר אינו מפיץ חבילות או releases. עליך להעתיק את תוכנו לקובץ ה-AGENTS.md בפרויקט שלך, וסוכן הקידוד שלך יפעל לפי הכללים המפורטים בו. קבע (pin) את ה-commit שהעתקת, 765ae4ac02cc884eefcd41a3d0f71941721adb89 נכון לזמן כתיבת שורות אלו, וציין אותו בהודעת ה-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 עצמו. כללים רחבים מופיעים במסמכי האב ופרטים קונקרטיים במסמכי הבן. העתקת אותה פקודה לכל ילד היא מה שגורם למעבר שגרתי לשכתב את כל העץ.
האם dox כדאי עבור מאגר קטן?
בדרך כלל לא. חבילה אחת עם פקודת בדיקה אחת וקובץ AGENTS.md בן עשרים שורות מתדרדרת לאט, ותוכל לתקן זאת בדקה שאחרי שתבחין בכך. dox מחזיר את ההשקעה כאשר במאגר יש כמה גבולות עם כללים שונים, או תורמים שחסרים את הרקע הנדרש, כיוון שאז שרשרת המסמכים מבצעת עבודה שאף אדם בודד אינו עושה.