---
name: japanese-technical-writing
description: '日本語の技術文書を Markdown ファイルとして作成、編集、レビューするときに使う。対象は技術書原稿、技術記事、解説文、提案書、ADR、README、設計文書、運用手順。技術的な誤読を防ぐ説明と、用語や表記を整える。通常のチャット応答、会話内だけの文章作成、レビューコメントには使わない。'
license: Unlicense
---

# 日本語技術文書の文章規範

日本語の技術文書を、判断に必要な情報と根拠が明確で、論理を追いやすい文章へ整える。事実の正確さ、論理の一貫性、判断に必要な情報を、文体や表記より優先する。

対象は Markdown ファイルとして作成、推敲、レビューする日本語の技術文書。通常のチャット応答、会話内だけの文章作成、レビューコメント、英語文書だけの編集、コードそのものの設計判断には使わない。

このスキルは https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d の文章規範を、Copilot CLI 向けに整理したものである。

## 技術的な誤読を防ぐ

- 事実、推測、推奨、検証結果を区別し、根拠に応じた強さで書く。未確認の内容を断定せず、確立した事実を不必要に弱めない。
- 能動態と直接的な記述を基本にし、誰が、何を、どの操作や仕組みで実行するかを明確にする。
- 機能の有無と、利用条件、適用範囲、保証範囲を分ける。一つの構成で生じる制約から、機能自体が存在しないと結論づけない。
- 因果、比較、推奨には、それを支える根拠と条件を示す。例が支える範囲を超えて一般化せず、異なる原因や問題を同一視しない。反論を扱う場合も、架空の読者や根拠のない通説を作らない。

## 構成と情報量を整える

- 文書の目的、読者の背景知識、対象範囲に合わせて構成と詳しさを選ぶ。主眼を早めに示し、判断に必要な説明、根拠、成立条件を文書に適した順で展開する。
- 一つの話題を扱う明快な段落を基本にし、前の文を受けて説明を進める。
- 各節の役割を明確にし、同じ問いに答える説明を重複させない。概念の分類、定義、用語を文書全体で統一し、理解に必要な説明と参照先を読者が追える位置に置く。
- 削るのは重複や論点を増やさない説明であり、判断に必要な対象、条件、因果ではない。識別子、数値、例は、読者の判断や理解に役立つものを選ぶ。
- 検証日や検証環境などの詳細は検証記録へ集約し、本文から参照する。ただし、文書の目的である操作手順や、採否の判断に必要な版の差は本文に残す。
- 箇条書きは並列項目や手順の整理に、表は比較に役立つ場合に使う。入れ子は文章では階層を明確に表せない場合に限る。
- 表は各列の分類をそろえる。効果、前提、限界を同じ列に混在させず、空欄や長い但し書きが続く場合は列の分け方か表形式を見直す。

## 用語、表記、文体

- 見出しは対象を特定できる自然な句にする。疑問形でも名詞句でもよい。区切り線で複数の論点を詰め込まず、執筆作業だけを示す表現や内容のない決め台詞を避ける。
- 段落は空行で区切り、段落内の改行は媒体や既存文書の形式に合わせる。コード、差分、ログ、設定断片はコードブロックに入れる。
- 脚注は、判断に必要だが本文の流れを妨げる補足に限る。
- 文書固有の用語や後続の議論で重要な定義は、初出時に太字で示す。一般語や一度しか使わない語は初出だけを理由に強調しない。それ以外の太字は、誤読を防ぐ否定や節の結論など論理上の要所に限る。
- 「」は、語そのものへの言及、引用、通称、UI ラベルなど境界を示す必要がある箇所に使う。定義後の通常の言及を一律に囲まない。定義の箇条書きは `**用語**：説明` の形にする。
- 読者になじみのある平易な語、具体例、正確な動詞で説明する。必要な術語や訳語は分野の慣用に従い、読者の背景知識に応じて補足する。「AI」「ツール」のような広い語や、その場で作った複合ラベルで対象や関係をぼかさない。
- 読者はむやみに「あなた」と呼ばず、「開発者」「管理者」などの役割名で書く。
- 評価や推奨では、命令調で選択を強制せず、根拠と判断条件を示す。操作手順では命令形で実行する操作を明確にしてよい。
- 日本語の地の文や見出しでダッシュ類を使わない。補足は括弧、言い換えは文の分割か読点で処理する。ただし、範囲を示す en ダッシュ、英語の複合語、コードブロック、書誌情報は対象外とする。
- 日本語の並列に中黒を使わない。ただし、固有名詞の一部なら使ってよい。
- 修辞や比喩は論点を明確にする場合に限る。「重要なのは」「要するに」などの予告や再要約だけの文、具体的な基準のない評価語、曖昧な修飾語、定型的なつなぎ表現を削る。対象や操作が分からない抽象表現は具体化する。修辞疑問、決め台詞、想像上の問答、接続語や強調語の多用を避ける。
- 説明に不要な対案を持ち出す「AではなくB」という対比や、執筆方針、実行しないこと、変更しないことの予告を加えない。対象範囲、互換性、制約が判断に必要な場合は明記する。

## 判断に迷う場合の例

### 記録と保証を分ける

悪い例：「監査ログで不正操作を検出できる」

良い例：「監査サービスは管理 API の呼び出しを記録する。データプレーンの操作は記録対象外であり、このログだけでは不正操作を網羅できない」

### 機能と構成上の条件を分ける

悪い例：「プライベート接続では開発端末から利用できないため、このサービスは閉域化できない」

良い例：「サービスはプライベート接続に対応する。開発端末から接続するには、端末を名前解決と経路制御の対象へ含める必要がある」

## 編集後の確認

修正した節と前後の節を読み直し、矛盾、重複、論点の脱落がないか確認する。局所的な文体修正によって、主張の強さや適用範囲を変えない。