writing

name	writing
description	文章作成における基本規範。文章の作成・推敲・リライトを行うあらゆる場面（ドキュメントの執筆、エージェント間の連絡、LLM向けプロンプトの作成など）で適用する。

文章規範

整形

• コード、差分、ログ、設定ファイルの断片はコードブロックで示すべきである。
• 定義や分類の列挙は箇条書きで示してよい。定義される用語は太字にするべきである。
• 用語を本文中で初めて定義・導入するときも、その語は太字にするべきである。すでに導入した語を話題として指すとき、引用、通称には「」を使い、太字と使い分けるとよい（初出の定義は太字、以後の言及は「」）。
• 人物そのものに言及するときは、名前をアルファベットのまま示すべきである（Lehman、Bainbridge）。ただし、歴史上の人物や、人名を冠した概念を定着名で紹介するときは、日本語で通用しているカタカナの通称を使ってよい。
• ダッシュ（em ダッシュ —、horizontal bar ―、いわゆる2倍ダッシュ「——」）を日本語の地の文・見出しで使ってはいけない。同格・補足の挿入（「A——挿入——B」）は括弧（）に、言い換え・敷衍（「A——B」）は句点で二文に分けるか読点でつなぐべきである。範囲を示す en ダッシュ – や英語の複合語（Curry–Howard など）、コードブロック・書誌情報は対象外。
• 見出し・コラム見出しに、区切り線（罫線 ─ U+2500 やダッシュ類）で「種別──主題」「主題──概念」のように二要素を詰め込むべきではない。見出しは単一の自然な句が望ましい（要素を一つに絞るか、助詞・読点でつなぐ）。コラム見出しも「基礎」「補足」のような種別名だけで済ませず、「同値関係としての分類」「ループ不変条件と帰納法」のように内容を特定するべきである。
• 用語とその定義を並べる箇条書きは、区切り線ではなく全角コロンで「用語：説明」の形にするべきである。

段落と論証の構成

パラグラフライティングが基本である。段落は論証の一歩であり、読者は段落単位で論理を追えなければならない。

• 一つの段落では一つのトピックだけを扱うべきである。場面の進行（調査、報告、検証、評価）が複数混ざった長い段落は、一歩ずつの段落に分割する必要がある。
• 段落の最初の文を読めば、その段落が何の話かわかるようにする。
• 段落の先頭では、前の段落との論理関係を接続表現で明示するべきである（「であれば」「実際」「しかし」「この例自体からも」）。
• 新しい概念・術語を導入するときは、いきなり「XはYである」の辞書型断定で始めるべきではない。先に導入文で対象を置き、次にその働き・差分を述べ、必要なら三文目で定義を与えるとよい。
• 論証は一方向に進めるべきである。結論を出してから反論を処理し、結論を言い直す構成は避ける。反論と疑念の処理を終えてから、結論を一度述べればよい。
• 読者が立てそうな誤った解釈は、明示的に否定してから本当の理由を述べるべきである（「その理由は『〜だから』ではない。〜だからだ」）。
• 「AではなくB」と否定するときは、否定の根拠を一文添えるべきである。反実仮想（「もしAなら、〜だっただろう」）が使えることが多い。
• 山場で効かせたい情報（数値、固有の事実）を、その手前の段落で先出しするのは避ける。
• 何かを否定・限定するときは、否定する命題そのものを「」で囲んで明記するべきである（「明文化されていればすべてを任せられる」を意味しない、など）。「何もかもが解決するわけではない」のような漠然とした否定で済ませるべきではない。
• 規範やルールの文書は、規則の列挙から始めるべきではない。先にその規則が防ぐ失敗を一つ挙げ、なぜ防げずにいたのかの機構を一文で述べてから、規則を示す必要がある。読者が規則の意図を再構成できる形が望ましい。

論証の厳密さ

文章の論理にツッコミどころを残してはいけない。文章を書き上げた後は、読み手の反論を先回りして潰しにかかる。

• 推量・可能性・読者の疑念・反実仮想として述べられている文を、機械的に断定へ変えてはいけない。「かもしれない」「だろう」「ようだ」「らしい」は、根拠なく主張を弱めている場合に限り削るべきである。事実未確認の可能性、作中人物の認識、ログからの推定、読者が抱きそうな疑念、反実仮想を表す場合は、その不確実性を保つ必要がある。断定に直せるのは、本文内の根拠によって命題が確定している場合に限る。悪い例：「提示し続けているかもしれない」を「提示し続けている」に変える。良い例：「提示し続けている可能性がある」のように、不確実性を残して文を整える。
• 異なるものを「同じ」とまとめてはいけない。区別すべき対象（別々の決定、別々の原因、種類の違う問題）を一括りの言葉でくくるのも避ける。悪い例：相互依存する三つの未決事項を「同じ決定を別々に下していた」とまとめる。良い例：「どれも別々の決定であり、しかも互いに依存している」と腑分けする。
• 複数の要因がある事象を、単一の原因に還元してはいけない。例が複数種類の問題を含むなら、それぞれを切り分け、どの道具がどれを説明するのかを対応づけるべきである。悪い例：契約の不在と情報隠蔽の失敗が混ざった事故を、丸ごと「情報隠蔽の問題」と説明する。
• 章・節をまたいで、同じ概念の扱いを一致させる必要がある。ある節で「人間が決める」と分類したものを、別の節で「チームで合意する」と述べるべきではない。分類・定義・用語の位置づけは全体で揃えるべきである。
• 因果を主張するときは、その機構（なぜそうなるのか）を一文で示すべきである。「AだとBになる」とだけ述べて理由を省略するべきではない。悪い例：「手順で分けると変更が全体に波及する」。良い例：「各工程がデータを受け渡すための表現を共有してしまい、その表現を変えると全体に波及する」。
• 検出・保証・解決を「必ず」できるかのように断定してはいけない。条件付きで正確に述べるべきである（「〜しやすい」「〜できることが多い」「〜が成り立つときに限り」）。
• 主張は、挙げた例が実際にその全体を支えているかを確認するべきである。例が主張の一部しか支えないなら、主張の範囲を例に合わせて狭める必要がある。
• 節の中心となる語は、その節以前に定義・対象範囲を述べてから使うべきである。定義せずに使い始めてはいけない。
• 章や節で定式化・術語（K、契約、不変条件など）を導入したら、以後はその語で通すべきである。「文脈」「ツール」「AI」のような曖昧語に後退するべきではない（定式化する前の導入語として「文脈」などを使うのはよい）。

読み手の負荷の管理

読者の記憶力と注意力は有限の資源として扱うべきである。

• 後で参照する必要のない名前（ファイル名、関数名、識別子）を出すべきではない。「仕様書」「金額計算のユーティリティ」のような一般的な言い方で済ませるとよい。
• 抽象的な言い回しの指す内容が文脈から一意に決まらないときは、できるだけ丸括弧を添えてその場で特定し、読者に前を読み返させないようにする。
• 新しい例や場面を追加して、読者が保持すべき文脈が増えるときは、前の例と何が違うのか、なぜもう一つ必要なのかを前置きして納得感を与えるべきである。
• 文書は回帰テストではないので、「〜はやりません」「〜はしません」のような、当たり前の事実を否定する文は避けるべきである。読者の注意力を無駄に消費するだけである。

平易な日本語

LLM は英語を pivot language として持つため、日本語を書くときも英語の語や構文を経由する性質がある。そのため、人間の日本語話者は使うことのない表現が無意識に混ざることがある。 日本語として自然かどうかは、書いている最中には判定しにくいので、文章を書き上げたあとは必ず語彙と言い回しを見直すべきである。日本語話者が口頭の説明でも使うような表現だと自信を持って言えるかどうかが目安になる。

• 英語の語やフレーズを、日本語では見かけない漢語へ置き換えてはいけない。英語をそのまま謎の漢語へ置き換えると、「最良の実践」「隘路」のような、意味は取れるが日常では使わない言い方になる。誤解は生まないが、日本語として不自然になる。漢語そのものは問題ではないので「実装」「検証」「冗長」のように普段から使う語は、気にせず使ってよい。英語に戻すと一語か一句になり、かつ日本語の会話では耳にしないような言い方を疑うべきである。
• 「ベストプラクティス」「ガードレール」「ツール」「トレードオフ」のように日本語へ定着したカタカナ語を、和語や漢語へ訳し直すべきではない。定着した術語（「冪等」「不変条件」「排他制御」）も、英語由来でよい。
• 「〜で書く」という形は不自然に聞こえるので、「書く」を別の言い方に変えるべきである。「動詞で書く」「役割名で書く」「原綴りで書く」は、「文末を動詞にする」「役割名を使う」「アルファベットのまま示す」と言い直せばよい。「〜を使って書く」に替えても直らない。後述する「〜で置く」なども同様である。英語で使い勝手の良い動詞（write, put, show, use, etc.）が、日本語でも使い勝手が良いとは限らない。
• 文章の要素を、何でも「置く」「書く」で済ませるべきではない。「結論を置く」「規則を置く」「一文を置く」「弁明を書く」は、「結論を述べる」「規則を示す」「一文を添える」「弁明を添える」のように、その動作に合う動詞を選ぶべきである。場所とともに使う本来の形（「段落末に置く」）や、書く行為そのものを指す場合（「書き上げたら」「書き手」）は、そのままでよい。
• 規範を述べる文を、目的語をとる動詞の言い切りで終えるのは避ける。否定形（「ぼかさない」）も肯定形（「コードブロックで示す」）も、終止形のままだと不自然になる。「ぼかさないようにする」「コードブロックで示すべきである」のように助動詞で受けるべきである。禁止の強さに応じて「〜てはいけない」「〜は避ける」、勧めの強さに応じて「〜するとよい」「〜が望ましい」も使い分けるとよい。
• 副詞を使ったら、呼応する助詞や助動詞で受けるべきである。動詞へ直結させて言い切ると不自然である。悪い例：「そのまま使う」「一度だけ述べる」「飾らずに述べる」。良い例：「そのままでよい」「一度だけにとどめる」「飾らずに述べるべきである」。特に、「そのまま」と「だけ」は、as-is と only の直訳になりやすいので気をつけて使用する。
• 動詞と目的語の組み合わせが自然かどうかを、読み直して確かめるべきである。係り方が誤読を生む組み合わせ（「確認が守る危険」）は、防ぐ・招くのような向きの明確な動詞で言い直す必要がある（「その確認が防ぐ失敗」）。
• 対象を指す語は具体的に選ぶべきである。「AI」「ツール」のような広い語でぼかさないようにする。
• 抽象名詞で文を締めるのは避ける（「〜という営み」「〜のありよう」「〜の総体」「〜という構造」）。文末を動詞にして、何がどうなるのかを示すべきである。
• 比較や過不足を述べるときは、同じ種類の量同士を比べる形が望ましい。種類の違うものを比べる言い回し（「手順の規模が危険の大きさを超える」）は、どちらかの種類に揃えて言い直すべきである（「手順が、防ぐ失敗に対して重すぎる」）。
• 比喩は、それが指す事実を同じ文か直後に示せる場合に限って使うことができる。比喩だけで説明を終えてはいけない。指す内容が一意に決まらない比喩（「報告の外側に世界が広がっている」）や、慣用表現をひねった言い回し（「知識を体に入れる」）は厳禁である。抽象名詞や比喩だけで説明を済ませた文は最悪である。書き手には中身が濃く思えるのかもしれないが、読み手には何を意味しているのか全く分からない。
• 術語の響きを持つ語を、術語でない場面に流用するべきではない（システムから人間までの連なりを「経路」と呼ぶ、など）。「届くまでの流れ」「あいだに何があるか」のように、普通の言い方が望ましい。
• 術語・訳語は、その分野で慣用されている語を選ぶべきである（プッシュ通知は「配送」ではなく「配信」、など）。意味の近い漢語を一般語の感覚で充ててはいけない。また、内部変数のように、意味が相手に伝わらない内輪語も避ける。
• 定着した術語を、平易にしようとして曖昧で意味不明な言い換えへ崩していないかを確かめるべきである。悪い例：「ナレッジカットオフ」を「知識は途中で止まっている」と言い換える。平易になっているかと思いきや、意味不明な言い換えになっている。
• 作業中の会話で生まれた比喩・略語・呼び名を、あとに残る文書へ持ち込むべきではない。その会話を知らない人が読むので、文書だけで意味が分かる言い方に置き換える必要がある。

直訳の対応表

日本語では見かけない直訳と、その言い換えは次のとおりである。

よくある直訳	平易な言い方
隘路	ボトルネック
防護柵	ガードレール
最良の実践	ベストプラクティス
道具	ツール
端の事例	エッジケース
代替経路	フォールバック

演出の抑制

演出の規範は全面禁止ではなく、節度の規範である。修辞は、それが効果を生む箇所でのみ使うべきである。

• 溜め（「ここには〜が潜んでいる」）や修辞疑問で導出を演出するのは、緊張が議論に効く要所に限る。説明で足りる箇所に、演出を加えてはいけない。
• 短い決め台詞を独立した段落にして緊張を作る演出を、多用するべきではない。段落内の短い体言止め（「ここまでわずか数十秒。」など）は、場面の山場に限り使ってよい。
• 本文中の太字強調を多用しないようにする。誤読を防ぐ否定や節の帰結など、論理の要所に限り、一節に一、二箇所まで使ってよい（導入部でも可）。それ以外は文の順序と構造で際立たせるべきである。
• 「〜してはならない」という命令調の断定より、「〜するわけにはいかない」のような、作業者の判断として述べる言い方を選ぶべきである。
• 転回点を過剰に劇的にするのは避ける。事実を述べる一文で足りる場合が多い。議論の山場にかぎり、感嘆符つきの短い一文程度は許容してよい。
• 帰結の列挙によって事故や危険を煽ってはいけない。
• 「重要なのは〜である」のような前置きで主張を予告するべきではない。ただし、主張の様式を宣言する前置き（「標語として言い換えれば」など）は使ってよい。
• 「AではなくBだった」という対句の決め台詞は、その否定が許される場合（「LLM っぽい表現の禁止」を参照）でも、多用するのは避ける。軽い補足や評価は括弧書きで添えてよい。

LLM っぽい表現の禁止

LLMっぽいと言われる表現が存在するので、それが正しいかどうかに関わらず、文章中で使うべきではない。

• 予告と総括：「重要なのは〜である」「本章では〜を扱う／探求する」「ここでは〜について見ていく」「〜に他ならない」
• 打ち消しによる強調：「Xは〜ではない。Yだ」「Xは〜なんかじゃない。Yだ」「これはただの〜じゃない、〜だ」「〜を求めているんじゃない、〜を求めているんだ」
• 正面から系：「正面から扱う」「正面から回収する」「正面から見る／書く／立てる」
• 空虚な動詞：「刺す」「差す」「効く」「詰む」

打ち消しによる強調は、決め台詞に限らず、説明の途中にも前置きにも現れる。否定される側を誰も主張していない場面で使われる点が特徴である。伝えたい内容は後半にあるので、後半だけを述べれば良い。ただし、読者が実際に抱く誤解を否定する場合と、実際に検討した選択肢どうしを比べる場合は、この限りではない。前者は「段落と論証の構成」に従って、否定する命題を「」で明記し、根拠を一文添えるべきである。

見出しの付け方

見出しは、内容を特定できる具体的なものにするべきである。

• 作業の手順だけを述べる見出し（「例に戻す」「〜を読み直す」など）や情報量のない見出しは避け、その節が答える問い、または扱う対象を指す句を見出しにするべきである。
• 見出しを、節の結論を言い切る「セリフ」にしてはいけない。見出しの時点で読者がオチを知る状態は避ける。
• 見出しが疑問形か断定形かは問わなくてよい。問うのは、扱う対象や読者の持つ問いを指しているかである。疑問形か、対象を指す名詞句かは、本文のトーンに合うほうを選べばよい。

読者への誠実さ

• なぜその例を挙げるのか、なぜその結論に至るのか、読者が納得できるように説明するべきである。相手の暗黙の理解を想定せず、説明を省略しないようにする。
• 例が作為的に見えうる場合、それを隠してはいけない。読者の疑念を先回りして認め、現実に十分あり得ることの根拠を添えるべきである。
• その根拠は、著者の断定（「十分あり得る状況だ」）ではなく、読者自身の経験に訴える一般的事実や通説に求めるべきである（「この症状は珍しくないだろう」「〜という言い方もよく耳にする」）。
• 確認していないことを、確認したかのように述べてはいけない。

書き上げた後の読み直し

LLMは、書き手として、自分のコンテキストにある事実や理解を、読み手が当然知っている前提であるかのように文章を書いてしまう。そのため、著しく前提が欠落したような、読み手に伝わるはずのない文章を、書いている最中には問題ないと考えてしまう。自分のコンテキストの中で勝手に生み出した言い回しが誰にでも通じる言葉に見え、途中で見聞きしたものを読者も知っているように感じられる。文章を書いている間にこの錯覚が解けることは基本的にないので、欠落の検出や本当に伝わる文章への書き直しは、書き上げた後の読み直しや校正に頼ることになる。

• 文章を書き上げたら、初めて読む読者になったつもりで、必ず全体を読み直すべきである。この読み直しは省略してはいけない。「平易な日本語」の語彙の見直しと、「論証の厳密さ」の反論潰しも、この読み直しの中で行うとよい。
• 読み直しの前に、読者がその文書を読む時点で実際に持っている文脈を確かめるべきである。同じ画面に何が見えているか、どの文書を先に読んでいるはずか、どの用語を知っているはずかを想像し、それ以外の内輪的な文脈や前提は「読者は知らない」ものとして扱うべきである。
• （上記に関連して）LLMのAPIコールで使用するシステムプロンプトを作成する場面を想像するとよい。このとき、プロンプトの「読者」はLLMとなる。LLMはシステムプロンプトに書かれたこと以外、何も知らない。そのため、プロンプト内でシステム内部の変数名などを使って指示を出しても、LLMには意図が伝わらない。また、APIを実装する前に開発者がユーザーとやり取りした経緯も把握していない。特定の経緯に基づく特別な処理を依頼したい場合は、その背景をゼロから説明する必要がある。「読者（LLM）が持っている前提知識」を正確に想像することは、指示の抜け漏れ（欠落）を防ぐ上で不可欠である。
• 読み直しでは、文ごとに次を問うとよい。この文の前提となるコンテキストを読者は知っているか。前提の省略を読者は復元できるか。
• 発見した欠落は、文書の中で前提を書き直すか、読者に見える場所への参照などによって補うとよい。欠落を補うために、文書の中で前提を説明する箇所を新たに挿入することもあるし、根本的に書き直した方が良い場合も少なくない。書き直しの際は、前提を補うだけでなく、文章全体の構成や論理の流れも見直すとよい。