Reglas de instrucción para reducir los errores de mojibake de Codex en Windows

Cuando se hace que Codex maneje en Windows archivos que contienen japonés, lo primero que realmente funciona no es alinear toda la configuración del editor o del shell, sino indicarle explícitamente a Codex «cómo leer, cómo escribir y dónde detenerse».

Las situaciones que suelen causar más problemas son las siguientes.

• Coexisten archivos en UTF-8, CP932 y variantes de UTF-16.
• El texto parece legible a simple vista, pero la interpretación real de los bytes está desalineada.
• Se pretendía hacer un ajuste menor a un archivo existente, pero al guardar se reescribe con un encoding distinto.
• Se dañan archivos «que no son código», como CSV, TXT, registros, Markdown o archivos de configuración.
• Se guarda tal cual la salida de un script temporal o del shell, y el error queda fijado de forma permanente.

Codex, de OpenAI, tiende a ser más estable si se lo trata no como un interlocutor de chat puntual, sino como un compañero de equipo al que se le dan configuraciones y reglas de trabajo para usar de forma continua. En particular, si existe la práctica de hacerle leer AGENTS.md, las reglas relativas a la codificación de caracteres funcionan mejor si se dejan establecidas de forma permanente, en lugar de repetirlas verbalmente cada vez.

En este artículo se organizan, con un enfoque práctico, las instrucciones que conviene dar desde el principio para que Codex maneje de forma segura archivos japoneses en Windows.

Antecedentes: el Codex y el AGENTS.md que asume este artículo

Para quienes no usan Codex, primero se explican solo los antecedentes.

Codex es un agente de codificación que lee y escribe realmente los archivos de un repositorio. Tiene varios puntos de entrada: una CLI que se ejecuta en la terminal local, una extensión de editor, o una versión que funciona en la nube. Sin embargo, este artículo asume el uso en el que se le hace editar directamente los archivos del repositorio local. Los errores de mojibake ocurren en el momento de «editar y guardar», así que lo esencial no es tanto qué punto de entrada se use, sino cómo se restringe la ruta de escritura hacia los archivos.

AGENTS.md es un archivo Markdown donde se escriben las instrucciones permanentes para trabajar en ese repositorio. La forma en que se carga tiene algunas propiedades que conviene recordar.

• No está en un único lugar. Se leen tanto la configuración global, como ~/.codex/AGENTS.md en el directorio personal, como el AGENTS.md del propio repositorio.
• Se concatenan en orden, desde la raíz del repositorio hacia el directorio de trabajo. Es decir, el AGENTS.md colocado en un subdirectorio se concatena después, por lo que tiene más peso que las instrucciones de niveles superiores.
• El tamaño total tiene un límite. Por defecto se corta alrededor de 32 KiB, así que si se intenta «escribirlo todo por si acaso», la parte final se pierde. Es más seguro colocar las reglas de codificación de caracteres de forma breve y en un nivel superior.

Por estos tres motivos, en la práctica conviene escribir las normas de codificación de caracteres de forma breve y cerca del principio del AGENTS.md de la raíz del repositorio. Si un subdirectorio tiene otra norma de escritura distinta, esa es la que prevalece.

1. Conclusión primero

Lo que más ayuda a reducir los errores de mojibake de Codex en entornos Windows es fijar de antemano el procedimiento de trabajo con la codificación de caracteres.

Las reglas que más funcionan son estas.

• Para los archivos existentes que contienen japonés, hacer que se confirmen los candidatos de encoding, la presencia de BOM y el tipo de salto de línea antes de leerlos.
• En los archivos donde se sospecha mojibake, no permitir que se guarden hasta tener certeza.
• En los archivos existentes, hacer que se mantengan el encoding, el BOM y el salto de línea originales.
• En los archivos nuevos, hacer que se orienten hacia UTF-8 siguiendo las normas del repositorio.
• Para la escritura, hacer que se use únicamente métodos donde se pueda especificar explícitamente el encoding.
• Después de guardar, hacer que se relea el archivo y se verifiquen líneas representativas en japonés.

En una versión breve para el trabajo diario, se reduce casi a esto.

• Confirmar antes de leer
• Si hay dudas, prohibido guardar
• Mantener lo existente, solo lo nuevo en UTF-8
• Prohibir rutas de escritura ambiguas
• Al final, releer para confirmar

En cambio, las instrucciones peligrosas son de este tipo.

• «Corrige el mojibake»
• «Pon todo en UTF-8»
• «Genera el CSV»
• «Ajústalo como te parezca»
• «Guárdalo y échale un vistazo»

Ninguna de estas instrucciones especifica en qué etapa debe detenerse Codex. En las medidas contra el mojibake, no basta con indicar qué hacer: también es necesario indicar dónde detener el guardado.

2. Por qué los errores de mojibake son frecuentes en Windows

El verdadero problema no es que Codex sea débil con el japonés, sino que en los activos de Windows coexisten múltiples codificaciones de caracteres y múltiples rutas de escritura.

En la práctica, esta mezcla no es rara.

• El código fuente más reciente y los archivos Markdown suelen estar en UTF-8.
• Los CSV, TXT, registros y archivos de configuración antiguos suelen estar en variantes de CP932.
• Algunas salidas y archivos generados por herramientas están en variantes de UTF-16.
• Las rutas de guardado varían según provengan del editor, del shell o de Excel.
• También se mezclan los saltos de línea LF y CRLF.

En este estado, basta con que Codex haga una interpretación errónea una sola vez para que trate una cadena que en realidad no puede leer como si la hubiera leído correctamente y continúe con la siguiente edición. Y si se guarda tal cual, el problema deja de ser de visualización y queda fijado como una corrupción del propio archivo.

Por eso, en última instancia, las medidas contra el mojibake se reducen a cómo se gestiona el procedimiento de E/S.

2.1 Antes que nada, cuatro términos

Aquí se reúnen los términos que aparecerán repetidamente más adelante.

Lo importante es que ni CP932 ni UTF-8 quedan registrados dentro del propio archivo. A menos que haya un BOM, el archivo no declara por sí mismo «cómo se debe leer». Por eso hace falta confirmarlo antes de leer.

3. Las reglas que conviene fijar primero para Codex

3.1 Antes de leer, hacer que se confirmen los candidatos de encoding, el BOM y el salto de línea

La primera regla es esta.

Antes de leer un archivo existente que contenga japonés, confirme los candidatos de encoding actuales, la presencia de BOM y el tipo de salto de línea; si algo resulta dudoso, no avance directamente a interpretar el contenido.

El punto clave es cambiar el enfoque a «antes de leer el texto, primero observar las premisas del archivo».

Cómo hacer que se confirme, en concreto

Si solo se escribe «confírmalo», tanto Codex como una persona pueden variar en la forma de hacerlo. Es más estable incorporar el propio procedimiento de verificación en la instrucción. A continuación se muestra una forma que funciona tanto en Windows PowerShell 5.1 como en PowerShell 7.

Primero, se observan los bytes iniciales en hexadecimal. Aquí se determina la presencia o ausencia de BOM.

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

# Mostrar los primeros 16 bytes en hexadecimal
$head = $bytes[0..([Math]::Min(15, $bytes.Length - 1))]
($head | ForEach-Object { $_.ToString('X2') }) -join ' '

Los siguientes bloques usan tal cual los $path y $bytes creados aquí. Así se interpreta el resultado.

A continuación, se cuentan los saltos de línea. Aquí se detecta si «se mezclan LF y 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"

Por último, se acotan los candidatos de encoding. Cuando no hay BOM, el criterio más rápido es si el archivo se puede decodificar de forma estricta como UTF-8. UTF-8 impone restricciones estrictas sobre la secuencia de bytes, así que al intentar leer de forma estricta como UTF-8 un archivo en CP932, normalmente falla a mitad de camino.

# El segundo argumento $true indica «lanzar una excepción si la secuencia de bytes es inválida»
$strictUtf8 = New-Object System.Text.UTF8Encoding($false, $true)
try {
    $null = $strictUtf8.GetString($bytes)
    'Se pudo decodificar como UTF-8 sin inconsistencias'
}
catch {
    'No es UTF-8. Pruebe con candidatos como CP932'
}

Al intentar leer con CP932, se especifica explícitamente el número de página de códigos.

# En PowerShell 6.2 y versiones posteriores, se puede indicar el número de página de códigos directamente
Get-Content -Path $path -Encoding 932 -TotalCount 3

# En Windows PowerShell 5.1, Default es la página de códigos ANSI del sistema. En un Windows en japonés, es CP932
Get-Content -Path $path -Encoding Default -TotalCount 3

Que la decodificación estricta funcione no significa «confirmado como UTF-8». Un archivo que solo contiene ASCII pasa la prueba en ambos casos. Al final, haga que se confirme visualmente si las líneas representativas en japonés se leen correctamente.

3.2 No permitir que se guarden por suposición los archivos donde se sospecha mojibake

Esto es especialmente importante.

Cuando se sospecha mojibake, mantenga el archivo en modo de solo lectura durante la fase de investigación y prohíba sobrescribirlo hasta tener confianza en la interpretación.

Esto vale igual para las personas: no se debe guardar un archivo que no se ha podido leer correctamente. Si se guarda pensando «se ve un poco raro, pero probablemente sea esto», ese guardado se convierte en la versión definitiva del error.

3.3 Mantener los archivos existentes y usar UTF-8 como base solo para los nuevos

En el contexto de las medidas contra el mojibake, sorprendentemente peligrosa es la instrucción «unifica todo a UTF-8».

Puede tener sentido, a la larga, decidir migrar todo el repositorio a UTF-8, pero es más seguro tratarlo como una tarea separada, avanzando mientras se observan el diff y el alcance del impacto. Para las modificaciones del día a día, esta forma de operar resulta estable.

• Al editar un archivo existente, mantener el encoding original.
• Al añadir un archivo nuevo, crearlo en una variante de UTF-8 siguiendo las normas del repositorio.
• Si es necesario convertir un archivo existente, separarlo de las modificaciones de funcionalidad habituales.

3.4 No usar por defecto rutas de escritura ambiguas

En Windows, lo que suele aumentar los errores es «como es una salida menor, se escribe de forma descuidada desde el shell».

• Volcar la salida directamente mediante redirección.
• Guardar tal cual con un comando de conveniencia.
• Promover directamente un artefacto temporal a archivo de producción.

Estas rutas, en muchos casos, no especifican explícitamente el encoding, y se convierten en un caldo de cultivo para los errores. Por eso es más seguro fijar de antemano, también para Codex, cómo elegir el método de escritura.

El «encoding por defecto» varía según la versión de PowerShell

Si no se conoce este punto, es casi seguro que se cae en la trampa. En PowerShell, el encoding de escritura por defecto difiere según la versión.

Es decir, incluso con el mismo script, se genera un archivo distinto según se haya ejecutado en 5.1 o en 7. Este es el clásico caso de «en la máquina de desarrollo funcionaba bien, pero se dañó en el servidor de producción».

Además, en 5.1 existe también la particularidad de que al especificar un encoding de tipo Unicode, siempre se añade un BOM. -Encoding UTF8 produce UTF-8 con BOM.

Por eso, hay que hacer que el encoding se especifique explícitamente cada vez que se escribe.

# Se definen las variables para que este apartado quede completo por sí solo
$path    = 'C:\work\orders.csv'
$newPath = 'C:\work\orders-new.csv'
$lines   = @('顧客コード,顧客名', 'C0001,株式会社サンプル')

# Si el archivo existente está en CP932, volver a escribirlo en CP932 (PowerShell 6.2 y versiones posteriores)
Set-Content -Path $path -Value $lines -Encoding 932

# En Windows PowerShell 5.1, ajustarse a la página de códigos ANSI del sistema
Set-Content -Path $path -Value $lines -Encoding Default

# Crear un archivo nuevo en UTF-8 sin BOM (PowerShell 7)
Set-Content -Path $newPath -Value $lines -Encoding utf8NoBOM

Si se quiere alinear el valor por defecto para toda la sesión, también existe la opción de usar $PSDefaultParameterValues. Sin embargo, esto es una configuración exclusiva de esa sesión, así que un procedimiento que dé por sentado «está escrito en mi perfil» se rompe en el entorno de otra persona.

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

La forma de escribir que usa > en lugar de Out-File tampoco escapa al problema, porque desde 5.1 en adelante internamente solo llama a Out-File, así que el encoding por defecto arrastra el mismo problema. Lo más seguro es prohibir la redirección y hacer que solo se usen cmdlets o APIs .NET donde se pueda especificar el encoding.

3.5 Después de guardar, releer y confirmar las líneas representativas en japonés

«Se pudo guardar» y «no está dañado» no son lo mismo.

Lo importante es hacer que, después de guardar, se vuelvan a leer las líneas japonesas representativas y se confirmen estos puntos.

• Si se ha introducido el carácter de reemplazo U+FFFD.
• Si el número de ? ha aumentado de forma anómala.
• Si el diff se ha vuelto enorme únicamente por el BOM o los saltos de línea.
• Si el japonés que no se pretendía cambiar por motivos de negocio permanece intacto.

3.6 Si aparecen indicios anómalos, hacer que se reporte antes de intentar corregir

En los errores de codificación de caracteres, en lugar de forzar una corrección, hacer que se detenga y reporte permite reducir el daño.

Por ejemplo, si aparecen indicios como estos, es más seguro tratarlos de inmediato como una anomalía.

• Aumento de U+FFFD.
• Aumento de ?.
• Cambio inesperado del BOM.
• Un diff masivo compuesto solo por saltos de línea.
• Cambios anómalamente grandes solo en las líneas japonesas.

4. Si se entrega como un texto de instrucción breve

Para una versión breve que acompañe cada tarea, con esto es suficiente.

En este trabajo, evite los errores de codificación de caracteres como máxima prioridad.

- Para los archivos existentes que contienen japonés, confirme los candidatos de encoding, la presencia de BOM y el tipo de salto de línea antes de leerlos.
- No guarde por suposición un archivo donde se sospeche mojibake.
- Mantenga el encoding, el BOM y el salto de línea originales en los archivos existentes.
- Cree los archivos nuevos en una variante de UTF-8, siguiendo las normas del repositorio.
- Para escribir, use únicamente métodos donde se pueda especificar explícitamente el encoding.
- Después de guardar, relea el archivo y confirme que las líneas representativas en japonés no están dañadas.
- Si aumenta `U+FFFD` o `?`, si hay un incidente de BOM o de salto de línea, o si aparece un diff masivo, repórtelo como una anomalía.

Además, si ya se sabe cuáles son los archivos objetivo, añadir esta línea aporta bastante estabilidad.

Archivos objetivo: <paths> / Cadenas representativas: "<examples>"

Pasar cadenas representativas funciona bastante bien, porque le da a Codex un punto de vigilancia concreto: «este japonés no debe dañarse».

5. Plantilla para dejar establecida de forma permanente en AGENTS.md

En lugar de repetir el mismo aviso una y otra vez, es mejor incluirlo en AGENTS.md. A continuación, una plantilla orientada a la práctica para repositorios que manejan archivos japoneses en 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

Lo bueno de esta plantilla es que permite fijar no solo cómo editar, sino también cómo no romper. En particular,

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

estas dos líneas son bastante efectivas.

5.1 Plantilla en japonés

Si las revisiones del equipo se hacen en japonés, a veces resulta más manejable que AGENTS.md también esté en japonés. El contenido es el mismo.

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

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

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

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

Basta con quedarse con una de las dos versiones, la inglesa o la japonesa. Si se colocan ambas, se consume el doble de espacio, así que, teniendo en cuenta el límite de tamaño de carga de AGENTS.md, es más seguro decidirse por una sola.

6. Instrucciones incorrectas e instrucciones correctas

En las medidas contra el mojibake, el nivel de detalle de la instrucción influye bastante en el resultado.

El punto clave es escribir siempre la verificación antes de actuar y la comprobación después de guardar.

7. Lista de verificación para la revisión

Fijar también los puntos que debe revisar una persona después de que Codex haga el trabajo aporta más estabilidad.

• Si se ha reportado el tratamiento de encoding, BOM y salto de línea para cada archivo modificado.
• Si solo las líneas japonesas han cambiado de forma anómalamente grande.
• Si ha aparecido una gran cantidad de diffs formados únicamente por saltos de línea.
• Si ha aumentado el número de U+FFFD o de ?.
• Si existe algún diff global que no tenga relación con el cambio de negocio.
• Si se han producido desalineaciones de columnas o de comillas en CSV o en registros.

Lo importante en las medidas contra el mojibake es detener pronto los diffs sospechosos, más que aumentar los diffs exitosos.

8. Resumen

Cuando se hace que Codex maneje archivos japoneses en un entorno Windows, lo que más funciona desde el principio no es dejar perfectamente configurado el lado del PC, sino indicarle explícitamente a Codex el procedimiento de trabajo con la codificación de caracteres.

Hay cinco puntos que conviene recordar especialmente.

• Hacer que se confirme el encoding, el BOM y el salto de línea antes de leer.
• Si se sospecha mojibake, no permitir que se guarde por suposición.
• Mantener los archivos existentes y orientar hacia UTF-8 solo los nuevos.
• Prohibir las rutas de escritura ambiguas.
• Después de guardar, hacer que se relea y se confirmen las líneas representativas en japonés.

Y, en lugar de repetirlo cada vez, incluirlo en AGENTS.md. Esto es lo más práctico.

El núcleo de las medidas contra el mojibake no está en pedir «trata bien el japonés», sino en dejar por escrito las condiciones bajo las cuales está permitido guardar y las condiciones bajo las cuales se debe detener. Si se llega a escribir hasta ese nivel, Codex se vuelve bastante más manejable incluso en Windows.

9. Referencias

• 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

Artículos relacionados

Artículos recientes con las mismas etiquetas para profundizar en temas cercanos.

Temas relacionados

Estas páginas sitúan el tema en un contexto más amplio de servicios y decisiones.

Servicios relacionados con este tema

El artículo está directamente relacionado con los siguientes servicios.

Preguntas frecuentes

Preguntas habituales en las consultas sobre el tema del artículo.

¿Por qué se produce mojibake en japonés al usar Codex en Windows?

La verdadera causa no es que Codex sea débil con el japonés, sino que, del lado de los activos de Windows, coexisten varias codificaciones de caracteres —UTF-8, CP932, variantes de UTF-16— y varias rutas de escritura. En este estado, basta con que Codex haga una interpretación errónea una sola vez para que continúe la siguiente edición tratando una cadena que en realidad no puede leer como si la hubiera leído correctamente. Y si se guarda tal cual, el problema deja de ser de visualización y queda fijado como una corrupción del propio archivo. Por eso, las medidas contra el mojibake se reducen, en el fondo, a cómo se gestiona el procedimiento de E/S.

¿Qué instrucciones hay que dar para evitar el mojibake de Codex?

Lo más efectivo es fijar de antemano el procedimiento de trabajo con la codificación de caracteres. En concreto, son cinco puntos: hacer que se confirmen los candidatos de encoding, la presencia de BOM y el tipo de salto de línea antes de leer un archivo existente que contenga japonés; no permitir que se guarde un archivo donde se sospeche mojibake hasta tener confianza; mantener el encoding original en los archivos existentes y orientar hacia UTF-8 solo los nuevos; usar únicamente métodos de escritura donde se pueda especificar explícitamente el encoding; y, después de guardar, releer el archivo y verificar las líneas representativas en japonés. Si además se indican los archivos objetivo y las «cadenas representativas que no deben dañarse», el resultado es todavía más estable.

¿No se debe instruir con «corrige el mojibake» o «pon todo en UTF-8»?

Ambas instrucciones son peligrosas. No especifican en qué etapa debe detenerse Codex antes de guardar, por lo que es fácil que el guardado se produzca por suposición y el error quede fijado. «Pon todo en UTF-8» es especialmente arriesgado: en la edición de archivos existentes conviene mantener el encoding, el BOM y el salto de línea originales, y tratar la migración de todo el repositorio a UTF-8 como una tarea separada que avance observando el diff y el alcance del impacto. En su lugar, conviene instruir algo como «determina si se trata de una corrupción real o solo de un problema de visualización, y no guardes por suposición», incluyendo tanto la verificación previa como la comprobación posterior al guardado.

¿Conviene escribir las reglas de codificación de caracteres en AGENTS.md?

Si se va a repetir el mismo aviso en cada tarea, es más efectivo dejarlo establecido de forma permanente en AGENTS.md. Conviene reunir ahí la confirmación de encoding, BOM y salto de línea antes de leer, la prohibición de guardar mientras se sospeche mojibake, el mantenimiento de los archivos existentes, la separación de la conversión a UTF-8 como tarea aparte, la prohibición de rutas de escritura ambiguas, la verificación mediante relectura después de guardar, y la regla de detenerse y reportar ante cualquier anomalía. Si además se fija un formato para que, por cada archivo modificado, se reporten el encoding, el BOM, el salto de línea y el método de verificación, la revisión por parte de las personas también se vuelve más estable.

Perfil del autor

Página de presentación del autor del artículo.

Go Komura

Representante de KomuraSoft LLC

Especializado en desarrollo de software para Windows, consultoría técnica e investigación de fallos, sobre todo en proyectos con sistemas existentes y errores difíciles de reproducir.