כללי prompt ל-Codex ב-Windows: איך לא להשחית קבצים ביפנית

כשמריצים Codex על קבצים עם טקסט יפני ב-Windows, מה שעוזר בהתחלה הוא לא ליישר את כל הגדרות העורך וה-shell. קודם כל צריך להגיד ל-Codex במפורש איך לקרוא, איך לכתוב, ואיפה לעצור.

המקרים שמכשילים הכי הרבה נראים כך:

• קבצי UTF-8, CP932 ומשפחת UTF-16 מעורבבים באותו repo
• על המסך נראה שאפשר לקרוא, אבל פרשנות הבייטים בפועל סטתה
• תכננתם תיקון קטן בקובץ קיים, ובשמירה הוא נכתב מחדש ב-encoding אחר
• השבירה קורית ב”לא-קוד”: CSV, TXT, לוג, Markdown, קבצי הגדרות
• סקריפט זמני או פלט shell נשמרים כמו שהם, והתקלה מתקבעת בקובץ

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

המאמר הזה מרכז, מנקודת מבט מעשית, prompts שכדאי לתת בהתחלה כדי ש-Codex יערוך קבצים ביפנית ב-Windows בלי להשחית אותם.

flowchart TB
    accTitle: לפני הגדרות הסביבה, מקבעים את ה-prompt
    accDescr: כשמריצים Codex על קבצים ביפנית ב-Windows, מה שעוזר בהתחלה הוא לא ליישר הגדרות של עורך ו-shell, אלא להגיד במפורש איך לקרוא, איך לכתוב, ואיפה לעצור.
    a1["ליישר הגדרות של עורך ו-shell"] -.-> a2["זה לא מה שעוזר בהתחלה"]
    a3["איך לקרוא"] --> a6["לכתוב במפורש ל-Codex"]
    a4["איך לכתוב"] --> a6
    a5["איפה לעצור"] --> a6

איור 1: מה שעוזר בהתחלה הוא לא הגדרות סביבה, אלא ניסוח מפורש של קריאה, כתיבה ונקודת עצירה.

רקע: איזה Codex ואיזה AGENTS.md המאמר מניח

למי שלא עובד עם Codex, קודם רק את הרקע.

Codex הוא coding agent שקורא וכותב בפועל קבצים ב-repository. יש כמה נקודות כניסה (CLI בטרמינל מקומי, הרחבת עורך, גרסה בענן), אבל המאמר הזה מניח שימוש שבו הוא עורך ישירות את הקבצים ב-repo המקומי. mojibake קורה ברגע של “עריכה ושמירה”, ולכן השאלה החשובה היא לא איזו נקודת כניסה, אלא איך מרסנים את נתיב הכתיבה לקובץ.

AGENTS.md הוא קובץ Markdown עם הנחיות קבועות לעבודה באותו repository. לאופן הטעינה שלו יש כמה תכונות שכדאי לזכור.

• זה לא קובץ אחד. גם ההגדרה הכללית כמו ~/.codex/AGENTS.md בתיקיית הבית, וגם ה-AGENTS.md שב-repo, שניהם נקראים.
• הם מחוברים לפי הסדר, משורש ה-repo אל תיקיית העבודה. כלומר AGENTS.md בתת-תיקייה מחובר מאוחר יותר, ולכן גובר על הנחיות ברמה גבוהה יותר.
• יש תקרה לגודל הכולל. כברירת מחדל זה נחתך בסביבות 32 KiB. אם כותבים “הכול בינתיים”, הזנב נופל. את כללי ה-encoding בטוח יותר לשים קצרים, קרוב להתחלה.

בגלל שלוש הנקודות האלה, מעשי לכתוב את כללי ה-encoding ב-AGENTS.md של שורש ה-repo, בקצרה, קרוב לראש הקובץ. אם יש כלל כתיבה אחר בתת-תיקייה, הוא ינצח.

flowchart TB
    accTitle: איך AGENTS.md נטען
    accDescr: AGENTS.md נקרא גם מתיקיית הבית וגם מה-repo, מחובר מהשורש אל תיקיית העבודה כך שהקובץ הנמוך יותר גובר, והגודל הכולל נחתך בסביבות 32KiB כברירת מחדל; לכן כללי encoding נכתבים בשורש, קצרים וקרוב להתחלה.
    b1["AGENTS.md בתיקיית הבית"] --> b3["חיבור מהשורש אל תיקיית העבודה"]
    b2["AGENTS.md בצד ה-repo"] --> b3
    b3 --> b4["קובץ נמוך יותר מחובר מאוחר וגובר"]
    b3 -.-> b5["נחתך בסביבות 32KiB כברירת מחדל"]
    b4 --> b6["הכלל נכתב בשורש, קצר וקרוב להתחלה"]
    b5 -.-> b6

איור 2: ל-AGENTS.md יש סדר חיבור ותקרת גודל, ולכן הכלל נכתב קצר בראש קובץ השורש.

1. קודם המסקנה

כדי להוריד תקלות mojibake של Codex ב-Windows, מה שעובד הכי טוב הוא לקבע מראש את תהליך העבודה על encoding.

הכללים שעוזרים במיוחד:

• בקובץ קיים עם יפנית, לבדוק לפני הקריאה מועמד ל-encoding, BOM, וסוג newline
• בקובץ חשוד ל-mojibake, לא לשמור עד שהפרשנות אמינה
• בקובץ קיים, לשמור על encoding, BOM ו-newline המקוריים
• בקובץ חדש, ללכת לפי מוסכמת ה-repo לכיוון UTF-8
• בכתיבה, להשתמש רק בשיטות שמציינות encoding במפורש
• אחרי שמירה, לפתוח מחדש ולאמת שורות יפניות מייצגות

בניסוח קצר לעבודה בפועל:

• בדיקה לפני קריאה
• אם זה חשוד, אסור לשמור
• קיים נשאר כמו שהוא; חדש בלבד UTF-8
• אין נתיב כתיבה בלי encoding מפורש
• בסוף קריאה חוזרת לאימות

flowchart TB
    accTitle: חמישה שלבים למניעת תקלת encoding
    accDescr: חמישה שלבים לפי הסדר: בדיקה לפני קריאה, איסור שמירה אם יש חשד, שמירה על קיים ו-UTF-8 רק לקבצים חדשים, איסור נתיב כתיבה בלי encoding מפורש, ובסוף קריאה חוזרת לאימות.
    c1["בדיקה לפני קריאה"] --> c2["אם חשוד, אסור לשמור"]
    c2 --> c3["קיים נשאר, חדש בלבד UTF-8"]
    c3 --> c4["אין נתיב כתיבה בלי encoding מפורש"]
    c4 --> c5["בסוף קריאה חוזרת לאימות"]

איור 3: את תהליך העבודה שרוצים לקבע אפשר לרכז בחמישה שלבים.

ולהפך, prompts כמו אלה מסוכנים:

• “תתקן את ה-mojibake”
• “תהפוך הכול ל-UTF-8”
• “תוציא CSV”
• “תתאים איכשהו”
• “תשמור בינתיים ותראה”

באף אחד מהם לא כתוב באיזה שלב Codex צריך לעצור. בטיפול ב-mojibake צריך להגיד לא רק מה לעשות, אלא גם איפה לעצור את השמירה.

ב-diagram, solid line מציינת relation שתמיד מתקיים ו-dashed line מציינת relation מותנה (התנאים מופיעים בהסבר של כל relation ב-detail page). הרשימה המלאה של ה-relations (סה”כ 22, כולל evidence ו-certainty) וההגדרות של ה-concepts המרכזיים נמצאות ב-detail page של ה-knowledge map (ביפנית). Data: JSON-LD / Turtle

2. למה mojibake כל כך נפוץ ב-Windows

הבעיה האמיתית היא לא ש-Codex חלש ביפנית, אלא שבצד הקבצים של Windows חיים כמה encodings במקביל, וכמה נתיבי כתיבה.

בעבודה בפועל זה לא נדיר:

• מקור חדש יחסית ו-Markdown ב-UTF-8
• CSV, TXT, לוג והגדרות ישנים במשפחת CP932
• חלק מהפלט או מתוצרי הכלים במשפחת UTF-16
• נתיבי שמירה מפוזרים בין עורך, shell ופלט שמגיע מ-Excel
• גם newline מעורבב: LF ו-CRLF

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

לכן טיפול ב-mojibake הוא בסוף שאלה של איך מנהלים את תהליך ה-I/O.

flowchart TB
    accTitle: איך תקלה מתקבעת כהשחתה
    accDescr: כשכמה encodings ונתיבי כתיבה חיים יחד, פרשנות שגויה אחת של Codex מובילה להמשך עריכה בלי קריאה אמיתית, והשמירה מקבעת את זה כהשחתת הקובץ; ליבת המניעה היא ניהול תהליך ה-I/O.
    d1["כמה encodings ונתיבי כתיבה במקביל"] --> d2["פרשנות שגויה אחת"]
    d2 --> d3["ממשיכים לערוך בלי קריאה אמיתית"]
    d3 --> d4["השמירה מקבעת השחתה"]
    d4 -.-> d5["ליבת המניעה: ניהול תהליך I/O"]

איור 4: mojibake מתחיל כבעיית תצוגה, ומתקבע כהשחתה ברגע השמירה.

2.1 ארבעה מונחים מראש

אלה המילים שיחזרו הרבה בהמשך.

הנקודה החשובה: גם CP932 וגם UTF-8 לא כתובים בתוך הקובץ עצמו. בלי BOM, הקובץ לא מכריז איך לקרוא אותו. לכן צריך בדיקה לפני הקריאה.

flowchart TB
    accTitle: הקובץ לא מכריז על ה-encoding שלו
    accDescr: אין כתוב בקובץ עצמו אם הוא CP932 או UTF-8, ובלי BOM הקובץ לא מכריז איך לקרוא אותו; לכן צריך בדיקה לפני הקריאה.
    e1["תוכן הקובץ הוא רק רצף בייטים"] --> e2{"יש BOM?"}
    e2 -->|"יש"| e3["יודעים שזה Unicode"]
    e2 -->|"אין"| e4["UTF-8 או CP932: שיפוט לפי התוכן"]
    e4 --> e5["לכן צריך בדיקה לפני הקריאה"]

איור 5: בלי BOM, הקובץ לא אומר איך לקרוא אותו.

3. הכללים שכדאי לקבע ל-Codex בהתחלה

3.1 לפני הקריאה: לבדוק מועמד ל-encoding, BOM ו-newline

הכלל הראשון הוא זה.

לפני שקוראים קובץ קיים עם יפנית, בודקים את המועמד הנוכחי ל-encoding, אם יש BOM, ומה סוג ה-newline. אם משהו חשוד, לא ממשיכים ישר לפרש את התוכן.

השינוי הוא לראות קודם את הנחות היסוד של הקובץ, ורק אחר כך לקרוא טקסט.

איך בודקים בפועל

אם כותבים רק “תבדוק”, גם Codex וגם בני אדם מתפזרים בשיטה. יציב יותר לשים בתוך ה-prompt את תהליך הבדיקה עצמו. הדוגמאות למטה רצות גם ב-Windows PowerShell 5.1 וגם ב-PowerShell 7.

קודם מסתכלים על הבייטים הראשונים בהקס. BOM נקבע כאן.

$path  = 'C:\work\orders.csv'
$bytes = [System.IO.File]::ReadAllBytes($path)

# מציגים את 16 הבייטים הראשונים בהקס
$head = $bytes[0..([Math]::Min(15, $bytes.Length - 1))]
($head | ForEach-Object { $_.ToString('X2') }) -join ' '

הבלוקים הבאים משתמשים ב-$path וב-$bytes שנוצרו כאן. כך קוראים את התוצאה.

אחר כך סופרים את קודי ה-newline. כאן רואים אם LF ו-CRLF מעורבבים.

$crlf = 0; $loneLf = 0; $loneCr = 0
for ($i = 0; $i -lt $bytes.Length; $i++) {
    if ($bytes[$i] -eq 0x0A) {
        if ($i -gt 0 -and $bytes[$i - 1] -eq 0x0D) { $crlf++ } else { $loneLf++ }
    }
    elseif ($bytes[$i] -eq 0x0D -and ($i -eq $bytes.Length - 1 -or $bytes[$i + 1] -ne 0x0A)) {
        $loneCr++
    }
}
"CRLF=$crlf  LF=$loneLf  CR=$loneCr"

לבסוף מצמצמים את המועמדים ל-encoding. בלי BOM, האם אפשר לפענח בהצלחה כ-UTF-8 קפדני הוא המבחן המהיר ביותר. ל-UTF-8 יש אילוצים חזקים על רצף הבייטים, ולכן קובץ CP932 שנקרא כ-UTF-8 קפדני נכשל בדרך כלל באמצע.

# הארגומנט השני $true אומר: זרוק exception אם רצף הבייטים לא תקין
$strictUtf8 = New-Object System.Text.UTF8Encoding($false, $true)
try {
    $null = $strictUtf8.GetString($bytes)
    'פוענח בלי סתירה כ-UTF-8'
}
catch {
    'זה לא UTF-8. נסו מועמד כמו CP932'
}

כשרוצים לקרוא מצד CP932, מציינים במפורש את מספר ה-code page.

# מ-PowerShell 6.2 אפשר לציין ישירות את מספר ה-code page
Get-Content -Path $path -Encoding 932 -TotalCount 3

# ב-Windows PowerShell 5.1, Default הוא ה-ANSI code page של המערכת. ב-Windows יפני זה CP932
Get-Content -Path $path -Encoding Default -TotalCount 3

פענוח קפדני שעבר עדיין לא אומר “זה UTF-8 בוודאות”. קובץ ASCII טהור עובר בשני המקרים. בסוף צריך לבדוק בעין אם שורה יפנית מייצגת באמת נקראת.

flowchart TB
    accTitle: תהליך הבדיקה לפני הקריאה
    accDescr: מסתכלים על הבייטים הראשונים בהקס כדי לקבוע BOM, סופרים newline, מצמצמים מועמדים בפענוח UTF-8 קפדני, ולבסוף בודקים בעין שורה יפנית מייצגת.
    f1["בייטים ראשונים בהקס"] --> f2["קובעים אם יש BOM"]
    f2 --> f3["סופרים newline"]
    f3 --> f4["מצמצמים מועמדים בפענוח UTF-8 קפדני"]
    f4 --> f5["בודקים בעין שורה יפנית מייצגת"]
    f4 -.-> f6["קובץ ASCII טהור עובר בשני המקרים"]

איור 6: בדיקה לפני קריאה: בייטים, newline, פענוח, ואז בדיקה בעין.

3.2 קובץ חשוד ל-mojibake: לא לשמור על סמך ניחוש

זה הכלל החשוב ביותר.

כשיש חשד ל-mojibake, בשלב הבדיקה הקובץ נשאר read-only. אסור overwrite עד שהפרשנות אמינה.

זה נכון גם לבני אדם: אסור לשמור קובץ שאתם לא באמת קוראים. אם שומרים בגישה של “נראה קצת שבור אבל כנראה זה זה”, זו הופכת לגרסה המתקבעת של התקלה.

3.3 קובץ קיים נשאר כמו שהוא; קובץ חדש בלבד ב-UTF-8

בהקשר של mojibake, prompt כמו “תאחד הכול ל-UTF-8” מסוכן יותר ממה שנדמה.

החלטה להעביר בסוף את כל ה-repo ל-UTF-8 בהחלט אפשרית, אבל בטוח יותר לעשות את זה כמשימה נפרדת, עם diff וטווח השפעה. בתיקונים יומיומיים הנוהל הבא יציב:

• בעריכת קובץ קיים: שומרים על ה-encoding המקורי
• בהוספת קובץ חדש: יוצרים ב-UTF-8 לפי מוסכמת ה-repo
• אם צריך המרה של קובץ קיים: מפרידים מתיקון פיצ’ר רגיל

3.4 לא להשתמש כברירת מחדל בנתיב כתיבה בלי encoding מפורש

ב-Windows, מה שמרבה תקלות הוא “זה רק פלט קטן, אז נזרוק אותו דרך ה-shell”.

• redirection ישר לפלט
• שמירה ישר דרך פקודת נוחות
• קידום תוצר זמני לקובץ פרודקשן

בנתיבים כאלה לרוב אין encoding מפורש, וזה קרקע פורייה לתקלות. לכן בטוח יותר לקבע ל-Codex גם איך בוחרים אמצעי כתיבה.

encoding ברירת המחדל משתנה לפי גרסת PowerShell

מי שלא יודע את זה דורך על זה. ב-PowerShell, encoding הכתיבה כברירת מחדל תלוי בגרסה.

כלומר אותו סקריפט מייצר קובץ אחר אם הריצו אותו ב-5.1 או ב-7. זה הדפוס הקלאסי של “במחשב הפיתוח היה בסדר, ובשרת בשטח זה נשבר”.

ובצד 5.1 יש עוד תכונה: ציון encoding ממשפחת Unicode תמיד מוסיף BOM. -Encoding UTF8 הוא UTF-8 עם BOM.

לכן מציינים encoding במפורש בכל כתיבה.

# משתנים כדי שהסעיף הזה יעמוד לבד
$path    = 'C:\work\orders.csv'
$newPath = 'C:\work\orders-new.csv'
$lines   = @('顧客コード,顧客名', 'C0001,株式会社サンプル')

# אם הקיים הוא CP932, כותבים בחזרה כ-CP932 (מ-PowerShell 6.2)
Set-Content -Path $path -Value $lines -Encoding 932

# ב-Windows PowerShell 5.1, מתאימים ל-ANSI code page של המערכת
Set-Content -Path $path -Value $lines -Encoding Default

# קובץ חדש ב-UTF-8 בלי BOM (PowerShell 7)
Set-Content -Path $newPath -Value $lines -Encoding utf8NoBOM

אם רוצים לקרב את ברירת המחדל לכל ה-session, אפשר $PSDefaultParameterValues. אבל זו הגדרה של אותו session בלבד, אז נוהל שמניח “זה כתוב בפרופיל שלנו” נשבר אצל מישהו אחר.

$PSDefaultParameterValues['*:Encoding'] = 'utf8NoBOM'

גם כתיבה עם > במקום Out-File נושאת את אותה בעיה: מ-5.1 ואילך זה רק קורא ל-Out-File מבפנים. הכי בטוח לאסור redirection, ולהשתמש רק ב-cmdlet או ב-.NET API שמאפשרים לציין encoding.

flowchart TB
    accTitle: אותו סקריפט מייצר קובץ אחר
    accDescr: encoding הכתיבה כברירת מחדל משתנה לפי גרסת PowerShell, ולכן אותו סקריפט מייצר קובץ ב-encoding אחר אם הריצו ב-5.1 או ב-7; הפתרון הוודאי הוא לאסור redirection ולהשתמש רק בנתיבים עם encoding מפורש.
    g0["אותו סקריפט"] --> g1["הרצה ב-Windows PowerShell 5.1"]
    g0 --> g2["הרצה ב-PowerShell 7"]
    g1 --> g3["מתקבל קובץ ב-encoding אחר"]
    g2 --> g3
    g3 -.-> g4["רק נתיבים עם encoding מפורש"]

איור 7: encoding ברירת המחדל שונה בין גרסאות, לכן מציינים אותו בכל כתיבה.

3.5 אחרי שמירה: לפתוח מחדש ולאמת שורה יפנית מייצגת

“הצלחתי לשמור” ו”הקובץ לא נשבר” הם לא אותו דבר.

מה שחשוב הוא לגרום ל-Codex לקרוא שוב שורה יפנית מייצגת אחרי השמירה, ולבדוק:

• האם נכנס תו החלפה U+FFFD
• האם ? התרבה בצורה לא טבעית
• האם ה-diff הפך ענק רק בגלל BOM או newline
• האם היפנית שלא הייתה אמורה להשתנות עסקית נשארה כמו שהיא

3.6 סימן חריגה: לדווח לפני שמתקנים

בתקלת encoding, לעצור ולדווח מקטין נזק יותר מלכפות תיקון.

למשל, אם מופיעים סימנים כאלה, בטוח יותר להתייחס אליהם כחריגה זמנית:

• ריבוי U+FFFD
• ריבוי ?
• שינוי BOM לא צפוי
• diff ענק שכולו newline
• שורות יפניות בלבד שהשתנו בצורה גדולה ולא טבעית

flowchart TB
    accTitle: סימן חריגה: עוצרים ומדווחים
    accDescr: ריבוי U+FFFD או ?, שינוי BOM לא צפוי, ו-diff ענק של newline נחשבים חריגה זמנית; עצירה ודיווח לפני תיקון מקטינים נזק.
    h1["ריבוי U+FFFD או ?"] --> h4["מתייחסים כחריגה זמנית"]
    h2["שינוי BOM לא צפוי"] --> h4
    h3["diff ענק של newline"] --> h4
    h4 --> h5["עוצרים ומדווחים לפני תיקון"]

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

4. אם מוסרים prompt קצר

גרסה קצרה לכל משימה מספיקה בהרבה מקרים.

בעבודה הזו, הימנעו מעל הכול מתקלות encoding.

- בקובץ קיים עם יפנית, בדקו לפני הקריאה מועמד ל-encoding, BOM, וסוג newline
- בקובץ חשוד ל-mojibake, אל תשמרו על סמך ניחוש
- בקובץ קיים שמרו על encoding / BOM / newline המקוריים
- קובץ חדש: צרו ב-UTF-8 לפי מוסכמת ה-repo
- בכתיבה השתמשו רק בשיטות שמציינות encoding במפורש
- אחרי שמירה, פתחו מחדש ואמתו ששורה יפנית מייצגת לא נשברה
- אם יש ריבוי U+FFFD או ?, תקלת BOM/newline, או diff ענק: דווחו כחריגה

אם ידועים גם קבצי היעד, השורה הזו מייצבת מאוד.

קבצי יעד: <paths> / מחרוזת מייצגת: "<examples>"

למסור מחרוזת מייצגת עובד מצוין. זה נותן ל-Codex נקודת פיקוח קונקרטית: “היפנית הזו אסור שתישבר”.

flowchart TB
    accTitle: מחרוזת מייצגת נותנת נקודת פיקוח
    accDescr: ציון קבצי היעד ומחרוזת מייצגת שאסור שתישבר נותן ל-Codex נקודת פיקוח קונקרטית, וה-prompt מתייצב.
    i1["ציון קבצי היעד"] --> i3["נקודת פיקוח קונקרטית"]
    i2["מחרוזת מייצגת שאסור שתישבר"] --> i3
    i3 --> i4["ה-prompt מתייצב"]

איור 9: קבצי יעד ומחרוזת מייצגת בשורה אחת מקבעים את יעד האימות.

5. תבנית שכדאי לקבע ב-AGENTS.md

אם חוזרים על אותה אזהרה שוב ושוב, עדיף לשים אותה ב-AGENTS.md. זו תבנית מעשית ל-repo שמטפל בקבצים ביפנית ב-Windows.

# Text Encoding Rules

## Scope
This repository may contain Japanese text and mixed legacy encodings.
Avoid mojibake and accidental re-encoding above all else.

## Mandatory Rules
- Before reading or editing an existing text file that may contain Japanese, first determine:
  - likely encoding
  - BOM presence
  - newline style
- If mojibake is suspected, do not save the file until the encoding interpretation is credible.
- Preserve the original encoding, BOM, and newline style for existing files.
- Treat "convert to UTF-8" as a separate, explicit task.
- New files should follow repository convention. If there is no clear rule, prefer UTF-8 and state whether BOM is used.
- Do not use ambiguous write paths by default, such as shell redirection or convenience commands without explicit encoding control.
- After writing, reopen the file and verify representative Japanese lines.
- If any of the following appears, stop and report:
  - replacement characters
  - unexpected `?`
  - unintended BOM change
  - unintended newline conversion
  - whole-file diffs without a business reason

## Reporting Format
For each changed text file, report:
- path
- detected or preserved encoding
- BOM presence
- newline style
- how verification was performed
- whether representative Japanese text remained intact

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

• If mojibake is suspected, do not save ...
• Treat "convert to UTF-8" as a separate, explicit task.

5.1 תבנית ביפנית

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

# 文字コードの取り扱い規約

## 適用範囲
このリポジトリには日本語テキストと、レガシーな文字コードのファイルが混在します。
文字化けと、意図しない再エンコードを、他の何よりも優先して避けてください。

## 必ず守ること
- 日本語を含む可能性がある既存テキストファイルは、読む前に次を確認する。
  - encoding の候補
  - BOM の有無
  - 改行コード
- 文字化けが疑われる間は、解釈に確信が持てるまでそのファイルを保存しない。
- 既存ファイルは、元の encoding、BOM、改行コードを維持する。
- 「UTF-8 に変換する」は、機能修正とは別の独立したタスクとして扱う。
- 新規ファイルはリポジトリ規約に従う。規約がなければ UTF-8 を選び、BOM の有無を明記する。
- encoding を明示できない書き込み経路を既定で使わない。
  シェルのリダイレクトや、encoding を指定できない便利コマンドが該当する。
- 書き込んだあとは開き直し、日本語の代表行が壊れていないことを確認する。
- 次のいずれかが出たら、修正しようとせず、いったん止めて報告する。
  - 置換文字 U+FFFD の増加
  - 想定していない `?` の増加
  - 意図しない BOM の変化
  - 意図しない改行コードの変換
  - 業務上の理由がないファイル全体の差分

## 報告のしかた
変更したテキストファイルごとに、次を報告する。
- パス
- 検出した、または維持した encoding
- BOM の有無
- 改行コード
- どうやって検証したか
- 日本語の代表文字列が無事だったか

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

6. prompt אסור ו-prompt מומלץ

בטיפול ב-mojibake, רמת הפירוט של ה-prompt משפיעה מאוד על התוצאה.

הנקודה היא תמיד לכתוב גם בדיקה לפני שנוגעים בקובץ וגם אימות אחרי שמירה.

flowchart TB
    accTitle: איך הופכים prompt אסור למומלץ
    accDescr: ב-prompt כמו תתקן את ה-mojibake לא כתוב איפה לעצור, ולכן מוסיפים בדיקה לפני הפעולה ואימות אחרי השמירה, כדי לקבל prompt שכולל גם היכן לעצור את השמירה.
    j1["תתקן את ה-mojibake"] --> j2["לא כתוב איפה לעצור"]
    j2 -.->|"מוסיפים"| j3["בדיקה לפני הפעולה"]
    j2 -.->|"מוסיפים"| j4["אימות אחרי שמירה"]
    j3 --> j5["prompt שכולל גם איפה לעצור"]
    j4 --> j5

איור 10: ההבדל מ-prompt אסור הוא בדיקה, אימות, ונקודת עצירה ברורה.

7. רשימת בדיקה בסקירה

אחרי ש-Codex עבד, יציב עוד יותר לקבע גם מה בני אדם בודקים.

• האם דווח הטיפול ב-encoding / BOM / newline לכל קובץ שהשתנה
• האם שורות יפניות בלבד השתנו בצורה גדולה ולא טבעית
• האם יש diff ענק שכולו newline
• האם U+FFFD או ? התרבו
• האם יש diff כולל שלא קשור לשינוי עסקי
• האם יש עיוות עמודות או מרכאות ב-CSV או בלוג

בטיפול ב-mojibake מה שחשוב הוא לא להגדיל את מספר ה-diff המוצלחים, אלא לעצור מהר diff חשוד.

8. סיכום

כשמריצים Codex על קבצים ביפנית ב-Windows, מה שעוזר בהתחלה הוא לא ליישר את המחשב עד הסוף, אלא להגיד ל-Codex במפורש את תהליך העבודה על encoding.

חמש נקודות שכדאי לזכור:

• לבדוק encoding / BOM / newline לפני הקריאה
• אם יש חשד ל-mojibake, לא לשמור על סמך ניחוש
• קובץ קיים נשאר כמו שהוא; קובץ חדש בלבד לכיוון UTF-8
• לאסור נתיב כתיבה בלי encoding מפורש
• אחרי שמירה לפתוח מחדש ולאמת שורה יפנית מייצגת

ואם חוזרים על זה בכל משימה, עדיף לשים ב-AGENTS.md. זה הכי מעשי.

ליבת הטיפול ב-mojibake היא לא לבקש “תטפל ביפנית כמו שצריך”, אלא לנסח במפורש מתי מותר לשמור ומתי צריך לעצור. אם כותבים עד לרמה הזו, גם ב-Windows Codex הופך נוח הרבה יותר לעבודה.

flowchart TB
    accTitle: הליבה היא ניסוח מפורש של התנאים
    accDescr: ליבת הטיפול ב-mojibake היא לא לבקש לטפל ביפנית כמו שצריך, אלא לנסח במפורש מתי מותר לשמור ומתי צריך לעצור.
    k1["בקשה לטפל ביפנית כמו שצריך"] -.-> k2["זו לא הליבה"]
    k3["ניסוח מתי מותר לשמור"] --> k5["Codex נוח יותר גם ב-Windows"]
    k4["ניסוח מתי צריך לעצור"] --> k5

איור 11: הליבה היא לא איך מבקשים, אלא ניסוח מפורש של תנאי שמירה ועצירה.

9. מקורות

• OpenAI Codex docs, Best practices
• OpenAI Codex docs, Custom instructions with AGENTS.md
• OpenAI Codex docs, Windows
• Microsoft Learn, about_Character_Encoding
• Microsoft Learn, Code Page Identifiers
• Microsoft Learn, Byte order mark

מאמרים קשורים

מאמרים עדכניים עם אותן תגיות, להעמקה בנושאים קרובים.

נושאים קשורים

העמודים האלה ממקמים את הנושא בהקשר רחב יותר של שירותים והחלטות.

שירותים הקשורים לנושא הזה

המאמר קשור ישירות לשירותים הבאים.

שאלות נפוצות

שאלות נפוצות בפניות בנושא המאמר.

למה טקסט יפני יוצא כ-mojibake כשמריצים Codex ב-Windows?

הבעיה היא לא ש-Codex חלש ביפנית. בצד הקבצים של Windows חיים כמה encodings במקביל (UTF-8, CP932, משפחת UTF-16) וכמה נתיבי כתיבה. אם Codex פירש פעם אחת לא נכון, הוא עלול להתייחס למחרוזת שהוא לא באמת קורא כאילו היא תקינה, ולהמשיך לעריכה הבאה. שמירה במצב כזה כבר לא בעיית תצוגה: הקובץ עצמו נשבר. לכן טיפול ב-mojibake הוא בסוף ניהול של תהליך ה-I/O.

איזה prompt עוזר למנוע mojibake ב-Codex?

מה שעובד הכי טוב הוא לקבע מראש את תהליך העבודה על encoding. חמש נקודות: לפני שקוראים קובץ קיים עם יפנית, לבדוק מועמד ל-encoding, BOM, וסוג newline; לא לשמור קובץ חשוד עד שהפרשנות אמינה; בקובץ קיים לשמור על ה-encoding המקורי, ובקובץ חדש בלבד לעבור ל-UTF-8; לכתוב רק בשיטות שמציינות encoding במפורש; אחרי שמירה לפתוח מחדש ולאמת שורות יפניות מייצגות. אם מוסיפים גם את נתיבי הקבצים וגם מחרוזת מייצגת שאסור שתישבר, זה מתייצב עוד יותר.

אסור לתת prompt כמו 'תתקן את ה-mojibake' או 'תהפוך הכול ל-UTF-8'?

שניהם מסוכנים. לא כתוב בהם באיזה שלב Codex צריך לעצור לפני שמירה, ולכן קל שהתקלה תתקבע אחרי שמירה על סמך ניחוש. 'תהפוך הכול ל-UTF-8' מסוכן במיוחד: בעריכת קובץ קיים עדיף לשמור על encoding, BOM ו-newline המקוריים, ולהוציא המרה של כל ה-repo ל-UTF-8 כמשימה נפרדת, עם diff וטווח השפעה. במקום זה כותבים משהו כמו 'להפריד בין השחתה לבעיית תצוגה, ולא לשמור על סמך ניחוש', כולל בדיקה לפני הפעולה ואימות אחרי השמירה.

כדאי לכתוב את כללי ה-encoding ב-AGENTS.md?

אם חוזרים על אותה אזהרה בכל משימה, עדיף לקבע אותה ב-AGENTS.md. כותבים שם את הבדיקה לפני קריאה (encoding, BOM, newline), איסור שמירה כל עוד יש חשד ל-mojibake, שמירה על קבצים קיימים, המרת UTF-8 כמשימה נפרדת, איסור נתיבי כתיבה בלי encoding מפורש, אימות בקריאה חוזרת אחרי שמירה, וכלל לעצור ולדווח כשמשהו חריג. אם מקבעים גם פורמט דיווח (encoding, BOM, newline ושיטת האימות לכל קובץ שהשתנה), גם הסקירה מתייצבת.

פרופיל הכותב

עמוד היכרות עם כותב המאמר.

Go Komura

מנהל KomuraSoft LLC

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