클로드 코드 한글 환경 설정 2026 — 한국어 응답 고정·한글파일 처리·토큰 절약

# 클로드 코드 한글 환경 설정 2026 — 한국어 응답 고정·한글파일 처리·토큰 절약

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

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

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

설치와 최초 실행

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

```bash

npm install -g @anthropic-ai/claude-code

claude --version # 2.1.235 (Claude Code)

```

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

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

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

가장 확실한 방법은 전역 설정 파일에 언어를 명시하는 것이다.

```bash

# ~/.claude/settings.json

{

"language": "korean"

}

```

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

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

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

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

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

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

```markdown

규칙

• 배포 절차 — 배포 요청 시 읽을 것
• 코드 스타일 — 컴포넌트 작성 시 참조

```

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

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

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

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

```bash

claude mcp list # 연결된 MCP 서버 확인

claude mcp add <서버> # 새 서버 연결

```

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

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

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

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

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

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

자주 쓰는 명령

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

한글 환경에서 흔한 문제 3가지

1. 한국어로 물었는데 영어로 답한다. `settings.json`의 `language` 설정이 없는 경우다. 대화창에서 "한국어로 답해줘"라고 매번 말하는 것보다 설정으로 고정하는 편이 확실하다.

2. 한글 파일명이 깨진다. macOS와 Linux의 한글 파일명 정규화 방식(NFD/NFC) 차이에서 오는 문제다. 클로드 코드 고유의 문제는 아니며, 파일명을 직접 다루는 스크립트를 작성할 때 유의해야 한다.

3. HWP를 첨부해도 읽지 못한다. 기본 지원 형식이 아니기 때문이며, 위에서 다룬 MCP 연결로 해결한다.

FAQ

클로드 코드는 무료인가?

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

터미널 말고 다른 곳에서도 쓸 수 있나?

CLI 외에 데스크톱 앱(Mac·Windows), 웹, VS Code·JetBrains 확장으로도 쓸 수 있다.

한국어 응답 설정이 코드 품질에 영향을 주나?

사람이 읽는 문장의 언어만 바뀐다. 코드 자체의 생성 품질과는 무관하다.

CLAUDE.md는 얼마나 길게 써야 하나?

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

정리

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