클로드 코드 한국어 설정하기 2026 — 응답 고정 3단계와 HWP 연결법

클로드 코드는 한국어를 지원하는가 — 3줄 요약

지원한다. 다만 기본값이 아니라 설정해야 고정된다. 클로드 코드(Claude Code)는 대화창에 한국어를 입력하면 한국어로 답하지만, 코드 주석이나 커밋 메시지는 영어로 돌아가는 경우가 잦다. 응답 언어를 고정하려면 설정 파일에 명시해야 한다.

이 글은 설치부터 위 세 가지를 순서대로 다룬다. 아래 내용은 macOS에서 v2.1.235(2026-08-18 배포)로 확인했다.

설치와 최초 실행

클로드 코드는 npm 패키지로 배포된다. Node.js 18 이상이 필요하다.

npm install -g @anthropic-ai/claude-code
claude --version   # 2.1.235 (Claude Code)

설치 후 작업할 폴더에서 claude를 실행하면 브라우저가 열리며 로그인을 요청한다. 로그인은 최초 1회만 하면 되고, 이후에는 인증 정보가 ~/.claude/에 남는다.

세션 중 다시 로그인해야 할 때는 대화창에 /login을 입력한다. 요금제를 바꾸거나 다른 계정으로 전환할 때 쓴다.

응답 언어를 한국어로 고정하기

가장 확실한 방법은 전역 설정 파일(~/.claude/settings.json)에 언어를 명시하는 것이다.

{
  "language": "korean"
}

이 값을 넣으면 코드 주석, 커밋 메시지, 설명문까지 한국어로 통일된다. 넣지 않으면 대화는 한국어로 하면서 산출물만 영어로 나오는 상태가 반복된다.

주의할 점이 하나 있다. 변수명·함수명·파일 경로 같은 코드 식별자는 한국어로 바뀌지 않으며, 바뀌어서도 안 된다. 언어 설정은 사람이 읽는 문장에만 적용된다.

설정 파일이 아직 없다면 직접 만들면 된다. 폴더가 없을 수도 있다.

mkdir -p ~/.claude
cat > ~/.claude/settings.json <<'EOF'
{
  "language": "korean"
}
EOF

이미 파일이 있다면 덮어쓰지 말고 language 키만 추가한다. 다른 설정이 같이 들어 있는 경우가 많다.

설정이 안 먹는 것처럼 보일 때

바꿨는데 여전히 영어로 답한다면 순서대로 확인한다.

세 번째가 의외로 자주 걸린다. 전역에 한국어를 넣어 뒀는데 특정 프로젝트만 영어로 나온다면 그 프로젝트 안에 설정 파일이 따로 있는 경우다.

설정과 지시문 중 무엇을 쓸 것인가

응답 언어를 정하는 방법은 두 가지인데 성격이 다르다.

"한국어로 답해줘"를 CLAUDE.md에 적는 것보다 설정으로 고정하는 편이 확실하다. 지시문은 대화가 길어지면 다른 맥락에 밀릴 수 있지만 설정은 그렇지 않다.

CLAUDE.md — 같은 지시를 반복하지 않는 법

프로젝트 루트에 CLAUDE.md 파일을 두면 클로드 코드가 세션을 시작할 때마다 자동으로 읽는다. "이 프로젝트는 pnpm을 쓴다", "테스트는 vitest로 돌린다" 같은 규칙을 매번 설명할 필요가 없어진다.

파일은 두 곳에 둘 수 있고 둘 다 적용된다.

핵심은 짧게 유지하는 것이다. 이 파일은 매 세션 컨텍스트에 통째로 올라가므로, 길수록 토큰을 상시 소모한다. 실무에서는 규칙 본문을 별도 .md로 빼고 CLAUDE.md에는 포인터만 남기는 방식이 효율적이다.

## 규칙
- [배포 절차](./docs/deploy.md) — 배포 요청 시 읽을 것
- [코드 스타일](./docs/style.md) — 컴포넌트 작성 시 참조

이렇게 두면 평소에는 목록만 컨텍스트에 올라가고, 실제 작업이 걸릴 때만 해당 문서를 읽는다.

무엇을 적고 무엇을 적지 않나

기준은 하나다. 읽어서 알 수 있는 것은 적지 않는다. 폴더 구조나 의존성은 파일을 보면 나오므로 적어 봐야 토큰만 쓴다. 반대로 "이 저장소는 main 에 직접 푸시하지 않는다" 같은 규칙은 코드 어디에도 없으므로 반드시 적어야 한다.

팀에서 쓸 때

개인 설정과 팀 규칙을 같은 파일에 섞지 않는 편이 좋다.

• ~/.claude/CLAUDE.md — 개인 작업 스타일. 저장소에 올리지 않는다
• 프로젝트/CLAUDE.md — 팀 규칙. 저장소에 커밋해 공유한다

프로젝트 파일을 커밋해 두면 팀원 전원이 같은 규칙으로 작업하게 된다. 새로 합류한 사람이 "이 저장소는 어떻게 빌드하나"를 묻지 않아도 되는 효과가 크다.

한글파일(HWP)을 다루려면

클로드 코드는 PDF·DOCX·TXT·마크다운을 그대로 읽지만 .hwp와 .hwpx는 기본 지원 형식이 아니다. 국내 업무 문서 상당수가 한글파일인 만큼 이 부분은 별도 연결이 필요하다.

해결 경로는 MCP 서버를 붙이는 것이다. MCP(Model Context Protocol)는 AI가 외부 도구를 호출하는 방식을 표준화한 규격으로, 한 번 연결하면 클로드 코드에서 한글파일을 읽고 편집하고 새로 만들 수 있다.

claude mcp list          # 연결된 MCP 서버 확인
claude mcp add <서버>    # 새 서버 연결

설치 절차와 사용 가능한 도구 목록은 HWP-MCP 한글문서 AI 도입 가이드에서 다뤘고, 연결한 뒤 실제 업무를 자동화하는 방법은 클로드로 한글파일 변환·작성·자동화하는 법에 정리했다.

세션이 길어질 때 — 컨텍스트와 토큰

클로드 코드는 대화가 길어지면 이전 내용을 요약해 컨텍스트에 유지한다. 작업이 끊기지는 않지만 토큰은 계속 쌓인다.

세션 기록은 로컬에 남는다. 실제로 프로젝트 250개를 다룬 환경에서 세션 로그가 2.7GB까지 커진 사례가 있다. 디스크 용량 문제는 아니지만, 한 세션 안에서 컨텍스트가 얼마나 누적되는지를 보여주는 수치다.

토큰을 아끼는 방법은 세 가지다.

특히 주제가 완전히 바뀔 때 /clear를 쓰지 않는 것이 가장 흔한 낭비다. 앞선 작업 맥락이 계속 따라다니며 매 요청마다 비용을 만든다.

한국어를 쓰면 같은 내용이라도 토큰이 더 든다. 영어는 단어 하나가 토큰 하나에 가깝지만 한글은 글자 하나가 여러 토큰으로 쪼개지는 경우가 많다. 대략 같은 의미의 문장이 영어보다 1.5~2배 든다고 보면 된다.

그래서 한국어 환경에서는 CLAUDE.md 길이가 더 민감하다. 영어로 쓴 200줄과 한국어로 쓴 200줄의 고정 비용이 다르다. 규칙 본문을 별도 문서로 빼는 방식이 한국어에서 특히 값을 하는 이유다.

다만 대화까지 영어로 바꿀 이유는 없다. 토큰을 아끼자고 익숙하지 않은 언어로 지시하면 의도 전달이 부정확해져서 되묻는 왕복이 늘어난다. 그 왕복이 아낀 토큰보다 비싸다. 아껴야 할 것은 매 세션 고정으로 올라가는 부분(CLAUDE.md)이지 대화가 아니다.

자주 쓰는 명령

! 접두사는 실무에서 특히 유용하다. 터미널을 따로 열지 않고 !git status 같은 명령을 실행하면 결과가 그대로 대화에 남아, 다음 요청에서 그 출력을 근거로 쓸 수 있다.

한국어 환경에서 이게 값을 하는 장면이 하나 더 있다. 브라우저 로그인이 필요한 명령(gcloud auth login, wrangler login 등)은 AI가 대신 못 하는데, !로 직접 실행하면 그 결과가 같은 대화에 남아 이어서 작업을 맡길 수 있다. 터미널을 오가며 결과를 복사해 붙일 필요가 없다.

한글 환경에서 흔한 문제

한국어로 쓸 때만 나오는 문제들이다. 대부분 클로드 코드 자체의 결함이 아니라 터미널·운영체제 쪽 설정에서 온다.

터미널 인코딩부터 확인한다

한글이 ㅁㅁㅁ이나 물음표로 보이면 대개 여기가 원인이다.

echo $LANG        # ko_KR.UTF-8 또는 en_US.UTF-8 이어야 한다
locale            # LC_CTYPE 이 UTF-8 인지 확인

ko_KR.UTF-8이 아니면 셸 설정 파일(~/.zshrc 또는 ~/.bashrc)에 넣는다.

export LANG=ko_KR.UTF-8
export LC_ALL=ko_KR.UTF-8

Windows에서 쓴다면 WSL을 쓰는 편이 낫다. 기본 명령 프롬프트는 코드 페이지가 949(CP949)라 한글 처리에서 문제가 자주 난다.

한글 입력이 밀리는 경우

한글은 자음과 모음이 합쳐지는 조합형이라, 조합 중인 글자를 터미널이 어떻게 그리느냐에 따라 커서가 밀려 보일 수 있다. 클로드 코드 쪽에서 고칠 수 있는 문제가 아니다.

긴 한국어 문장을 자주 입력한다면 에디터에서 쓰거나(VS Code·JetBrains 확장), 다른 곳에서 작성해 붙여넣는 방식이 편하다. 짧은 지시는 터미널에서, 긴 설명은 붙여넣기로 나누면 대부분 해소된다.

파일명 한글 정규화

macOS는 한글 파일명을 자모 단위로 분해해 저장하고(NFD), 리눅스와 윈도우는 완성형으로 저장한다(NFC). 같은 보고서.hwp가 바이트 수준에서 다르다는 뜻이다.

깃 저장소를 맥과 리눅스에서 같이 쓰면 같은 파일이 두 개로 보이거나 스크립트의 파일명 비교가 실패한다. 파일명을 직접 다루는 코드를 쓸 때는 정규화를 명시한다.

import unicodedata
name = unicodedata.normalize('NFC', filename)   # 비교 전에 통일

클로드 코드 고유의 문제는 아니지만, AI에게 파일 정리를 맡길 때 이 차이를 모르면 "분명히 있는 파일을 못 찾는" 상황이 생긴다.

한국어 작업에 스킬을 쓸 때

같은 지시를 반복하고 있다면 스킬로 굳히는 편이 낫다. 스킬은 절차를 파일로 적어 두고 필요할 때 불러 쓰는 방식이다.

한국어 환경에서 스킬이 특히 값을 하는 경우는 이렇다.

작성법과 MCP와의 차이는 클로드 스킬 만들기에서 다룬다. 한글파일 작업을 스킬로 묶는 구체적인 방법은 클로드로 한글파일 변환·작성·자동화하는 법에 있다.

FAQ

클로드 코드는 무료인가? 유료 구독이 필요하다. Claude 요금제에 포함되며, API 키를 직접 쓰는 방식도 지원한다.

터미널 말고 다른 곳에서도 쓸 수 있나? CLI 외에 데스크톱 앱(Mac·Windows), 웹, VS Code·JetBrains 확장으로도 쓸 수 있다.

한국어 응답 설정이 코드 품질에 영향을 주나? 사람이 읽는 문장의 언어만 바뀐다. 코드 자체의 생성 품질과는 무관하다. 변수명이나 함수명이 한글로 바뀌는 일도 없다.

설정을 바꿨는데 그대로인데요? 설정은 새 세션부터 적용된다. 실행 중인 세션을 종료하고 다시 열어야 한다. 그래도 안 되면 JSON 문법 오류이거나 프로젝트별 설정이 전역을 덮고 있는 경우다.

CLAUDE.md는 얼마나 길게 써야 하나? 짧을수록 좋다. 매 세션 컨텍스트에 올라가므로 길면 토큰을 상시 소모한다. 상세 규칙은 별도 문서로 빼고 링크만 남기는 방식을 권한다.

정리

클로드 코드를 한국어 환경에서 제대로 쓰려면 세 가지를 세팅하면 된다. settings.json으로 응답 언어를 고정하고, CLAUDE.md로 반복 지시를 없애고, 한글파일이 필요하면 MCP를 연결한다. 설치 자체는 npm 한 줄이지만 실제 생산성은 이 세 가지에서 갈린다.

클로드 코드를 개인 도구로 쓰는 것과 팀 개발 환경으로 세팅하는 것은 다른 작업입니다. CLAUDE.md 규칙 설계, MCP 도구 통합, 권한과 비용 관리까지 정해야 팀이 같은 결과를 냅니다.

트리숲은 팀원 전원이 Claude Code Max 플랜을 기본 개발 환경으로 쓰는 AI-Native Team입니다.