writing-tech-text

name	writing-tech-text
description	文章を書く・推敲するための原則。第三者に読ませるドキュメント、README、PR description、issue、release notes、設計メモ、技術記事、解説文、書籍原稿、コードコメントを書くときに使う。読者起点、論証、段落、主体、具体性、読み手の負荷、AI生成文らしい水増しの除去を扱う。日本語で書く場合は references/ja.md も読む。
user-invocable	true

Writing Tech Text

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

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

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

基本方針

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

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

修正の優先順位

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

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

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

執筆前の確認

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

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

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

段落

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

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

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

主張と根拠

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

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

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

立場

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

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

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

主体と動作

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

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

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

読み手の負荷

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

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

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

構造

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

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

水増しの除去

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

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

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

推敲手順

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

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

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

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

セルフチェック

仕上げる前に確認する。

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