Windows에서 Codex의 문자 깨짐 사고를 줄이는 지시 규칙

Windows에서 Codex에 일본어를 포함한 파일을 다루게 할 때, 먼저 효과가 있는 것은 에디터나 shell 설정을 전부 맞추는 것보다 Codex에 「어떻게 읽고, 어떻게 쓰고, 어디서 멈추는가」를 명시하는 것입니다.

특히 곤란해지기 쉬운 것은 다음과 같은 장면입니다.

• UTF-8, CP932, UTF-16 계열 파일이 혼재한다
• 겉보기에는 읽히는 것처럼 보이지만, 실제 바이트의 해석이 어긋나 있다
• 기존 파일을 조금만 고친 셈인데, 저장 시 다른 encoding으로 다시 저장해 버린다
• CSV, TXT, 로그, Markdown, 설정 파일처럼 「코드 이외」에서 망가진다
• 임시 스크립트나 shell 출력을 그대로 저장해 사고가 고정된다

OpenAI의 Codex는 단발 채팅 상대라기보다, 설정과 작업 규칙을 주어 지속적으로 쓰는 팀 메이트에 가까운 형태로 다루는 편이 안정되기 쉽습니다. 특히 AGENTS.md를 읽게 하는 운영이 있다면, 문자 코드에 관한 규칙은 매번 구두로 반복하기보다 상시 두는 편이 효과가 있습니다.

이 글에서는 Windows에서 Codex에 일본어 파일을 안전하게 다루게 하기 위해, 먼저 주면 효과가 있는 지시를 실무용으로 정리합니다.

flowchart TB
    accTitle: 설정보다 먼저 지시를 고정한다
    accDescr: Windows에서 Codex에 일본어 파일을 다루게 할 때, 먼저 효과가 있는 것은 에디터나 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는 홈 쪽과 리포지토리 쪽이 둘 다 읽히고, 루트에서 작업 디렉터리로 향해 연결되어 하위가 강하게 적용되며, 합계 크기는 기본값으로 약 32KiB에서 잘리므로 문자 코드 규약은 루트에 짧게 앞쪽에 쓴다는 것을 나타내는 그림.
    b1["홈 쪽 AGENTS.md"] --> b3["루트에서 작업 디렉터리로 연결"]
    b2["리포지토리 쪽 AGENTS.md"] --> b3
    b3 --> b4["나중에 연결되는 하위가 강하게 적용된다"]
    b3 -.-> b5["기본값으로 약 32KiB에서 자른다"]
    b4 --> b6["규약은 루트에 짧게, 앞쪽으로"]
    b5 -.-> b6

그림 2: AGENTS.md는 연결 순서와 크기 상한이 있으므로, 규약은 루트 위쪽에 짧게 둔다.

1. 먼저 결론

Windows 환경에서 Codex의 문자 깨짐 사고를 줄이는 데 가장 효과가 있는 것은 문자 코드의 작업 절차를 먼저 고정하는 것입니다.

특히 효과가 있는 규칙은 대략 다음입니다.

• 일본어를 포함한 기존 파일은 읽기 전에 encoding 후보, BOM 유무, 개행 코드를 확인시킨다
• 문자 깨짐이 의심스러운 파일은 확신이 들 때까지 저장시키지 않는다
• 기존 파일은 원래의 encoding, BOM, 개행을 유지시킨다
• 신규 파일은 리포지토리 규약에 따라 UTF-8 계열로 맞춘다
• 쓰기는 encoding을 명시할 수 있는 방법만 쓰게 한다
• 저장 후에는 다시 읽어 일본어 대표 행을 검증시킨다

실무에서의 짧은 표현으로 하면 거의 이것입니다.

• 읽기 전에 확인
• 의심스러우면 저장 금지
• 기존은 유지, 신규만 UTF-8
• 애매한 쓰기 경로를 금지
• 마지막에 다시 읽어 확인

flowchart TB
    accTitle: 문자 코드 사고를 막는 5가지 절차
    accDescr: 읽기 전에 확인하고, 의심스러우면 저장 금지, 기존은 유지하고 신규만 UTF-8, 애매한 쓰기 경로를 금지, 마지막에 다시 읽어 확인한다는 실무의 짧은 표현을 차례로 나타내는 그림.
    c1["읽기 전에 확인"] --> c2["의심스러우면 저장 금지"]
    c2 --> c3["기존은 유지, 신규만 UTF-8"]
    c3 --> c4["애매한 쓰기 경로를 금지"]
    c4 --> c5["마지막에 다시 읽어 확인"]

그림 3: 고정하고 싶은 작업 절차는 이 다섯 흐름으로 모을 수 있다.

반대로 위험한 것은 이런 지시입니다.

• 「문자 깨짐을 고쳐 줘」
• 「전부 UTF-8로 해 줘」
• 「CSV를 내 줘」
• 「적당히 맞춰 줘」
• 「일단 저장해서 봐 줘」

이것들은 전부 Codex가 어느 단계에서 멈춰야 하는지가 쓰여 있지 않습니다. 문자 깨짐 대책에서는 무엇을 할지뿐만 아니라, 어디서 저장을 멈출지까지 지시할 필요가 있습니다.

이 글의 지식 맵

Windows에서 Codex에 일본어 파일을 다루게 할 때 관건은 추측한 채로 파일을 저장하게 하지 않는 것입니다. CP932와 UTF-8은 같은 바이트열을 양쪽 모두 올바르게 해석할 수 없으므로, 읽기 전에 BOM 유무나 엄밀한 UTF-8 디코딩으로 encoding 후보를 확인하는 절차가 실제 바이트열의 해석이 본래의 encoding과 어긋나는 사고를 줄여줍니다. 그래도 놓치면 문자 깨짐은 파일 자체의 파손으로 고정되므로, 기존 encoding 유지, encoding을 명시하는 쓰기, 저장 후의 재독 검증이라는 작업 규칙을 AGENTS.md에 상설하는 것이 권장됩니다. Windows PowerShell 5.1과 PowerShell 7은 기본 쓰기 encoding이 다르므로, 애매한 쓰기 경로를 피하는 것도 필수적입니다.

flowchart LR
    accTitle: Codex 문자 깨짐 대책 지식 맵
    accDescr: Codex에 AGENTS.md로 문자 코드 작업 규칙을 부여하는 것이, encoding 해석의 어긋남이나 추측한 채로의 저장에 의한 파일 파손을 어떻게 막는지를, CP932와 UTF-8의 비호환성이나 PowerShell 버전에 따른 encoding 기본값의 차이와 함께 보여주는 그림
    codex["Codex"]
    mojibake["문자 깨짐"]
    agents_md["AGENTS.md"]
    character_encoding_rules["문자 코드 작업 규칙"]
    pre_read_encoding_check["읽기 전 인코딩/BOM/줄 바꿈 확인"]
    unverified_save["추측에 의존한 저장"]
    existing_file_encoding_preservation["기존 파일의 인코딩 유지 방침"]
    explicit_encoding_write["인코딩을 명시하는 쓰기"]
    post_write_reread_verification["저장 후 재읽기 검증"]
    ambiguous_write_path["모호한 쓰기 경로"]
    utf8_migration_as_separate_task["UTF-8 전환의 별도 작업화"]
    cp932["CP932"]
    utf_8["UTF-8"]
    bom["BOM(Byte Order Mark)"]
    strict_utf8_decode_check["엄격한 UTF-8 디코딩 판정"]
    encoding_misinterpretation["인코딩 해석 불일치"]
    reencoding_corruption["잘못된 인코딩 해석으로 인한 파일 손상"]
    replacement_character["U+FFFD(REPLACEMENT CHARACTER)"]
    windows_powershell_5_1["Windows PowerShell 5.1"]
    ansi_codepage["ANSI 코드 페이지"]
    utf_16["UTF-16"]
    powershell_7["PowerShell 7"]
    character_encoding_rules -->|"에서 구성할 수 있다"| agents_md
    character_encoding_rules -->|"권장되는 대응"| codex
    pre_read_encoding_check -->|"권장되는 대응"| codex
    unverified_save -->|"사용은 비권장"| codex
    existing_file_encoding_preservation -->|"권장되는 대응"| codex
    explicit_encoding_write -->|"권장되는 대응"| codex
    post_write_reread_verification -->|"권장되는 대응"| codex
    ambiguous_write_path -->|"사용은 비권장"| codex
    utf8_migration_as_separate_task -->|"권장되는 대응"| codex
    cp932 -.->|"양립하지 않는다"| utf_8
    pre_read_encoding_check -->|"에서 확인할 수 있다"| bom
    pre_read_encoding_check -->|"에서 확인할 수 있다"| strict_utf8_decode_check
    encoding_misinterpretation -->|"원인이 될 수 있다"| mojibake
    mojibake -.->|"원인이 될 수 있다"| reencoding_corruption
    unverified_save -.->|"원인이 될 수 있다"| reencoding_corruption
    pre_read_encoding_check -->|"완화한다"| encoding_misinterpretation
    reencoding_corruption -->|"에서 확인할 수 있다"| replacement_character
    windows_powershell_5_1 -->|"이용한다"| ansi_codepage
    windows_powershell_5_1 -->|"이용한다"| utf_16
    powershell_7 -->|"이용한다"| utf_8
    ambiguous_write_path -->|"이용한다"| windows_powershell_5_1
    ambiguous_write_path -->|"이용한다"| powershell_7

그림의 실선은 항상 성립하는 관계, 점선은 조건이 붙는 관계입니다(성립 조건은 상세 페이지의 관계별 설명에 적혀 있습니다). 관계 전체 목록(총 22건, 근거와 확신도 포함)과 주요 개념의 정의는 지식 맵 상세 페이지에 정리되어 있습니다(일본어). 데이터: JSON-LD / Turtle

2. 왜 Windows에서 문자 깨짐 사고가 일어나기 쉬운가

진짜 문제는 Codex가 일본어에 약해서가 아니라, Windows 쪽 자산에 여러 문자 코드와 여러 쓰기 경로가 공존하고 있는 것입니다.

실무에서는 이런 혼재가 드물지 않습니다.

• 비교적 새로운 소스나 Markdown은 UTF-8
• 오래된 CSV, TXT, 로그, 설정은 CP932 계열
• 일부 출력이나 도구 생성물은 UTF-16 계열
• 에디터, shell, Excel에서 나온 출력으로 저장 경로가 제각각
• 개행 코드도 LF와 CRLF가 혼재

이 상태에서 Codex가 한 번이라도 잘못된 해석을 하면, 읽지 못한 문자열을 「읽고 있는 것」으로 다음 편집에 넘기는 경우가 있습니다. 그대로 저장하면 이번에는 표시상의 문제가 아니라 파일 자체의 파손으로 고정됩니다.

그래서 문자 깨짐 대책은 결국 I/O 절차를 어떻게 관리하는가의 이야기가 됩니다.

flowchart TB
    accTitle: 사고가 파손으로 고정될 때까지
    accDescr: 여러 문자 코드와 쓰기 경로가 공존하는 자산에서 Codex가 한 번이라도 잘못된 해석을 하면, 읽지 못한 문자열을 읽고 있는 것으로 다음 편집에 넘기고, 저장한 시점에 표시상의 문제가 아니라 파일 자체의 파손으로 고정됨을 나타내는 그림.
    d1["여러 encoding과 쓰기 경로의 공존"] --> d2["한 번의 잘못된 해석"]
    d2 --> d3["읽지 못한 채로 다음 편집으로 진행"]
    d3 --> d4["저장으로 파손으로서 고정된다"]
    d4 -.-> d5["대책의 본체는 I/O 절차 관리"]

그림 4: 문자 깨짐은 표시 문제로 시작해, 저장하는 순간에 파손으로 고정된다.

2.1 용어를 먼저 네 가지만

이후에서 반복해서 나오는 말을 여기서 맞춰 둡니다.

중요한 점은 CP932와 UTF-8은 둘 다 파일 자신에는 적혀 있지 않다는 것입니다. BOM이 없는 한, 파일은 「어떻게 읽어야 하는지」를 스스로 밝히지 않습니다. 그래서 읽기 전의 확인이 필요합니다.

flowchart TB
    accTitle: 파일은 자신의 encoding을 밝히지 않는다
    accDescr: CP932인지 UTF-8인지는 파일 자신에는 적혀 있지 않고, BOM이 없는 한 파일은 어떻게 읽어야 하는지를 밝히지 않으므로 읽기 전의 확인이 필요함을 나타내는 그림.
    e1["파일 내용은 바이트열뿐"] --> e2{"BOM이 있는가"}
    e2 -->|"있다"| e3["Unicode 계열임을 알 수 있다"]
    e2 -->|"없다"| e4["UTF-8인지 CP932인지는 내용으로 판단"]
    e4 --> e5["그래서 읽기 전의 확인이 필요하다"]

그림 5: BOM이 없으면 파일은 읽는 법을 알려 주지 않는다.

3. 먼저 Codex에 고정하고 싶은 규칙

3.1 읽기 전에 encoding 후보와 BOM과 개행을 확인시킨다

첫 번째 규칙은 이것입니다.

일본어를 포함한 기존 파일을 읽기 전에, 현재 encoding 후보, BOM 유무, 개행 코드를 확인하고, 의심스러우면 그대로 내용 해석으로 넘어가지 말 것.

핵심은 「텍스트를 읽기 전에, 먼저 파일의 전제를 본다」로 바꾸는 것입니다.

구체적으로 어떻게 확인시키는가

「확인해」라고만 쓰면 Codex도 사람도 방법이 흔들립니다. 확인 절차까지 지시에 넣어 두는 편이 안정됩니다. 아래는 Windows PowerShell 5.1과 PowerShell 7 어디서든 동작하는 형태입니다.

먼저 선두 바이트를 16진으로 봅니다. BOM 유무는 여기서 결정됩니다.

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

# 선두 16바이트를 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: 선두 바이트를 16진으로 보고 BOM 유무를 판정하고, 개행 코드를 세고, 엄격 UTF-8 디코드로 encoding 후보를 좁힌 뒤, 마지막으로 일본어 대표 행이 읽히는지 눈으로 확인하는 절차를 나타내는 그림.
    f1["선두 바이트를 16진으로 본다"] --> f2["BOM 유무를 판정"]
    f2 --> f3["개행 코드를 센다"]
    f3 --> f4["엄격 UTF-8 디코드로 후보를 좁힌다"]
    f4 --> f5["일본어 대표 행을 눈으로 확인"]
    f4 -.-> f6["ASCII만이면 어느 쪽으로도 통과한다"]

그림 6: 읽기 전의 확인은 바이트·개행·디코드·육안 순으로 진행한다.

3.2 문자 깨짐이 의심스러운 파일은 추측한 채로 저장시키지 않는다

이것은 특히 중요합니다.

문자 깨짐이 의심될 때는 조사 단계에서는 read-only로 두고, 해석에 확신이 들 때까지 덮어쓰기를 금지한다.

사람도 마찬가지이지만, 읽지 못한 파일을 저장해서는 안 됩니다. 조금 깨져 보이지만 아마 이것일 것이다, 로 저장하면 그것이 사고의 확정판이 됩니다.

3.3 기존 파일은 유지하고, 신규 파일만 UTF-8을 기본으로 한다

문자 깨짐 대책 맥락에서 의외로 위험한 것이 「전부 UTF-8로 통일해 줘」입니다.

최종적으로 repo 전체를 UTF-8로 맞추는 판단은 있을 수 있지만, 그것은 별도 태스크로 diff와 영향 범위를 보면서 하는 편이 안전합니다. 일상 수정에서는 이 운영이 안정됩니다.

• 기존 파일을 편집할 때는 원래의 encoding을 유지한다
• 신규 파일을 추가할 때는 repo 규약에 따라 UTF-8 계열로 만든다
• 기존 파일 변환이 필요하면 통상의 기능 수정과 분리한다

3.4 애매한 쓰기 경로를 기본으로 쓰게 하지 않는다

Windows에서 사고를 늘리기 쉬운 것은 「사소한 출력이니까 shell에서 대충 쓴다」입니다.

• 리다이렉트로 그대로 내보낸다
• 편의 명령으로 그대로 저장한다
• 임시 생성물을 그대로 운영 파일로 승격한다

이런 경로는 encoding이 명시되어 있지 않은 경우가 많아, 사고의 온상이 됩니다. 그래서 Codex에는 쓰기 수단의 선택도 고정해 두는 편이 안전합니다.

「기본 encoding」은 PowerShell 버전마다 다르다

여기는 모르면 반드시 밟습니다. PowerShell은 버전에 따라 기본 쓰기 encoding이 다릅니다.

즉 같은 스크립트라도 5.1에서 돌렸는지 7에서 돌렸는지에 따라 다른 파일이 생깁니다. 「개발 머신에서는 괜찮았는데, 현장 서버에서 깨졌다」의 단골이 이것입니다.

게다가 5.1 쪽에는 Unicode 계열 encoding을 지정하면 반드시 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

# 신규 파일을 BOM 없는 UTF-8로 만든다（PowerShell 7）
Set-Content -Path $newPath -Value $lines -Encoding utf8NoBOM

세션 전체에서 기본값을 맞추고 싶다면 $PSDefaultParameterValues를 쓰는 방법도 있습니다. 다만 이것은 그 세션만의 설정이므로, 「우리 프로필에는 적혀 있다」를 전제로 한 절차서는 다른 사람 환경에서 깨집니다.

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

Out-File 대신 >를 쓰는 방식도, 5.1 이후는 내부에서 Out-File을 호출할 뿐이므로 기본 encoding은 같은 문제를 안고 있습니다. 리다이렉트를 금지하고, encoding을 적을 수 있는 cmdlet이나 .NET API만 쓰게 하는 것이 가장 확실합니다.

flowchart TB
    accTitle: 같은 스크립트라도 다른 파일이 생긴다
    accDescr: PowerShell은 버전에 따라 기본 쓰기 encoding이 다르므로, 같은 스크립트라도 5.1에서 돌렸는지 7에서 돌렸는지에 따라 다른 파일이 생기며, 리다이렉트를 금지하고 encoding을 적을 수 있는 cmdlet이나 .NET API만 쓰게 하는 것이 확실함을 나타내는 그림.
    g0["같은 스크립트"] --> g1["Windows PowerShell 5.1에서 실행"]
    g0 --> g2["PowerShell 7에서 실행"]
    g1 --> g3["다른 encoding의 파일이 생긴다"]
    g2 --> g3
    g3 -.-> g4["encoding을 명시할 수 있는 경로만 쓰게 한다"]

그림 7: 기본 encoding은 버전마다 다르므로, 쓰기는 매번 명시시킨다.

3.5 저장 후에는 다시 읽어 일본어 대표 행을 확인시킨다

「저장됐다」와 「망가지지 않았다」는 같지 않습니다.

중요한 것은 저장 후에 대표적인 일본어 행을 한 번 더 읽혀, 이런 점을 확인시키는 것입니다.

• 치환 문자 U+FFFD가 들어가지 않았는지
• ?가 부자연스럽게 늘지 않았는지
• BOM이나 개행만의 거대한 diff가 되지 않았는지
• 업무상 바꾸지 않은 일본어가 그대로 남아 있는지

3.6 이상 징후가 나오면 수정보다 먼저 보고시킨다

문자 코드 사고에서는 무리하게 고치게 하기보다 멈추고 보고시키는 편이 피해를 작게 할 수 있습니다.

예를 들어 이런 징후가 나오면 일단 이상으로 다루는 편이 안전합니다.

• U+FFFD의 증가
• ?의 증가
• 예상 밖의 BOM 변화
• 개행만의 대량 diff
• 일본어 행만 부자연스럽게 크게 바뀐다

flowchart TB
    accTitle: 이상 징후가 나오면 멈추고 보고
    accDescr: 치환 문자 U+FFFD나 ?의 증가, 예상 밖의 BOM 변화, 개행만의 대량 diff 같은 징후가 나오면, 무리하게 고치게 하기보다 멈추고 보고시키는 편이 피해를 작게 할 수 있음을 나타내는 그림.
    h1["U+FFFD나 ?의 증가"] --> h4["일단 이상으로 다룬다"]
    h2["예상 밖의 BOM 변화"] --> h4
    h3["개행만의 대량 diff"] --> h4
    h4 --> h5["수정보다 먼저 멈추고 보고시킨다"]

그림 8: 이상의 징후가 나오면 고치게 하는 것이 아니라 멈추고 보고시킨다.

4. 짧은 지시문으로 넘긴다면

매번 태스크에 붙이는 짧은 판이라면 이 정도면 충분히 효과가 있습니다.

이 작업에서는 문자 코드 사고를 최우선으로 피해 주세요.

- 일본어를 포함한 기존 파일은 읽기 전에 encoding 후보, BOM 유무, 개행 코드를 확인한다
- 문자 깨짐이 의심되는 파일은 추측한 채로 저장하지 않는다
- 기존 파일은 원래의 encoding / BOM / 개행을 유지한다
- 신규 파일은 repo 규약에 따라 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에서 일본어 파일을 다루는 repo를 위한, 실용 쪽에 가까운 템플릿입니다.

# 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을 명시할 수 없는 쓰기 경로를 기본으로 쓰지 않는다.
  셸 리다이렉트나 encoding을 지정할 수 없는 편의 명령이 해당한다.
- 쓴 뒤에는 다시 열어, 일본어 대표 행이 망가지지 않았는지 확인한다.
- 다음 중 하나가 나오면 고치려 하지 말고, 일단 멈추고 보고한다.
  - 치환 문자 U+FFFD의 증가
  - 예상하지 않은 `?`의 증가
  - 의도하지 않은 BOM 변화
  - 의도하지 않은 개행 코드 변환
  - 업무상 이유가 없는 파일 전체 diff

## 보고 방법
변경한 텍스트 파일마다 다음을 보고한다.
- 경로
- 검출했거나 유지한 encoding
- BOM 유무
- 개행 코드
- 어떻게 검증했는지
- 일본어 대표 문자열이 무사했는지

영어판과 한국어판 중 한쪽이면 됩니다. 둘 다 두면 분량이 두 배가 되므로, AGENTS.md의 읽기 크기 상한을 생각하면 한쪽으로 정하는 편이 안전합니다.

6. NG 지시와 OK 지시

문자 깨짐 대책에서는 지시의 구체성이 결과를 꽤 좌우합니다.

핵심은 손을 대기 전의 확인과 저장 후 검증을 반드시 쓰는 것입니다.

flowchart TB
    accTitle: NG 지시를 OK 지시로 바꾸는 형
    accDescr: 문자 깨짐을 고쳐 줘 같은 지시에는 어디서 멈춰야 하는지가 쓰여 있지 않으므로, 손을 대기 전의 확인과 저장 후 검증을 보태 어디서 저장을 멈출지까지 포함한 지시로 바꿈을 나타내는 그림.
    j1["「문자 깨짐을 고쳐 줘」"] --> j2["멈추는 위치가 쓰여 있지 않다"]
    j2 -.->|"보탠다"| j3["손을 대기 전의 확인"]
    j2 -.->|"보탠다"| j4["저장 후 검증"]
    j3 --> j5["어디서 멈출지까지 포함한 지시"]
    j4 --> j5

그림 10: NG 지시와의 차이는 확인과 검증, 그리고 멈추는 위치의 유무에 있다.

7. 리뷰 시 체크리스트

Codex에 작업을 시킨 뒤, 사람 쪽에서 볼 점검 지점도 고정해 두면 더 안정됩니다.

• 변경한 파일마다 encoding / BOM / 개행 처리가 보고되어 있는가
• 일본어 행만 부자연스럽게 크게 바뀌지 않았는가
• 개행만의 diff가 대량으로 나오지 않았는가
• U+FFFD나 ?가 늘지 않았는가
• 업무 변경과 무관한 전체 diff가 없는가
• CSV나 로그에서 열이 어긋나거나 따옴표가 깨지지 않았는가

문자 깨짐 대책에서 중요한 것은 성공한 diff를 늘리는 것보다, 수상한 diff를 빨리 멈추는 것입니다.

8. 정리

Windows 환경에서 Codex에 일본어 파일을 다루게 할 때, 먼저 효과가 있는 것은 PC 쪽을 완벽하게 맞추는 것보다 Codex에 문자 코드 작업 절차를 명시하는 것입니다.

특히 기억해 두고 싶은 것은 다섯 가지입니다.

• 읽기 전에 encoding / BOM / 개행을 확인시킨다
• 문자 깨짐이 의심스러우면 추측한 채로 저장시키지 않는다
• 기존 파일은 유지하고, 신규 파일만 UTF-8 계열로 맞춘다
• 애매한 쓰기 경로를 금지한다
• 저장 후 다시 읽어 일본어 대표 행을 확인시킨다

그리고 매번 말할 정도라면 AGENTS.md에 넣는다. 이것이 가장 실무적입니다.

문자 깨짐 대책의 핵심은 「일본어를 제대로 다뤄 줘」라고 부탁하는 것이 아니라, 저장해도 되는 조건과 멈춰야 하는 조건을 명문화하는 것에 있습니다. 거기까지 쓰면 Windows에서도 Codex는 꽤 다루기 쉬워집니다.

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

관련 기사

같은 태그를 공유하는 최신 기사입니다. 더 가까운 주제로 지식을 넓힐 수 있습니다.

관련 토픽

이 기사와 가까운 토픽 페이지입니다. 기사를 출발점 삼아 관련 서비스와 다른 기사로 이어집니다.

이 주제와 연결되는 서비스

이 기사는 다음 서비스 페이지로 이어집니다. 가까운 입구부터 확인해 주세요.

자주 묻는 질문

이 기사 주제에 대해 상담 시 자주 나오는 질문을 모았습니다.

Windows에서 Codex를 쓰면 일본어가 깨지는 이유는 무엇인가요?

진짜 원인은 Codex가 일본어에 약해서가 아니라, Windows 쪽 자산에 UTF-8, CP932, UTF-16 계열 등 여러 문자 코드와 여러 쓰기 경로가 공존하기 때문입니다. 이 상태에서 Codex가 한 번이라도 잘못된 해석을 하면, 읽지 못한 문자열을 「읽고 있는 것」으로 다음 편집에 넘기는 경우가 있습니다. 그대로 저장하면 표시상의 문제가 아니라 파일 자체의 파손으로 고정됩니다. 그래서 문자 깨짐 대책은 결국 I/O 절차를 어떻게 관리하는가의 이야기입니다.

Codex의 문자 깨짐을 막으려면 어떤 지시를 하면 되나요?

문자 코드의 작업 절차를 먼저 고정하는 것이 가장 효과가 있습니다. 구체적으로는 일본어를 포함한 기존 파일은 읽기 전에 encoding 후보·BOM 유무·개행 코드를 확인시키고, 문자 깨짐이 의심스러운 파일은 확신이 들 때까지 저장시키지 않으며, 기존 파일은 원래의 encoding을 유지하고 신규만 UTF-8 계열로 만들고, encoding을 명시할 수 있는 쓰기 방법만 쓰게 하며, 저장 후에는 다시 읽어 일본어 대표 행을 검증시키는 다섯 가지입니다. 대상 파일과 「깨지면 안 되는 대표 문자열」을 넘기면 더 안정됩니다.

「문자 깨짐을 고쳐 줘」「전부 UTF-8로 해 줘」라고 지시하면 안 되나요?

둘 다 위험한 지시입니다. Codex가 어느 단계에서 저장을 멈춰야 하는지가 쓰여 있지 않아, 추측한 채로 저장되어 사고가 확정되기 쉽습니다. 「전부 UTF-8로」는 특히 위험하므로, 기존 파일 편집에서는 원래의 encoding·BOM·개행을 유지시키고, repo 전체의 UTF-8화는 diff와 영향 범위를 보면서 진행하는 별도 태스크로 분리하는 편이 안전합니다. 대신 「파손인지 표시 쪽 문제인지를 구분하고, 추측한 채로 저장하지 마라」처럼, 손을 대기 전의 확인과 저장 후 검증까지 포함해 지시합니다.

문자 코드 규칙은 AGENTS.md에 쓰는 편이 좋나요?

같은 주의를 매번 태스크에서 반복할 정도라면 AGENTS.md에 상시 두는 편이 효과가 있습니다. 읽기 전의 encoding·BOM·개행 확인, 문자 깨짐이 의심되는 동안의 저장 금지, 기존 파일 유지, UTF-8 변환의 별도 태스크화, 애매한 쓰기 경로 금지, 저장 후 다시 읽어 검증, 이상 시 멈추고 보고하는 규칙을 모아 둡니다. 여기에 변경한 파일마다 encoding·BOM·개행·검증 방법을 보고하게 하는 형식까지 고정하면, 리뷰 쪽 점검도 안정됩니다.

저자 프로필

기사 저자의 프로필 페이지입니다.

Go Komura

합동회사 코무라소프트 대표

Windows 소프트웨어 개발, 기술 상담, 장애 조사를 중심으로 재현이 어려운 장애 조사와 기존 자산이 남아 있는 프로젝트에 강점이 있습니다.