| name | japanese-tech-writing |
| description | 日本語の技術文書の文章規範。整形（引用ブロック、脚注、コラム記法）、段落と論証の構成（パラグラフライティング）、論証の厳密さ（ツッコミどころの除去）、読み手の負荷の管理、視点と語り、演出の抑制、LLM っぽい空句の禁止、冗長の排除を定める。日本語で解説文・草稿・記事を書くとき、GitHub Issue や PR の本文を書くとき、英語ドキュメントを日本語に翻訳するとき（README.ja.md など）、または推敲・リライトするときに使用する。 |
日本語技術文書の文章規範
日本語で技術的な原稿（解説文、記事、Issue や PR の本文、README）を書く・推敲するときは、以下の規範に従う。
文体（敬体・常体）
このリポジトリの日本語ドキュメント（README.ja.md など）と GitHub Issue / PR の本文は、
敬体（ですます調）で書く。AGENTS.md や SKILL.md のような作業規範の文書は、簡潔にするため常体
（だ・である調）で書く。どちらの場合も、一つの文書のなかで敬体と常体を混在させない。敬体にするのは文末の述語だけで、連体修飾節や接続・条件の形（「〜する場合」「〜すると」
「〜であり」）は常体のままにする。見出しや純粋な体言止めのラベルには繋辞を付けない。
整形
- 段落の区切りは空行で示す。
- コード、差分、ログ、設定ファイルの断片はコードブロックで示す。
- 用語の由来や定式化の名称など、本筋から一段外れる補足は、本文に並べず脚注（
[^ラベル]）に降ろす。
- 定義や分類の列挙は箇条書きで示してよい。定義される用語は太字にする。
- 用語を本文中で初めて定義・導入するときも、その語は太字にする。すでに導入した語を話題として指すとき、引用、通称には「」を使い、太字と使い分ける（初出の定義は太字、以後の言及は「」）。
- ダッシュ（em ダッシュ
—、horizontal bar ―、いわゆる2倍ダッシュ「——」）を日本語の地の文・見出しで使わない。同格・補足の挿入は括弧（）に、言い換え・敷衍は句点で二文に分けるか読点でつなぐ。範囲を示す en ダッシュ – や英語の複合語、コードブロック・書誌情報は対象外。
- 中黒（・）を日本語の並列で使わない。ただし単一の固有名詞の内部では使ってよい。
- 見出しに、区切り線（罫線
─ やダッシュ類）で「種別──主題」のように二要素を詰め込まない。見出しは単一の自然な句にする。
- 用語とその定義を並べる箇条書きは、区切り線ではなく全角コロンで「用語：説明」と書く。
段落と論証の構成
パラグラフライティングを基本とする。段落は論証の一歩であり、読者は段落単位で論理を追えなければならない。
- 一つの段落には一つのトピックだけを置く。場面の進行（調査、報告、検証、評価）が複数混ざった長い段落は、一歩ずつの段落に分割する。
- 段落の最初の文を読めば、その段落が何の話かわかるようにする。
- 段落の先頭では、前の段落との論理関係を接続表現で明示する。
- 論証は一方向に進める。結論を出してから反論を処理し、結論を言い直す構成にしない。反論と疑念の処理を終えてから、結論を一度だけ置く。
- 読者が立てそうな誤った解釈は、明示的に否定してから本当の理由を述べる（「その理由は『〜だから』ではない。〜だからだ」）。
- 「AではなくB」と否定するときは、否定の根拠を一文添える。
- 譲歩（「確かに〜」）では、事実の確認にとどめる。あとで訂正する内容を著者の声で因果として断定すると、自己矛盾になる。
- 何かを否定・限定するときは、否定する命題そのものを「」で正確に書き出す。漠然とした否定で済ませない。
論証の厳密さ
文章の論理にツッコミどころを残さない。書き上げたら、読み手の反論を先回りして次の点を点検する。
- 推量・可能性・読者の疑念・反実仮想として書かれている文を、機械的に断定へ変えない。「かもしれない」「だろう」「ようだ」は、根拠なく主張を弱めている場合だけ削る。事実未確認の可能性や推定を表す場合は、その不確実性を保つ。
- 異なるものを「同じ」とまとめない。区別すべき対象（別々の決定、別々の原因）を一括りの言葉でくくらない。
- 複数の要因がある事象を、単一の原因に還元しない。
- 章・節をまたいで、同じ概念の扱いを一致させる。分類・定義・用語の地位は全体で揃える。
- 因果を主張するときは、その機構（なぜそうなるのか）を一文で示す。「AだとBになる」とだけ書いて理由を省略しない。
- 検出・保証・解決を「必ず」できるかのように書かない。条件付きで正確に述べる（「〜しやすい」「〜できることが多い」）。
- 「次節で扱う」と前方に逃がした論点は、本当にそこで回収されることを確認する。
読み手の負荷の管理
読者の記憶と注意は有限の資源として扱う。
- 後で参照する必要のない固有名（ファイル名、関数名、識別子）を出さない。一般的な言い方で済ませる。
- 抽象的な言い回しの指す内容が文脈から一意に決まらないときは、可能なときは丸括弧による同格挿入でその場で特定する。
- 新しい例や場面を追加して読者が保持すべき文脈が増えるときは、前の例と何が違うのか、なぜもう一つ必要なのかを前置きする。
- 議論に必要な具体は残す。省略の典型は、装飾的精度（時刻、HTTP ステータスなど）や、後で参照しない固有名。
視点と語り
- 例示では、結果の羅列や受動態ではなく、行為者を主語にした動作の連なりで書く。
- 論証の中で読者を「あなた」と呼ばず、役割名（「開発者」「読者」）で書く。
- 対象を指す語は具体的に選ぶ。「AI」「ツール」のような広い語でぼかさない。
- 術語・訳語は、その分野で慣用されている語を選ぶ。意味の近い漢語を一般語の感覚で充てない。
演出の抑制
演出の規範は全面禁止ではなく、節度の規範である。修辞は、それが効果を生む箇所でのみ使う。
- 溜めや修辞疑問で導出を演出するのは、緊張が議論に効く要所に限る。説明で足りる箇所では、そのまま述べる。
- 本文中の太字強調を多用しない。論理の要所に限り、一節に一、二箇所まで。
- 転回点を過剰に劇的にしない。事実を述べる一文で足りる場合が多い。
- 「重要なのは〜である」のような前置きで主張を予告しない。主張をそのまま書く。
LLM っぽい表現の禁止
論点を増やさず「ちゃんと書いている感」だけを付ける LLM 口調は使わない。書き上げたら点検する。
- 予告と総括：「重要なのは〜である」「本章では〜を扱う／探求する」「まとめると」「要するに」（直前の言い換えだけのとき）、「〜に他ならない」
- 正面から系：「正面から扱う」「正面から回収する」——中身の代わりに姿勢だけを宣言する
- 空虚な形容：「不可欠」「核心的」「鍵となる」「根本的な」、「多角的」「包括的」「総合的」
- 空虚な動詞：「掘り下げる」「深掘りする」「言語化する」、「触れる」「言及する」
- 接続の型：「〜において」「〜という側面から」「〜の観点から」（新情報なし）、「さらに」「また」「加えて」の連打
- 弱い緩和と称賛：根拠なく主張を弱める「〜と言えるだろう」、中身のない強調「非常に」「極めて」
冗長の排除
- 同じ主張を言い換えて繰り返さない。一つの主張は一度だけ書く。
- 隣接する節が同じことを別の角度で述べているなら、片方に吸収して一つにまとめる。
- 読者が自力で補える中間段階の説明は書かない。
- 接続や評価のためだけの文（「それ自体はよいことである」など）を置かない。
- 本文でまだ導入していない概念や文書名を、先回りして持ち出さない。
見出しの付け方
見出しは内容を特定できる具体的なものにする。その節が答える問い、または扱う対象を指す句にする。
- 作業の手順だけを述べる見出しや、情報量のない見出しにしない。
- 見出しを、節の結論を言い切る「セリフ」にしない。
- 疑問形か、対象を指す名詞句かは、本文のトーンに合うほうを選ぶ。
