coji/natural-japanese

What it solves

It addresses the "AI-smelling" quality of Japanese text generated by LLMs, which often feels mechanical, repetitive, or like a direct translation from English. The project provides a system to transform these outputs into clear, professional, and natural-sounding Japanese suitable for business documents, blogs, and essays.

How it works

The project operates as an "Agent Skill" that integrates mechanical detection with AI judgment through a three-step process:

1. Pre-writing Design: It establishes the reader, main message, and heading skeleton before generation begins.
2. Generation Constraints: It applies a "writing constitution" consisting of 12 style rules (e.g., "start with the conclusion," "avoid repeating the same pattern three times") to prevent AI-like patterns from occurring.
3. Mechanical Detection & Iteration: It uses a Python-based linting tool (lint.py) powered by sudachipy for morphological analysis to identify forbidden phrases, monotonous rhythms, and translation-style syntax. The AI then reviews these findings and iterates on the text until the patterns are resolved.

Additionally, it includes specialized scripts for extracting outlines and terms, and an experimental semantic analysis tool to detect "flatness" in topic progression using sentence embeddings.

Who it’s for

Professionals and writers who use AI to draft business documents (minutes, reports, guides, research memos), slide structures, or public-facing content like notes, blogs, and essays in Japanese.

Highlights

• Hybrid Detection: Combines deterministic mechanical linting (to find what AI often misses about itself) with AI-driven contextual judgment.
• Style Constitution: A set of 12 strict rules to constrain generation at the source rather than just fixing it afterward.
• Reading Load Analysis: A specific mode (--reading-load) to flag long sentences, double negatives, and excessive kanji chains.
• Iterative Convergence: A loop that tracks differences between versions using a baseline to ensure the text converges toward a natural state.
• Agent Integration: Easily installable as a skill for Claude Code and other agents via npx skills add or openskills.