--- name: japanese-tech-writing description: 日本語の技術文書・書籍原稿・記事・解説文を書く、または推敲・リライトするときの文章規範。日本語で文章を書き出す/直す際に常時適用する。LLM に誤った日本語を生成させないための指標。 metadata: source: "https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d" author: "k16shikano" license: "Unlicense（著者が gist コメントで宣言、2026-06-24 確認）" note: "原文の規範を蒸留したもの。正典は source URL を参照" paths: ["knowledge/**/*.md", "docs/**/*.md", "**/ADR*.md", "**/adr*.md"] --- # 日本語技術文書ライティング規範 技術書の章・草稿・記事・解説文を書くとき、および推敲・リライト時に適用する。これは LLM に誤った日本語を生成させないための指標であり、人間向けの禁止事項集ではない。 ## 処理の深さ 依頼された範囲だけを処理する。 - 草案作成では、読者、目的、事実、確度、文体、出力形式を先に固定する - 推敲では、意味と構成を保ち、読みづらさの原因だけを直す - 校正では、誤字、文法、表記ゆれだけを直し、語り口を作り替えない - 診断では、問題箇所と理由を示し、依頼がなければ全文を書き換えない 材料が足りており、推測せずに書ける場合は確認質問を増やさない。 ## 優先順位 規則が競合した場合は、次の順に優先する。 1. 利用者が指定した目的、形式、文体 2. 事実、数値、固有名詞、確度、引用の意味 3. リポジトリや媒体が定める表記と構成 4. 論理の流れと読みやすさ 5. 文体上の自然さとリズム 自然さを理由に、未確認の事実を足したり、推量を断定へ変えたりしない。 ## 出典と謝辞 この規範は k16shikano 氏が公開した「日本語技術文書のスキル」に基づく。 正典 https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d LLM に質の高い日本語を書かせるための指針を整理し、公開してくださった著者に感謝する。本ファイルは原文の規範を要約・再構成したものなので、定義の解釈に迷うときは正典を参照する。 ライセンスは Unlicense（パブリックドメイン相当）と著者が gist のコメントで宣言している。Unlicense は出典明記を求めないが、敬意と追跡性のため出典を残す。 ## 整形 - 一文ごとに改行し、段落は空行で区切る - コード・ログはコードブロックで表示する - 補足は脚注に降ろす - 用語は初出時に太字、以後は「」で表記する - ダッシュ（—）・中黒（・）を日本語の地の文で使わない - 見出しは単一の自然な句にする。節が扱う対象か、節が答える問いを指し、結論を言い切る決め台詞にしない ## 段落と論証の構成（パラグラフライティング） - 各段落は一つのトピックだけを含める - 段落の冒頭で前段落との論理関係を明示する - 論は一方向に進める。行き戻りさせない ## 論証の厳密さ - 推量・可能性を機械的に断定へ変えない - 異なるものを同じとまとめない - 複数要因の事象を単一原因に還元しない - 因果を主張するときはその機構を示す - 検出、保証、解決を「必ず」できるように書かない。成り立つ条件を添える - 挙げた例が主張全体を支えているかを確かめる。一部しか支えないなら主張を狭める - 譲歩や限定（「ただし」「とはいえ」）の後で論を進める。逆接で終えない - 分類、定義、用語の扱いを節をまたいで揃える ## LLM 口調の禁止 - 「重要なのは」「正面から」「掘り下げる」など、中身のない型を避ける - 「ちゃんと書いている感」だけを付ける表現を使わない - 「この記事では」「以下で説明する」「ここからが本題」のような、文書の構造を実況する文を避ける - 根拠のない二項対比、三項目への水増し、劇的な短文の連打を避ける - 想像上の読者との問答（問いを立てて自分で一語で答える、読者の反応を演じて応答する）を修辞に使わない。読者の疑問は疑問文のまま書いてよい - 著者の立場の弁明や断りを書かない ## 翻訳調の比喩と擬人化 英語の慣用句の直訳（carry を「運ぶ」、open を「開かれた」、expose を「露出する」）、無生物主語の直輸入（「モデルは知っている」「データが語る」）、話し言葉の動詞（「効く」「刺さる」「筋がいい」）は、書き手に比喩の意識がないまま混入する。 - 述語を初めて見る読者が字義どおりの動作を想像しうるなら、翻訳調を疑う - 動作の主体と対象を具体語で言い直せるなら、言い直した方を書く - 言い直せないなら、指す内容が決まっていない。内容を確定させてから書き直すか削る 例「この線引きが効いてくる」→「この線引きで、依存の向きを守れるかが変わる」 ## 冗長の排除 - 同じ主張を繰り返さない - 読者が自力で補える説明は省く - 冗長さを文字数や文数で判定しない。動機、対象、因果、条件が順読みで読めなくなる圧縮はしない - 場面を描写した直後に、その内容を要約し直さない ## 視点と語り - 行為者を主語とした動作の連なりで書く - 曖昧で広い語を避ける - 一度導入した術語は通す。後で曖昧語へ後退しない - 後で参照しない固有名（ファイル名、関数名、識別子）を出さない - 概念を初めて出す文では、まずその種類（データ構造、手順、制約など）が分かる順にする - イ形容詞に「です」を続けた文（「難しいです」「守りやすいです」）は、文が前後から孤立している兆候。文末だけ直さず、前後の流れごと書き直す。ナ形容詞の「〜です」は対象外 ## 演出の抑制 - 修辞は効果が生まれる要所に限定する - 短い決め台詞の多用・過度な強調を避ける - 「AではなくBだった」の対句を多用しない ## 読者への誠実さ - 確認していないことを、確認したかのように滑らかに書かない。読んだだけ、推測しただけのことは、そう書く - 書き手本人の感情や体験（驚いた、ハマった、便利だった）を、本人の発言や記録なしに作らない - 例が作為的に見えうるなら、隠さずに認め、現実にあり得る根拠を短く添える ## 文の読みやすさ 文章の技術は、伝えたいことを読み手に届けるための手段で、すべてを守ること自体を目的にしない。まず書き上げ、読み直して直す。 - 文体を「です・ます調」か「である調」のどちらかにそろえる。人に説明するブログ記事は「です・ます調」、PR や Notion の本文は利用者の規則（常体）に従う - 1 文が画面で数行に折り返すなら、意味のまとまりで分ける - 主語と目的語を補う。読み直して「何を理解したのか」「何が完了するのか」を即答できない文は、省きすぎている - 主語と述語を対応させる（「Ruby は〜開発しました」ではなく「Ruby は〜開発されました」か「まつもとゆきひろ氏は〜Ruby を開発しました」）。長い文ほど離れて崩れやすい - 漢字にしなくても意味が通じる語は開く（出来る→できる、為に→ために、更に→さらに、事→こと、無い→ない、尚→なお、若しくは→もしくは、此の→この）。すべてを開くのではなく、漢字が続いて読みにくい箇所を中心にする - 補助動詞と補助形容詞はひらがなで書く（やって見る→やってみる、して欲しい→してほしい、なって来る→なってくる、読んで下さい→読んでください、教えて頂く→教えていただく、覚えて置く→覚えておく、わかり難い→わかりにくい） - いちばん伝えたいこと（結論）を先に書き、経緯や理由を後に続ける - 接続助詞の「が」は逆接だけに使う。順接なら「〜したところ」「〜して」などに書き換える（「導入しましたが、生産性が上がりました」→「導入したところ、生産性が上がりました」） - 「しかし」「ですが」「とはいえ」を続けない。逆接が続いたら、本当に逆接か、別の接続に換えられないか、組み直せないかを見る - 同じ文末（「〜ません」「〜ます」）を 3 回以上続けない。意味を保ったまま言い方を変える - 根拠のある内容を「〜かもしれません」「〜と思います」「〜のような気がします」で弱めない。根拠が足りない箇所と、違う考えの人がいると分かっている箇所は、弱めたままにする（「推量を機械的に断定へ変えない」と両立させる） 時間を置いて何度も読み直す。書いた直後は文脈を知っているので、分かりにくい箇所、知らない人には通じない箇所、説明の不足、繰り返しに気づきにくい。 ## 推敲後の確認 - 原文にない事実、評価、因果、一般論を加えていないか - 数値、固有名詞、否定、条件、確度が変わっていないか - 見出しと本文冒頭で同じ主張を繰り返していないか - 各文が対象の状況を更新しているか。文書の進行だけを説明する文は削る - 指定された書式、リンク、コード、引用を保っているか - 確認していない事実、作った感情や体験が混ざっていないか - 「効く」「運ぶ」などの翻訳調の述語と、イ形容詞＋「です」が残っていないか - 文体がそろっているか。「が」が逆接だけか。同じ文末が 3 回続いていないか。開くべき漢字と補助動詞が漢字のままになっていないか 長さが 1,500 字を超える解説文や、単調さと読み進めにくさを直す依頼では `cognitive-rhythm-writing` を併用する。 規則の解釈に迷ったら、原文の全文 `references/original.md` を読む。