iTerm2에서 Claude Code 화면이 점선으로 깨질 때: CJK 폭 설정과 코딩 폰트

화면이 이상하게 깨지기 시작했다

터미널에서 Claude Code를 쓰던 중이었다. 분명 깔끔한 박스 UI여야 하는데, 화면이 이렇게 보였다.

안 녕 하 세 요 ! 무 엇 을  도 와 드 릴 까 요 ?- - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

가로 구분선이 실선(─)이 아니라 점선 대시(- - - -) 로 쪼개져 있고, 한글은 한 글자씩 어색하게 벌어져 보였다. 글자가 깨지는 건 아니라서 사용에 큰 지장은 없었지만, 볼 때마다 거슬렸다.

처음엔 Claude Code 버그인 줄 알았다. 결론부터 말하면 터미널 폰트와 문자 폭(width) 처리 문제였다. 같은 증상을 겪는 사람이 꽤 있을 것 같아 원인과 해결 과정을 정리해 둔다.

왜 이런 일이 생길까

증상은 두 가지인데, 원인은 사실상 하나로 이어진다.

1. 한글이 한 글자씩 벌어지는 이유 — East Asian Width

한글, 한자, 일부 이모지 같은 문자는 터미널에서 영문자 두 칸 폭을 차지한다. 이걸 "East Asian Wide" 문자라고 부른다.

문제는 이 "폭이 2칸"이라는 규칙이 유니코드 버전마다 조금씩 달라졌다는 점이다. 터미널이 옛날 기준(Unicode 8 이하) 으로 폭을 계산하면, 프로그램(Claude Code)이 생각하는 글자 폭과 터미널이 실제로 그리는 폭이 어긋난다. 그 어긋남이 글자 사이 빈칸으로 나타난다.

2. 가로줄이 점선으로 깨지는 이유 — 폰트 글리프

Claude Code 같은 TUI는 구분선을 그릴 때 박스 드로잉 문자를 쓴다. 예를 들면 ─(U+2500) 같은 문자다. 그런데 터미널 폰트에 이 글리프가 없거나, 폭 계산이 어긋나면 연속된 실선이 이어지지 못하고 끊겨서 점선처럼 보인다.

정리하면 이렇다.

증상	원인	해결 키워드
한글이 한 글자씩 벌어짐	문자 폭을 옛 유니코드 기준으로 계산	Unicode 9+ widths 옵션
가로줄이 `- - -` 점선으로 깨짐	폰트에 박스 드로잉 글리프가 부실	CJK 지원 코딩 폰트

둘 다 iTerm2 설정과 폰트 교체로 잡을 수 있다.

사전 준비

macOS + iTerm2
Homebrew (폰트 설치에 사용)

Homebrew가 없다면 brew.sh에서 먼저 설치하면 된다.

Step 1. CJK 지원 코딩 폰트 설치

기본 폰트로도 어느 정도는 되지만, 박스 드로잉과 한글을 모두 깔끔하게 그리려면 전용 폰트를 쓰는 게 확실하다. 나는 두 가지를 추천한다.

D2Coding — 네이버가 만든 한글 코딩 폰트. 한글 가독성이 좋고 박스 드로잉도 잘 지원한다.
Sarasa Term K — CJK 폭 처리가 가장 깔끔한 편. 영문/한글 폭 비율이 정확히 1:2로 떨어진다.

Homebrew로 설치한다.

# D2Coding
brew install --cask font-d2coding

# Sarasa (Sarasa Term K 포함)
brew install --cask font-sarasa-gothic

둘 다 설치해두고 취향에 맞는 쪽을 골라 써도 된다. 나는 Sarasa Term K로 정착했다.

Step 2. iTerm2 폰트 변경

폰트 설치 후 iTerm2에서 적용한다.

iTerm2 → Settings(⌘,) 열기
Profiles → Text 탭으로 이동
Font 섹션에서 방금 설치한 폰트 선택
- D2Coding 또는 Sarasa Term K

여기까지만 해도 점선이 실선으로 바뀌는 경우가 많다. 하지만 한글 벌어짐은 다음 단계까지 해야 완전히 잡힌다.

Step 3. Unicode 9+ widths 옵션 켜기 (핵심)

이게 진짜 핵심이다. 같은 Profiles → Text 화면 아래쪽에서 두 옵션을 손본다.

✅ Use Unicode version 9+ widths — 켜기
✅ Unicode normalization form → NFC (또는 None)

Use Unicode version 9+ widths가 바로 East Asian Width를 최신 기준으로 계산하게 만드는 스위치다. 이걸 켜야 Claude Code가 생각하는 한글 폭과 iTerm2가 그리는 폭이 일치하면서, 한 글자씩 벌어지던 게 사라진다.

Unicode normalization form을 NFC로 맞추는 건 한글 조합 방식(자모 분리 vs 완성형) 차이로 생기는 또 다른 깨짐을 예방하는 용도다.

Step 4. 새 창에서 확인

설정 변경은 새 탭/창에서 적용된다. 기존에 떠 있던 Claude Code 세션은 한 번 종료하고, 새 창에서 다시 띄워보자.

# 새 iTerm2 창(⌘N)을 열고 다시 실행
claude

이제 가로줄은 이어진 실선 ─으로, 한글은 정상 간격으로 보일 것이다.

자주 막히는 지점 (트러블슈팅)

Q. 폰트를 설치했는데 iTerm2 폰트 목록에 안 보여요. iTerm2를 완전히 종료(⌘Q)했다가 다시 켜보자. 폰트 캐시가 갱신되면서 목록에 뜬다.

Q. Unicode 9 옵션을 켰는데도 여전히 벌어져요. 설정을 바꾼 뒤 새 창에서 확인했는지 보자. 기존 세션에는 적용되지 않는다. 그래도 안 되면 폰트를 Sarasa Term K로 바꿔보길 권한다. Sarasa는 폭 비율이 1:2로 정확해서 가장 안정적이다.

Q. 점선은 사라졌는데 이모지만 깨져요. 이모지는 폭 계산이 더 까다롭다. iTerm2 Settings → Profiles → Text의 Anti-aliased 및 폰트 fallback 설정을 확인하고, 그래도 거슬리면 이모지 폭 처리가 더 나은 폰트(예: Sarasa)로 바꾸는 게 빠르다.

정리

터미널이 깨져 보일 때 흐름은 이렇다.

증상 파악 — 한글 벌어짐(폭 문제) + 가로줄 점선(폰트 문제)
CJK 코딩 폰트 설치 — brew install --cask font-d2coding 또는 font-sarasa-gothic
iTerm2 Profiles → Text에서 폰트 변경
Use Unicode version 9+ widths 켜기 ← 한글 벌어짐 해결의 핵심
새 창에서 확인

핵심은 "Claude Code 버그가 아니라 터미널 렌더링 문제"라는 점이다. 한 번 설정해두면 다른 TUI 도구(vim, tmux, lazygit 등)에서도 똑같이 깔끔해지니, 개발 환경 세팅 초반에 잡아두면 두고두고 편하다.