כללי הנחיה שמפחיתים תקלות קריאה משובשת של Codex ב-Windows

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

המקרים שבהם קל להיתקל בקושי הם במיוחד:

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

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

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

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

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

הנחת יסוד: ה-Codex וה-AGENTS.md שהמאמר מניח

למי שלא משתמש ב-Codex, כותבים כאן קודם רק את הנחות היסוד.

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

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

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

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

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

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

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

הכי יעיל להפחתת תקלות קריאה משובשת של Codex בסביבת Windows הוא לקבע מראש את הליך העבודה עם קידוד התווים.

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

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

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

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

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

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

ולהפך, הנחיות כמו אלה מסוכנות:

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

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

מפת הידע של המאמר

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

flowchart LR
    accTitle: מפת הידע של מניעת קריאה משובשת של תווים (mojibake) ב-Codex
    accDescr: תרשים המראה איך מתן כללי עבודה עם קידוד תווים ל-Codex דרך AGENTS.md מונע פער בפרשנות ה-encoding והשחתת קבצים עקב שמירה מבוססת ניחוש, לצד אי-ההתאמה בין CP932 ל-UTF-8 וההבדל ב-encoding ברירת המחדל בין גרסאות PowerShell.
    codex["Codex"]
    mojibake["קריאה משובשת של תווים (mojibake)"]
    agents_md["AGENTS.md"]
    character_encoding_rules["כללי עבודה עם קידוד תווים"]
    pre_read_encoding_check["בדיקת encoding‏/BOM/סוף שורה לפני הקריאה"]
    unverified_save["שמירה על סמך ניחוש"]
    existing_file_encoding_preservation["מדיניות שימור ה-encoding של קבצים קיימים"]
    explicit_encoding_write["כתיבה עם ציון encoding מפורש"]
    post_write_reread_verification["אימות בקריאה חוזרת אחרי השמירה"]
    ambiguous_write_path["נתיב כתיבה עמום"]
    utf8_migration_as_separate_task["הפרדת המעבר ל-UTF-8 למשימה נפרדת"]
    cp932["CP932"]
    utf_8["UTF-8"]
    bom["BOM(Byte Order Mark)"]
    strict_utf8_decode_check["בדיקת פענוח UTF-8 קפדנית"]
    encoding_misinterpretation["פער בפרשנות ה-encoding"]
    reencoding_corruption["השחתת קובץ עקב פרשנות encoding שגויה"]
    replacement_character["U+FFFD(REPLACEMENT CHARACTER)"]
    windows_powershell_5_1["Windows PowerShell 5.1"]
    ansi_codepage["דף קוד ANSI"]
    utf_16["UTF-16"]
    powershell_7["PowerShell 7"]
    character_encoding_rules -->|"מוגדר באמצעות"| agents_md
    character_encoding_rules -->|"מענה מומלץ ל"| codex
    pre_read_encoding_check -->|"מענה מומלץ ל"| codex
    unverified_save -->|"שימוש לא מומלץ ל"| codex
    existing_file_encoding_preservation -->|"מענה מומלץ ל"| codex
    explicit_encoding_write -->|"מענה מומלץ ל"| codex
    post_write_reread_verification -->|"מענה מומלץ ל"| codex
    ambiguous_write_path -->|"שימוש לא מומלץ ל"| codex
    utf8_migration_as_separate_task -->|"מענה מומלץ ל"| codex
    cp932 -.->|"אינו מתיישב עם"| utf_8
    pre_read_encoding_check -->|"נבדק באמצעות"| bom
    pre_read_encoding_check -->|"נבדק באמצעות"| strict_utf8_decode_check
    encoding_misinterpretation -->|"עלול לגרום ל"| mojibake
    mojibake -.->|"עלול לגרום ל"| reencoding_corruption
    unverified_save -.->|"עלול לגרום ל"| reencoding_corruption
    pre_read_encoding_check -->|"מצמצם"| encoding_misinterpretation
    reencoding_corruption -->|"נבדק באמצעות"| replacement_character
    windows_powershell_5_1 -->|"משתמש ב"| ansi_codepage
    windows_powershell_5_1 -->|"משתמש ב"| utf_16
    powershell_7 -->|"משתמש ב"| utf_8
    ambiguous_write_path -->|"משתמש ב"| windows_powershell_5_1
    ambiguous_write_path -->|"משתמש ב"| powershell_7

בתרשים, קו מלא מציין קשר שמתקיים תמיד וקו מקווקו מציין קשר מותנה (תנאי ההתקיימות מפורטים בהסבר של כל קשר בעמוד המפורט). רשימת כל הקשרים (סך הכול 22, עם אסמכתה ורמת ודאות) והגדרות המושגים המרכזיים מרוכזות בעמוד המפורט של מפת הידע (ביפנית). נתונים: JSON-LD / Turtle

2. למה תקלות קריאה משובשת נפוצות ב-Windows

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

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

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

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

לכן, מניעת קריאה משובשת מתמצה בסופו של דבר בשאלה איך מנהלים את הליך ה-I/O.

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

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

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 וסוף שורה לפני הקריאה

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

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

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

איך בדיוק גורמים לבדוק

אם כותבים רק “תבדוק”, גם Codex וגם בני אדם מתפזרים בשיטה. יציב יותר לטמון בהנחיה את הליך הבדיקה עצמו. הדוגמאות למטה עובדות גם ב-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 שנוצרו כאן. אופן הקריאה הוא כך.

לאחר מכן, סופרים את קודי סוף השורה. כאן מתגלה “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 אומר 'זרוק חריגה אם רצף הבייטים לא תקין'
$strictUtf8 = New-Object System.Text.UTF8Encoding($false, $true)
try {
    $null = $strictUtf8.GetString($bytes)
    'UTF-8 として矛盾なくデコードできました'
}
catch {
    'UTF-8 ではありません。CP932 などの候補を試してください'
}

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

# מ-PowerShell 6.2 ואילך, אפשר לציין ישירות את מספר דף הקוד
Get-Content -Path $path -Encoding 932 -TotalCount 3

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

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

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

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

3.2 לא לתת לשמור קובץ שקריאה משובשת חשודה בו, על סמך ניחוש

זה חשוב במיוחד.

כשיש חשד לקריאה משובשת, בשלב הבדיקה שומרים על מצב read-only, ואוסרים כתיבת-דריסה (overwrite) עד שיש ביטחון בפרשנות.

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

3.3 משמרים קובץ קיים, ורק קובץ חדש מבוסס UTF-8

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

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

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

3.4 לא להשתמש כברירת מחדל בנתיב כתיבה עמום

ב-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 של המערכת
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 או API של .NET שמאפשרים לציין 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 אחרי השמירה, קוראים שוב ומאמתים שורה יפנית מייצגת

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

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

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

3.6 אם מופיע סימן חריגה, לדווח לפני התיקון

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

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

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

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

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

4. אם מוסרים כהנחיה קצרה

אם מצרפים גרסה קצרה לכל משימה, זה מספיק יעיל.

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

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

אם בנוסף ידועים קבצי היעד, הוספת השורה הזו מייצבת מאוד.

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

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

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

איור 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 נוח יותר לתפעל בעברית. התוכן זהה.

# כללי הטיפול בקידוד תווים

## היקף
ב-repository הזה מעורבבים טקסט ביפנית וקבצים בקידודים מסורתיים (legacy).
הימנעו מקריאה משובשת ומקידוד מחדש בלתי מכוון, מעל לכל דבר אחר.

## חובה לשמור על אלה
- בקובץ טקסט קיים שעשוי להכיל יפנית, בודקים לפני הקריאה:
  - את מועמדי ה-encoding
  - קיום BOM
  - סוג סוף השורה
- כל עוד קריאה משובשת חשודה, לא שומרים את הקובץ עד שיש ביטחון בפרשנות.
- בקובץ קיים, משמרים את ה-encoding, BOM וסוג סוף השורה המקוריים.
- מתייחסים ל"המרה ל-UTF-8" כמשימה נפרדת ועצמאית, לא כחלק מתיקון פיצ'ר.
- קובץ חדש - פועלים לפי תקן ה-repository. אם אין תקן ברור, בוחרים UTF-8 ומציינים במפורש אם יש BOM.
- לא משתמשים כברירת מחדל בנתיב כתיבה שלא מאפשר לציין encoding, כמו redirection של ה-shell או פקודת נוחות בלי בקרת encoding.
- אחרי הכתיבה, פותחים מחדש ומאמתים ששורות יפניות מייצגות לא נשברו.
- אם מופיע אחד מאלה, לא מנסים לתקן - עוצרים ומדווחים:
  - תו החלפה (replacement character)
  - `?` בלתי צפוי
  - שינוי BOM בלתי מכוון
  - המרת סוף שורה בלתי מכוונת
  - diff של הקובץ כולו בלי סיבה עסקית

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

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

6. הנחיות אסורות והנחיות מומלצות

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

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

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

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

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

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

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

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

8. סיכום

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

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

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

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

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

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

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

מקורות

• 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

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

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

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

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

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

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

שאלות נפוצות

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

‏למה יפנית מוצגת כקריאה משובשת כשמשתמשים ב-Codex ב-Windows?

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

‏אילו הנחיות עוזרות למנוע קריאה משובשת ב-Codex?

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

‏האם אסור לתת הנחיה כמו 'תקן את הקריאה המשובשת' או 'הפוך הכול ל-UTF-8'?

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

‏כדאי לכתוב את כללי קידוד התווים ב-AGENTS.md?

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

פרופיל הכותב

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

Go Komura

מנהל KomuraSoft LLC

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