AI(Claude Code·Codex CLI·Gemini CLI)가 한국어 자료를 자동으로 영어 페이지로 변환하는 문제를
CLAUDE.md·AGENTS.md·GEMINI.md 4줄 언어 정책으로 해결. 한·영 태그 결정 기준,
한글 kebab-case 파일명, wikilink 혼용 실전. 76 페이지 60% 한국어 vault 검증. 2026.05.
이 글에서 해결하는 문제: Claude Code·Codex CLI·Gemini CLI로 한국어 자료를 정리하면
AI가 자동으로 모든 것을 영어로 만들어버립니다. 파일명·태그·페이지명 모두 영어로 변환되어
한국어 원본의 미묘한 의미가 사라집니다. 본인도 처음 셋업했을 때 한국어 자료 100개 중
약 70개가 영어 페이지로 만들어졌습니다.
이 글은 vault 루트의 CLAUDE.md(또는 AGENTS.md·GEMINI.md)에 4줄 정책을 추가하는 것만으로
이 문제를 해결하는 패턴을 정리합니다. 본인 vault(76 페이지, 한국어 60% / 영어 40%)에서
1년간 검증한 결과입니다.
📚 이 글은 LLM 위키 만들기 완벽 가이드 (2026)의 후속 2편입니다.
📚 LLM 위키 시리즈 (2026)
- LLM 위키 만들기 완벽 가이드 — Claude·Codex·Gemini + Obsidian 30분 셋업 (418) (본편)
- Obsidian Graph View 색상 그룹 완벽 설정법 (419)
- LLM 위키 한국어·영어 자료 동시 처리 완벽 패턴 ← 현재 글
- 2,470개 자료를 76 페이지로 줄이는 distillation 노하우 (2026) — 예정
/wiki-synthesize로 두 개념 교차 분석 페이지 만들기 (2026) — 예정
해결 — CLAUDE.md 언어 정책 4줄 ⭐
💎 핵심 자산 — vault 루트의
CLAUDE.md(또는 Codex의AGENTS.md·Gemini의GEMINI.md)에
다음 섹션을 추가하세요. 이 4줄이 LLM 위키의 한국어 일관성을 결정합니다.
## Language policy
- 한국어 콘텐츠 → 한국어 title·태그·페이지명 유지. 영어로 번역하지 않는다.
- 영어 콘텐츠 또는 글로벌 기술 용어 → 영어 유지
- 파일명은 kebab-case (한글도 적용: `원온원-미팅.md`)
- wikilink·본문은 자연스러운 언어 혼용 허용
✅ 세 도구 공통 적용 가능: Claude Code →
CLAUDE.md, OpenAI Codex CLI →AGENTS.md, Gemini CLI →GEMINI.md. 파일명만 다르고 내용은 동일하게 작동합니다.
AI가 자동으로 영어로 번역하는 이유
Claude·Codex·Gemini 모두 영어 학습 데이터가 압도적입니다. 명시적 지시가 없으면 AI는 다음을 자동으로 합니다.
- 한국어 글의 핵심을 영어로 요약
- 파일명을 영문 kebab-case로 변환
- 태그를 영문 canonical로 정규화
- wikilink 대상을 영어 페이지명으로 생성
본인이 처음 셋업했을 때 한국어 자료 100개를 ingest했더니 약 70%가 영어 페이지로 만들어졌습니다. 원본은 한국어, 결과는 영어 — 검색·이해 모두 비효율적이었습니다.
해결 — CLAUDE.md 언어 정책 4줄
vault 루트의 CLAUDE.md (또는 AGENTS.md·GEMINI.md)에 아래 섹션을 추가합니다.
## Language policy
- 한국어 콘텐츠 → 한국어 title·태그·페이지명 유지. 영어로 번역하지 않는다.
- 영어 콘텐츠 또는 글로벌 기술 용어 → 영어 유지
- 파일명은 kebab-case (한글도 적용: `원온원-미팅.md`)
- wikilink·본문은 자연스러운 언어 혼용 허용적용 전후 비교
| 항목 | Before | After |
|---|---|---|
| 페이지명 | one-on-one-meetings.md |
원온원-미팅.md |
| 태그 | management |
매니지먼트 |
| frontmatter title | One-on-One Meetings |
원온원 미팅 |
| wikilink | [[one-on-one-meetings]] |
[[원온원-미팅]] |
source: 인용 |
영어 번역본 | 한국어 원본 그대로 |
이 4줄로 위키 전체의 언어 일관성이 결정됩니다.
한국어 vs 영어 태그 결정 기준
모든 태그를 한국어로 강제하는 것도, 영어로 강제하는 것도 답이 아닙니다. 자연스러운 사용을 기준으로 합니다.
한국어를 유지하는 도메인
| 도메인 | 한국어 태그 예시 |
|---|---|
| 매니지먼트·HR | 매니지먼트, 리더십, 피드백, 미팅, 평가, 채용, 인재유지 |
| 커리어 | 커리어, 이직, 자격증, 시험 |
| 생활 | 생활, 여행, 재무, 취미, 집안, 양육, 교육 |
| 한국 특수 | 한국, 회사, 세무, 스톡옵션 |
→ 원본 자료가 한국어라 영어로 번역하면 의미가 미묘하게 달라집니다. 매니지먼트와 management는 같은 단어가 아닙니다 — 한국 직장 컨텍스트의 매니지먼트는 미국 management와 미묘하게 다른 뉘앙스를 가집니다.
영어를 유지하는 도메인
| 도메인 | 영어 태그 예시 |
|---|---|
| AI/LLM 기술 | ai, llm, agent, prompt, mcp, rag, transformer |
| 개발 도구 | claude-code, obsidian, cursor, python, docker, aws |
| SW 개념 | architecture, mlops, evaluation, testing, refactoring |
→ 글로벌 기술 용어는 영어가 표준이고 한국어 번역이 어색합니다. vibe-coding을 바이브-코딩으로 쓰는 것보다 영어가 직관적입니다.
파일명 kebab-case (한글 포함)
한글 파일명도 kebab-case로 통일합니다. 공백 대신 하이픈을 씁니다.
| Bad | Good |
|---|---|
원온원 미팅.md |
원온원-미팅.md |
핵심_인재_유지.md |
핵심-인재-유지.md |
CTO합류체크리스트.md |
cto-합류-체크리스트.md |
정보처리기술사 시험준비.md |
정보처리기술사-시험-준비.md |
- macOS와 Windows 모두 공백·언더스코어 처리가 다릅니다
- wikilink에서 공백은 인코딩 문제를 일으킵니다
- Git 호환성 확보
wikilink 혼용 실전 사례
본인 vault의 실제 페이지에서 한국어·영어가 자연스럽게 섞이는 예시입니다.
사례 1. 매니지먼트 페이지에서 AI 개념 참조
# 1-1 미팅에서 AI 도구 활용
[[skills/원온원-미팅]]에서 시니어 개발자에게 [[concepts/vibe-coding]]
도입 의향을 물어볼 수 있습니다. 이때 [[entities/claude-code]] 같은
구체적 도구 이름을 거론하면 대화가 깊어집니다.→ 원온원-미팅(한국어), vibe-coding(영어), claude-code(영어)가 한 문장에 자연스럽게 혼용.
사례 2. 영어 페이지에서 한국 컨텍스트 참조
# Claude Code Authoring Pattern
When applying this pattern to Korean codebases, refer to
[[skills/cto-합류-체크리스트]] for Korea-specific equity considerations
and [[references/정보처리기술사-시험-준비]] for Korean engineer
certification context.→ 본문은 영어, 참조하는 페이지는 한국어. wikilink가 다리 역할.
핵심 원칙
언어를 강제하지 말고 의미를 보존합니다. 원본의 언어가 그대로 살아 있어야 검색이 자연스럽습니다.
자주 발생하는 문제
문제 1. 정책을 추가해도 영어로 만들어진다
CLAUDE.md를 vault 루트가 아닌 다른 폴더에 둔 경우입니다. 반드시 vault 루트에 두어야 모든 CLI가 인식합니다.
문제 2. 기존 영어 페이지를 한국어로 일괄 변경하고 싶다
/wiki-ingest 재실행 시 언어 정책을 보고 갱신합니다. 다만 파일명 변경은 자동으로 안 되는 경우가 있어, 본인이 수동으로 한 번 정리한 뒤 wikilink를 일괄 교체하는 것이 안전합니다.
문제 3. 한국어·영어 같은 의미 태그가 중복된다
매니지먼트와 management가 같이 쓰이면 검색이 분산됩니다. _meta/taxonomy.md에 alias map을 작성해 한쪽으로 정규화하세요.
| Alias | → Canonical |
|---|---|
| `management` | `매니지먼트` |
| `leadership` | `리더십` |
| `career` | `커리어` |문제 4. AI가 한국어 태그를 영문 슬러그로 바꿔버린다
가장 흔한 실수: 언어 정책 한 줄만 넣고 페이지 작성 규칙(Page rules)에 태그 규칙을 빼먹은 경우입니다. CLAUDE.md의 ## Page rules 섹션에도 명시:
- 한국어 태그는 영문 슬러그화 금지 (`매니지먼트` X→ `management`)자주 묻는 질문 (FAQ)
Q. 영어 자료를 한국어로 번역해서 위키화하는 것은 가능한가요?
A. 가능하지만 권장하지 않습니다. AI 번역은 미묘한 의미 손실이 있고, 출처 추적이 어려워집니다. 원문을 그대로 두고 본인이 한국어로 요약 노트를 추가하는 것이 낫습니다.
Q. 한국어 페이지를 영문 검색으로 찾을 수 있나요?
A. Obsidian 검색은 언어 구분 없이 동작합니다. 매니지먼트로 검색하면 한국어 페이지가, management로 검색하면 영어 페이지가 나옵니다. 두 언어로 같은 개념을 찾고 싶다면 둘 다 검색하면 됩니다.
Q. 영어 태그와 한국어 태그를 동시에 쓰면 안 되나요?
A. 의미가 다르면 양립 가능합니다. 본인 vault에는 평가(개인·조직 평가)와 evaluation(AI/LLM eval)이 의미 차이로 양립합니다. 다만 같은 의미의 한·영 중복은 피하세요.
Q. Claude·Codex·Gemini 모두 한국어 정책이 잘 동작하나요?
A. 네. 세 도구 모두 지시 문서의 명시적 지시를 잘 따릅니다. 본인 경험상 Claude가 한국어 태그 일관성이 가장 높았습니다.
Q. AGENTS.md 하나로 Codex·Gemini를 동시에 쓸 수 있나요?
A. 네. Codex와 Gemini 모두 AGENTS.md를 인식합니다. 한 vault에서 두 도구를 번갈아 쓰고 싶다면 AGENTS.md 하나로 통일하는 것이 깔끔합니다.
Q. 일본어·중국어 자료도 같은 패턴이 적용되나요?
A. 네. 한국어를 일본어 또는 중국어로 바꿔서 정책을 추가하면 됩니다. 다중 언어도 가능합니다.
부록 — 본인 vault 언어 분포
본인 vault 76 페이지 언어 분포:
- 한국어 페이지: 약 45개 (60%)
- 영어 페이지: 약 31개 (40%)
- 한·영 혼용 본문: 거의 모든 페이지
태그 분포:
- 한국어 도메인 태그: 14종 (매니지먼트·커리어·학습·리더십 등)
- 영어 도메인 태그: 8종 (ai·llm·agent·coding 등)
- 합계 unique 태그: 101개
→ 도구를 영어로만 강제했다면 한국어 자료의 가치가 절반으로 줄었을 것입니다.
후속 글 예고
- 2,470개 자료를 76 페이지로 줄이는 distillation 노하우 (2026)
/wiki-synthesize로 두 개념 교차 분석 페이지 만들기 (2026)
댓글