Prompting-Regeln gegen Mojibake-Unfälle mit Codex unter Windows

Wenn Codex unter Windows mit Dateien arbeiten soll, die japanischen Text enthalten, hilft am Anfang weniger das vollständige Angleichen von Editor- und Shell-Einstellungen als vielmehr Codex explizit mitzuteilen, wie es lesen, wie es schreiben und wo es anhalten soll.

Besonders leicht kommt es in Situationen wie diesen zu Problemen:

• UTF-8-, CP932- und UTF-16-artige Dateien liegen gemischt vor
• Der Text sieht auf den ersten Blick lesbar aus, aber die Interpretation der tatsächlichen Bytes ist verschoben
• Man wollte nur eine bestehende Datei leicht anpassen, aber beim Speichern wird sie in einem anderen Encoding neu geschrieben
• Der Schaden entsteht bei „Nicht-Code“ wie CSV, TXT, Logs, Markdown oder Konfigurationsdateien
• Ein Wegwerf-Skript oder eine rohe Shell-Ausgabe wird unverändert gespeichert, und der Unfall wird dauerhaft

OpenAIs Codex verhält sich stabiler, wenn man es weniger wie einen einmaligen Chat-Partner behandelt und mehr wie ein Teammitglied, dem man dauerhafte Einstellungen und Arbeitsregeln mitgibt. Besonders wenn in Ihrem Ablauf AGENTS.md gelesen wird, ist es wirkungsvoller, Regeln zur Zeichenkodierung dort dauerhaft zu hinterlegen, statt sie jedes Mal mündlich zu wiederholen.

Dieser Artikel ordnet aus Praxissicht die Anweisungen, die sich am Anfang am meisten auszahlen, damit Codex unter Windows japanische Dateien sicher handhabt.

Voraussetzung: Welches Codex und welches AGENTS.md dieser Artikel voraussetzt

Für alle, die Codex nicht nutzen, hier zuerst nur die Voraussetzungen.

Codex ist ein Coding-Agent, der Dateien eines Repositorys tatsächlich liest und schreibt. Es gibt mehrere Zugänge – eine CLI, die im lokalen Terminal läuft, eine Editor-Erweiterung, eine Cloud-seitige Variante –, aber dieser Artikel setzt die Nutzung voraus, bei der Dateien eines lokalen Repositorys direkt bearbeitet werden. Mojibake-Unfälle entstehen beim „Bearbeiten und Speichern“, deshalb ist weniger entscheidend, über welchen Zugang gearbeitet wird, als wie man den Schreibpfad zu den Dateien einschränkt.

AGENTS.md ist eine Markdown-Datei, in der dauerhafte Anweisungen für die Arbeit an diesem Repository stehen. Bei ihrer Einlesung gibt es Eigenschaften, die man sich merken sollte.

• Der Ort ist nicht nur einer. Sowohl globale Einstellungen wie ~/.codex/AGENTS.md im Home-Verzeichnis als auch das AGENTS.md im Repository selbst werden gelesen.
• Sie werden der Reihe nach vom Repository-Root zum Arbeitsverzeichnis hin verkettet. Das heißt, ein AGENTS.md in einem Unterverzeichnis wirkt stärker als übergeordnete Anweisungen, weil es später angehängt wird.
• Für die Gesamtgröße gibt es eine Obergrenze. Standardmäßig wird bei etwa 32 KiB abgeschnitten. Wer „erst mal alles hineinschreibt“, verliert deshalb den hinteren Teil. Regeln zur Zeichenkodierung sollten kurz und weiter oben stehen.

Wegen dieser drei Punkte ist es praxistauglich, die Zeichenkodierungs-Konvention kurz und weit oben im AGENTS.md des Repository-Roots zu platzieren. Gibt es in einem Unterverzeichnis eine abweichende Schreibkonvention, setzt sich diese durch.

1. Zuerst das Fazit

Im Windows-Umfeld hilft es am meisten, um Mojibake-Unfälle bei Codex zu reduzieren, den Arbeitsablauf für Zeichenkodierung vorab festzulegen.

Besonders wirksam sind diese Regeln.

• Bei bestehenden Dateien mit japanischem Text: vor dem Lesen die Encoding-Kandidaten, das Vorhandensein eines BOM und den Zeilenumbruch-Stil prüfen lassen
• Bei Dateien, bei denen Mojibake vermutet wird: erst speichern lassen, wenn Sicherheit besteht
• Bei bestehenden Dateien: das ursprüngliche Encoding, BOM und die Zeilenumbrüche beibehalten lassen
• Bei neuen Dateien: gemäß Repository-Konvention auf UTF-8-Varianten ausrichten
• Beim Schreiben: nur Methoden verwenden lassen, die das Encoding explizit angeben können
• Nach dem Speichern: erneut einlesen und repräsentative japanische Zeilen prüfen lassen

Kurz für den Alltag formuliert, läuft es auf Folgendes hinaus.

• Vor dem Lesen prüfen
• Bei Verdacht: Speichern verboten
• Bestehendes beibehalten, nur Neues UTF-8
• Mehrdeutige Schreibpfade verbieten
• Am Ende erneut einlesen und prüfen

Umgekehrt sind Anweisungen wie diese gefährlich.

• „Behebe das Mojibake“
• „Mach alles zu UTF-8“
• „Gib eine CSV aus“
• „Pass es irgendwie an“
• „Speichere es erst mal und schau“

Bei keiner dieser Anweisungen steht, an welcher Stelle Codex anhalten soll. Bei der Mojibake-Vermeidung muss man nicht nur festlegen, was zu tun ist, sondern auch, wo das Speichern zu stoppen ist.

2. Warum es unter Windows leicht zu Mojibake-Unfällen kommt

Das eigentliche Problem ist nicht, dass Codex schlecht mit Japanisch umgehen kann, sondern dass auf der Windows-Seite mehrere Zeichenkodierungen und mehrere Schreibpfade nebeneinander existieren.

In der Praxis ist eine solche Mischung nicht ungewöhnlich.

• Neuere Quellen und Markdown liegen als UTF-8 vor
• Ältere CSV-, TXT-, Log- und Konfigurationsdateien sind CP932-artig
• Manche Ausgaben und tool-generierten Artefakte sind UTF-16-artig
• Die Speicherpfade variieren je nach Editor, Shell und Excel-Herkunft
• Auch die Zeilenumbrüche sind zwischen LF und CRLF gemischt

Interpretiert Codex in diesem Zustand auch nur einmal falsch, kann es mit einer Zeichenkette, die es gar nicht richtig gelesen hat, so weiterarbeiten, als hätte es sie gelesen. Speichert man dann ab, wird daraus kein Anzeigeproblem mehr, sondern eine dauerhafte Beschädigung der Datei selbst.

Deshalb läuft Mojibake-Vermeidung letztlich darauf hinaus, wie man den I/O-Ablauf steuert.

2.1 Zuerst nur vier Begriffe

Hier werden die Begriffe geklärt, die im Folgenden immer wieder auftauchen.

Wichtig ist, dass weder CP932 noch UTF-8 in der Datei selbst vermerkt sind. Ohne BOM gibt eine Datei von sich aus nicht an, „wie sie zu lesen ist“. Deshalb ist eine Prüfung vor dem Lesen nötig.

3. Die Regeln, die man Codex zuerst fest einprogrammieren sollte

3.1 Vor dem Lesen Encoding-Kandidaten, BOM und Zeilenumbruch prüfen lassen

Die erste Regel lautet:

Bevor eine bestehende Datei mit japanischem Text gelesen wird, die aktuellen Encoding-Kandidaten, das Vorhandensein eines BOM und den Zeilenumbruch-Stil prüfen und bei Verdacht nicht direkt mit der inhaltlichen Interpretation fortfahren.

Der entscheidende Dreh ist, den Ablauf zu „zuerst die Voraussetzungen der Datei betrachten, bevor man den Text liest“ zu ändern.

Wie man das konkret prüfen lässt

Schreibt man nur „prüfen“, gehen sowohl Codex als auch Menschen unterschiedlich vor. Stabiler ist es, den Prüfablauf selbst in die Anweisung einzubetten. Das Folgende funktioniert sowohl unter Windows PowerShell 5.1 als auch unter PowerShell 7.

Zuerst betrachtet man die ersten Bytes hexadezimal. Daran entscheidet sich, ob ein BOM vorhanden ist.

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

# Zeigt die ersten 16 Bytes hexadezimal an
$head = $bytes[0..([Math]::Min(15, $bytes.Length - 1))]
($head | ForEach-Object { $_.ToString('X2') }) -join ' '

Die folgenden Blöcke verwenden die hier erzeugten $path und $bytes unverändert weiter. So liest man das Ergebnis:

Als Nächstes zählt man die Zeilenumbrüche. Daran erkennt man, ob „LF und CRLF gemischt sind“.

$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"

Zuletzt grenzt man die Encoding-Kandidaten ein. Fehlt ein BOM, ist die Frage, ob sich die Datei streng als UTF-8 dekodieren lässt, das schnellste Kriterium. UTF-8 unterliegt strengen Bytefolge-Regeln, daher schlägt das strenge Lesen einer CP932-Datei als UTF-8 meist mittendrin fehl.

# Das zweite Argument $true bedeutet: "Bei ungültiger Bytefolge eine Ausnahme werfen"
$strictUtf8 = New-Object System.Text.UTF8Encoding($false, $true)
try {
    $null = $strictUtf8.GetString($bytes)
    'Konnte widerspruchsfrei als UTF-8 dekodiert werden'
}
catch {
    'Ist kein UTF-8. Kandidaten wie CP932 ausprobieren'
}

Möchte man testweise als CP932 lesen, gibt man die Codepage-Nummer explizit an.

# Ab PowerShell 6.2 lässt sich die Codepage-Nummer direkt angeben
Get-Content -Path $path -Encoding 932 -TotalCount 3

# Unter Windows PowerShell 5.1 ist Default die ANSI-Codepage des Systems. Bei japanischem Windows ist das CP932
Get-Content -Path $path -Encoding Default -TotalCount 3

Dass die strenge Dekodierung gelingt, bedeutet noch nicht „UTF-8 ist bestätigt“. Eine reine ASCII-Datei besteht beide Prüfungen. Lassen Sie sich am Ende visuell bestätigen, ob repräsentative japanische Zeilen lesbar sind.

3.2 Bei Verdacht auf Mojibake nicht auf Verdacht speichern lassen

Das ist besonders wichtig.

Wird Mojibake vermutet, die Datei in der Untersuchungsphase als read-only behandeln und das Überschreiben verbieten, bis die Interpretation glaubwürdig ist.

Das gilt für Menschen genauso: Eine Datei, die man nicht wirklich lesen konnte, darf man nicht speichern. Speichert man mit „sieht etwas kaputt aus, ist aber vermutlich das hier“, wird genau das zur endgültigen Fassung des Unfalls.

3.3 Bestehende Dateien beibehalten, nur neue Dateien standardmäßig auf UTF-8

Im Kontext der Mojibake-Vermeidung ist überraschend gefährlich: „Alles einheitlich auf UTF-8 bringen“.

Die Entscheidung, das gesamte Repository letztlich auf UTF-8 umzustellen, kann sinnvoll sein, ist aber sicherer als eigene Aufgabe umzusetzen, bei der man Diff und Auswirkungsbereich im Blick behält. Für die tägliche Wartung ist dieser Ablauf stabil.

• Beim Bearbeiten einer bestehenden Datei das ursprüngliche Encoding beibehalten
• Beim Hinzufügen einer neuen Datei diese gemäß Repo-Konvention als UTF-8 anlegen
• Ist eine Konvertierung bestehender Dateien nötig, diese von normalen Funktionskorrekturen trennen

3.4 Mehrdeutige Schreibpfade nicht standardmäßig verwenden lassen

Unter Windows entstehen zusätzliche Unfälle vor allem durch „ist ja nur eine kleine Ausgabe, also schnell und unbedacht aus der Shell heraus schreiben“.

• Direktes Ausgeben per Umleitung
• Direktes Speichern mit einem Komfortbefehl
• Ein temporäres Artefakt unverändert zur Produktivdatei befördern

Bei solchen Pfaden ist das Encoding oft nicht explizit angegeben, was sie zum Nährboden für Unfälle macht. Deshalb ist es sicher, für Codex auch festzulegen, wie Schreibmethoden ausgewählt werden.

Das „Standard-Encoding“ unterscheidet sich je nach PowerShell-Version

Das ist eine Stelle, in die man ohne Vorwissen garantiert hineintappt. Bei PowerShell unterscheidet sich das Standard-Encoding beim Schreiben je nach Version.

Das heißt, bei ein und demselben Skript entstehen je nachdem, ob es unter 5.1 oder unter 7 läuft, unterschiedliche Dateien. „Auf der Entwicklungsmaschine ging es, aber auf dem Server vor Ort ging es kaputt“ ist der Klassiker dafür.

Zusätzlich hat 5.1 die Eigenschaft, dass bei Angabe eines Unicode-artigen Encodings immer ein BOM angehängt wird. -Encoding UTF8 bedeutet dort UTF-8 mit BOM.

Deshalb sollte das Schreiben jedes Mal explizit angegeben werden.

# Damit dieser Abschnitt für sich funktioniert, werden die Variablen hier definiert
$path    = 'C:\work\orders.csv'
$newPath = 'C:\work\orders-new.csv'
$lines   = @('顧客コード,顧客名', 'C0001,株式会社サンプル')

# Ist der Bestand CP932, als CP932 zurückschreiben (ab PowerShell 6.2)
Set-Content -Path $path -Value $lines -Encoding 932

# Unter Windows PowerShell 5.1 an die ANSI-Codepage des Systems anpassen
Set-Content -Path $path -Value $lines -Encoding Default

# Eine neue Datei als UTF-8 ohne BOM anlegen (PowerShell 7)
Set-Content -Path $newPath -Value $lines -Encoding utf8NoBOM

Möchte man den Standard für die gesamte Sitzung festlegen, kann man auch $PSDefaultParameterValues verwenden. Das gilt allerdings nur für diese eine Sitzung – ein Vorgehen, das voraussetzt, „das steht doch in unserem Profil“, geht in der Umgebung anderer Personen kaputt.

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

Auch die Schreibweise > statt Out-File ruft ab 5.1 intern nur Out-File auf, weshalb dasselbe Problem beim Standard-Encoding besteht. Am zuverlässigsten ist es, Umleitungen zu verbieten und nur Cmdlets oder .NET-APIs verwenden zu lassen, die ein Encoding angeben können.

3.5 Nach dem Speichern erneut einlesen und repräsentative japanische Zeilen prüfen lassen

„Das Speichern hat funktioniert“ und „es ist nicht kaputt“ sind nicht dasselbe.

Wichtig ist, nach dem Speichern repräsentative japanische Zeilen erneut lesen zu lassen und Folgendes zu prüfen.

• Ist kein Ersatzzeichen U+FFFD hineingeraten?
• Hat sich ? nicht unnatürlich vermehrt?
• Ist der Diff nicht ein riesiger, nur aus BOM- oder Zeilenumbruch-Änderungen bestehender Diff?
• Ist japanischer Text, der geschäftlich nicht geändert werden sollte, unverändert erhalten geblieben?

3.6 Zeigen sich Anomalien, erst berichten lassen, bevor korrigiert wird

Bei Zeichenkodierungs-Unfällen lässt sich der Schaden eher begrenzen, indem man Codex anhalten und berichten lässt, statt es gewaltsam korrigieren zu lassen.

Zeigen sich zum Beispiel diese Anzeichen, ist es sicherer, die Situation vorerst als Anomalie zu behandeln.

• Zunahme von U+FFFD
• Zunahme von ?
• unerwartete BOM-Änderung
• ein großer, nur aus Zeilenumbrüchen bestehender Diff
• nur die japanischen Zeilen ändern sich unnatürlich stark

4. Als kurzer Anweisungstext

Für eine kurze Version, die man jeder Aufgabe beifügt, reicht schon so viel aus.

Vermeiden Sie bei dieser Aufgabe Zeichenkodierungs-Unfälle mit höchster Priorität.

- Bei bestehenden Dateien mit japanischem Text vor dem Lesen die Encoding-Kandidaten, das Vorhandensein eines BOM und den Zeilenumbruch-Stil prüfen
- Dateien, bei denen Mojibake vermutet wird, nicht auf Verdacht speichern
- Bei bestehenden Dateien das ursprüngliche Encoding / BOM / die Zeilenumbrüche beibehalten
- Neue Dateien gemäß Repo-Konvention als UTF-8-Variante anlegen
- Beim Schreiben nur Methoden verwenden, die das Encoding explizit angeben können
- Nach dem Speichern erneut einlesen und bestätigen, dass repräsentative japanische Zeilen nicht beschädigt sind
- Eine Zunahme von `U+FFFD` oder `?`, BOM-/Zeilenumbruch-Unfälle oder große Diffs als Anomalie melden

Stehen die betroffenen Dateien bereits fest, stabilisiert diese eine zusätzliche Zeile die Sache erheblich.

Betroffene Dateien: <paths> / Repräsentative Zeichenfolgen: "<examples>"

Repräsentative Zeichenfolgen zu übergeben ist sehr wirkungsvoll. Dadurch erhält Codex einen konkreten Beobachtungspunkt: „dieser japanische Text darf nicht kaputtgehen.“

5. Eine Vorlage, die dauerhaft in AGENTS.md stehen sollte

Statt denselben Hinweis immer wieder zu wiederholen, ist es besser, ihn in AGENTS.md aufzunehmen. Im Folgenden eine praxisnahe Vorlage für Repositorys, die unter Windows japanische Dateien handhaben.

# 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

Der Vorteil dieser Vorlage ist, dass sie nicht nur wie bearbeitet wird, sondern auch wie nichts kaputtgeht festschreibt. Besonders diese beiden Zeilen

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

leisten viel.

5.1 Japanische Version der Vorlage

Läuft die Review im Team auf Japanisch ab, lässt sich AGENTS.md mitunter leichter betreiben, wenn es ebenfalls auf Japanisch verfasst ist. Der Inhalt ist derselbe – hier dieselbe Vorlage auf Japanisch:

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

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

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

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

Es genügt, sich für eine der beiden Sprachen zu entscheiden. Beide gleichzeitig zu hinterlegen verbraucht die doppelte Textmenge, und angesichts der Obergrenze für die eingelesene Größe von AGENTS.md ist es sicherer, sich auf eine festzulegen.

6. Schlechte und gute Anweisungen

Bei der Mojibake-Vermeidung entscheidet die Granularität der Anweisung stark über das Ergebnis.

Entscheidend ist, immer die Prüfung vor dem Handeln und die Verifikation nach dem Speichern mit anzugeben.

7. Checkliste für das Review

Nachdem Codex die Arbeit erledigt hat, wird es noch stabiler, wenn man auch die Prüfpunkte auf menschlicher Seite festlegt.

• Ist für jede geänderte Datei der Umgang mit Encoding / BOM / Zeilenumbrüchen berichtet worden?
• Haben sich nur die japanischen Zeilen unnatürlich stark verändert?
• Gibt es keine großen, nur aus Zeilenumbrüchen bestehenden Diffs?
• Haben U+FFFD oder ? nicht zugenommen?
• Gibt es keine geschäftlich unbegründeten Diffs über die ganze Datei?
• Sind bei CSV oder Logs keine Spalten- oder Anführungszeichen-Verschiebungen aufgetreten?

Bei der Mojibake-Vermeidung zählt vor allem, verdächtige Diffs früh zu stoppen, statt möglichst viele erfolgreiche Diffs anzuhäufen.

8. Zusammenfassung

Wenn Codex unter Windows japanische Dateien handhaben soll, hilft am Anfang weniger, die PC-Seite perfekt anzugleichen, als vielmehr Codex den Arbeitsablauf für Zeichenkodierung explizit mitzuteilen.

Fünf Punkte sind besonders wichtig.

• Vor dem Lesen Encoding / BOM / Zeilenumbrüche prüfen lassen
• Bei Verdacht auf Mojibake nicht auf Verdacht speichern lassen
• Bestehende Dateien beibehalten, nur neue Dateien auf UTF-8-Varianten ausrichten
• Mehrdeutige Schreibpfade verbieten
• Nach dem Speichern erneut einlesen und repräsentative japanische Zeilen prüfen lassen

Und statt es jedes Mal zu sagen: in AGENTS.md aufnehmen. Das ist am praxistauglichsten.

Der Kern der Mojibake-Vermeidung liegt nicht darin, zu bitten, „mit Japanisch ordentlich umzugehen“, sondern darin, schriftlich festzulegen, unter welchen Bedingungen gespeichert werden darf und unter welchen Bedingungen anzuhalten ist. Ist das einmal so festgehalten, wird Codex auch unter Windows deutlich einfacher zu handhaben.

9. Quellen

• 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

Verwandte Artikel

Aktuelle Artikel mit denselben Schlagwörtern führen zu verwandten Themen weiter.

Verwandte Themen

Diese Seiten ordnen den Artikel in einen größeren Leistungs- und Entscheidungskontext ein.

Leistungen zu diesem Thema

Dieser Artikel ist direkt mit den folgenden Leistungen verbunden.

Häufige Fragen

Fragen, die in Beratungen zu diesem Artikelthema häufig gestellt werden.

Warum kommt es unter Windows bei der Nutzung von Codex zu Mojibake bei japanischem Text?

Die eigentliche Ursache ist nicht, dass Codex schlecht mit Japanisch umgehen kann, sondern dass auf der Windows-Seite mehrere Zeichenkodierungen – UTF-8, CP932, UTF-16-Varianten – und mehrere Schreibpfade nebeneinander existieren. Interpretiert Codex in diesem Zustand auch nur einmal falsch, kann es mit einer Zeichenkette, die es gar nicht richtig gelesen hat, so weiterarbeiten, als hätte es sie gelesen. Speichert man dann ab, wird daraus kein Anzeigeproblem mehr, sondern eine dauerhafte Beschädigung der Datei selbst. Deshalb läuft Mojibake-Vermeidung letztlich darauf hinaus, wie man den I/O-Ablauf steuert.

Welche Anweisungen verhindern Mojibake-Probleme bei Codex?

Am wirksamsten ist es, den Arbeitsablauf für Zeichenkodierung vorab festzulegen. Konkret sind das fünf Punkte: bei bestehenden Dateien mit japanischem Text vor dem Lesen die Encoding-Kandidaten, das Vorhandensein eines BOM und den Zeilenumbruch-Stil prüfen lassen; Dateien, bei denen Mojibake vermutet wird, erst speichern lassen, wenn Sicherheit besteht; bei bestehenden Dateien das ursprüngliche Encoding beibehalten und nur neue Dateien auf UTF-8-Varianten ausrichten; beim Schreiben nur Methoden verwenden lassen, die das Encoding explizit angeben können; und nach dem Speichern erneut einlesen lassen, um repräsentative japanische Zeilen zu prüfen. Übergibt man zusätzlich die betroffenen Dateien und „repräsentative Zeichenfolgen, die nicht kaputtgehen dürfen“, wird es noch stabiler.

Darf man nicht einfach anweisen „Behebe das Mojibake“ oder „Mach alles zu UTF-8“?

Beide Anweisungen sind riskant. Es steht nirgends geschrieben, an welcher Stelle Codex das Speichern stoppen sollte, wodurch leicht auf Verdacht gespeichert und der Unfall damit festgeschrieben wird. „Alles zu UTF-8“ ist besonders gefährlich: Bei der Bearbeitung bestehender Dateien sollte man das ursprüngliche Encoding, BOM und die Zeilenumbrüche beibehalten lassen, und eine Umstellung des gesamten Repositorys auf UTF-8 sicherer als separate Aufgabe herausziehen, bei der man Diff und Auswirkungsbereich im Blick behält. Stattdessen formuliert man Anweisungen wie „Trenne, ob es sich um eine Beschädigung oder nur ein Anzeigeproblem handelt, und speichere nicht auf Verdacht“ – inklusive der Prüfung vor dem Handeln und der Verifikation nach dem Speichern.

Sollte man die Regeln zur Zeichenkodierung in AGENTS.md schreiben?

Wenn man denselben Hinweis bei jeder Aufgabe wiederholen müsste, ist es wirkungsvoller, ihn dauerhaft in AGENTS.md festzuhalten. Man schreibt dort gesammelt die Prüfung von Encoding, BOM und Zeilenumbrüchen vor dem Lesen, das Speicherverbot, solange Mojibake vermutet wird, die Beibehaltung bestehender Dateien, das Auslagern der UTF-8-Umstellung als eigene Aufgabe, das Verbot mehrdeutiger Schreibpfade, die erneute Verifikation nach dem Speichern durch erneutes Einlesen sowie die Regel, bei Auffälligkeiten anzuhalten und zu berichten. Legt man zusätzlich ein Format fest, in dem für jede geänderte Datei Encoding, BOM, Zeilenumbruch und Prüfmethode berichtet werden, wird auch die Prüfung im Review stabiler.

Autorenprofil

Profilseite des Artikelautors.

Go Komura

Geschäftsführer von KomuraSoft LLC

Spezialisiert auf Windows-Softwareentwicklung, technische Beratung und Fehleranalyse, insbesondere bei bestehenden Systemen und schwer reproduzierbaren Störungen.