Правила инструкций, которые уменьшают кракозябры Codex в Windows

Когда Codex в Windows работает с файлами, содержащими японский текст, первым делом помогает не выровнять все настройки редактора и shell, а явно указать Codex, как читать, как писать и где останавливаться.

Особенно часто застревают в таких ситуациях.

• Одновременно встречаются файлы в UTF-8, CP932 и семействе UTF-16
• На экране текст выглядит читаемым, но интерпретация фактических байт уже съехала
• Хотели лишь чуть поправить существующий файл, а при сохранении он пересохранился в другой encoding
• Ломается не код, а CSV, TXT, логи, Markdown, файлы конфигурации
• Временный скрипт или сырой вывод shell сохраняют как есть, и инцидент закрепляется навсегда

С OpenAI Codex стабильнее работать не как с разовым собеседником в чате, а как с напарником, которому заданы настройки и рабочие правила для постоянного использования. Если в вашем процессе Codex читает 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 — это агент для кода, который реально читает и пишет файлы репозитория. Входов несколько: CLI в локальном терминале, расширение редактора, вариант в облаке. В этой статье речь о сценарии, когда агенту дают править файлы локального репозитория напрямую. Инциденты с кракозябрами случаются в момент «отредактировал и сохранил», поэтому суть не в том, какой вход вы выбрали, а в том, как вы ограничиваете путь записи в файл.

AGENTS.md — это Markdown-файл с постоянными инструкциями для работы в данном репозитории. Как его читают, полезно помнить.

• Место не одно. Читаются и общая настройка вроде ~/.codex/AGENTS.md в домашнем каталоге, и AGENTS.md со стороны репозитория.
• Файлы склеиваются по пути от корня репозитория к рабочему каталогу. То есть AGENTS.md в подкаталоге подключается позже и поэтому перекрывает инструкции выше по дереву.
• У суммарного размера есть потолок. По умолчанию обрезка примерно на 32 KiB, поэтому стратегия «на всякий случай напишем всё» отрезает хвост. Правила кодировки безопаснее держать короткими и ближе к началу.

Из этих трёх пунктов следует практический вывод: соглашение о кодировке лучше писать в AGENTS.md в корне репозитория, коротко и ближе к началу. Если в подкаталоге окажется другое соглашение о записи, победит оно.

flowchart TB
    accTitle: Как читается AGENTS.md
    accDescr: Рисунок показывает, что читаются и домашний, и репозиторный AGENTS.md, они склеиваются от корня к рабочему каталогу, нижние перекрывают верхние, суммарный размер по умолчанию обрезается примерно на 32 KiB, поэтому соглашение о кодировке пишут коротко в корне, ближе к началу.
    b1["Домашний AGENTS.md"] --> b3["Склейка от корня к рабочему каталогу"]
    b2["Репозиторный AGENTS.md"] --> b3
    b3 --> b4["Позже склеенный нижний перекрывает"]
    b3 -.-> b5["По умолчанию обрезка около 32 KiB"]
    b4 --> b6["Соглашение: коротко в корне, ближе к началу"]
    b5 -.-> b6

Рис. 2: У AGENTS.md есть порядок склейки и потолок размера, поэтому соглашение держат коротко в верхней части корневого файла.

1. Сначала вывод

Самый действенный способ уменьшить инциденты с кракозябрами Codex в среде Windows — заранее зафиксировать порядок работы с кодировкой.

Особенно хорошо работают такие правила.

• Для существующих файлов с японским текстом перед чтением проверить кандидата encoding, наличие BOM и символы новой строки
• Для файлов с подозрением на кракозябры не давать сохранять, пока нет уверенности
• Для существующих файлов сохранять исходные encoding, BOM и переводы строк
• Для новых файлов по соглашению репозитория склоняться к семейству UTF-8
• Для записи использовать только методы, где 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: Схема показывает, как рабочие правила кодировки в AGENTS.md для Codex предотвращают расхождение в интерпретации encoding и порчу файла из-за сохранения «по догадке», вместе с несовместимостью CP932 и UTF-8 и различием encoding по умолчанию между версиями PowerShell.
    codex["Codex"]
    mojibake["mojibake (искажение кодировки)"]
    agents_md["AGENTS.md"]
    character_encoding_rules["правила работы с encoding"]
    pre_read_encoding_check["проверка encoding/BOM/переводов строк перед чтением"]
    unverified_save["сохранение без проверки encoding"]
    existing_file_encoding_preservation["сохранение encoding существующих файлов"]
    explicit_encoding_write["запись с явным encoding"]
    post_write_reread_verification["проверка повторным чтением после сохранения"]
    ambiguous_write_path["путь записи без явного encoding"]
    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 хотя бы раз неверно интерпретирует байты, он может продолжить следующее редактирование, приняв непрочитанную строку за корректно прочитанную. А если после этого файл сохраняется как есть, проблема перестаёт быть визуальной и закрепляется как порча самого файла.

Поэтому защита от кракозябр, если довести до сути, сводится к тому, как вы управляете процедурой ввода-вывода.

flowchart TB
    accTitle: Как инцидент фиксируется как порча файла
    accDescr: Рисунок показывает, что если в активах сосуществуют несколько кодировок и путей записи и Codex хотя бы раз неверно интерпретирует байты, он продолжает правку, не прочитав строку, а в момент сохранения проблема перестаёт быть визуальной и фиксируется как порча самого файла.
    d1["Сосуществование нескольких encoding и путей записи"] --> d2["Одна неверная интерпретация"]
    d2 --> d3["Правка продолжается, строка так и не прочитана"]
    d3 --> d4["Сохранение фиксирует порчу"]
    d4 -.-> d5["Суть защиты — управление процедурой ввода-вывода"]

Рис. 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 проходит в обеих интерпретациях. В конце заставьте глазами проверить, читаются ли контрольные японские строки.

flowchart TB
    accTitle: Порядок проверки до чтения
    accDescr: Рисунок показывает порядок: посмотреть первые байты в hex и определить наличие BOM, посчитать символы новой строки, строгим декодированием UTF-8 сузить кандидата encoding и в конце глазами проверить, читаются ли контрольные японские строки.
    f1["Посмотреть первые байты в hex"] --> f2["Определить наличие BOM"]
    f2 --> f3["Посчитать символы новой строки"]
    f3 --> f4["Строгим UTF-8 сузить кандидата"]
    f4 --> f5["Глазами проверить контрольные японские строки"]
    f4 -.-> f6["Один ASCII проходит в обеих интерпретациях"]

Рис. 6: Проверку до чтения ведут в порядке байты — переводы строк — декодирование — взгляд.

3.2 Файлы с подозрением на кракозябры не сохранять наугад

Это особенно важное правило.

Если есть подозрение на кракозябры, на этапе расследования держать файл только для чтения и запретить перезапись, пока интерпретация не станет достоверной.

Как и у человека: нельзя сохранять файл, который вы по факту не смогли прочитать. Если сохранить его на основании «выглядит немного странно, но, наверное, это оно», догадка становится закреплённой версией сбоя.

3.3 Существующие файлы сохранять как есть, UTF-8 по умолчанию — только для новых

В контексте защиты от кракозябр неожиданно опасной оказывается формулировка «унифицируй всё в UTF-8».

В конечном итоге решение перевести весь репозиторий на UTF-8 вполне может быть обоснованным, но безопаснее делать это как отдельную задачу, глядя на diff и область воздействия. Для повседневных доработок стабилен именно такой порядок.

• при правке существующего файла сохранять его исходный encoding;
• при добавлении нового файла создавать его в семействе UTF-8 по соглашению репозитория;
• если существующий файл нужно перекодировать, отделять это от обычных функциональных правок.

3.4 По умолчанию не давать пользоваться неоднозначными способами записи

В Windows число инцидентов чаще всего увеличивает подход «это же небольшой вывод, запишем через shell как попало».

• вывести напрямую через перенаправление;
• сохранить напрямую «удобной» командой;
• сразу повысить временный артефакт до статуса рабочего файла.

У таких путей часто не указан encoding явно, и это питательная почва для сбоев. Поэтому Codex заранее стоит зафиксировать и то, как выбирать способ записи.

«Кодировка по умолчанию» зависит от версии PowerShell

Этого не знаешь — обязательно наступишь. У PowerShell кодировка записи по умолчанию разная в разных версиях.

То есть один и тот же скрипт даёт разные файлы в зависимости от того, прогнали его в 5.1 или в 7. Классика жанра: «на машине разработчика было нормально, на сервере в поле сломалось».

Плюс у 5.1 есть свойство: если указать encoding семейства Unicode, BOM ставится всегда. -Encoding UTF8 — это UTF-8 с BOM.

Поэтому запись каждый раз заставляйте указывать явно.

# Переменные объявлены так, чтобы этот раздел был самодостаточным
$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

Если хотите сдвинуть значение по умолчанию на всю сессию, есть $PSDefaultParameterValues. Но это настройка только этой сессии, поэтому регламент, который исходит из «у нас это прописано в профиле», ломается в чужой среде.

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

Запись через > вместо Out-File начиная с 5.1 внутри всё равно только вызывает Out-File, так что кодировка по умолчанию несёт ту же проблему. Самый надёжный вариант — запретить перенаправление и разрешить только командлеты или .NET API, где encoding можно записать явно.

flowchart TB
    accTitle: Один скрипт даёт разные файлы
    accDescr: Рисунок показывает, что у PowerShell кодировка записи по умолчанию зависит от версии, поэтому один скрипт даёт разные файлы в 5.1 и в 7, и надёжнее запретить перенаправление и разрешить только командлеты или .NET API, где encoding можно указать явно.
    g0["Один и тот же скрипт"] --> g1["Запуск в Windows PowerShell 5.1"]
    g0 --> g2["Запуск в PowerShell 7"]
    g1 --> g3["Получается файл с другой кодировкой"]
    g2 --> g3
    g3 -.-> g4["Разрешать только пути, где encoding указывают явно"]

Рис. 7: Кодировка по умолчанию зависит от версии, поэтому запись каждый раз указывают явно.

3.5 После сохранения заново прочитать файл и проверить контрольные японские строки

«Файл сохранился» и «файл не повреждён» — не одно и то же.

Важно после сохранения ещё раз прочитать характерные японские строки и проверить такие моменты.

• нет ли символа замены U+FFFD;
• не выросло ли неестественно число символов ?;
• не превратился ли diff в гигантское изменение из одного BOM или переводов строк;
• остался ли без изменений японский текст, который по смыслу задачи менять не требовалось.

3.6 Если появились признаки аномалии — сначала сообщать, а не сразу исправлять

При инцидентах с кодировкой ущерб меньше, если заставить Codex остановиться и сообщить, а не пытаться всё починить самому.

Например, при появлении следующих признаков ситуацию безопаснее временно считать аномальной.

• рост числа 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 по соглашению репозитория
- Используй для записи только методы, где 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. Ниже — практический шаблон для репозиториев, где в 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 нельзя указать явно.
  Сюда относятся перенаправление shell и «удобные» команды без параметра encoding.
- После записи открыть файл заново и убедиться, что контрольные японские строки не повреждены.
- Если появилось любое из следующего, не пытаться чинить, а остановиться и сообщить.
  - рост символов замены U+FFFD
  - непредвиденный рост `?`
  - непреднамеренное изменение 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 или ?
• Нет ли изменений по всему файлу, не связанных с существом задачи
• Не нарушена ли структура столбцов или кавычек в CSV и логах

В защите от кракозябр важно не столько наращивать число успешных diff, сколько как можно раньше останавливать подозрительные diff.

8. Итог

Когда Codex в Windows работает с японскими файлами, первым делом помогает не идеально выровнять настройки компьютера, а явно указать Codex порядок работы с кодировкой.

Особенно стоит запомнить пять пунктов.

• Перед чтением проверять encoding / BOM / переводы строк
• При подозрении на кракозябры не давать сохранять наугад
• Существующие файлы сохранять как есть, к UTF-8 склонять только новые
• Запрещать неоднозначные способы записи
• После сохранения заново читать файл и проверять контрольные японские строки

А если приходится повторять это каждый раз — правило стоит внести в AGENTS.md. Это самый практичный путь.

Суть защиты от кракозябр не в просьбе «аккуратно обращайся с японским текстом», а в том, чтобы письменно зафиксировать условия, при которых сохранение разрешено, и условия, при которых нужно остановиться. Если довести инструкцию до такой детализации, с Codex становится заметно легче работать даже в Windows.

flowchart TB
    accTitle: Суть — письменно зафиксировать условия
    accDescr: Рисунок показывает, что суть защиты от кракозябр не в просьбе аккуратно обращаться с японским текстом, а в том, чтобы письменно зафиксировать условия, при которых сохранение разрешено, и условия, при которых нужно остановиться.
    k1["Просьба «аккуратно обращайся с японским текстом»"] -.-> k2["Это не суть"]
    k3["Письменно зафиксировать, когда сохранение разрешено"] --> k5["В Windows с Codex становится легче работать"]
    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

Похожие статьи

Недавние статьи с теми же тегами помогут подробнее изучить близкие темы.

Связанные темы

Эти страницы показывают тему статьи в более широком контексте услуг и решений.

Услуги по этой теме

Статья напрямую связана со следующими услугами.

Частые вопросы

Вопросы, которые часто возникают при консультациях по теме статьи.

Почему при работе Codex в Windows японский текст превращается в кракозябры?

Настоящая причина не в том, что Codex плохо справляется с японским языком, а в том, что на стороне активов Windows сосуществуют сразу несколько кодировок — UTF-8, CP932, семейство UTF-16 — и несколько разных путей записи. Если в такой ситуации Codex хотя бы раз неверно интерпретирует байты, он может продолжить редактирование, приняв непрочитанную строку за корректно прочитанную. А если после этого файл сохранить как есть, проблема перестаёт быть визуальной и фиксируется как порча самого файла. Поэтому защита от кракозябр, по сути, сводится к тому, как вы управляете процедурой ввода-вывода.

Какие инструкции не дают Codex испортить кодировку?

Лучше всего заранее зафиксировать порядок работы с кодировкой. Конкретно это пять пунктов: для существующих файлов с японским текстом перед чтением проверять кандидата encoding, наличие BOM и символы новой строки; файлы с подозрением на кракозябры не сохранять, пока нет уверенности; у существующих файлов сохранять исходную кодировку, а UTF-8 оставлять только для новых; пользоваться только теми способами записи, где encoding можно указать явно; после сохранения заново прочитать файл и проверить контрольные японские строки. Ещё стабильнее становится, если передать целевые файлы и «японский текст, который нельзя повредить».

Разве нельзя сказать «исправь кракозябры» или «переведи всё в UTF-8»?

Обе формулировки опасны. В них не сказано, на каком этапе Codex должен остановить сохранение, поэтому файл легко сохраняется наугад, и инцидент становится фактом. Особенно опасна фраза «переведи всё в UTF-8»: при правке существующих файлов нужно сохранять исходные encoding, BOM и переводы строк, а перевод всего репозитория на UTF-8 лучше вынести в отдельную задачу и вести, глядя на diff и область воздействия. Вместо этого указывайте вроде «отделите порчу самого файла от проблемы отображения и не сохраняйте наугад» — то есть включите и проверку до начала работы, и проверку после сохранения.

Стоит ли фиксировать правила кодировки в AGENTS.md?

Если одно и то же предупреждение приходится повторять в каждой задаче, эффективнее закрепить его в AGENTS.md на постоянной основе. Соберите там: проверку encoding, BOM и переводов строк перед чтением; запрет на сохранение, пока есть подозрение на кракозябры; сохранение исходного состояния существующих файлов; вынесение перекодировки в UTF-8 в отдельную задачу; запрет неоднозначных способов записи; проверку повторным чтением после сохранения; и правило останавливаться и сообщать при аномалиях. Дополнительно стоит зафиксировать формат отчёта — encoding, BOM, перевод строки и способ проверки для каждого изменённого файла: тогда стабильнее становится и проверка со стороны ревьюера.

Об авторе

Страница с профилем автора статьи.

Го Комура

Представитель KomuraSoft LLC

Специализируется на разработке программного обеспечения для Windows, техническом консалтинге и расследовании сбоев, особенно в проектах с унаследованными системами и трудно воспроизводимыми ошибками.