Writing Tech Text Skill

Writing Tech Text

文章を書く、または推敲するときに使う。対象は、第三者に読ませる文章である。ドキュメント、README、PR description、issue、release notes、設計メモ、技術記事、解説文、書籍原稿、コードコメントを含む。いま会話している相手への直接返信には、明示されない限り適用しない。

この skill は、文章の読み方、密度、構成、言い方を整える。調査量や作業範囲を減らすためのものではない。十分な調査や詳細な報告を求められている場合は、必要な中身を保ったまま、読者が追える形にする。

日本語で文章を書く、または日本語の文章を推敲する場合は、必ず references/ja.md も読む。英語固有の規範はまだ持たない。

基本方針

読者が必要な判断に進める文章を書く。文章をきれいに見せる前に、何を言う文章なのか、何が根拠なのか、どこまで分かっているのかを整える。

空疎な丁寧さ、一般論、感情のない水増しを避ける。
推測で意図を補わない。分かっていること、確認したこと、本文に根拠があることを書く。
読者が最初に必要とする文脈から始める。根拠、限定、反論処理、具体例が必要なら展開する。
独自の言い回しや造語に頼らない。広く理解される語で書く。
機械的に保証、検証、強制されている事実を説明しない。読者の判断や行動に必要な場合だけ書く。
実装詳細を入口にしない。メソッド名や変数名は、読者の作業に必要な場合だけ出す。

修正の優先順位

文章を直すときは、表記より先に中身を直す。

立場：この文章が何を言うのか、どこまで言い切るのかを明確にする。
根拠：読者に必要な事実、決定、制約、不確実性を保つ。
主体：誰が何をしたのか、誰が決めたのか、何が変わったのかをぼかさない。
具体性：大きすぎる主語、曖昧な対象、一般論だけの説明を避ける。
構造：段落、見出し、箇条書きが読者の理解を助けているかを直す。
表現：最後に語彙、文体、表記、フォーマットを整える。

表現だけを整えても、立場、根拠、主体が曖昧な文章はよくならない。短くする場合も、論証や判断に必要な要素は削らない。

執筆前の確認

本文を書く前に、次の問いに短く答える。

この文章で読者に何を伝えるのか。
読者はこの文章を読んだあと、何を判断できるべきか。
確定している事実、決定、制約は何か。
未確認、仮説、推測、不確実な点は何か。
読者が誤解しそうな点は何か。
どの具体例、観察、ログ、実装、数値、失敗、比較が主張を支えるのか。

答えられない場合は、本文を書く前にメモを作る。読者に必要な判断が定まっていないまま、文章だけを整えない。

段落

段落は、読者を一歩進める単位として扱う。

一段落に置く話題は一つだけにする。
段落の最初の文で、その段落が何を扱うか分かるようにする。
前段落との関係を必要に応じて明示する。
調査、発見、評価、判断が同じ段落に混ざっているなら分ける。
反論、限定、例外を処理してから結論を置く。
前方参照や補足は、論証の途中ではなく段落末か節末に置く。

段落を短くすること自体を目的にしない。一つの段落が一つの役割を果たしているかを見る。

主張と根拠

主張は、根拠、制約、不確実性と一緒に扱う。

因果を述べるときは、なぜそうなるのかを説明する。
複数の原因がある問題を、一つの原因に還元しない。
異なる概念をまとめる場合は、何が同じで何が違うのかを書く。
例が主張全体を支えていないなら、主張の範囲を狭める。
検出、保証、解決を過剰に言い切らない。条件があるなら条件を書く。
推測、仮説、読者の疑念、反実仮想は断定に変えない。
否定や限定は、否定する命題を具体的に書く。

根拠なしに文章を強くしない。本文内の根拠で確定していることは、ためらわず具体的に書く。

立場

文章には立場が必要である。ここでいう立場は、書き手の人格ではなく、何を見て、何を根拠に、どこまで言うのかという位置取りである。

一般論に逃げない。対象、範囲、状況を具体化する。
両論併記だけで終えない。比較したうえで、どの判断に進むのかを書く。
評価語だけを書かない。何が起き、なぜ問題で、どの判断につながるのかを書く。
未確認のことを、確認したかのように書かない。
個人的な感想や違和感を入れる場合は、主張を支える観察として扱う。

一人称を増やすことが立場ではない。対象、根拠、判断の範囲を具体化することが立場である。

主体と動作

誰が何をしたのか、誰が判断するのかを曖昧にしない。

結果の羅列や受動態だけにしない。
行為者、判断者、責任の所在が必要なら明示する。
「懸念される」「期待される」だけで終えない。誰が何を懸念するのか、何を期待してよいのかを書く。
「AI」「ツール」「システム」のような広い語でぼかさない。必要な粒度まで具体化する。
何が変わったのか、読者に何が影響するのかを書く。

ただし、不要な固有名や内部名を増やさない。読者の理解や作業に必要な主体だけを書く。

読み手の負荷

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

後で参照しない固有名、ファイル名、関数名を出さない。
抽象的な語の指す内容が曖昧なら、文を書き直して特定する。
新しい例を追加する前に、前の例と何が違うのか、なぜ必要なのかを書く。
導入部に、本文で使わない詳細を詰め込まない。
読者が自力で補える中間説明は削る。
読者が前を読み返さないと分からない指示語や抽象語を減らす。

具体性は増やすが、不要な固有情報は増やさない。議論や判断に必要な具体だけを残す。

構造

構造は読者の移動を助けるために使う。

見出しは、その節が扱う対象または問いを示す。
箇条書きは、分類、条件、手順、対比を読みやすくするために使う。
同じ論理的役割の項目だけを並べる。
原因、症状、対策を同じ階層に混ぜない。
文章でつなぐべき関係を、箇条書きに逃がさない。
冒頭と結論は、本文の繰り返しや装飾だけなら短くする。

水増しの除去

中身を増やさない文は削る。

空疎な予告や総括を置かない。
汎用的な称賛や励ましで温度を上げない。
同じ主張を言い換えて繰り返さない。
場面を描写した直後に、その内容を要約し直さない。
接続や評価だけの文を置かない。
読者の反応を演じる問答を乱用しない。

文章を温かくするために空の言葉を足さない。具体的で、短く、判断しやすい文章にする。

推敲手順

レビューだけを求められたら、書き換えずに重大な順に指摘する。書き換えを求められたら、意味と根拠を変えずに直す。

文章の立場を一文で要約する。
根拠、決定、制約、不確実性が保たれているかを見る。
主体、対象、影響範囲を具体化する。
段落、見出し、箇条書きを整える。
水増し、重複、一般論を削る。
最後に語彙、文体、表記を整える。

レビュー出力では、必要に応じて次の形式を使う。

重大度: 高|中|低
箇所: 対象の文または見出し
問題: 何が読み手の理解や判断を妨げるか
理由: なぜそう言えるか
修正方針: どう直すか

セルフチェック

仕上げる前に確認する。

読者は、この文章の目的をすぐ理解できるか。
立場、根拠、主体が曖昧なまま表現だけを整えていないか。
必要な制約や不確実性を削っていないか。
実装詳細を入口にしていないか。
どの文も情報、文脈、判断のいずれかを増やしているか。
冒頭と結論が定型文や装飾だけになっていないか。

Agent Skills: Writing Tech Text

Install this agent skill to your local

Skill Files