Regole di prompting che riducono gli incidenti di mojibake di Codex su Windows

Quando fai lavorare Codex con file contenenti testo giapponese su Windows, la prima cosa che aiuta davvero non è allineare ogni editor e impostazione della shell — è dire esplicitamente a Codex come leggere, come scrivere e dove fermarsi.

Le situazioni che causano più problemi sono queste.

• Coesistono file UTF-8, CP932 e UTF-16
• Il testo sembra leggibile a schermo, ma l’interpretazione dei byte reali è sbagliata
• Volevi solo modificare un file esistente, ma viene risalvato con un encoding diverso
• La rottura avviene in file “non di codice”: CSV, TXT, log, Markdown, file di configurazione
• Uno script usa-e-getta o un output shell vengono salvati così com’è, e l’incidente diventa permanente

OpenAI Codex è più stabile quando lo tratti meno come un partner chat una-tantum e più come un compagno di squadra che usi continuamente, con impostazioni e regole di lavoro. In particolare, se il tuo flusso fa sì che Codex legga AGENTS.md, le regole di encoding appartengono lì in modo permanente invece di essere ripetute verbalmente ogni volta.

In questo articolo organizziamo, dal punto di vista di chi pratica, le istruzioni più efficaci da dare a Codex in anticipo perché gestisca in sicurezza file giapponesi su Windows.

1. La conclusione prima di tutto

Il modo singolarmente più efficace per ridurre gli incidenti di mojibake di Codex su Windows è fissare in anticipo la procedura di lavoro dell’encoding.

Queste sono le regole che aiutano di più.

• Per file esistenti con testo giapponese, far controllare l’encoding probabile, la presenza di BOM e lo stile dei newline prima della lettura
• Per file in cui si sospetta mojibake, non permettere di salvare finché non è confidente
• Per file esistenti, far preservare l’encoding, il BOM e i newline originali
• Per nuovi file, spingere verso UTF-8 secondo la convenzione del repository
• Per le scritture, permettere solo metodi in cui l’encoding può essere reso esplicito
• Dopo il salvataggio, far rileggere il file e verificare le righe giapponesi rappresentative

In forma breve quotidiana, si riduce a questo.

• Controlla prima di leggere
• Nessun salvataggio in caso di dubbio
• Preserva i file esistenti; UTF-8 solo per i nuovi
• Bandisci percorsi di scrittura ambigui
• Rileggi e verifica alla fine

Viceversa, queste sono le istruzioni pericolose.

• “Fix the mojibake”
• “Convert everything to UTF-8”
• “Output a CSV”
• “Just make it match”
• “Save it for now and let’s see”

Nessuna di queste dice a quale punto Codex dovrebbe fermarsi. Per prevenire il mojibake devi specificare non solo cosa fare, ma anche dove fermarsi prima di salvare.

2. Perché gli incidenti di mojibake sono così comuni su Windows

Il problema reale non è che Codex sia debole in giapponese — è che sul lato degli asset Windows coesistono più encoding e più percorsi di scrittura.

In pratica, questa mescolanza non è insolita.

• Fonti più recenti e Markdown sono UTF-8
• CSV, TXT, log e configurazioni più vecchi sono in famiglia CP932
• Alcuni output e artefatti generati da strumenti sono in famiglia UTF-16
• I percorsi di salvataggio variano tra editor, shell e output derivati da Excel
• Anche i newline sono misti tra LF e CRLF

In questo stato, se Codex interpreta male i byte anche una volta, può procedere alla modifica successiva trattando stringhe che non è riuscito a leggere come se le avesse lette correttamente. E se poi salva, il problema non è più un problema di visualizzazione — diventa corruzione fissa del file stesso.

Ecco perché la prevenzione del mojibake si riduce in definitiva a come gestisci la procedura di I/O.

3. Le regole che vuoi fissare per Codex per prime

3.1 Fargli controllare l’encoding probabile, il BOM e i newline prima della lettura

La prima regola è questa.

Prima di leggere un file esistente che contiene testo giapponese, controlla l’encoding probabile, la presenza di BOM e lo stile dei newline; se qualcosa sembra sospetto, non procedere interpretando il contenuto così com’è.

Il punto è cambiare il flusso di lavoro in “prima di leggere il testo, guarda prima le premesse del file”.

3.2 Non fargli salvare un file con mojibake sospeto basandosi su congetture

Questo è particolarmente importante.

Quando si sospetta mojibake, tratta il file come sola lettura durante l’investigazione e vietane la sovrascrittura finché l’interpretazione dell’encoding non è credibile.

Lo stesso vale per gli umani: non salvare mai un file che non sei riuscito effettivamente a leggere. Salvare con “sembra un po’ rotto, ma probabilmente è così” trasforma quella congettura nella versione confermata dell’incidente.

3.3 Preserva i file esistenti; usa UTF-8 di default solo per i nuovi file

Nel contesto della prevenzione del mojibake, “unifica tutto in UTF-8” è sorprendentemente pericoloso.

Decidere alla fine di spostare l’intero repository in UTF-8 è una scelta legittima, ma è più sicuro farlo come compito separato revisionando il diff e il raggio di esplosione. Per la manutenzione quotidiana, questo flusso è quello stabile.

• Quando si modifica un file esistente, preserva il suo encoding originale
• Quando si aggiunge un file nuovo, crealo come UTF-8 secondo la convenzione del repository
• Se un file esistente deve essere convertito, tieni quell’operazione separata dalle normali correzioni funzionali

3.4 Non fargli usare percorsi di scrittura ambigui di default

Ciò che moltiplica gli incidenti su Windows è “è solo un piccolo output, quindi scrivilo alla buona dalla shell”.

• Scaricare output direttamente tramite ridirezione
• Salvare direttamente con un comando comodo
• Promuovere un artefatto temporaneo direttamente a file di produzione

Questi percorsi spesso non hanno encoding esplicito, e diventano un terreno fertile per incidenti. Quindi è più sicuro fissare anche per Codex la scelta dei meccanismi di scrittura.

3.5 Dopo il salvataggio, fargli rileggere e verificare righe giapponesi rappresentative

“Salvato con successo” e “non è rotto” non sono la stessa cosa.

Ciò che conta è fargli rileggere righe giapponesi rappresentative dopo il salvataggio e controllare punti come questi.

• Non sono entrati caratteri sostitutivi U+FFFD
• Non c’è un aumento innaturale di ?
• Il diff non è un enorme cambiamento solo di BOM o newline
• Il testo giapponese che non doveva cambiare è ancora intatto

3.6 Quando appaiono segnali di allarme, fargli segnalare prima di correggere

Negli incidenti di encoding, limiti i danni meglio facendo fermare e segnalare Codex piuttosto che forzare una correzione.

Ad esempio, se appare uno di questi segni, è più sicuro trattare la situazione come anomala per il momento.

• Aumento di U+FFFD
• Aumento di ?
• Cambiamento inatteso di BOM
• Grande diff solo di newline
• Solo le righe giapponesi cambiano in modo innaturale e sostanziale

4. Come istruzione breve da allegare ai compiti

Se vuoi una versione breve da allegare a ogni compito, questa quantità è già abbastanza efficace.

In questo compito, evitare incidenti di encoding è la priorità assoluta.

- Per i file esistenti con testo giapponese, controlla l'encoding probabile, la presenza di BOM e lo stile dei newline prima di leggere
- Non salvare file con mojibake sospeto basandoti su congetture
- Preserva l'encoding / BOM / newline dei file esistenti
- Crea nuovi file come UTF-8 secondo la convenzione del repository
- Usa solo metodi di scrittura in cui l'encoding può essere reso esplicito
- Dopo il salvataggio, rileggi il file e conferma che le righe giapponesi rappresentative siano intatte
- Segnala come anomalo qualsiasi aumento di `U+FFFD` o `?`, incidenti di BOM / newline, o grandi diff

Se i file target sono già noti, aggiungere questa riga stabilizza molto le cose.

Target files: <paths> / Representative strings: "<examples>"

Fornire stringhe rappresentative è notevolmente efficace. Dà a Codex un punto di controllo concreto: “questo testo giapponese non deve rompersi”.

5. Un template da tenere in AGENTS.md

Invece di ripetere gli stessi avvertimenti, mettili in AGENTS.md. Qui sotto un template pratico per repository che gestiscono file giapponesi su 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

La forza di questo template sta nel fissare non solo come modificare ma come non rompere le cose. In particolare, queste due righe contano molto:

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

6. Istruzioni cattive vs istruzioni buone

Nella prevenzione del mojibake, la granularità delle istruzioni modella fortemente il risultato.

Il punto è scrivere sempre in termini di i controlli prima di toccare e la verifica dopo il salvataggio.

7. Una checklist per il momento della revisione

Dopo che Codex ha fatto il lavoro, fissare i punti di controllo anche dal lato umano rende tutto ancora più stabile.

• L’encoding / BOM / newline è riportato per ogni file modificato?
• Solo le righe giapponesi sono cambiate in modo innaturale e sostanziale?
• Ci sono grandi diff solo di newline?
• U+FFFD o ? sono aumentati?
• Ci sono diff di file interi non collegati alla modifica di business?
• Colonne o virgolette sono rotte in CSV o log?

Ciò che conta nella prevenzione del mojibake è fermare i diff sospetti presto, più che accumulare diff di successo.

8. Riassunto

Quando fai gestire a Codex file giapponesi su Windows, la prima cosa che aiuta non è perfezionare la configurazione della macchina — è dare esplicitamente a Codex la procedura di lavoro dell’encoding.

I cinque punti da ricordare:

• Fagli controllare encoding / BOM / newline prima di leggere
• Se sospetta mojibake, non fargli salvare basandosi su congetture
• Preserva i file esistenti; spingi solo i nuovi file verso UTF-8
• Bandisci percorsi di scrittura ambigui
• Fagli rileggere dopo il salvataggio e verificare righe giapponesi rappresentative

E se ti ritrovi a dirlo ogni volta, mettilo in AGENTS.md. Questa è la mossa più pratica.

Il nucleo della prevenzione del mojibake non è chiedere di “gestire bene il giapponese” — è scrivere le condizioni in cui il salvataggio è permesso e le condizioni in cui deve fermarsi. Una volta che hai quelle per iscritto, lavorare con Codex diventa molto più facile anche su Windows.

9. Riferimenti

• OpenAI Codex docs, Best practices
• OpenAI Codex docs, Custom instructions with AGENTS.md
• OpenAI Codex docs, Windows

Articoli correlati

Articoli recenti con gli stessi tag per approfondire argomenti vicini.

Argomenti correlati

Queste pagine collocano l’argomento in un contesto più ampio di servizi e decisioni.

Servizi collegati all’argomento

L’articolo è direttamente collegato ai servizi seguenti.

Domande frequenti

Domande che ricorrono nelle consulenze sull’argomento dell’articolo.

Perché Codex corrompe testo giapponese su Windows?

La causa radice di solito non è che Codex sia debole in giapponese, ma che gli asset Windows mescolino più encoding e percorsi di scrittura. Fonti più recenti e Markdown tendono a essere UTF-8, mentre CSV, TXT, log e configurazioni più vecchi sono in famiglia CP932, con alcuni artefatti UTF-16 e newline misti LF/CRLF. Se Codex interpreta i byte anche una sola volta in modo sbagliato e poi salva, il problema cessa di essere un problema di visualizzazione e diventa corruzione permanente del file stesso. Ecco perché la prevenzione si riduce alla gestione della procedura di I/O.

Quali regole di prompting prevengono gli incidenti di mojibake con strumenti di AI coding?

Cinque regole fanno la maggior parte del lavoro: far controllare allo strumento l'encoding probabile, la presenza di BOM e lo stile dei newline prima di leggere qualsiasi file esistente con testo giapponese; vietare di salvare un file con mojibake sospetto basandosi su congetture; preservare l'encoding, il BOM e i newline originali dei file esistenti creando però nuovi file come UTF-8; bandire percorsi di scrittura ambigui come ridirezioni shell senza encoding esplicito; e rileggere il file dopo il salvataggio per verificare che le righe giapponesi rappresentative siano intatte.

Perché dire a un'AI di convertire tutto in UTF-8 è pericoloso?

Perché nella manutenzione quotidiana ricodifica silenziosamente file che altri strumenti e flussi di lavoro si aspettano ancora nel loro encoding originale. Spostare tutto un repository in UTF-8 può essere una decisione legittima, ma è più sicuro farlo come compito separato ed esplicito in cui si revisiona il diff e il raggio di esplosione. Quotidianamente, il flusso stabile è preservare l'encoding originale quando si modificano file esistenti e usare UTF-8 solo per i file nuovi.

Dove dovrebbero essere scritte le regole di encoding per Codex?

Se il tuo flusso di lavoro fa sì che Codex legga AGENTS.md, le regole di encoding appartengono lì in modo permanente invece di essere ripetute verbalmente ad ogni sessione. Le regole dovrebbero coprire il controllo di encoding, BOM e newline prima della lettura, il divieto di salvataggio quando si sospetta mojibake, la preservazione dei file esistenti, l'uso solo di metodi di scrittura con encoding esplicito, e la segnalazione di segnali di allarme come caratteri sostitutivi o cambi inattesi di BOM. Per compiti individuali, aggiungere i percorsi dei file target e le stringhe giapponesi rappresentative da monitorare è notevolmente efficace.

Profilo dell’autore

Pagina di presentazione dell’autore dell’articolo.

Go Komura

Rappresentante di KomuraSoft LLC

Specializzato nello sviluppo di software Windows, nella consulenza tecnica e nell’analisi dei malfunzionamenti, soprattutto nei progetti con sistemi esistenti e guasti difficili da riprodurre.