日本語技術文書・記事の執筆規範 Skill

日本語技術文書・記事の執筆規範

このスキルは二つのモードをカバーする。成果物の性質に応じて使い分ける。

文章規範モード: 書籍の章、技術解説文、しっかりした地の文の記事を書く・推敲するときに従う規範。
記事執筆モード: 箇条書きの技術コンテンツを、自然な文体のカジュアルな技術記事（ブログ記事）に仕上げるためのガイドライン。

両モードは文体の要求が異なる（文章規範モードは硬い地の文と論証の厳密さを求め、記事執筆モードはです・ます調のカジュアルな個人的トーンを求める）。混同せず、書く対象に合わせて適用するモードを選ぶ。

文章規範モード（技術文書・書籍原稿）

日本語で技術的な原稿（書籍の章、記事、解説文）を書く・推敲するときは、以下の規範に従う。

整形

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

段落と論証の構成

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

一つの段落には一つのトピックだけを置く。場面の進行（調査、報告、検証、評価）が複数混ざった長い段落は、一歩ずつの段落に分割する。
段落の最初の文を読めば、その段落が何の話かわかるようにする。
段落の先頭では、前の段落との論理関係を接続表現で明示する（「であれば」「実際」「しかし」「この例自体からも」）。
論証は一方向に進める。結論を出してから反論を処理し、結論を言い直す構成にしない。反論と疑念の処理を終えてから、結論を一度だけ置く。
例への弁明（作為的に見える、への先回りなど）は、場面の山場の直後に挟んで流れを切らない。次の節の冒頭でまとめて処理する。
読者が立てそうな誤った解釈は、明示的に否定してから本当の理由を述べる（「その理由は『〜だから』ではない。〜だからだ」）。
「AではなくB」と否定するときは、否定の根拠を一文添える。反実仮想（「もしAなら、〜だっただろう」）が使えることが多い。
譲歩（「確かに〜」）では、事実の確認にとどめる。あとで訂正する内容を著者の声で因果として断定すると、自己矛盾になる。表面的な診断を一度認めたいときは、読者や通説の声に帰属させる（「〜と要約できてしまうかもしれない」）。
山場で効かせたい情報（数値、固有の事実）は、その手前の段落で先出ししない。
何かを否定・限定するときは、否定する命題そのものを「」で正確に書き出す（「明文化されていればすべてを任せられる」を意味しない、など）。「何もかもが解決するわけではない」のような漠然とした否定で済ませない。
「後の章で扱う」のような前方参照は、論証が一段落した位置（段落末・節末）に置く。論証の途中に挟んで流れを切らない。

論証の厳密さ

文章の論理にツッコミどころを残さない。書き上げたら、読み手の反論を先回りして次の点を点検する。

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

読み手の負荷の管理

読者の記憶と注意は有限の資源として扱う。

後で参照する必要のない固有名（ファイル名、関数名、識別子）を出さない。「仕様書」「金額計算のユーティリティ」のような一般的な言い方で済ませる。
抽象的な言い回しの指す内容が文脈から一意に決まらないときは、可能なときは丸括弧による同格挿入でその場で特定し、できるだけ読者に前を読み返させない。
新しい例や場面を追加して、読者が保持すべき文脈が増えるときは、前の例と何が違うのか、なぜもう一つ必要なのかを前置きして納得感を与える。
章冒頭や節の導入では、これから例で扱う内容に関係しない過剰な詳細を詰め込まない。
例の節の中でも、その節の問い・帰結に関係しない過剰な詳細だけを omit する。議論に必要な具体は残す。省略の典型は、エージェント報告の装飾的精度（時刻、HTTP ステータス、カバレッジ率など）や、後で参照しない固有名

視点と語り

例示では、結果の羅列や受動態（「特定され、判明した」）ではなく、行為者を主語にした動作の連なり（「リポジトリを調査して特定し、見つけてくれた」）で書く。
「入社2年目のエンジニアが」のような架空の人物設定を無意味に冠しない。
論証の中で読者を「あなた」と呼ばず、役割名（「開発者」「読者」）で書く。二人称の呼びかけは、場面への導入（「〜としよう」）や章・本の結びなど、限られた要所にとどめる。
対象を指す語は具体的に選ぶ。「AI」「ツール」のような広い語でぼかさない。
章や節で定式化・術語（K、契約、不変条件など）を導入したら、以後はその語で通す。「文脈」「ツール」「AI」のような曖昧語に後退しない（定式化する前の導入語として「文脈」などを使うのはよい）。
術語・訳語は、その分野で慣用されている語を選ぶ（プッシュ通知は「配送」ではなく「配信」、など）。意味の近い漢語を一般語の感覚で充てない。
人物そのものに言及するときは原綴りで書く（Lehman、Bainbridge）。ただし、歴史上の人物や、人名を冠した概念を定着名で紹介するときは、日本語で通用しているカタカナの通称を使う。
術語の響きを持つ語を、術語でない場面に流用しない（システムから人間までの連なりを「経路」と呼ぶ、など）。「届くまでの流れ」「あいだに何があるか」のように普通の言い方で書く。

演出の抑制

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

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

LLM っぽい表現の禁止

LLM が大量生成する、中身のない型に誘惑されない。書き上げたら、この節で点検する。本書の術語（本質的複雑さ、回収、判断の配置など）を議論に使うのはよい。空虚な装飾として使うのが問題である。

次のような言い回しは、論点を増やさず「ちゃんと書いている感」だけを付ける LLM 口調である。使わない。

予告と総括：「重要なのは〜である」「本章では〜を扱う／探求する」「ここでは〜について見ていく」「まとめると」「要するに」（直前の言い換えだけのとき）、「〜に他ならない」
正面から系：「正面から扱う」「正面から回収する」「正面から見る／書く／立てる」——中身の代わりに姿勢だけを宣言する
空虚な形容：「不可欠」「核心的」「鍵となる」「根本的な」（主張の中身を説明せず強調だけする）、「多角的」「包括的」「総合的」（何をどう見たかを書かない）
空虚な動詞：「掘り下げる」「深掘りする」「言語化する」（何をどう書いたかを示さず終わる）、「触れる」「言及する」（一段落で済ませるだけ）
接続の型：「〜において」「〜という側面から」「〜の観点から」（新情報なし）、「さらに」「また」「加えて」の連打
弱い緩和と称賛：「〜と言えるだろう」「〜かもしれない」（根拠なく主張を弱める場合だけ。推量・仮定・読者の疑念・作中人物の認識なら残す）、「非常に」「極めて」「大いに」（中身のない強調）

悪い例：「本章では、〇〇の理論を正面から扱う」「この前提を、ここで正面から回収する」「多角的に分析すると、重要なのは〜である」。良い例：「本章では、〇〇の理論を扱う」「ここで、この前提を回収する」「評価の核心は、正しさを誰が知っているかにある」。

冗長の排除

無駄な文章をなるべく残さない。

同じ主張を言い換えて繰り返さない。一つの主張は一度だけ書く。
隣接する節が同じことを別の角度で述べているなら、役割が重複している。片方に吸収して一つの節にまとめる。
場面を描写した直後に、その内容を要約し直さない。意味づけの一文（「このような作業は、ほぼ完全に任せられる」など）だけを置く。
同じ論理的役割を持つ並列の事実は、文を分けて重ねず一文にまとめる。その事実群の論理的地位は文頭の語で示す（「当然、経理部の月次処理も顧客の支払いも〜」）。
読者が自力で補える中間段階の説明は書かない。
数文にわたる議論を一文に圧縮できるなら、圧縮した一文だけを残す。要約の合図として「要するに」を使ってよい。
接続や評価のためだけの文（「それ自体はよいことである」など）を置かない。
想像上の読者との問答（問いを立てて一語で答える形など）を修辞として使わない。主張はそのまま述べる。読者の反応を演じて応答する形（「〜と感じたかもしれない。そのとおりである」）も同様に避け、譲歩は地の文で簡潔に行う（「もちろん、処置そのものは開発者が決める問題ではない」）。
読者が抱きそうな発想を、メタな枠取り（「ここまでの話には自然な続きがある」「〜という発想である」）で紹介しない。その発想自体を直接書く。読者の疑問なら疑問文のまま書いてよい（「その保守も任せればよいのではないだろうか」）。
「本書もそれを否定しない」のような、著者の立場の弁明や断りを書かない。事実の記述（「〜に書かせる場合が多い」）だけを置く。
文脈を最短で読み手と共有できる文章にする。導出を一歩ずつ展開しなくても伝わるなら、構造に名前を与えて言い切る。
本文でまだ導入していない概念や文書名を、先回りして持ち出さない。
ためらいのある弱い述語（「有効な対策であり」など）で済ませない。本文内の根拠で確定していることは強く具体的に言い切る（「活用において必須であり」など）。ただし、不確実性・可能性・仮定・読者の疑念を表すための弱い述語は保持する。語調を整えるための意図的な緩和（「必須だと言ってもいい」など）は許す。
文章のリズムを作るための接続表現（「しかし一方で」など）は、冗長と見なさない。

見出しの付け方

見出しは内容を特定できる具体的なものにする。その節が答える問い、または扱う対象を指す句にする。

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

読者への誠実さ

例が作為的に見えうる場合、それを隠さない。読者の疑念を先回りして認め、現実に十分あり得ることの根拠を短く添える。
その根拠は、著者の断定（「十分あり得る状況だ」）ではなく、読者自身の経験に訴える一般的事実や通説に求める（「この症状は珍しくないだろう」「〜という言い方もよく耳にする」）。
確認していないことを、確認したかのように滑らかに書かない。

記事執筆モード（箇条書きからの技術記事）

箇条書きの技術コンテンツを、AI生成っぽさを避けた自然で読みやすい技術記事（ブログ記事）に仕上げるときは、以下のガイドラインに従う。技術的な正確さを保ちながら、人が書いたような文章を目指す。

自然な文体の特徴

基本方針: AIが生成した文章特有の機械的・形式的な印象を避け、人が書いたような自然な技術記事を目指す。

文体:

です・ます調を基本とする
カジュアルで親しみやすいトーン
適度に一人称（「私は」「個人的には」）を使用
「〜してみました」「〜と思います」「〜が便利です」などの個人的な表現を含める

段落構成:

短めの段落を心がける
1段落1トピックを基本とする
段落間の接続は自然な流れを意識（「さて、」「ところで、」「そんな中、」など）
適度な改行で読みやすさを確保

AIっぽい表現を避けるための具体策

見出しの番号付けを避ける:

❌ ## 1. はじめに
❌ ## 2. 実装方法
✅ ## はじめに
✅ ## 実装方法

リストの使い方:

箇条書き（-）を優先、番号付きリスト（1. 2. 3.）は本当に順序が重要な場合のみ使用
❌ 多用しすぎる番号付きリスト
✅ 適度な箇条書きと説明的な段落のバランス

手順書的な表現を避ける:

❌ 「まず、〜を実行します。次に、〜を設定します。最後に、〜を確認します。」
✅ 「〜を実行してから、〜を設定します。これで〜が確認できるようになります。」

形式的すぎる表現を避ける:

❌ 「実施する」「確認する」「〜することができます」
✅ 「やる」「試す」「見てみる」「〜できます」

結論を押し付けない:

❌ 「これにより、明らかに〜が向上します」
✅ 「〜が改善されると感じています」「〜という効果がありそうです」

記事構成のパターン

導入: 背景や問題提起、個人的な動機から始める

本文: h2/h3 で構造化（見出しに番号なし）、説明と具体例のバランス

まとめ: 要点を再説し、読者への呼びかけや次のステップを提案

コンテンツのバランス

箇条書きと説明的な段落を組み合わせる
具体例とユースケースを含める（「なぜそうしたのか」も説明）
技術的事実は客観的に、感想や評価は個人的視点で
断定しすぎず適度な不確実性を残す（「〜かもしれません」「〜だと考えられます」）

コードブロックの扱い

言語を適切に指定（typescript, bash, ```json など）
必要に応じてファイル名をタイトルとして追加（```typescript:src/config.ts）
本文でコードの説明を含める（コメントだけに頼らない）
長いコードは抜粋のみ掲載

参考記事

CRITICAL: 記事を書く前に、以下の4つの参考記事をすべて読むこと。

文体は言語化では完全に捉えられない。必ず4つすべての実際の記事を読んで、その流れ、表現、リズムを学習する。

Use the Skill tool to view ALL reference articles:

view(skill='skills/japanese-tech-writing/examples/sample-article-1.md')
view(skill='skills/japanese-tech-writing/examples/sample-article-2.md')
view(skill='skills/japanese-tech-writing/examples/sample-article-3.md')
view(skill='skills/japanese-tech-writing/examples/sample-article-4.md')

参考記事を読むときは、次の点に注目する:

自然な段落遷移（「さて、」「で、」「そんな中、」「という感じで、」「といったことがありました」）
個人的な声とカジュアルな表現（「〜してみました」「〜だったりします」「〜ですね」「〜が便利です」）
著者がリストと文章のどちらを使い分けているか
コードブロックの自然な導入と説明の仕方
導入から結論までの会話的な流れ
個人的な逸話や動機（「退屈な開発をサボりたくて」「かくいう私も」）

Agent Skills: 日本語技術文書・記事の執筆規範

Install this agent skill to your local

Skill Files