| name | japanese-technical-writing |
| description | 日本語の技術文書を Markdown ファイルとして作成または編集するときに使う。対象は技術書原稿、技術記事、解説文、提案書、ADR、README、設計文書、運用手順。文書構成、主体と適用範囲、段落と論証、事実・推測・推奨・検証結果の区別、表の設計、用語と文体を扱う。通常のチャット応答、会話内だけの文章作成、レビューコメントには使わない。 |
日本語技術文書の文章規範
文章規範スキル：日本語の技術文書を、判断に必要な情報と根拠が明確で、論理を追いやすい文章へ整える。
使用する場面：日本語の技術書原稿、技術記事、解説文、README、ADR、設計文書、運用手順、提案書を Markdown ファイルとして作成、推敲、リライト、レビューする場合。
使用しない場面：通常のチャット応答、会話内だけの文章作成、レビューコメント、カジュアルな雑談、英語文書だけの編集、コードそのものの設計判断。
このスキルは https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d の文章規範を、Copilot CLI で使うための運用チェックリストとして整理したものである。
規則の優先順位
規則が競合するときは、次の順に優先する。文体を整えるために、事実、論理、判断材料を損なってはならない。
- 事実を正確に書き、確認済みの事実と推測を区別する。
- 章と節の役割を定め、文書全体の論理を一貫させる。
- 読者の判断に必要な条件、根拠、制約を示す。
- 文体、用語、表記を整える。
文書全体の構造
- 文書の目的、想定読者、扱う範囲と扱わない範囲を定める。
- 一つの章または節が答える問いを一つ定める。見出しは、その問いまたは対象を特定できる自然な句にする。
- 見出しは疑問形でも名詞句でもよい。区切り線で複数の論点を詰め込まず、「例に戻す」のような執筆作業だけを示す表現や、内容を伴わない決め台詞を避ける。
- 章や節をまたいで、概念の分類、定義、用語を一致させる。
- 局所的に修正した後は、修正した段落、その節、前後の節を読み直す。別の節に属する内容、重複、修正によって不要になった説明、理解に必要な説明より先に置かれた前方参照を除く。
- 前方参照が必要な場合は段落末か節末に置き、参照先で論点を回収する。
根拠、主体、適用範囲
- 事実、推測、推奨、検証結果を区別する。確認していないことを、確認済みの事実として書かない。
- 断定、可能性、未確認を根拠に応じて使い分ける。確立した事実を不必要に弱めず、不確実な内容を断定へ変えない。
- 誰が、何を、どの仕組みで制御または実行するのかを書く。筆者、読者、製品、管理者のいずれも主語になり得る文では、主語を省略しない。
- 機能や効果を述べるときは、適用条件と保証範囲を示す。検出、保証、解決を無条件に約束しない。
- 因果を主張するときは、原因から結果が生じる仕組みを示す。複数の要因がある事象を単一原因へ還元しない。
- 異なる決定、原因、問題を「同じ」とまとめない。例が主張の一部しか支えない場合は、主張を例が支える範囲へ狭める。
- 反論や別の解釈を扱うときは、対象となる主張と根拠を具体的に示す。根拠のない内容を「読者はこう考える」「一般にはこう言われる」と架空の声へ帰属させない。
機能と制約の説明
機能は、次の順に説明する。読者が機能の存在と採用条件を分けて判断できるようにする。
- 何を実現する機能か。
- どの条件で成立するか。
- どの対象や環境へ適用できるか。
- どの制約が構成や運用の選択へ影響するか。
一つの構成で生じる制約を、機能そのものが存在しない根拠にしない。制約が影響する対象、条件、回避方法の有無を分けて書く。
節、段落、論証
- 一つの段落には一つのトピックを置き、最初の文で話題を示す。
- 段落の先頭では、前段落との関係を必要に応じて示す。
- 条件、例外、想定される反論を処理してから結論を書く。後続の文で前の断定を訂正する構成にしない。
- 「AではなくB」と対比するときは、Aと解釈され得る理由と、Aを退ける根拠を示す。対比が不要ならBだけを書く。
- 「ただし」「とはいえ」で限定を置いたら、限定が結論へ与える影響まで書く。逆接だけで段落を終えない。
- 抽象語が指す対象を文脈から一意に決められない場合は、その場で具体化する。
- 例示では、行為者が実行する操作と、その結果を対応させる。受動態による結果の列挙だけで仕組みを説明しない。
情報量、保守性、表
- 読者の判断や後続の説明に使わないファイル名、関数名、識別子、時刻、数値を出さない。
- 導入部には、後の問いや結論に関係する情報だけを置く。
- 同じ主張の言い換え、場面描写直後の再要約、接続や評価だけの文を削る。隣接する節が同じ問いへ答えている場合は統合する。
- 読者が推測しなければならない対象、条件、因果は省略しない。削る対象は情報量ではなく、重複と論点を増やさない説明である。
- 新しい例を追加するときは、既存の例では示せない点を明らかにする。
- 製品バージョン、検証日、検証環境、詳細な操作手順など変化しやすい情報は検証記録へ集約し、本文には判断に必要な結論と参照先を置く。版による差自体が構成や採否の判断材料になる場合だけ、本文に版を記載する。
- 表の列名は、各セルに書く情報の分類と一致させる。同じ列へ効果、限界、前提、注意点を無理に混在させない。
- 複数の分類軸が必要な場合は、列を追加するか表を分割する。空欄や長い但し書きが続く場合は、分類軸か表形式を見直す。
用語、書式、文体
- 段落の区切りは空行で示す。段落内の改行は、媒体や既存文書の形式に合わせて必要な場合だけ使う。
- コード、差分、ログ、設定断片はコードブロックに入れる。
- 脚注がなくても論旨が通る場合は削除する。判断に必要だが本文の流れを妨げる補足だけを脚注へ置く。
- 文書固有の用語、または後続の議論で重要な定義は、初出時に太字で示す。一般語や一度しか使わない語は初出だけを理由に強調しない。
- 「」は、語そのものへの言及、引用、通称、UI ラベルなど境界を示す必要がある箇所に使う。定義後の通常の言及を一律に囲まない。
- 定義の箇条書きは
**用語**：説明 の形にする。
- 術語や訳語は分野で慣用される語を選ぶ。「AI」「ツール」のような広すぎる語で対象をぼかさない。
- 読者をむやみに「あなた」と呼ばず、「開発者」「管理者」「読者」など役割名で書く。
- 評価や推奨では、命令調で選択を強制せず、根拠と判断条件を示す。操作手順では、実行する操作を命令形で明確に書いてよい。
- 日本語の地の文や見出しでダッシュ類を使わない。補足は括弧、言い換えは文の分割か読点で処理する。ただし、範囲を示す en ダッシュ、英語の複合語、コードブロック、書誌情報は対象外とする。
- 日本語の並列に中黒を使わない。ただし、固有名詞の一部なら使ってよい。
装飾と空句
修辞や強調は全面禁止ではない。論点を明確にする効果がある箇所だけで使う。
- 溜め、修辞疑問、短い決め台詞、想像上の読者との問答を多用しない。
- 太字強調は、誤読を防ぐ否定や節の結論など、論理上の要所に限る。
- 指す内容が一意に決まらない比喩や、危険を煽るためだけの列挙を避ける。
- 主張を予告するだけの「重要なのは」、作業を宣言するだけの「ここでは見ていく」、直前を言い換えるだけの「要するに」を削る。
- 「不可欠」「核心的」「根本的」「多角的」「包括的」などの評価語は、評価基準や具体的な効果を示せない場合は使わない。
- 「掘り下げる」「正面から扱う」「の観点から」など、対象や操作を特定しない表現を具体的な動詞へ置き換える。
- 「さらに」「また」「加えて」の連続や、中身のない「非常に」「極めて」を避ける。
規則の判断を支える例
- 主体と仕組み。悪い例：「設定すると外部アクセスを防止できる」。良い例：「管理者が送信規則を有効にすると、ゲートウェイは許可リストにない宛先への通信を拒否する」。誰が設定し、どの構成要素が、何を拒否するかを示す。
- 適用範囲と保証。悪い例：「監査ログで不正操作を検出できる」。良い例：「監査サービスは管理 API の呼び出しを記録する。データプレーンの操作は記録対象外であり、このログだけでは不正操作を網羅できない」。記録対象と保証しない範囲を分ける。
- 機能と制約。悪い例：「プライベート接続では開発端末から利用できないため、このサービスは閉域化できない」。良い例：「サービスはプライベート接続に対応する。開発端末から接続するには、端末を名前解決と経路制御の対象へ含める必要がある」。機能の有無と構成上の条件を分ける。
- 節の役割。悪い例：概要の節で詳細な移行手順を説明し、手順の節でも同じ内容を繰り返す。良い例：概要の節は採用判断に必要な効果と条件を示し、手順の節は実行順と確認方法を示す。
レビュー手順
- 文書の目的、読者、扱う範囲と扱わない範囲を確認する。
- 各章と節が答える問いを特定し、配置、重複、前方参照を確認する。
- 事実、推測、推奨、検証結果を区別し、それぞれの根拠を確認する。
- 誰が、何を、どの条件で、どの仕組みによって制御または実行するかを確認する。
- 段落ごとのトピック、段落間の接続、条件と反論を処理してから結論へ進む順序を確認する。
- 重複、表の分類軸、変化しやすい固有情報の配置を確認する。
- 用語、文体、引用、強調、脚注、コードブロックなどの書式を整える。
- 修正した節全体と前後の節を通読し、修正による矛盾、不要な説明、論点の脱落がないか確認する。
