מאת אסף ביטון
כש-Codex מחזיר משימה קטנה, ההודעה האחרונה שלו מסתיימת בדרך כלל בגרסה כלשהי של ״הטסטים עוברים״. האם אפשר לסמוך על המשפט הזה תלוי בהחלטות שקיבלתם לפני שהמשימה התחילה: האם הריפו (מאגר הקוד) אמר ל-Codex איזו פקודת טסט היא האמיתית, האם הפרומפט ביקש במפורש את הפקודות ואת התוצאות, והאם יש לכם שגרה קבועה לבדיקת הדיף (diff, רשימת השינויים שנעשו בקוד) אחרי שהעבודה חוזרת. המדריך הזה מכסה את שני החצאים, עבור Codex CLI המקומי ותוסף ה-IDE. קודם קובץ AGENTS.md קומפקטי ש-Codex באמת יטען, עם שרשרת הגילוי, כללי העקיפה ותקרת הבייטים כפי שהם מתועדים אצל OpenAI. אחר כך בדיקת קבלה בארבעה חלקים שאפשר לחזור עליה בכל משימה.
Codex reads AGENTS.md before doing any work, walking from the project root to the launch directory and concatenating files up to a 32 KiB default cap; the guide covers its documented discovery chain, override files, the /review presets and the sandbox behavior that makes a post-task acceptance check necessary
הכי מתאים ל: Developers who want to delegate background tasks without managing a local agent environment, Teams already on ChatGPT Plus who want autonomous coding without an additional tool subscription
שני תוצרים, לא אחד. AGENTS.md הוא קבוע: Codex קורא אותו לפני שהוא מתחיל לעבוד, בונה מחדש את השרשרת בכל ריצה, הולך משורש הפרויקט למטה עד הספרייה שממנה הפעלתם אותו, ומשרשר את מה שהוא מוצא עד 32 KiB כברירת מחדל. קריטריוני קבלה הם למשימה אחת: מקומם בפרומפט ובצ׳קליסט שלכם אחרי שהעבודה חוזרת. כל שורה בקובץ ההוראות צריכה להתקיים כי היא מאפשרת שלב קבלה מאוחר יותר.
מה Codex עושה עם AGENTS.md
המדריך הרשמי ל-AGENTS.md קובע ש-Codex קורא קובצי AGENTS.md לפני שהוא עושה כל עבודה, ומתאר את הרעיון כשכבות: הנחיה גלובלית, ומעליה עקיפות ספציפיות לפרויקט, כך שכל משימה מתחילה מאותן ציפיות בכל ריפו שתפתחו. Codex בונה את שרשרת ההוראות הזאת כשהוא עולה: פעם אחת בכל ריצה, ובממשק הטרמינל האינטראקטיבי (TUI) בדרך כלל פעם אחת לכל סשן שהפעלתם. אם ערכתם את הקובץ וההוראות נראות ישנות, העצה של המדריך היא להפעיל מחדש את Codex בספריית היעד. זה יחזור בהמשך, כשתבדקו אם שינוי נטען.
הגילוי מתרחש בשתי רמות.
| רמה | איפה Codex מחפש | מה הוא לוקח |
|---|---|---|
| גלובלי | ספריית הבית של Codex: ~/.codex כברירת מחדל, או לאן ש-CODEX_HOME מצביע |
AGENTS.override.md אם קיים, אחרת AGENTS.md. רק הקובץ הראשון שאינו ריק ברמה הזאת |
| פרויקט | כל ספרייה על הנתיב משורש הפרויקט (בדרך כלל שורש ה-Git) ועד ספריית העבודה הנוכחית שלכם. אם לא נמצא שורש פרויקט, רק הספרייה הנוכחית | בכל ספרייה: AGENTS.override.md, אחר כך AGENTS.md, אחר כך כל שם שמופיע ב-project_doc_fallback_filenames. לכל היותר קובץ אחד לספרייה |
| משולב | כל הקבצים שנבחרו, משורשרים מהשורש למטה ומופרדים בשורות ריקות | קבצים ריקים מדולגים. Codex מפסיק להוסיף קבצים כשהגודל המשולב מגיע ל-project_doc_max_bytes, שהוא 32 KiB כברירת מחדל |
שרשור, לא החלפה
זה הפרט שהכי קל לטעות בו. Codex לא בוחר את הקובץ הקרוב ביותר וזורק את השאר. הוא משרשר קבצים מהשורש למטה, וקבצים קרובים יותר לספרייה הנוכחית שלכם עוקפים הנחיה קודמת רק מפני שהם מופיעים מאוחר יותר בפרומפט המשולב. קובץ השורש עדיין נמצא בפרומפט. קובץ מקונן מקבל את המילה האחרונה לפי מיקום, לא לפי מחיקה.
אתר הפורמט agents.md, שבשאלות הנפוצות שלו כתוב "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything" (בתרגום: ה-AGENTS.md הקרוב ביותר לקובץ שנערך מנצח; פרומפטים מפורשים של המשתמש בצ׳אט עוקפים הכל), מתאר את הפורמט כמוסכמה כללית לכלל הכלים שקוראים אותו. עבור Codex, לכו לפי התיעוד של Codex: יחידת הגילוי היא הספרייה שממנה הפעלתם את Codex, לא הקובץ שנערך, והנחיית השורש נשארת בשרשרת. הסעיף על פרומפטים בצ׳אט שעוקפים הכל הוא אמירה של אתר הפורמט; מדריך Codex לא טוען טענה מקבילה, ולכן לא הייתי נשען עליו כהתנהגות מתועדת של Codex.
ההחלפה האמיתית היחידה קורית בתוך ספרייה אחת. אם AGENTS.override.md יושב ליד AGENTS.md, ה-AGENTS.md שלצידו מתעלמים ממנו. עץ הדוגמה של המדריך עצמו מסמן את services/payments/AGENTS.md בהערה "Ignored because an override exists" (מתעלמים ממנו כי קיימת עקיפה). זה המנגנון לעקיפה אישית או זמנית שלא צריכה לגעת בקובץ המשותף.
ההליכה נגמרת איפה שהתחלתם
Codex מפסיק לחפש כשהוא מגיע לספרייה הנוכחית שלכם, והמדריך ממליץ למקם עקיפות קרוב ככל האפשר לעבודה הייעודית. ההשלכה המעשית קלה לפספוס: קובץ services/payments/AGENTS.md מקונן הוא חלק מהשרשרת רק כשמפעילים את Codex מתוך הספרייה הזאת או עמוק יותר. הפעילו מהשורש של הריפו, ורק קובץ הפרויקט בשורש (בתוספת הקובץ הגלובלי, אם יש) נטען. אם אתם רוצים שהנחיה ספציפית לשירות תחול, הפעילו את Codex בתוך השירות. המדריך מגדיר את סוף ההליכה כספריית העבודה הנוכחית של Codex ולא אומר איך תוסף ה-IDE קובע אותה; אם אתם עובדים בתוסף, אמתו את השרשרת עם בדיקת ה-CLI שבהמשך במקום להניח.
תקרת 32 KiB ושני המפתחות
שני העמודים הרשמיים שמתארים את ההגדרה הזאת לא מנסחים אותה אותו דבר. מדריך ה-AGENTS.md מתאר מגבלה משולבת: Codex מפסיק להוסיף קבצים כשהגודל המשולב מגיע ל-project_doc_max_bytes. עמוד ההגדרות המתקדמות, שמנסח זאת כך ש-Codex כולל "a limited amount of project guidance in the first turn of a session" (בתרגום: כמות מוגבלת של הנחיית פרויקט בתור הראשון של סשן), בשליטת שני מפתחות, מתאר את אותו מפתח לכל קובץ, ככמות שנקראת מכל קובץ AGENTS.md. המדריך הזה הולך לפי מדריך ה-AGENTS.md הרשמי, כי הוא העמוד שמפרט את הליכת הגילוי ואת צעדי פתרון התקלות, והתווית שלו לכשל היא "Instructions truncated" (ההוראות נחתכו). לפי הקריאה של המדריך, קבצים מתווספים מהשורש למטה עד שהתקציב נגמר, ולכן ההנחיה שנחתכת או נשארת בחוץ כשעוברים 32 KiB היא המאוחרת, העמוקה והספציפית יותר, שהיא בדרך כלל החלק שהכי היה אכפת לכם ממנו. מסמך העזר של ההגדרות מציג את project_doc_max_bytes עם תיאור בלבד ולא מדפיס את ברירת המחדל; המספר 32 KiB מגיע ממדריך ה-AGENTS.md עצמו. הדוגמה של המדריך לכוונון שני המפתחות ב-config.toml נראית כך:
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536עם ההגדרה הזאת, Codex בודק כל ספרייה בסדר AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. שמות קבצים שלא ברשימה לא נחשבים לגילוי הוראות. שימו לב ש-65536 הוא ערך דוגמה לעקיפה בתיעוד, לא ברירת מחדל; לא המדריך, לא עמוד ההגדרות המתקדמות ולא מסמך העזר נוקבים בברירת מחדל אחרת.
הוראות קבועות מול קריטריוני קבלה למשימה
אתר agents.md, ביתו של הפורמט שמנוהל היום על ידי Agentic AI Foundation תחת Linux Foundation, מותח את הקו בבירור: קובצי README מיועדים לבני אדם, ו-AGENTS.md נושא את ההקשר הנוסף, לפעמים המפורט, שסוכני קוד צריכים, כמו צעדי build, טסטים ומוסכמות שהיו מעמיסים על README.
קריטריוני קבלה הם תוצר אחר, והנחיות הפרומפטינג של OpenAI עצמה מדגימות את ההפרדה. בתהליך "Fix a bug" של Codex, האילוצים חיים בפרומפט של המשימה ("Do not change the API shape." ו-"Keep the fix minimal and add a regression test if feasible.", כלומר לא לשנות את צורת ה-API, ולשמור על תיקון מינימלי ולהוסיף טסט רגרסיה אם אפשר). למשתמש נאמר שצעדי השחזור (repro) והאילוצים "matter more than a high-level description" (חשובים יותר מתיאור ברמה גבוהה), ש-Codex "should re-run the repro steps after the fix" (צריך להריץ מחדש את צעדי השחזור אחרי התיקון), ושורת האימות היא: "After the fix, run lint + the smallest relevant test suite. Report the commands and results." (בתרגום: אחרי התיקון, הריצו lint ואת חבילת הטסטים הרלוונטית הקטנה ביותר, ודווחו על הפקודות ועל התוצאות.)
המשפט האחרון נמצא בפרומפט, לא בקובץ הגדרות. ההבחנה חשובה כי השאלות הנפוצות של agents.md עונות בחיוב על השאלה אם סוכנים מריצים את הטסטים שרשמתם, ומוסיפות שהסוכן "will attempt to execute relevant programmatic checks and fix failures before finishing the task" (בתרגום: ינסה להריץ בדיקות תכנותיות רלוונטיות ולתקן כשלים לפני שיסיים את המשימה). "Attempt" (ינסה) היא המילה הקובעת, וזו טענה על הפורמט באופן כללי. לא מדריך ה-AGENTS.md ולא עמוד הפרומפטינג מבטיחים הבטחה מקבילה; עמוד הפרומפטינג מדגים בקשה מפורשת בפרומפט של המשימה. אז התייחסו לפקודת טסט שרשומה בקובץ כהכרחית אבל לא מספיקה. היא אומרת ל-Codex איזו פקודה היא האמיתית. היא לא מבטיחה שהפקודה רצה. הפרומפט למשימה מבקש; בדיקת הקבלה מאשרת.
לשלמות התמונה, ל-Codex יש שכבה שלישית שאינה אף אחת מהשתיים. Rules שולטים באילו פקודות Codex רשאי להריץ מחוץ לארגז החול (sandbox, הגבול המבודד שבתוכו הוא מריץ פקודות). זו מדיניות פקודות, לא הוראות, והיא מחוץ להיקף כאן.
AGENTS.md התחלתי, להמחשה
הקובץ ההתחלתי שלמטה הוא המחשה. לא הרצתי אותו דרך Codex, והוא מתאר ריפו TypeScript היפותטי. הוא בנוי על הדוגמה הרשמית במדריך, שהיא רק שתי שורות תחת הכותרת "Repository expectations" (להריץ npm run lint לפני פתיחת pull request; לתעד כלי עזר ציבוריים ב-docs/ כשמשנים התנהגות), ועל תבנית הדיווח מעמוד הפרומפטינג. התאימו כל שורה לריפו שלכם. פקודת טסט שגויה גרועה מאין פקודה בכלל, כי כל דיווח שנבנה עליה לא אומר לכם כלום.
המבחן שאני מפעיל על כל שורה הוא אם היא מאפשרת שלב קבלה ספציפי אחר כך.
| שורה ב-AGENTS.md | שלב הקבלה שהיא מאפשרת |
|---|---|
| פקודות ההתקנה, הטסטים, ה-lint ובדיקת הטיפוסים האמיתיות | אפשר להריץ מחדש בדיוק מה ש-Codex מדווח, ו״הטסטים עוברים״ הופך לטענה שאפשר להפריך |
| אילו טסטים צריכים רשת או משתני סביבה | אתם יודעים אילו הצלחות מדווחות לא יכלו לקרות בתוך גבול ארגז החול |
| בעלות על ספריות ונתיבים שאסור לגעת בהם | התרחבות היקף (scope creep) נראית ברשימת הקבצים של הדיף במקום להיקבר בסיכום |
| ציפיית הדיווח | ההודעה האחרונה נוקבת בפקודות, בתוצאות ובפערים במקום לתאר תחושת סיום |
# AGENTS.md (illustrative; adapt to your repository)
## Setup
- Package manager: pnpm. Install with `pnpm install --frozen-lockfile`.
- Do not change toolchain or dependency versions unless the task says so.
## Verification
- Unit tests: `pnpm test`. For a single file: `pnpm test path/to/file.test.ts`.
- Lint and types: `pnpm lint` and `pnpm typecheck`.
- Tests under `tests/integration/` need network access and `INTEGRATION=1`.
If you did not run them, say so explicitly in your final message.
## Ownership
- Do not edit `migrations/` or lockfiles unless the task names them.
- Changes under `src/billing/` need a one-line justification in the final message.
## Reporting
- End every task with three lists: files changed, commands run with their
results (pass/fail counts, not "passed"), and anything you could not verify.הקובץ כולו הוא שבריר קטן מתקרת 32 KiB, וזו הנקודה. לפי הקריאה של המדריך, שבה המגבלה חלה על הגודל המשולב של כל הקבצים יחד, קובץ שורש קומפקטי משאיר מקום לקבצים מקוננים בספריות שבהן ההנחיה שונה, והוא קצר מספיק כדי שתשימו לב כשהוא מתיישן. אם הריפו שלכם גדול עד כדי כך שקובץ יחיד מתקרב לתקרה, העצה של המדריך עצמו היא להגדיל את project_doc_max_bytes או לפצל את התוכן בין ספריות מקוננות כדי שההנחיה הקריטית תישאר שלמה.
לוודא שהשרשרת נטענה
לפני שסומכים על קובץ חדש או ערוך, בדקו ש-Codex באמת קורא אותו. המדריך מתעד את הצעדים הבאים. אלה פקודות CLI; אם אתם עובדים בתוסף ה-IDE, הריצו אותן מטרמינל שנפתח בספרייה שאת השרשרת שלה אתם רוצים לאמת.
- משורש הריפו, הריצו
codex --ask-for-approval never "Summarize the current instructions.". Codex אמור להחזיר הנחיה מהקבצים הגלובליים ומקובצי הפרויקט לפי סדר העדיפות. אם הסיכום משמיט את ההנחיה מהקובץ שלכם, התייחסו לטעינה כלא מאומתת ולא ככושלת, והשתמשו בביקורת הלוג בצעד 4 כדי לראות אילו קבצים נקראו בפועל. - אם אתם נשענים על קבצים מקוננים, הריצו
codex --cd subdir --ask-for-approval never "Show which instruction files are active.", כאשרsubdirהוא מציין מקום לנתיב של הספרייה המקוננת שאת השרשרת שלה אתם רוצים לאמת. הבדיקה המקוננת של המדריך מעבירה את הספרייה הזאת עם--cdבמקום להפעיל מתוכה. זכרו שההליכה נגמרת בספריית העבודה של Codex, ולכן הבדיקה ברמת השורש בצעד 1 לא מציגה קבצים מקוננים. - אם ההוראות נראות ישנות, הפעילו מחדש את Codex בספריית היעד. Codex בונה מחדש את השרשרת בכל ריצה ובתחילת כל סשן TUI, כך שאין מטמון לנקות.
- כדי לבדוק בדיוק אילו קבצים נטענו, הפעילו את לוג ה-TUI בטקסט פשוט עם
codex -c log_dir=./.codex-logוקראו את./.codex-log/codex-tui.log, או בדקו את קובץ ה-session-*.jsonlהעדכני ביותר אם הפעלתם רישום סשנים.
שני מצבי כשל מתועדים ישירות. אם ההוראות נחתכות, הגדילו את project_doc_max_bytes או פצלו קבצים גדולים בין ספריות מקוננות. אם מופיעה הנחיה שגויה, חפשו AGENTS.override.md גבוה יותר בעץ הספריות או תחת ספריית הבית של Codex; לשם המדריך מפנה אתכם קודם.
בדיקת הקבלה למשימה
קובץ ההוראות מאפשר את השגרה הבאה. החצי של המשימה מתחיל לפני הפרומפט, עם נקודת ייחוס. תעדו את מצב עץ העבודה כמו שהוא: הריצו git status ושמרו את הפלט, ואם בעץ כבר יש עריכות שלכם שעדיין לא עברו commit, רשמו באילו קבצים הן נוגעות. לא צריך לעשות commit, stash או ניקוי קודם. המטרה היא לדעת אחר כך אילו שינויים כבר היו שם, כדי שאפשר יהיה לייחס את רשימת הקבצים שאחרי המשימה למשימה הזאת, ושהעריכות הקודמות שלכם יישמרו. חלקים 1 ו-3 שלמטה נקראים מול הרישום הזה.
הנה פרומפט להמחשה לתיקון קטן, כתוב באותה תבנית של תהליך "Fix a bug" הרשמי:
Fix: formatPrice returns "NaN" for zero amounts.
Repro: `pnpm test src/lib/price.test.ts` fails on the "zero amount" case.
Constraints:
- Do not change the function signature.
- Keep the fix minimal and add a regression test.
Verification: re-run the repro, then `pnpm lint` and the smallest relevant
test suite. Report the commands you ran and their results, and list anything
you could not run.כש-Codex מסיים, עברו על ארבעה חלקים לפי הסדר. הסדר חשוב כי כל חלק מצמצם את מה שהבא צריך לכסות.
1. היקף: הוצהר מראש, נשמר בסוף
השוו את רשימת הקבצים ששונו מול ההיקף שבפרומפט, שורות הבעלות ב-AGENTS.md ונקודת הייחוס שתיעדתם. הניחו בצד כל מה שנקודת הייחוס כבר כללה: אלה העריכות שלכם, והן נשארות. אם Codex שינה גם קובץ כזה, הפרידו את המקטעים (hunks) שלו משלכם לפני שאתם שופטים אותם. בין השינויים שאפשר לייחס למשימה הזאת, כל קובץ מחוץ להיקף המוצהר הוא ממצא לחקירה, לא שינוי לבטל על המקום. הוא צריך הצדקה בהודעה האחרונה או שאלה חזרה ל-Codex למה הוא השתנה, ורק אז החלטה אם לשמור אותו. זו הבדיקה הזולה ביותר, והיא תופסת הפתעה מוכרת: ״תיקון מינימלי״ שגם עשה refactor לקוד שכן. אם לא הצהרתם על היקף בפרומפט, אי אפשר לבצע את השלב הזה, וזה הטיעון בעד להצהיר עליו תמיד.
2. פקודות ותוצאות: דווחו, ואז הורצו מחדש
ההודעה האחרונה חייבת לנקוב בפקודות בפועל ובתוצאות שלהן. ״הטסטים עוברים״ זו לא תוצאה; שורה בסגנון ״pnpm test src/lib/price.test.ts, 14 עברו, 0 נכשלו״ כן. ואז הריצו בעצמכם את הפקודה שצוינה בהודעה. זה צעד קצר שהופך את הטענה של Codex לתצפית שלכם.
תיעוד ארגז החול מסביר למה ההרצה מחדש אינה אופציונלית. ארגז החול חל על פקודות שהסוכן מפעיל, לא רק על פעולות קבצים מובנות: אם הסוכן מריץ git, מנהלי חבילות או מריצי טסטים, הפקודות האלה יורשות את אותם גבולות. מצב ברירת המחדל לעבודה מקומית עם מעט חיכוך הוא workspace-write, שבו הסוכן יכול לקרוא קבצים, לערוך בתוך סביבת העבודה ולהריץ פקודות מקומיות שגרתיות בתוך הגבול הזה, ותחת מדיניות האישורים on-request הסוכן עובד בתוך ארגז החול ושואל כשהוא צריך לחרוג ממנו. האישורים קובעים מתי Codex עוצר; ארגז החול קובע לאילו קבצים ומשאבי רשת פקודות יכולות לגשת. אותו עמוד מונה גישה חסומה לרשת בין בקשות האישור שיכולות לעלות בגבול הזה.
ביחד: אם טסט צריך משאב שארגז החול לא מעניק, החשיבו אותו כטסט שרץ רק אם התמליל מראה גישה שאושרה או ריצה שהושלמה עם תוצאה. אם הגישה נדחתה או נחסמה, אם הטסט לא רץ, או אם ההודעה האחרונה שותקת לגבי חבילת האינטגרציה, החבילה הזאת לא מאומתת עד שתריצו אותה. בגלל זה הקובץ ההתחלתי אומר ל-Codex אילו טסטים צריכים רשת ומבקש ממנו להגיד כשדילג עליהם.
3. הדיף נסקר, ביד או עם /review
קראו את הדיף. לכל דבר מעבר לכמה שורות, פיצ׳ר סקירת הקוד של Codex עצמו הוא קורא שני סביר. הקלדת /review ב-CLI פותחת את תבניות הסקירה המוכנות (presets) ומפעילה סוקר ייעודי שקורא את הדיף שנבחר ומדווח ממצאים מתועדפים וברי ביצוע בלי לשנות את עץ העבודה שלכם. ארבעה היקפים מתועדים: סקירה מול ענף בסיס (Codex מוצא את נקודת המיזוג הבסיסית וסוקר את הדיף של הענף), סקירת שינויים שעדיין לא עברו commit (קבצים ב-staging, מחוץ ל-staging ולא מנוטרים), סקירת commit יחיד, והוראות סקירה מותאמות שממקדות את הסקירה בקריטריונים שאתם מספקים. למשימה קטנה, היקף השינויים שלא עברו commit הוא בדרך כלל הנכון, עם הסתייגות אחת: הוא מכסה קבצים ב-staging, מחוץ ל-staging ולא מנוטרים, ולכן אם נקודת הייחוס שלכם לא הייתה נקייה הוא מכסה גם את העריכות הקודמות שלכם. קראו את הממצאים שלו מול נקודת הייחוס והתעלמו מאלה שנופלים במקטעים שאתם עצמכם כתבתם. ההיקף המותאם הוא המקום שבו אפשר להעביר לסוקר את אילוצי המשימה מילה במילה (מדריך הפרומפטינג של OpenAI נותן כדוגמה את "Do not change the API shape.").
התייחסו לממצאי הסוקר כמו שאתם מתייחסים לסיכום של הסוכן: כטענות לבדיקה מול הדיף, לא כפסק דין. זה Codex שקורא את העבודה של Codex.
4. מה לא אומת, כתוב במפורש
סיימו ברשימה מפורשת של מה שלא בדקתם: טסטי אינטגרציה שלא רצו, מסלול UI ידני שלא נבדק, migration שלא הוחל מקומית, שינוי תלות שלא נסקר. הרשימה הזאת היא החלק הכן של תיאור ה-pull request, והיא החלק שסיכום ״הטסטים עוברים״ מוחק. אם ההודעה האחרונה של Codex כבר מכילה רשימה משלו של מה שהוא לא הצליח להריץ, מזגו את השתיים; אם לא, ההיעדר עצמו הוא ממצא, ושורת הדיווח ב-AGENTS.md קיימת כדי שזה יקרה פחות.
מה התיעוד לא מבטיח
כל מה שלמעלה מתאר איך Codex טוען הוראות ומה אפשר לבדוק אחר כך. שום דבר מזה אינו ערובה לציות. המדריך הרשמי מתאר גילוי ופתרון תקלות; הוא לא אומר עד כמה Codex עוקב באמינות אחרי מה שהוא טען, וסעיף פתרון התקלות שלו עצמו צופה מקרים שבהם מופיעה הנחיה שגויה או שהוראות נחתכות. זו הסיבה שבדיקת הקבלה קיימת, במקום תקווה שהקובץ מספיק.
המדידה העצמאית שמצוטטת כאן עוסקת ביעילות, לא בנכונות. מאמר טרום-פרסום (preprint) ב-arXiv של Lulla, Mohsenimofidi, Galster, Zhang, Baltes ו-Treude (גרסה ראשונה 28 בינואר 2026, מתוקנת 30 במרץ 2026) ניתח 10 מאגרי קוד ו-124 pull requests, הריץ סוכנים עם ובלי קובץ AGENTS.md, ומדד זמן ריצה כולל (wall-clock) ושימוש בטוקנים. המחברים מדווחים שנוכחות AGENTS.md "is associated with a lower median runtime (Δ 28.64%) and reduced output token consumption (Δ 16.58%), while maintaining a comparable task completion behavior" (בתרגום: קשורה לחציון זמן ריצה נמוך יותר, Δ 28.64%, ולצריכת טוקני פלט מופחתת, Δ 16.58%, תוך שמירה על התנהגות השלמת משימה דומה). זה מאמר טרום-פרסום, זה קשר סטטיסטי (association), וזו מדידה של זמן וטוקנים. הוא לא מראה שהקובץ הופך את הפלט לנכון יותר, ולא הייתי מצטט אותו כאילו כן.
שתי הערות היקף. המדריך מתעד גם סעיף ## Code Review Rules, שממוקם ב-AGENTS.md הקרוב ביותר לקוד שהכללים מסדירים, עם בדיקות לכל הריפו בשורש ובדיקות ספציפיות לשירות בקבצים מקוננים, והוא ממליץ להשאיר בדיקות עיצוב ו-lint ל-CI. הסעיף הזה מתועד לסקירת קוד של Codex ב-GitHub; לא המדריך ולא עמוד סקירת הקוד אומרים שהוא משנה את ההתנהגות של /review המקומי, אז אל תניחו שכן. והמדריך הזה מכסה את ה-CLI המקומי ואת תוסף ה-IDE, שבהם עובדות ארגז החול שלמעלה חלות. משימות ענן של Codex לא נחקרו כאן.
מאיפה להתחיל
כתבו קודם את קובץ השורש ושמרו אותו בגודל של מסך אחד. הכניסו את פקודת הטסט האמיתית, פקודת ההתקנה האמיתית, הטסטים שלא יכולים לרוץ בארגז החול, הנתיבים ש-Codex לא אמור לגעת בהם, וציפיית הדיווח. הריצו פעם אחת את בדיקת "Summarize the current instructions" כדי שתדעו שהקובץ נטען. ואז, במשימה הקטנה הבאה, תעדו את מצב עץ העבודה, הצהירו על ההיקף ועל האימות בפרומפט, והריצו את הבדיקה בארבעה חלקים כשהעבודה חוזרת: ההיקף נשמר, הפקודות הורצו מחדש, הדיף נקרא, רשימת הלא-מאומת נכתבה. הקובץ הוא עלות חד-פעמית; הבדיקה היא ההרגל שהופך את הקובץ לשווה משהו.
אם אתם משתמשים גם ב-Claude Code, קובץ ההגדרות המקביל מכוסה במדריך ה-CLAUDE.md וה-AGENTS.md שלי, שעוסק בצד של Claude Code ומזכיר את AGENTS.md באופן מושגי ולא מכסה את שרשרת הגילוי של Codex. ה-hooks לאימות של Claude Code עצמו נדונים בסקירת Claude Code 2.1 שלי. אף אחד מהם לא מכסה את מה שהמדריך הזה מכסה: איך Codex טוען הוראות ואיך מקבלים את העבודה שהוא מחזיר.
