yomiyasu란
yomiyasu（よみやす）는 AI 프로그래밍 환경을 위한 일본어 문장 다듬기 스킬입니다. AI가 생성한 일본어의 부자연스러운 표현을 바로잡고, 초안을 더 읽기 쉽고 정보 밀도가 높은 글로 수정합니다.
이 프로젝트는 Codex, Claude Code, Cursor 등의 환경에 로드할 수 있습니다. 단순히 'AI처럼 보이기' 쉬운 단어 몇 개를 바꾸는 것이 아니라, 문장의 주어와 서술 관계, 동작의 주체, 수사적 표현, 정보 구조를 바탕으로 조정합니다.
이 프로젝트는 개인 연구와 창작을 통해 제작되었으며 MIT License로 공개되었습니다. 설계 배경과 말뭉치 검증 과정은 프로젝트 해설 글에서 확인할 수 있습니다.
해결하는 일본어 글쓰기 문제
일반적인 문체 프롬프트는 '解像度', '手触り', '泥臭い'와 같은 단어만 금지하는 경우가 많습니다. 모델이 다른 모호한 단어로 바꿔도 기존의 문법 문제는 사라지지 않습니다. 편집 규칙이 지나치게 많으면 모델이 만들어 낸 단어나 과장된 표현을 사용할 수도 있습니다.
yomiyasu는 주로 다음 문제를 처리합니다.
- 누가 무엇을 실행했는지 문장에 명확히 드러나지 않는 경우
- 'これ', '両者', '片方' 등 의미가 불분명한 지시어를 사용하는 경우
- 개념이나 도구를 의인화된 주어로 사용하는 경우
- '壊れる', '倒す', '効く', '溶かす', '潰す' 등 모호한 비유 동사를 사용하는 경우
- 굵은 글씨, 목록, 고정된 도입부를 반복하면서 실제 단계와 작동 원리는 생략하는 경우
- 원문에 없는 주체, 사양, 면책 문구 또는 일반적인 결론을 추가하는 경우
7가지 핵심 변환 원칙
- 완전한 SVOCM 구조 복원: 개발자, 사용자, 시스템 등의 동작 주체를 명확히 하고 모호한 대명사를 구체적인 명사로 되돌립니다.
- 주체와 표현 목적 구분: 독자를 향한 요구는 명확한 요청으로 작성하고, 기능 설명은 시스템이 무엇을 수행할 수 있는지 분명히 씁니다.
- 무생물 주어 분해: 의인화된 표현을 사람이나 시스템이 실행하는 객관적인 동작으로 바꿉니다.
- 비유 동사를 기술적 작업으로 변경: 처리, 건너뛰기, 종료, 감소 또는 불일치 발생 등의 상태를 직접 설명합니다.
- 불필요한 서론 삭제: '중요한 것은'과 같은 상투적인 표현을 생략하고, 이중 부정과 수사적 대조를 간결한 긍정문으로 바꿉니다.
- 원래 의미 유지: 수치와 기술적 제약을 보존하며, 초안에 없는 사실을 임의로 추가하지 않습니다.
- 문장 길이와 장식 조절: 문장당 평균 30~45자의 일본어 문자를 기준으로 삼고, 문장마다 쉼표를 0~2개로 제한하며 이모티콘, 문장 끝의 콜론, 굵은 글씨와 불필요한 반각 공백을 줄입니다.
yomiyasu 설치
방법 1: skills add 사용
README에서 권장하는 설치 방법입니다. 다음 명령을 실행하면 도구가 Claude Code 등의 에이전트 설정 디렉터리에 스킬을 설치합니다.
npx skills add nanaism/yomiyasu방법 2: Cursor 또는 Codex에서 사용
OpenSkills를 통해 스킬을 설치하고 동기화할 수 있습니다.
npx openskills install nanaism/yomiyasu
npx openskills sync동기화가 완료되면 각 에이전트에서 AGENTS.md를 통해 이 스킬을 사용할 수 있습니다.
방법 3: Claude Code 플러그인 설치
Claude Code에서 다음 순서로 실행합니다.
/plugin marketplace add nanaism/yomiyasu
/plugin install yomiyasu@yomiyasu방법 4: 수동 배치
GitHub Releases에서 yomiyasu.skill을 다운로드하고 압축을 푼 뒤 사용하는 에이전트의 스킬 디렉터리에 넣습니다.
같은 환경에서 다른 일본어 교정 또는 문체 조정 스킬을 활성화한 경우 지시가 서로 충돌할 수 있습니다. yomiyasu를 사용할 때는 기능이 유사한 스킬을 일시적으로 비활성화하는 것이 좋습니다.
기본 사용법
설치가 완료되면 AI 채팅 인터페이스나 프로그래밍 에이전트에 일본어 초안을 붙여 넣고 간단한 다듬기 요청을 입력합니다.
この文章を読みやすくして。
（ここに修正したい文章を貼り付け）용도를 지정하지 않으면 yomiyasu가 입력 내용에 따라 적합한 분야를 자동으로 판단합니다. 초안의 사실, 수치, 기술적 제약은 최대한 유지하면서 주어와 서술 관계, 추상적인 표현, 과도한 장식을 수정합니다.
간단한 예시
원문에 다음과 같은 표현이 있다고 가정해 보겠습니다.
DBの負荷を逃がし、失敗したメッセージを潰していきます。yomiyasu에 비유를 구체적인 작업으로 바꾸도록 요청할 수 있습니다. 프로젝트의 편집 원칙에 따르면 수정 결과는 시스템이 부하를 어떻게 낮추는지, 실패한 메시지를 어떻게 처리하는지를 명확히 설명해야 합니다. 예를 들어 재시도 대기 시간을 늘리고, 정해진 재시도 횟수를 초과한 데이터를 데드 레터 큐로 옮기는 방식입니다. 실제 출력은 전체 문맥에 따라 결정되므로, 한 문장만으로 원문에 없는 사양을 추가해서는 안 됩니다.
용도에 따른 문체 지정
더 안정적인 결과가 필요하다면 프롬프트에서 분야를 지정할 수 있습니다. 프로젝트는 tech, business, essay 세 가지 지침을 제공합니다.
기술 문서: tech
이 모드는 기술 블로그와 코드 설명에 적합합니다. 작업 단계와 구현 메커니즘을 우선적으로 복원하고 불필요한 목록 사용을 억제합니다.
この文章を技術記事向けに読みやすくして。
（ここに修正したい文章を貼り付け）분야를 명시적으로 입력할 수도 있습니다.
ドメイン tech
この文章を読みやすくして。
（ここに修正したい文章を貼り付け）업무 문서: business
이 모드는 사양서, 홍보 자료, 제안서에 적합합니다. 비유를 삭제하고 경계 조건과 책임 주체를 명확히 하는 데 중점을 둡니다.
ドメイン business
この文章を業務仕様向けに読みやすくして。
（ここに修正したい文章を貼り付け）에세이: essay
이 모드는 개인 블로그와 note 글에 적합합니다. 평범한 경험을 교훈으로 과장하지 않으면서 자연스러운 감정과 개인적인 경험을 유지합니다.
ドメイン essay
この文章をエッセイ向けに読みやすくして。
（ここに修正したい文章を貼り付け）내장 검사기로 AI 흔적 정량화
저장소에는 scripts/yomiyasu_lint.py가 포함되어 있습니다. 이 스크립트는 부자연스러운 비유, 과도한 굵은 글씨나 목록, 이모티콘, 문장 끝의 콜론, 같은 문장 어미의 연속 출현 등을 검사할 수 있습니다.
검사기는 Python 표준 라이브러리만 사용하므로 추가 서드파티 패키지를 설치할 필요가 없습니다. Markdown 파일을 검사할 때는 다음을 실행합니다.
python3 scripts/yomiyasu_lint.py README.md보고서에는 총점, 문자 수, 줄 수, 1,000자당 굵은 글씨 수, 목록 비율 등의 정보가 표시됩니다. 규칙에 해당하는 항목이 없으면 결과에 PASS가 표시됩니다.
CI 또는 Git Hook에서 엄격 모드 활성화
--strict를 추가하면 경고가 하나라도 있을 때 스크립트가 종료 코드 1을 반환합니다.
python3 scripts/yomiyasu_lint.py article.md --strict따라서 이 명령을 지속적 통합 과정이나 커밋 전 Git Hook에 넣어 뚜렷한 문체 문제가 있는 글이 다음 단계로 넘어가지 않도록 할 수 있습니다.
고급 사용 팁
먼저 내용을 확정한 뒤 다듬기
yomiyasu의 목적은 표현을 조정하는 것이지 사실 확인을 대신하는 것이 아닙니다. 입력하기 전에 초안의 매개변수, 제한 조건, 기술적 결론을 먼저 확인해야 합니다. 이렇게 하면 의미 유지 원칙을 살리고 다듬는 과정에서 사실이 달라질 위험을 줄일 수 있습니다.
프롬프트에서 독자와 용도 명시
분야명 외에도 글이 개발자를 대상으로 하는지 업무 담당자를 대상으로 하는지 등 필요한 문맥을 초안에 남길 수 있습니다. 프로젝트가 명시적으로 지원하는 것은 세 가지 분야 모드이므로 README에 언급되지 않은 다른 전용 모드가 내장되어 있다고 가정해서는 안 됩니다.
사람의 검토와 lint 병행
검사기는 미리 정해진 규칙이 다루는 형식적 문제를 발견하기 위한 도구이며, 사람의 판단을 대신할 수 없습니다. 먼저 에이전트가 수정하도록 한 다음 yomiyasu_lint.py를 실행하고, 마지막으로 기술적 사실, 어조, 원작자의 문체를 사람이 확인하는 방식을 권장합니다.
저장소 규칙의 출처 이해
핵심 스킬 진입점은 SKILL.md에 있습니다. 문법 변환 원칙과 부자연스러운 어휘 및 구조 목록, 분야별 규칙은 각각 references 디렉터리에 있습니다. 비교 검증 데이터는 evals/comparison_benchmark.md에 있습니다. 스킬의 동작을 연구하거나 조정해야 한다면 이 파일부터 읽어 보세요.
맺음말
yomiyasu는 일본어 다듬기의 초점을 유행하는 개별 단어를 금지하는 방식에서 문법 구조, 주체 관계, 기술적 작업, 정보 밀도로 전환합니다. 적절한 분야별 프롬프트, 사람의 검토, 내장 lint 도구를 활용하면 기술 문서, 업무 문서, 에세이에 적용할 수 있는 AI 일본어 편집 프로세스를 구축할 수 있습니다.