한글 파일명이 기기마다 다르게 보이거나 도구가 같은 파일을 못 찾는다면, 파일 이름을 유니코드 NFC(음절을 한 글자로 합친 형태)로 맞추면 됩니다. 파이썬 표준 라이브러리 unicodedata 로 이름이 NFC 인지 검사하고, 아니면 os.rename 으로 NFC 이름으로 바꾸는 61줄짜리 스크립트를 만들어 두었습니다. 이것을 새 기기 설치 스크립트의 첫 단계와 매일 도는 점검에 넣어서, 저장소를 새로 받아도 한글 이름이 풀린 채로 남지 않게 합니다.
AI 생성 이미지
지난 편에서는 한글 때문에 마크다운 표의 세로줄이 밀리는 문제를 다뤘습니다. 이번 편은 같은 한글 문제의 다른 얼굴, 파일 이름 이야기입니다.
왜 새로 받은 저장소에서 명령이 전부 사라졌을까?
에이전트가 쓰는 규칙·명령 파일을 저장소 하나에 모아 두고 씁니다. Claude Code 의 슬래시 명령은 파일 이름이 곧 명령 이름이라, 저는 자주 쓰는 명령을 한글 이름 파일로 만들어 둡니다. 2026년 11월 14일에 세어 보니 이 저장소가 추적하는 파일 1,115개 중 경로에 한글이 든 것이 300개, 그중 명령 폴더 아래가 61개였습니다.
2026년 10월 11일에 이 저장소를 원격에서 새로 클론했습니다. 그런데 한글 이름 명령을 치면 전부 「Unknown skill」이 떴습니다. 그날 커밋 기록을 보면 명령 폴더의 한글 파일명 27개가 자모가 분리된 형태로 풀려 있었고, 명령 목록과 실제 파일을 대조하는 점검은 실패 22건을 냈습니다.
이상한 점은 git status 가 깨끗했다는 것입니다. git 은 아무것도 바뀌지 않았다고 말하는데, 파일 시스템 위의 이름은 바뀌어 있었습니다.
NFC 와 NFD 는 무엇이 다를까?
검색해 보면 「맥에서 보낸 한글 파일명이 자음·모음으로 분리돼 보인다」는 질문이 정말 많습니다. 원인은 같은 글자를 유니코드로 저장하는 방식이 두 가지라는 데 있습니다.
- NFC 는 「지」를 완성형 음절 한 글자로 저장합니다.
- NFD 는 「지」를 초성 ㅈ과 중성 ㅣ, 두 글자로 나눠 저장합니다.
화면에는 똑같이 보여도 바이트가 다르니, 프로그램은 둘을 다른 문자열로 봅니다. 직접 재 보면 「지침」이라는 두 음절은 NFC 로 2글자, NFD 로 5글자이고 두 문자열을 비교하면 같지 않다고 나옵니다. 명령 이름은 NFC 로 쳤는데 파일 이름이 NFD 이면 찾지 못하는 것이 당연했습니다.
git 이 조용했던 이유도 여기 있습니다. macOS 용 git 에는 core.precomposeunicode 라는 설정이 있어서, 파일 시스템에서 읽은 NFD 이름을 NFC 로 합쳐서 다룹니다. 제 저장소에서 이 값은 true 였습니다. 그래서 git 이 보기에는 이름이 같고, 바꿀 것이 없었습니다. 고쳐야 할 것은 git 의 기록이 아니라 디스크 위의 이름뿐이었습니다.
바꾼 방법: 디스크 이름만 NFC 로 바꾼다
핵심은 「이름이 NFC 가 아닌 경로를 깊은 것부터 모은다」는 함수입니다.
def nfd_paths(root):
out = []
for cur, dirs, files in os.walk(root, topdown=False):
if ".git" in os.path.relpath(cur, root).split(os.sep):
continue
for name in files + dirs:
if name != ".git" and not unicodedata.is_normalized("NFC", name):
out.append(os.path.join(cur, name))
return out
이 짧은 함수에 실제로 겪은 예외 세 가지를 막는 장치가 들어 있습니다.
topdown=False로 깊은 경로부터 돕니다. 상위 폴더 이름을 먼저 바꾸면 그 아래 파일의 경로가 바뀌어서, 이미 모아 둔 경로로는 찾을 수 없게 됩니다..git폴더와 그 아래, 그리고 하위 저장소의.git은 건너뜁니다. git 내부 파일을 건드리면 저장소가 망가질 수 있습니다.- 바꿀 이름(NFC)의 파일이 이미 따로 있으면 덮지 않고 건너뜁니다. 정규화를 구분하지 않는 파일 시스템에서 엉뚱한 파일을 덮는 일을 막습니다.
쓰는 법은 두 가지입니다. 폴더를 주면 이름을 바꾸고, --check 를 붙이면 아무것도 바꾸지 않고 풀린 이름만 찍은 뒤 하나라도 있으면 종료 코드 1 을 냅니다.
python3 scripts/session/nfc-names.py --check .
python3 scripts/session/nfc-names.py .
한 번 고치고 끝내면 안 되는 이유는?
이 문제는 저장소를 새로 받을 때마다 다시 생길 수 있습니다. 새 기기, 지운 뒤 다시 클론, 압축 파일로 옮긴 사본이 모두 해당합니다. 그래서 고친 날 바로 두 군데에 끼워 넣었습니다.
첫째는 새 기기 설치 스크립트의 0단계입니다. 설치를 돌리면 다른 어떤 설정보다 먼저 한글 파일명을 맞춥니다. 명령 파일 이름이 맞아야 그 뒤 단계에서 명령을 찾을 수 있기 때문입니다.
# 0. 한글 파일명 NFC(git 이 아닌 파일 시스템 이름만)
python3 "$INSTR/scripts/session/nfc-names.py" "$INSTR"
둘째는 매일 도는 점검입니다. 설치 스크립트를 점검 모드로 돌리면 --check 결과를 차이 개수에 더하고, 하나라도 있으면 그날 점검이 알려 줍니다. 덕분에 설치를 잊고 넘어간 기기가 있어도 하루 안에 알 수 있습니다.
이 스크립트에는 시험도 붙였습니다. 고친 날 커밋 기록에는 일부러 코드를 망가뜨려 시험이 정말 실패하는지 본 결과가 남아 있습니다. .git 건너뛰기를 빼면 실패 2건, 이름 바꾸기를 빼면 실패 2건이 났습니다. 시험이 이 두 장치를 실제로 지키고 있다는 뜻입니다.
지금은 무엇이 달라졌을까?
2026년 11월 14일에 저장소 전체에 --check 를 돌렸더니 풀린 이름은 0개였습니다. 한글 경로 300개가 모두 NFC 로 맞춰진 상태입니다.
가장 큰 변화는 한글 이름을 망설이지 않게 된 것입니다. 전에는 「다른 기기에서 깨지면 어쩌지」 하는 생각에 영문 이름을 고민했는데, 지금은 명령 이름을 내가 기억하기 쉬운 한글로 짓습니다. 새 기기에서도 설치 스크립트 한 번이면 같은 명령이 그대로 잡힙니다. 그 설치 스크립트 이야기는 다음 편에서 이어 가겠습니다.
자주 묻는 질문
git 설정 core.precomposeunicode 만 켜면 해결되지 않나요?
git 이 이름을 어떻게 보느냐는 해결되지만, 디스크에 놓인 파일 이름은 그대로입니다. 제 경우 git 은 깨끗하다고 했는데 파일 이름으로 명령을 찾는 프로그램은 실패했습니다. 파일 이름을 직접 읽는 도구가 있다면 이름 자체를 NFC 로 바꿔야 합니다.
윈도우로 옮긴 한글 파일명이 자모로 보이는 것도 같은 원인인가요?
같은 원인입니다. NFD 로 저장된 이름을 NFC 를 기대하는 환경에서 보면 자모가 따로 놓인 것처럼 보입니다. 이 스크립트처럼 이름을 NFC 로 정규화하면 어느 쪽에서든 한 음절로 보입니다.
파일 이름을 바꾸면 git 이 삭제·추가로 보지 않나요?
core.precomposeunicode 가 켜진 macOS 에서는 git 이 바꾸기 전과 후를 같은 이름으로 봅니다. 저도 이름을 바꾼 뒤 git status 에 변경이 나오지 않았습니다. 이 설정이 꺼진 환경이라면 먼저 바꾸지 않는 --check 로 대상을 확인해 보는 편이 안전합니다.