cursor 한글 주석·출력 깨질 때 인코딩 잡는 법: UTF-8로 프로젝트를 고정한 기록

Cursor에서 한글 주석이 깨지거나 AI가 만든 출력이 이상한 문자로 보이면, 대부분은 파일 인코딩·터미널 코드페이지·Git 줄바꿈 설정이 서로 어긋난 상태입니다. 결론부터 말하면 프로젝트 전체를 UTF-8로 고정하고, 기존에 깨진 파일은 재저장한 뒤, 터미널과 Git 설정까지 같이 맞춰야 재발이 줄어듭니다.

Cursor 프로젝트에서 새 파일을 하나 만들어 한글 주석·터미널 출력·Git 재열기까지 순서대로 테스트해 보세요.

특히 Claude Code, ChatGPT, Cursor Composer로 코드를 생성한 뒤 README, 주석, 콘솔 로그에 한글을 섞는 팀이라면 이 문제를 초반에 잡아두는 게 좋습니다. 한 번 꼬이면 AI가 깨진 문자열을 정상 데이터로 학습하듯 이어서 수정해 버려 디버깅 시간이 길어집니다.

가장 먼저 볼 곳: 파일 인코딩은 UTF-8인가

Cursor는 VS Code 기반이라 기본 원리는 같습니다. 하단 상태바에 UTF-8이라고 표시되는지 확인하고, 아니라면 Reopen with Encoding과 Save with Encoding을 구분해서 써야 합니다.

깨진 파일을 열었을 때의 순서

이미 한글이 깨져 보이는 파일은 무작정 저장하면 깨진 상태가 덮어써질 수 있습니다. 먼저 우측 하단 인코딩 표시를 눌러 Reopen with Encoding을 선택하고, CP949 또는 EUC-KR로 열어 정상 표시되는지 확인합니다. 정상으로 보이면 다시 인코딩 메뉴에서 Save with Encoding → UTF-8로 저장합니다.

반대로 새로 만드는 파일이 계속 다른 인코딩으로 저장된다면 Cursor 설정에서 files.encoding을 utf8로 고정하세요. 설정 JSON에는 아래처럼 넣으면 됩니다.

{
  "files.encoding": "utf8",
  "files.autoGuessEncoding": false,
  "files.eol": "\n"
}

AI 출력이 터미널에서만 깨질 때

파일 안에서는 한글이 멀쩡한데 Cursor 터미널에서만 깨진다면 에디터 문제가 아니라 셸 문제일 가능성이 큽니다. Windows PowerShell에서는 임시로 chcp 65001을 실행하고, Node.js나 Python 출력도 UTF-8 환경인지 확인합니다.

# Windows PowerShell
chcp 65001

# Python 실행 시
$env:PYTHONUTF8=1
python app.py

macOS나 Linux는 보통 UTF-8이 기본이지만, Docker 컨테이너 안에서는 로케일이 비어 있는 경우가 있습니다. 이때는 Dockerfile에 ENV LANG=C.UTF-8 같은 설정을 넣어두면 Cursor에서 실행한 로그도 안정적입니다.

어디가 문제인지 빠르게 가르는 비교표

프로젝트에 박아두면 좋은 최소 설정

혼자 쓰는 토이 프로젝트라면 Cursor 사용자 설정만으로 충분할 수 있습니다. 하지만 팀 저장소, SaaS MVP, 자동화 스크립트처럼 GitHub에 올릴 코드는 설정 파일을 저장소에 같이 넣는 편이 안전합니다.

.editorconfig로 에디터 기본값 맞추기

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2

.gitattributes로 줄바꿈까지 고정하기

* text=auto eol=lf
*.bat text eol=crlf
*.ps1 text eol=crlf

여기까지 넣어두면 Cursor, VS Code, JetBrains 계열 IDE를 섞어 쓰더라도 한글 주석과 줄바꿈이 뒤엉킬 확률이 줄어듭니다. Git의 core.autocrlf는 팀 정책에 맞춰야 하지만, 새 프로젝트라면 Windows에서도 false 또는 input으로 맞추고 저장소 파일로 제어하는 방식이 깔끔합니다.

예시: Next.js 앱에서 한글 로그가 깨진 경우

가상의 예시입니다. Cursor Composer로 Next.js 관리자 페이지를 만들고, console.log('결제 상태 확인') 같은 로그를 넣었는데 Windows 터미널에서만 깨진다고 가정해 보겠습니다.

이 경우 파일을 먼저 확인합니다. app/api/payments/route.ts가 UTF-8이면 파일 문제는 아닙니다. 그다음 PowerShell에서 chcp를 실행해 949로 나오면 chcp 65001로 바꿉니다. 그래도 CI에서 깨지면 GitHub Actions나 Docker 실행 환경의 로케일을 봅니다. 즉, 파일 → 터미널 → 실행 환경 순서로 좁히면 불필요한 재생성을 줄일 수 있습니다.

누구에게 어떤 설정을 추천하나

혼자 Cursor로 빠르게 프로토타입을 만드는 사람은 우선 사용자 설정의 files.encoding만 UTF-8로 고정해도 체감이 큽니다. README와 주석을 많이 쓰는 경우에는 .editorconfig까지 추가하세요.

Claude Code, Codex, Cursor를 번갈아 쓰는 빌더라면 저장소에 .vscode/settings.json, .editorconfig, .gitattributes를 함께 넣는 쪽을 추천합니다. AI 에이전트가 만든 파일도 같은 규칙을 따라가게 만드는 것이 핵심입니다.

Windows 팀원이 있는 협업 프로젝트는 터미널 코드페이지와 Git 설정 문서를 README에 짧게 남겨두세요. “깨지면 재생성”보다 “환경을 맞춘 뒤 재실행”이 훨씬 빠릅니다.

자주 막히는 질문

Q. 자동 인코딩 감지를 켜두면 더 편하지 않나요?

기존 레거시 파일을 자주 열면 도움이 될 수 있지만, 새 파일까지 들쭉날쭉해질 수 있습니다. 새 프로젝트는 files.autoGuessEncoding을 끄고 UTF-8을 명시하는 편이 안정적입니다.

Q. 이미 깨진 한글은 복구할 수 있나요?

원본 바이트가 남아 있고 잘못된 방식으로 열렸을 뿐이라면 CP949/EUC-KR로 다시 열어 복구할 수 있습니다. 다만 깨진 상태로 저장까지 했다면 Git 이전 커밋이나 백업에서 되돌리는 게 가장 안전합니다.

Q. Cursor만의 문제인가요?

아닙니다. VS Code, IntelliJ, 터미널, Git, Docker 중 하나만 어긋나도 같은 현상이 납니다. Cursor는 AI 출력이 많아 문제가 더 눈에 띄는 편입니다.

오늘 바로 할 액션

새 파일 하나를 만들고 한글 주석, 한글 콘솔 출력, Git 커밋 후 재열기까지 테스트해 보세요. 문제가 없으면 그 설정을 저장소에 넣고, 문제가 있으면 위 표의 순서대로 한 단계씩 좁히면 됩니다.

Cursor에서 한글이 깨지는 문제는 감으로 고치는 영역이 아닙니다. UTF-8을 기준으로 파일, 터미널, Git을 같은 방향으로 맞추면 AI 코딩 에이전트가 만든 코드도 훨씬 예측 가능해집니다.

관련 링크

• ai 코딩 구독 요금 비교: Claude Code·Cursor·Copilot, 빌드용으로 돈값 하는 조합
• claude code artifacts, 웹 미리보기 대신 파일로 남기는 실전 작업법
• claude code 모델 추천: 실제 빌드 작업에서 Sonnet과 Opus를 나눠 쓰는 기준
• 관련 태그 더 보기
• 카테고리 더 보기
• 검색 결과 더 보기
• 참고 링크