jp-writing

日本語の文章規範。README・技術記事・Zenn・リポ内解説など、日本語で Markdown や文書を新規に書くとき、または既存文書をリライト・推敲するときは必ず適用する。冗長の排除、LLM口調・翻訳調の禁止、型の反復禁止、視点と語りの一貫性、リライト時の一律適用の禁止を定める。

SKILL.md

GitHub

jp-writing

日本語の Markdown・文書を書く/直すときに常に適用する文章規範。README・技術記事・Zenn・リポ内の解説 Markdown を主対象とする。ソースコード内(.astro, .tsx 等)の日本語にも同じ規範を適用する。

使い方

  • 執筆時: 後述の規範に従って書く。プロジェクトに context/conventions.md 等があれば先に読む。書き終えたら「執筆後の点検」を行う。
  • リライト時: 規範に照らして修正する。「リライトの作法」に従う。
  • Zenn リポ(articles/ が存在する): 修正を終えた記事のフロントマターに writing-reviewed: true を付ける。すでに付いている記事は対象外。

リライトの作法

デフォルトは keep(直さずに残す)で、直すのは、その箇所を直すことで読者の得が具体的に言える場合だけにする。ただし、この既定は他人が書いた文と、今回の作業より前からある文に当てる。自分がいま書いた文は、規範をすべて当てて直す。

個々の修正が正しくても、同じ変換を全箇所へ一律に当てると、その処理の均質さ自体が新しい機械臭になる。元の文書が持つ自然な不揃い(節ごとの濃淡、口語の引用、表記の癖)は欠陥ではなく資産であり、実際に読解を妨げている箇所だけを整える。

やらないこと

  • 著者の主張・論旨を変えない。変えるのは表現だけ
  • 著者の意図・方針を新設しない。元文書が未解決のまま置いている論点に見解を書き足さない。本文の「未定」を断定に格上げしない
  • 判断に迷う箇所(意図的な表現か規範違反か区別できない)は修正せず、報告に回す
  • コミット・push はしない。変更はワーキングツリーに残し、ユーザーの指示があったときのみ行う

報告

修正後に以下を報告する:

  • 修正した箇所と理由(規範のどのルールか)
  • 迷って手を付けなかった箇所(あれば)
  • Zenn 記事の場合: writing-reviewed: true を追加した旨

規範

文体

  • ですます調と、である調の混合を許容する。
  • 新規執筆時は、地の文を「ます」調、体験談や所感を「る」調にする程度の自然な混合にする。

整形

  • 段落の区切りは空行で示す。
  • 段落内では、意味の区切りで改行してよい。一文ずつ機械的に改行しない。ベタ書きもしない。改行位置は書き手の判断に委ねる。
  • コード、設定ファイル、ログの断片はコードブロックで示す。
  • 定義や分類の列挙は箇条書きで示してよい。定義される用語は太字にする。
  • ダッシュ(—、――)を日本語の地の文で使わない。補足は括弧()に、言い換えは読点か句点で処理する。

冗長の排除

  • 同じ主張を言い換えて繰り返さない。
  • 場面や例を示した直後に、その内容を要約し直さない。意味づけの一文だけを置く。
  • 接続や評価のためだけの文(「それ自体はよいことである」など)を置かない。
  • 読者が自力で補える中間段階の説明は書かない。
  • 想像上の読者との問答を修辞として使わない。主張はそのまま述べる。
  • 「重要なのは〜である」のような前置きで主張を予告しない。主張をそのまま書く。
  • 「この状況を解決するために」のような、次に書く内容を予告するだけの文は省く。

LLM口調の禁止

次のような言い回しは、中身のない型である。使わない。単体では日常語のものもあるため、機械的な語狩りではなく頻度と文脈で判断する。

  • 予告と総括: 「本記事では〜を扱う」「まとめると」「要するに」(直前の言い換えだけのとき)、「〜に他ならない」
  • 空虚な形容: 「不可欠」「核心的」「鍵となる」「根本的な」「多角的」「包括的」
  • 空虚な動詞: 「掘り下げる」「深掘りする」「言語化する」(何をどう書いたかを示さず終わる)
  • 姿勢だけの宣言: 「正面から扱う」「正面から論じる」(何をどう論じるかが一切増えていない。扱う内容そのものを書く)
  • 弱い緩和: 「〜と言えるだろう」「〜かもしれない」「〜のではないでしょうか」(根拠なく主張を弱めている場合のみ削る。推量・仮定・読者の疑念を表す場合は残す)
  • 予防線の積み上げ: 「一概には言えないが」「あくまで一例だが」(頻出すると何も言っていない文章になる。言い切れないなら条件を具体的に書く)
  • 空虚な強調: 「非常に」「極めて」「大いに」
  • 無理な三点整理: 「大きく分けて3つの」と先に数を決めてから列挙する型。論点の数だけ書く。

翻訳調の禁止

日本語として成立していても、英語の構文を透かして見える言い回しは避ける。

  • 「〜することができる」(can の直訳): 可能形か「〜できる」に。「〜することが可能です」も同様。
  • 「〜することによって」(by ~ing の直訳): 「〜すると」「〜すれば」に。
  • 無生物主語 + 他動詞: 「この事実は〜を示している」→「この事実から〜と分かる」。主語を人や状況に戻すか、述語を状態描写に変える。
  • 「〜という観点から」「〜という点で」: 「〜で見ると」「〜については」で足りる場面に機械的に挿入しない。
  • 「〜を持つ」(抽象名詞が目的語のとき): 「この決定は大きな意味を持つ」→「この決定には大きな意味がある」。

視点と語り

  • 対象を指す語は具体的に選ぶ。「AI」「ツール」のような広い語でぼかさない。記事内で名前がある対象は名前で呼ぶ。
  • 術語・固有名を導入したら、以後はその語で通す。曖昧語に後退しない。
  • 内輪の呼び名や比喩を術語にしない。その語だけを見て、初めて読む人が中身を言えないなら、中身をそのまま書く。術語として入れるなら、初めて出るところで何を指すかを書く。
  • 技術用語は和語の比喩に置き換えず、通用している呼び名で書く。git の branch は「ブランチ」と書き、「枝」と呼ばない。
  • 例示では、結果の羅列や受動態ではなく、行為者を主語にした動作で書く。
  • 「入社2年目のエンジニアが」のような架空の人物設定を無意味に冠しない。

型の反復禁止

  • 同じ鋳型を3回続けない。定義文の型(「Xは〜ではない。〜である。」)、文の書き出し(数字→数字→数字)、文末の形(体言止めの連続、「〜だ。〜だ。」)のいずれも、3回目は入り口か構造を変える。
  • 「〜ではなく、〜」の否定→肯定対比は、読み手が実際に誤解していそうな場面に限る。単なる言い換えの強調に使わない。見分け方は、対比の後半だけで文が成立するかどうか。
  • 段落あたりの文数・厚みを揃えない。重要な節は厚く、軽い節は正直に軽く書く。全節が同じ厚みに見える構成は、それ自体が機械臭になる。

演出の節度

全面禁止ではなく、節度の規範。

  • 太字強調を多用しない。誤読を防ぐ否定や帰結など、論理の要所に限る。
  • 太字の両端に句読点や括弧を置かない。** の外側に和文が続くと GitHub では太字にならず、** がそのまま出る。句読点や括弧は ** の外に出す(**〜する**。、「**〜**」)。
  • 短い決め台詞を独立段落にする演出は、記事の山場に限る。
  • 「〜してはならない」より「〜するわけにはいかない」のような判断の形を選ぶ。
  • 慣用表現をひねった比喩や、指す内容が一意に決まらない比喩を使わない。平易な動詞でそのまま言う。

執筆後の点検

  • スケルトン通読: 見出しと各段落の先頭文だけを抜き出して読み、論旨が通るか確かめる。細部を読み直すより構成の乱れを見つけやすい。
  • 素材不足の判別: 段落から固有名詞・数値・実例をすべて抜いても文意が変わらないなら、それは一般論止まりのサインである。原因は書き方でなく素材の不足にあり、言い回しの修正では解決しない。素材を集め直すか、ないなら空欄・要確認として残す。