diff --git a/dot_claude/skills/japanese-tech-writing/SKILL.md b/dot_claude/skills/japanese-tech-writing/SKILL.md index fb8e4c3..ea7ea56 100644 --- a/dot_claude/skills/japanese-tech-writing/SKILL.md +++ b/dot_claude/skills/japanese-tech-writing/SKILL.md @@ -1,24 +1,13 @@ --- name: japanese-tech-writing -description: 日本語の技術文書・書籍原稿の文章規範。整形（一文一行、引用ブロック、脚注、コラム記法）、段落と論証の構成（パラグラフライティング）、論証の厳密さ（ツッコミどころの除去）、読み手の負荷の管理、視点と語り、演出の抑制、LLM っぽい空句の禁止、冗長の排除を定める。日本語で技術書の章、草稿、記事、解説文を書くとき、または推敲・リライトするときに使用する。 +description: 日本語の技術文書・書籍原稿の文章規範。段落と論証の構成（パラグラフライティング）、論証の厳密さ（ツッコミどころの除去）、読み手の負荷の管理、視点と語り、演出の抑制、LLM っぽい空句の禁止、翻訳調の比喩と擬人化の禁止（「運ぶ」「効く」「開かれた問い」など）、冗長の排除を定める。日本語で技術書の章、草稿、記事、解説文を書くとき、または推敲・リライトするときに使用する。 +license: Unlicense（https://gist.github.com/k16shikano/67625f2a7d96e3bbdfae8d571a936063） --- # 日本語技術文書の文章規範 日本語で技術的な原稿（書籍の章、記事、解説文）を書く・推敲するときは、以下の規範に従う。 -## 整形 - -- 一文ごとに改行する。段落の区切りは空行で示す。 -- コード、差分、ログ、設定ファイルの断片はコードブロックで示す。 -- 用語の由来や定式化の名称など、本筋から一段外れる補足は、本文に並べず脚注（`[^ラベル]`）に降ろす。 -- 定義や分類の列挙は箇条書きで示してよい。定義される用語は太字にする。 -- 用語を本文中で初めて定義・導入するときも、その語は太字にする。すでに導入した語を話題として指すとき、引用、通称には「」を使い、太字と使い分ける（初出の定義は太字、以後の言及は「」）。 -- ダッシュ（em ダッシュ `—`、horizontal bar `―`、いわゆる2倍ダッシュ「——」）を日本語の地の文・見出しで使わない。同格・補足の挿入（「A——挿入——B」）は括弧（）に、言い換え・敷衍（「A——B」）は句点で二文に分けるか読点でつなぐ。範囲を示す en ダッシュ `–` や英語の複合語（`Curry–Howard` など）、コードブロック・書誌情報は対象外。 -- 中黒（・）を日本語の並列で使わない。ただし単一の固有名詞の内部では使ってよい。 -- 見出し・コラム見出しに、区切り線（罫線 `─` U+2500 やダッシュ類）で「種別──主題」「主題──概念」のように二要素を詰め込まない。見出しは単一の自然な句にする（要素を一つに絞るか、助詞・読点でつなぐ）。コラム見出しも「基礎」「補足」のような種別名だけで済ませず、「同値関係としての分類」「ループ不変条件と帰納法」のように内容を特定する。 -- 用語とその定義を並べる箇条書きは、区切り線ではなく全角コロンで「**用語**：説明」と書く。 - ## 段落と論証の構成 パラグラフライティングを基本とする。段落は論証の一歩であり、読者は段落単位で論理を追えなければならない。 @@ -30,6 +19,7 @@ description: 日本語の技術文書・書籍原稿の文章規範。整形（ - 例への弁明（作為的に見える、への先回りなど）は、場面の山場の直後に挟んで流れを切らない。次の節の冒頭でまとめて処理する。 - 読者が立てそうな誤った解釈は、明示的に否定してから本当の理由を述べる（「その理由は『〜だから』ではない。〜だからだ」）。 - 「AではなくB」と否定するときは、否定の根拠を一文添える。反実仮想（「もしAなら、〜だっただろう」）が使えることが多い。 +- 同じ概念を二つの対象で対比定義するときは、両文の述部を同じ型にする。既出の説明の回収は文頭の枠に置き、定義そのものを「〜だと説明した」に埋め込まない。特徴の句は「」で切り出し、対比の接続を明示する。第二極について続ける属性は、主語を改めて名乗らず継承する。 - 譲歩（「確かに〜」）では、事実の確認にとどめる。あとで訂正する内容を著者の声で因果として断定すると、自己矛盾になる。表面的な診断を一度認めたいときは、読者や通説の声に帰属させる（「〜と要約できてしまうかもしれない」）。 - 山場で効かせたい情報（数値、固有の事実）は、その手前の段落で先出ししない。 - 何かを否定・限定するときは、否定する命題そのものを「」で正確に書き出す（「明文化されていればすべてを任せられる」を意味しない、など）。「何もかもが解決するわけではない」のような漠然とした否定で済ませない。 @@ -61,11 +51,14 @@ description: 日本語の技術文書・書籍原稿の文章規範。整形（ 読者の記憶と注意は有限の資源として扱う。 +- 読者が順読みで保持する情報は、一度に一段だけ増やす。箇所を削ったら残った言及を辿り、この文書のほかで使われなくなった主題は落とす。直前までの文の上に一段で足りる許可や読み方は直接書く。 - 後で参照する必要のない固有名（ファイル名、関数名、識別子）を出さない。「仕様書」「金額計算のユーティリティ」のような一般的な言い方で済ませる。 - 抽象的な言い回しの指す内容が文脈から一意に決まらないときは、可能なときは丸括弧による同格挿入でその場で特定し、できるだけ読者に前を読み返させない。 +- 概念を初めて示す文では、読者が順に読んだだけで、まずその概念が何であるか（データ構造、手順、制約などの種類や地位）を読み取れる順序にする。その概念を既に知っている読者にだけ自然な性質・仕組み・制約を、種類の同定より前に置かない。前置すると、未習の読者は文を読み終えた時点で逆戻りしなければ核となる情報を見逃すか、理解が滞る。 - 新しい例や場面を追加して、読者が保持すべき文脈が増えるときは、前の例と何が違うのか、なぜもう一つ必要なのかを前置きして納得感を与える。 +- 同一節内に図、表、コードなど複数の提示があるとき、各媒体が担う説明（配置の見え方、数値、手順など）を分けて書く。媒体間で型やデータを揃える必要はなく、別例として並べてよい。指示語（「この2つ」「上記の例」）は、どの媒体のどの例を指すか文脈だけで一意に決まるように置く。一つの媒体で確認した性質を、別の媒体の例にもそのまま当てはめない。二方式を「Aの代わりにB」と対比するときも、やめる側と採る側の語順を置換関係と一致させ、後に書く側が採用される方式であることを順読みで読み取れるようにする。 - 章冒頭や節の導入では、これから例で扱う内容に関係しない過剰な詳細を詰め込まない。 -- 例の節の中でも、**その節の問い・帰結に関係しない**過剰な詳細だけを omit する。議論に必要な具体は残す。省略の典型は、エージェント報告の装飾的精度（時刻、HTTP ステータス、カバレッジ率など）や、後で参照しない固有名 +- 例の節の中でも、**その節の問い・帰結に関係しない**過剰な詳細だけを omit する。議論に必要な具体は残す。省略の典型は、エージェント報告の装飾的精度（時刻、HTTP ステータス、カバレッジ率など）や、後で参照しない固有名詞。 ## 視点と語り @@ -77,6 +70,7 @@ description: 日本語の技術文書・書籍原稿の文章規範。整形（ - 術語・訳語は、その分野で慣用されている語を選ぶ（プッシュ通知は「配送」ではなく「配信」、など）。意味の近い漢語を一般語の感覚で充てない。 - 人物そのものに言及するときは原綴りで書く（Lehman、Bainbridge）。ただし、歴史上の人物や、人名を冠した概念を定着名で紹介するときは、日本語で通用しているカタカナの通称を使う。 - 術語の響きを持つ語を、術語でない場面に流用しない（システムから人間までの連なりを「経路」と呼ぶ、など）。「届くまでの流れ」「あいだに何があるか」のように普通の言い方で書く。 +- イ形容詞の終止に「です」を続けた文（「難しいです」「多いです」）を書かない。これは文体の規則ではなく、文の流れの破綻の兆候である。イ形容詞を裸で言い切る必要が生じるのは、その文が前後から孤立しているからであり、流れている文章なら「〜は難しく、…」と文が続くか、「〜でしょう」「〜である」で受けられる。出現したら文末だけ取り繕わず、前後の流れごと書き直す。ナ形容詞の「〜です」（「重要です」）は対象外。 ## 演出の抑制 @@ -109,16 +103,38 @@ LLM が大量生成する、中身のない型に誘惑されない。書き上 悪い例：「本章では、〇〇の理論を正面から扱う」「この前提を、ここで正面から回収する」「多角的に分析すると、重要なのは〜である」。 良い例：「本章では、〇〇の理論を扱う」「ここで、この前提を回収する」「評価の核心は、正しさを誰が知っているかにある」。 +## 翻訳調の比喩と擬人化の禁止 + +LLM は、日本語として存在しない言い回しを、次の三つの経路で生成する。 +前節の空句と違い、書き手（LLM）に比喩や演出の意識がないまま混入するので、比喩を使ったつもりのない文も含めて点検する。 + +- **英語慣用句の直訳**：英語の技術文では carry / open / expose / live / land などの比喩的用法が慣用句として定着しており、比喩として意識されない。これを日本語の対応語に直訳すると、日本語では慣用化していないため、字義どおりに読める奇妙な生きた比喩になる。 + - 悪い例：「ベクトルが選好を運ぶ」（carry）。良い例：「選好がベクトルとして表現される」「ベクトルに反映される」。 + - 悪い例：「この問いは開かれている」（open question）。良い例：「この問いにはまだ答えが出ていない」「未解決である」。 + - 悪い例：「推敲の軸が露出する」（expose）。良い例：「推敲の軸が線形に取り出せる」。 + - 悪い例：「この情報は残差ストリームに住んでいる」（live in）。良い例：「残差ストリームに含まれる」。 +- **無生物主語構文の直輸入**：英語では無生物主語の他動詞文が普通だが、そのまま日本語にすると、モデル、データ、ベクトル、損失といった抽象物が意思を持って振る舞う擬人化になる。日本語では、人か処理を主体に戻すか、「〜から分かる」「〜に含まれる」の形に言い直す。 + - 悪い例：「モデルは文体を知っている」。良い例：「モデルの出力には文体の一貫性がある」など、確認できる事実として書く。 + - 悪い例：「データが語るのは〜である」。良い例：「データから分かるのは〜である」。 +- **研究者の話し言葉の混入**：機械学習の口頭議論で流通する動詞（「効く」「刺さる」「筋がいい」など）は、話し言葉としては通じるが、書き言葉の技術文書では俗語である。効果や見込みの内容を具体的に書く。 + - 悪い例：「規範スキルが効く」。良い例：「規範スキルを与えると生成が選好に近づく」。 + - 悪い例：「この手法は筋がいい」。良い例：「この手法は〜という理由で有望である」。 + +判定の目安は二段である。 +まず、その述語を初めて見る読者が字義どおりの動作（運ぶ、開く、住む）を想像しうるなら、翻訳調の比喩を疑う。 +次に、動作の主体と対象を具体語で言い直せるか試す。 +言い直せるなら、その言い直しをそのまま書く。 +言い直せないなら、その文は指す内容が特定できていないので、主張として成立していない。削るか、内容を確定させてから書き直す。 + ## 冗長の排除 無駄な文章をなるべく残さない。 -- 同じ主張を言い換えて繰り返さない。一つの主張は一度だけ書く。 +- 同じ主張を言い換えて繰り返さない。一つの主張は一度だけ書く。題材が直前と同じでも、その文が加えている命題が違えば繰り返しではない。列挙の各項が同じ論理的地位であることを示す枠語の反復や、定義の直後に適用条件や限定を足す文も、主張の繰り返しではない。 - 隣接する節が同じことを別の角度で述べているなら、役割が重複している。片方に吸収して一つの節にまとめる。 - 場面を描写した直後に、その内容を要約し直さない。意味づけの一文（「このような作業は、ほぼ完全に任せられる」など）だけを置く。 - 同じ論理的役割を持つ並列の事実は、文を分けて重ねず一文にまとめる。その事実群の論理的地位は文頭の語で示す（「当然、経理部の月次処理も顧客の支払いも〜」）。 -- 読者が自力で補える中間段階の説明は書かない。 -- 数文にわたる議論を一文に圧縮できるなら、圧縮した一文だけを残す。要約の合図として「要するに」を使ってよい。 +- 冗長さは文字数や文数で判定しない。短文化と一文化は、動機、対象、操作、その同一性、因果、条件が順読みで明示されたまま保てる場合に限る。これらを読者の推論に委ねる圧縮はせず、必要な反復と長さを残す。 - 接続や評価のためだけの文（「それ自体はよいことである」など）を置かない。 - 想像上の読者との問答（問いを立てて一語で答える形など）を修辞として使わない。主張はそのまま述べる。読者の反応を演じて応答する形（「〜と感じたかもしれない。そのとおりである」）も同様に避け、譲歩は地の文で簡潔に行う（「もちろん、処置そのものは開発者が決める問題ではない」）。 - 読者が抱きそうな発想を、メタな枠取り（「ここまでの話には自然な続きがある」「〜という発想である」）で紹介しない。その発想自体を直接書く。読者の疑問なら疑問文のまま書いてよい（「その保守も任せればよいのではないだろうか」）。 @@ -143,4 +159,3 @@ LLM が大量生成する、中身のない型に誘惑されない。書き上 - 例が作為的に見えうる場合、それを隠さない。読者の疑念を先回りして認め、現実に十分あり得ることの根拠を短く添える。 - その根拠は、著者の断定（「十分あり得る状況だ」）ではなく、読者自身の経験に訴える一般的事実や通説に求める（「この症状は珍しくないだろう」「〜という言い方もよく耳にする」）。 - 確認していないことを、確認したかのように滑らかに書かない。 -