Writing Ja

writing-ja

日本語の技術記事、ブログ記事、解説文の本文を扱うための推敲スキル。 目標は、文章を均質な「きれいな文章」に寄せることではない。 読者が事実、理由、判断の順に無理なく追えて、書き手が実際に知っている範囲を正確に受け取れる状態にする。

使う範囲

新しく書く本文、または依頼で指定された推敲範囲に使う。 一文だけの言い換えにも使えるが、見出し構成、記事の順序、タイトル、導入、結論、検索意図の判断は、blog-writing-guide-ja がある環境ではそちらに任せる。ない環境では、依頼範囲を記事全体へ勝手に広げず、依頼された本文の範囲だけを推敲する。

本文を書き換えない依頼は、このスキルの仕事ではない。一文一行への整形、脚注や記号の統一のような体裁だけの作業、言葉づかいが失礼でないかという確認だけの依頼、翻訳は、文の中身を判断せずに済むため、この規範を持ち出すと依頼していない書き換えを招く。そのまま依頼された作業だけを行う。

次のものは、意味を変えないために原則として編集しない。

• コード、コマンド、ログ、設定値、ファイルパス、URL
• 引用、一次資料の表記、製品名、API名、エラー文
• front matter と、依頼範囲外の文章

ローカルの表記規約がある場合は、その規約をこのスキルより優先する。

まず守る境界

推敲は情報を補完する作業ではない。 書き手が示していない出来事、感情、利用経験、比較結果を追加しない。 根拠が不足している主張は、もっともらしい説明で埋めず、根拠を尋ねるか主張の範囲を狭める。

文章中の内容を、次の三種類として扱う。

• 事実: 観測結果、仕様、引用できる資料、実施済みの作業
• 推測: 条件付きの見通し、未確認の原因、再現できていない説明
• 判断: 書き手の選択、評価、好み、方針

事実は出所や条件を失わないようにする。 推測は断定に変えない。 判断は、書き手が実際に述べたものだけを残す。 この区別が曖昧な文では、文を分けるか、主語と根拠を明示する。 無生物や抽象概念を主語にした表現では、責任主体や観測条件が隠れて因果が曖昧にならないかを確かめる。 「〜と考えられている」「対応が求められている」のような受動態が重なるときも同じで、誰が観測し、誰が判断したかを確かめる。 表現自体を機械的に避けず、誰が何を観測、判断、実施したかが必要な場面だけ補う。

短くすること自体は目的ではない。 削除によって条件、例外、再現手順、判断の理由が失われるなら、その情報は残す。 専門用語も、正確さを保つために必要なら言い換えない。

編集の進め方

1. 読者が受け取る結論を確かめる

対象範囲ごとに、何が分かればよいかを一文で捉える。 結論が先に分かっている場合は、後続の説明がその結論を支えているか確認する。 結論が未確定なら、未確定である理由と、次に必要な確認を分けて書く。

節や段落の役割が重複しているときは、同じ内容を繰り返さず、片方を削るか役割を分ける。 読者へのあいさつ、これから説明するという予告、直前の内容を言い直すだけのまとめは、理解に寄与しなければ外す。 段落の導入や独立した短文では、対象の状況、事実、判断を新たに伝えているかを確かめる。 本文の進行だけを説明する文は、範囲、手順、例外を理解させるために必要な場合を除き、削るか対象の情報に書き換える。

2. 論理の接続を直す

一段落では、一つの問いかけに答える。 段落の冒頭で扱う対象を示し、その後で理由、条件、具体例のどれが続くのかを分かるようにする。 段落をまたぐときは、追加、対比、条件、結果のどれなのかが読める順番に置く。 接続詞は、その関係を示す必要があるときだけ使う。段落の書き出しを整えるためだけに、同じ接続詞を繰り返さない。

因果を述べるなら、原因と結果の間にある仕組みを書く。 例えば性能が変わったなら、何の処理や待機が減ったのかを示す。 事実の後に、根拠のない将来性や意義を付け足さない。

一つの例が支えられる範囲を超えて、一般論に広げない。 複数の原因や対象がある場合は、同じ言葉でまとめず、それぞれの関係を分けて説明する。 「場合による」などの留保で結論を終えるときは、その条件が判断に必要かを確かめる。 条件を示せないなら、書き手の判断を示すか、主張の範囲を狭める。

3. 文を情報の単位に戻す

一文に、主張、背景、例外、評価を詰め込みすぎない。 読点でつながった情報が別の役割を持つなら、文を分ける。 逆に、同じ主語で並ぶ短い文が続くなら、意味を損なわない範囲でまとめる。

修飾語は、長いものを先に、短いものを述語の近くに置く。 短い修飾語を先に出すと、後から来る長い修飾語がどこに係るのか、読み終えてから組み直すことになる。 読点は、息継ぎではなく文の構造の切れ目に打つ。長い修飾語が並ぶならその境界に打ち、事情があって短い修飾語を先に出したなら、逆順であることを示すために打つ。切れ目のない位置の読点は削る。

主語と述語は近づける。 間に長い連体修飾節が入ると、読者は主語を覚えたまま読むことになる。書き手も、「〜の理由は」で始めて「〜する」で終わるねじれを起こしやすい。 「〜が、〜が、」と接続助詞の「が」を一文に重ねない。逆接なのか単純接続なのかが読めなくなり、文も伸び続ける。 語順、主述の距離、受動態の改稿例は references/examples.md にある。直し方に迷う文が出たら開く。

指示語は、直前の文脈だけで対象が一つに決まるときに使う。 複数の候補がある場合は、対象の名詞を書き直す。 技術用語は、導入時に必要な説明を添え、その後は同じ意味で使い続ける。 読者が初出の技術用語を知らない可能性がある場合は、先に機能や挙動を示してから名称を添える。 専門読者にとって既知の用語は、そのまま名前で書く。

抽象語や大きな形容詞は、観測可能な内容に置き換えるか、削る。 観測可能とは、数字、対象範囲、操作、制約、引用元のいずれかで示せることをいう。 「有効」「安全」「簡単」といった評価語だけで結論にせず、評価する対象、判断材料、成り立つ条件のうち必要なものを足す。 資料を示せない内容は、一般的な事実のように扱わず、書き手の判断として表す。

行為を表すときは、何をするのかが分かる動詞を選ぶ。意味が薄くなる抽象動詞や名詞化へ置き換えない。 意味や条件を変えないなら、「〜することができる」「検証を行う」のような冗長な名詞化や可能表現は簡潔にする。 動詞の連用形をそのまま名詞にした「直り」「気づき」「学び」も、何がどうなったのかがぼやける。述語の形に戻し、そのときに主語も一緒に書く。「直りを証明する」は「誤発火が直ったことを証明する」になる。

4. 回りくどい言い方と難しい語を減らす

定着した呼び名がある対象は、その名前で呼ぶ。 「パッケージの入口からexportしたもの」は「公開API」で足りる。 説明的に言い換えるのは、その名前をまだ読者に渡していないときだけにする。

逆に、一度説明した対象を「この縛り」「この仕組み」のような抽象名詞で受け直さない。 読者が何を指すのか探し直す。対象の名前か、その中身をもう一度書く。

主張は、形の勢いではなく中身で締める。標語や比喩(「Xは約束だ」)、対句(「AはPを教える。BはQを教える」)、三連の反復(体言止めを三つ続ける、否定を三つ重ねてから種明かしをする)は、言い切った感じは出るが、読者には「結局どういうことか」が残る。 何が起きるか、誰がどのコストを払うかという、観測可能な内容に置き換える。 名前で呼ぶ改稿と、形で締めた文の言い換えの例は references/examples.md にある。

硬い漢語は、同じ意味の日常語があるなら日常語にする。 冪等→何度呼んでも安全、担保する→守る、迂回する→飛ばす、温存する→残す、齟齬→ずれ、枯渇する→なくなる、推敲→手直し、迂言→回りくどい言い方。 その分野で意味が固まっていて、言い換えると内容が変わる用語（ヒューリスティック、フォールバックなど）は残す。 残す場合は、先に何が起きるかを書いてから名前を添える。

道具や規範そのものを説明する文章では、その道具が内部で使う用語を本文へ持ち出さない。 推敲、迂言、漢語、体言止めのような、書き方を語るための言葉がこれにあたる。 読者が受け取りたいのは何が起きたかであって、書き手が判断に使った枠組みの名前ではない。 「硬い漢語を減らした」は「難しい言葉を減らした」で足りる。

用語をそのまま使うかどうかは、読者の知識、意欲、目的で決める。 何を前提として知っていて、どれくらい読みたがっていて、何を求めて読むのかを想定する。 迷ったときは、その語を残すことが読者の負担を下げるかで判断する。

二重否定は、読者に符号を反転させる。「できないわけではない」は「条件つきでできる」と書く。 カタカナ語を密集させない。和語や漢語より意味の輪郭がぼやけ、読者の語彙背景で理解が変わる。 漢字が続きすぎると語の切れ目が見えなくなる。文書全体で2〜3割を目安にし、それを超えるならひらがなに開くか、語を分ける。

5. 文体を文書に合わせる

技術記事では、本文全体で常体か敬体の基調を決める。 常体は判断や技術説明を直接伝えたい本文に、敬体は案内や対外文書に向く。 体言止めや短文は、情報を区切る効果がある場所だけで使う。

同じ終わり方が連続して単調に見えるときは、文の長さ、主語の省略、語順のどれを変えるかを選ぶ。 対象範囲を通して似た文長や段落ごとの文数が続くときは、どこで情報の重みや関係が変わるかを見直す。 主張を短く切り出すか、密接な関係を一文に畳むかは内容に応じて選ぶ。文を短くそろえたり、長短を交互に置いたりして、変化だけを作らない。 日本語として自然なら主語を省くが、責任の所在、観測者、条件が変わる場所では省かない。 見出しと、節の結論を述べる文でも省かない。読者は本文を読む前に見出しを読むので、「何が」を補う文脈がまだ手元にない。

既存の一人称、口調、率直な留保は、書き手の声として尊重する。 反対に、原文にない体験談、感想、熱意、親しげな呼びかけを追加して人間味を演出しない。 リズムや構文の反復を見つけても、それだけで不自然と決めつけない。正確さや意図した並列性に必要な場合は残し、判断が必要なレビューでは理由を短く示す。

Markdown と文書の形

見出し、箇条書き、表は、情報の関係が実際にそうなっているときだけ使う。 見出しの分割数と項目数は、内容が決める。

一文ごとの改行、強調記法、脚注、記号の扱いは、対象リポジトリまたは媒体の規約に従う。これは本文を推敲する過程で書式を壊さないための指針であり、体裁の統一だけを依頼されたときにこのスキルを持ち出す理由にはならない。 規約がなければ、同じ文書内で一貫させ、読解を妨げる装飾を増やさない。 本文の意図に対応しない装飾記号や、壊れた Markdown の残骸は取り除く。

仕上げの確認

推敲後、対象範囲を元の意図と照合する。 全項目を確認し終えた時点で推敲を終える。

• 「まず守る境界」— 事実、推測、判断の境界。原文にない経験や感情。責任主体や観測条件を隠した無生物主語
• 「1. 読者が受け取る結論」— 段落と節の役割の重複。予告や言い直しの残り
• 「2. 論理の接続」— 主張を支える理由、条件、根拠。段落間のつながりが追えるか
• 「3. 文を情報の単位に戻す」— 修飾語の順序、読点の位置、主語と述語の距離。抽象的な評価が観測可能な内容になったか
• 「4. 回りくどい言い方と難しい語」— 名前で呼べる対象、形で締めた結論、日常語で書ける硬い漢語やカタカナ語、本文へ漏れた道具の用語
• 「5. 文体を文書に合わせる」— 対象読者と媒体への適合。見出しと結論文の主語。技術用語やコードの意味を壊していないか
• 全体 — 読みやすさのために情報量や書き手の声を削りすぎていないか。同じ型の言い換えを一律に当てて、文長や濃淡を均質にしていないか

必要であれば、声に出して読んだときにつまずく長い文や、参照先が曖昧な指示語を最後に直す。

書き手から「この語が難しい」「この言い回しが気になる」と個別に指摘されたときは、指摘された箇所を直して終わりにしない。 指摘は書き手が目に留めた例であって、全件の一覧ではない。 同じ種類の語や言い回しが他に残っていないか本文全体を走査してから返す。 硬い漢語を1語指摘されたなら、残りの硬い漢語も同じ基準で見直す。走査せずに返すと、書き手が同じ種類の指摘をもう一度書くことになる。

定型表現の候補を機械的に探す

このスキルディレクトリ内の scripts/check_style.py は、内容のない予告、根拠のない結論の強調、一般論から始める導入、抽象的な宣伝語、根拠を要する形容詞、埋め草、コード直後の締め、日常語にできる硬い漢語、回りくどい言い回し、em ダッシュを候補として報告する。さらに、同じ語尾の3文連続、240字を超える段落、4項目以上の連続した箇条書き、接続語（さらに・また・加えて）の過多も確認する。報告は文脈を見て判断する WARN であり、機械的に置換しない。WARN は1件ずつ、直したか、残す（理由を添える）かに仕分ける。全件の仕分けが済んだ時点でこの工程を終える。

太字と行末のコロンは --strict を付けたときだけ報告する。用語の強調や箇条書きの導入といった正当な用法が多く、既定で報告すると仕分けの手間が増えるわりに直す箇所が少ない。装飾が多すぎると感じた原稿にだけ付ける。

保存済みの原稿には次を実行する。

python3 "$SKILL_DIR/scripts/check_style.py" content/posts/example.md

SKILL_DIR はこのスキルをインストールした writing-ja ディレクトリを指す。front matter、引用、fenced code block、インラインコードは自動的に除外する。チャット上など、まだファイルにしていない本文は、標準入力を表す - を指定して同じ検査を使える。閾値は --help で確認できる。実行できない場合は、この節に挙げた候補を本文から目視で確認する。