코딩 에이전트를 한국어로 쓰다 보면 묘하게 피곤할 때가 있다. 단어 하나하나는 한국어인데, 문장 전체는 잘 읽히지 않는다.
원인 확인 완료. 설정 변경 필요. 다음 단계 진행 가능.
뜻을 짐작할 수는 있다. 하지만 누가 무엇을 확인했고, 어떤 설정을 바꿔야 하며, 무엇을 해야 다음 단계로 갈 수 있는지는 독자가 직접 복원해야 한다. 짧게 쓰려다가 문장에 필요한 정보까지 생략한 결과다.
fluent-korean은 이 문제를 해결하려고 만든 오픈소스 지침이다. 처음에는 Claude Code용 output style로 공개되었지만, 지침 본문을 다른 AI 환경에도 넣을 수 있도록 구성되어 있다. 나는 이 지침을 Codex용 스킬로 옮겨 사용해 보았다.
결론부터 말하면, 효과는 분명했다. 답변이 화려해진다기보다, 사람이 문장을 해석하면서 치러야 하는 비용이 줄었다. 다만 모든 문장을 자동으로 잘 쓰게 만드는 교정기는 아니며, 긴 작업이나 지침이 많은 환경에서는 적용 강도가 약해질 수 있다.
사람이 생략된 의미를 복원하는 대신, AI가 처음부터 관계가 드러나는 문장을 만들게 했다.
이 프로젝트가 해결하려는 문제
이 저장소가 추구하는 목표는 “사람처럼 보이는 한국어”가 아니다. README는 수려한 문체보다 의미가 확실하게 전달되는 문장을 우선한다고 밝힌다.
저장소가 지적하는 문제는 크게 네 가지다.
- 조사와 어미가 빠진다.
- 문장이 명사구나 연결어미로 끝난다.
- 주어, 목적어, 수식 대상이 생략된다.
- 평범한 설명에 과도한 비유나 압축 표현이 들어간다.
이 문제들은 맞춤법 검사만으로는 잡히지 않는다. “설정 변경 필요”는 맞춤법상 틀린 표현이 아니기 때문이다. 문제는 문법 오류보다 의미 관계의 손실에 가깝다.
fluent-korean은 그래서 문장을 더 자연스럽게 꾸미기보다, 독자가 생략된 관계를 추론하지 않아도 되게 만든다. 저장소가 번역체 제거 도구나 AI 문체를 숨기는 humanizer와 자신을 구분하는 이유도 여기에 있다.
구현은 놀랄 만큼 단순하다
저장소에는 언어 모델도, 형태소 분석기도, 실행 코드도 없다. 핵심 구현은 Markdown 파일 두 개다.
fluent-korean.md는 Claude Code의 코딩 지침을 유지한다.fluent-korean-not-coding.md는 코딩 지침을 유지하지 않는다.
두 파일의 본문은 거의 같다. 코딩용 파일에 keep-coding-instructions: true가 있고, 한국어로 작성된 서브에이전트 프롬프트에도 같은 기준을 적용하라는 조항이 추가되어 있다. 나머지는 모델이 한국어를 생성할 때 따라야 할 규칙과 Before/After 예시다.
Claude Code에서는 플러그인이 이 Markdown을 output style로 등록한다. 사용자가 스타일을 선택하고 새 세션을 시작하면 지침이 모델의 상위 프롬프트에 포함된다. 다른 AI에서는 같은 본문을 개인 지침, 프로젝트 지침 또는 스킬이 참조하는 문서로 넣으면 된다.
구조를 단순화하면 다음과 같다.
사용자의 요청
↓
fluent-korean 지침이 포함된 프롬프트
↓
모델이 다음 토큰을 선택할 때 문장 완결성과 의미 관계를 함께 고려
↓
한국어 답변
↓
출력 직전 조사·어미·생략·비유 표현을 다시 점검
중요한 점은 이 도구가 완성된 문장을 받아 변환하는 후처리 프로그램이 아니라는 사실이다. 모델이 처음부터 어떤 문장을 생성할지에 관여한다.
Codex에는 어떻게 옮겼나
Claude Code의 output style을 Codex에 그대로 설치할 수는 없다. 두 제품의 확장 방식이 다르기 때문이다. 대신 원문의 역할을 두 층으로 나누었다.
첫 번째 층은 업스트림 지침 원문이다. Codex 스킬 안에 references/upstream-fluent-korean.md로 보존했다. 현재 로컬 사본은 기준으로 삼은 업스트림 커밋의 코딩용 지침과 내용이 같다.
두 번째 층은 Codex용 SKILL.md다. 이 파일은 새로운 문체 규칙을 만들지 않는다. 다음 동작만 담당한다.
- 한국어 답변이나 한국어 문서를 작성할 때 스킬을 활성화한다.
- 요약본이 아니라 업스트림 지침 전체를 읽는다.
- 사용자에게 보이는 모든 한국어 문장에 지침을 적용한다.
- 코드, 로그, 식별자, 인용문에는 적용하지 않는다.
- 출력 직전에 생략된 문장 성분, 명사구 종결, 조사와 어미, 불필요한 비유를 다시 확인한다.
프로젝트의 AGENTS.md에는 사용자가 한국어로 대화하면 이 스킬을 기본 적용하도록 적었다. 결과적으로 적용 경로는 다음과 같다.
AGENTS.md가 한국어 작업을 감지
↓
Codex가 fluent-korean 스킬을 선택
↓
SKILL.md가 업스트림 지침 전체를 로드
↓
답변 작성과 최종 점검에 적용
이 방식의 장점은 원문과 플랫폼별 연결부를 분리했다는 점이다. 원문이 바뀌면 참조 문서만 비교해서 갱신할 수 있고, Codex에서 언제 발동할지는 SKILL.md와 AGENTS.md에서 관리할 수 있다.
새로운 한국어 처리기를 만든 것이 아니라, 원문 지침과 Codex의 적용 경로만 연결했다.
왜 이런 지침이 작동하는가
언어 모델은 규칙 기반 교정기처럼 문장을 만든 뒤 고치는 방식으로만 동작하지 않는다. 앞에 주어진 지시와 예시를 바탕으로 다음에 올 표현의 가능성을 계속 조정한다.
fluent-korean은 이 특성을 세 가지 방식으로 활용한다.
1. 금지보다 대안을 함께 준다
“명사구로 끝내지 마라”에서 멈추지 않고, 서술어와 종결어미를 사용해 완성된 문장으로 끝내라고 지시한다. 모델이 피해야 할 형식과 선택해야 할 형식을 함께 알 수 있다.
2. 추상적인 품질 기준을 관찰 가능한 항목으로 바꾼다
“자연스럽게 써라”는 사람에게도 모호하다. 반면 “조사를 생략하지 않는다”, “수식 대상을 밝힌다”, “엠대시 대신 접속사로 관계를 드러낸다”는 출력에서 확인할 수 있다. 지침이 구체적일수록 모델도 일관되게 적용하기 쉽다.
3. 지침 자체가 원하는 문체의 예시가 된다
모델은 명시적인 명령뿐 아니라 주변 문장의 어휘와 리듬에도 영향을 받는다. 저장소는 이를 어휘 priming으로 설명하며, 지침 본문 자체도 가능한 한 같은 원칙으로 작성했다고 밝힌다. 즉, 규칙을 설명하는 문장도 동시에 few-shot 예시처럼 작동한다.
다만 “저품질 한국어가 모델의 추론 품질까지 낮춘다”는 저장소 저자의 문제 제기는 아직 공개된 정량 실험으로 입증된 결론은 아니다. 현재 공개 저장소의 원리 문서도 작성 중이다. 이 부분은 가능한 가설로 다루는 편이 정확하다.
실제로 써보니 무엇이 달라졌나
상태를 나열하는 데서 그치지 않고, 무엇을 했고 무엇을 아직 하지 않았는지 연결해서 설명한다.
가장 먼저 체감한 변화는 문장의 길이가 아니라 책임 소재와 조건이 선명해졌다는 점이었다.
- “설정 확인 필요”를 “새 세션에 적용하려면 설정 파일의 스킬 경로를 확인해야 합니다”로 바꾸면, 무엇을 왜 확인하는지 드러난다.
- “검증 후 진행 가능”을 “브라우저에서 로그인 흐름을 검증한 뒤에 배포를 진행할 수 있습니다”로 바꾸면, 검증 대상과 다음 행동이 연결된다.
- “이 결정은 이후 중요 정책이 갈리는 자리”를 “이 결정은 이후의 중요한 정책에 지속적으로 영향을 줍니다”로 바꾸면, 명사 나열이 완결된 판단이 된다.
- “코드로 박아 둔다”를 “설정값을 코드에 명시한다”로 바꾸면, 비유 대신 실제 행동을 설명할 수 있다.
긴 개발 작업에서는 중간 보고가 특히 읽기 편해졌다. “수정 완료, 테스트 통과, 배포 미진행”처럼 상태표만 나열하는 대신, 무엇을 수정했고 어떤 테스트가 통과했으며 배포는 왜 진행하지 않았는지가 문장 안에서 연결된다. 사용자는 누락된 맥락을 되묻는 횟수를 줄일 수 있다.
공유 문서에서도 효과가 있었다. 모델에게 단순히 “자연스럽게 써줘”라고 요청하면 문장이 과장되거나 원래의 근거 수준이 달라질 때가 있다. 이 스킬은 사실과 구조를 보존하라고 명시하므로, 내용을 새로 꾸미기보다 관계가 빠진 문장을 복원하는 방향으로 작동한다.
반대로 비용도 있다.
- 조사와 문장 성분을 복원하므로 출력 토큰이 조 금 늘어난다.
- 짧은 상태 목록에서는 문장이 다소 길게 느껴질 수 있다.
- 다른 시스템 지침이 많거나 작업이 길어지면 문체 규칙의 영향이 약해질 수 있다.
- 창작물, 대사, 브랜드 카피처럼 별도의 문체가 중요한 결과물에는 일괄 적용하면 안 된다.
- 코드와 로그까지 억지로 한국어화하지 않도록 적용 범위를 분리해야 한다.
이번 평가는 현재 Codex 세션과 실제 작업 문서를 관찰한 정성 평가다. 동일한 모델과 프롬프트를 여러 번 실행한 통제 실험은 아니므로, 품질 향상률이나 토큰 증가율을 수치로 주장할 수는 없다. 제대로 비교하려면 같은 작업 20개 이상을 스킬 적용 전후로 실행하고, 의미 누락, 재질문 횟수, 문장당 토큰 수를 함께 측정해야 한다.
잘 작동하게 만든 핵심은 설치보다 적용 범위였다
처음에는 Markdown 파일을 복사하면 끝이라고 생각하기 쉽다. 실제로는 어느 시점에, 어떤 출력에, 얼마나 강하게 적용할지가 더 중요했다.
내 환경에서는 다음 구성이 가장 실용적이었다.
AGENTS.md는 한국어 작업에서 스킬을 자동으로 선택하게 한다.SKILL.md는 전체 지침을 읽고 최종 점검하도록 지시한다.- 업스트림 원문은 별도 참조 파일로 보존한다.
- 코드, 로그, 커밋 메시지, 고유 형식은 적용 대상에서 제외한다.
- 창작이나 브랜드 문체처럼 별도 규칙이 있는 결과물은 해당 규칙을 우선한다.
매번 사용자가 $fluent-korean을 직접 입력하게 만드는 것보다 안정적이었고, 원문 전체를 전역 시스템 프롬프트에 항상 넣는 것보다 적용 범위를 관리하기 쉬웠다. 이 스킬이 한국어 작업에서만 로드되므로, 관계없는 세션의 컨텍스트를 차지하지 않는다는 장점도 있다.
이 사례에서 얻은 결론
fluent-korean의 흥미로운 점은 기술적으로 복잡하지 않다는 데 있다. 이 프로젝트는 한국어 전용 모델을 만들지 않았고, 형태소 분석 파이프라인도 추가하지 않았다. 대신 “좋은 한국어”라는 모호한 요구를 모델이 실행할 수 있는 작은 판단 기준으로 나눴다.
효과의 중심도 문장의 아름다움이 아니다. 누가 무엇을 했는지, 어떤 조건에서 다음 행동이 가능한지, 수식어가 무엇을 가리키는지가 분명해진다. 코딩 에이전트와 오래 협업할수록 이 차이는 크다. 사용자가 문장을 해독하는 데 쓰던 시간을 실제 결정에 사용할 수 있기 때문이다.
따라서 이 도구를 한국어 humanizer로 소개하면 절반만 설명한 셈이다. 더 정확한 설명은 다음과 같다.
fluent-korean은 AI의 한국어를 사람처럼 위장하는 도구가 아니라, 사람이 AI의 한국어를 다시 해석하지 않아도 되게 만드는 생성 지침이다.
