| 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 も読む。
英語固有の規範はまだ持たない。
基本方針
読者が必要な判断に進める文章を書く。
文章をきれいに見せる前に、何を言う文章なのか、何が根拠なのか、どこまで分かっているのかを整える。
- 空疎な丁寧さ、一般論、感情のない水増しを避ける。
- 推測で意図を補わない。
分かっていること、確認したこと、本文に根拠があることを書く。
- 読者が最初に必要とする文脈から始める。
根拠、限定、反論処理、具体例が必要なら展開する。
- 独自の言い回しや造語に頼らない。
広く理解される語で書く。
- 機械的に保証、検証、強制されている事実を説明しない。
読者の判断や行動に必要な場合だけ書く。
- 実装詳細を入口にしない。
メソッド名や変数名は、読者の作業に必要な場合だけ出す。
修正の優先順位
文章を直すときは、表記より先に中身を直す。
- 立場：この文章が何を言うのか、どこまで言い切るのかを明確にする。
- 根拠：読者に必要な事実、決定、制約、不確実性を保つ。
- 主体：誰が何をしたのか、誰が決めたのか、何が変わったのかをぼかさない。
- 具体性：大きすぎる主語、曖昧な対象、一般論だけの説明を避ける。
- 構造：段落、見出し、箇条書きが読者の理解を助けているかを直す。
- 表現：最後に語彙、文体、表記、フォーマットを整える。
表現だけを整えても、立場、根拠、主体が曖昧な文章はよくならない。
短くする場合も、論証や判断に必要な要素は削らない。
執筆前の確認
本文を書く前に、次の問いに短く答える。
- この文章で読者に何を伝えるのか。
- 読者はこの文章を読んだあと、何を判断できるべきか。
- 確定している事実、決定、制約は何か。
- 未確認、仮説、推測、不確実な点は何か。
- 読者が誤解しそうな点は何か。
- どの具体例、観察、ログ、実装、数値、失敗、比較が主張を支えるのか。
答えられない場合は、本文を書く前にメモを作る。
読者に必要な判断が定まっていないまま、文章だけを整えない。
段落
段落は、読者を一歩進める単位として扱う。
- 一段落に置く話題は一つだけにする。
- 段落の最初の文で、その段落が何を扱うか分かるようにする。
- 前段落との関係を必要に応じて明示する。
- 調査、発見、評価、判断が同じ段落に混ざっているなら分ける。
- 反論、限定、例外を処理してから結論を置く。
- 前方参照や補足は、論証の途中ではなく段落末か節末に置く。
段落を短くすること自体を目的にしない。
一つの段落が一つの役割を果たしているかを見る。
主張と根拠
主張は、根拠、制約、不確実性と一緒に扱う。
- 因果を述べるときは、なぜそうなるのかを説明する。
- 複数の原因がある問題を、一つの原因に還元しない。
- 異なる概念をまとめる場合は、何が同じで何が違うのかを書く。
- 例が主張全体を支えていないなら、主張の範囲を狭める。
- 検出、保証、解決を過剰に言い切らない。
条件があるなら条件を書く。
- 推測、仮説、読者の疑念、反実仮想は断定に変えない。
- 否定や限定は、否定する命題を具体的に書く。
根拠なしに文章を強くしない。
本文内の根拠で確定していることは、ためらわず具体的に書く。
立場
文章には立場が必要である。
ここでいう立場は、書き手の人格ではなく、何を見て、何を根拠に、どこまで言うのかという位置取りである。
- 一般論に逃げない。
対象、範囲、状況を具体化する。
- 両論併記だけで終えない。
比較したうえで、どの判断に進むのかを書く。
- 評価語だけを書かない。
何が起き、なぜ問題で、どの判断につながるのかを書く。
- 未確認のことを、確認したかのように書かない。
- 個人的な感想や違和感を入れる場合は、主張を支える観察として扱う。
一人称を増やすことが立場ではない。
対象、根拠、判断の範囲を具体化することが立場である。
主体と動作
誰が何をしたのか、誰が判断するのかを曖昧にしない。
- 結果の羅列や受動態だけにしない。
- 行為者、判断者、責任の所在が必要なら明示する。
- 「懸念される」「期待される」だけで終えない。
誰が何を懸念するのか、何を期待してよいのかを書く。
- 「AI」「ツール」「システム」のような広い語でぼかさない。
必要な粒度まで具体化する。
- 何が変わったのか、読者に何が影響するのかを書く。
ただし、不要な固有名や内部名を増やさない。
読者の理解や作業に必要な主体だけを書く。
読み手の負荷
読者の記憶と注意は有限として扱う。
- 後で参照しない固有名、ファイル名、関数名を出さない。
- 抽象的な語の指す内容が曖昧なら、文を書き直して特定する。
- 新しい例を追加する前に、前の例と何が違うのか、なぜ必要なのかを書く。
- 導入部に、本文で使わない詳細を詰め込まない。
- 読者が自力で補える中間説明は削る。
- 読者が前を読み返さないと分からない指示語や抽象語を減らす。
具体性は増やすが、不要な固有情報は増やさない。
議論や判断に必要な具体だけを残す。
構造
構造は読者の移動を助けるために使う。
- 見出しは、その節が扱う対象または問いを示す。
- 箇条書きは、分類、条件、手順、対比を読みやすくするために使う。
- 同じ論理的役割の項目だけを並べる。
- 原因、症状、対策を同じ階層に混ぜない。
- 文章でつなぐべき関係を、箇条書きに逃がさない。
- 冒頭と結論は、本文の繰り返しや装飾だけなら短くする。
水増しの除去
中身を増やさない文は削る。
- 空疎な予告や総括を置かない。
- 汎用的な称賛や励ましで温度を上げない。
- 同じ主張を言い換えて繰り返さない。
- 場面を描写した直後に、その内容を要約し直さない。
- 接続や評価だけの文を置かない。
- 読者の反応を演じる問答を乱用しない。
文章を温かくするために空の言葉を足さない。
具体的で、短く、判断しやすい文章にする。
推敲手順
レビューだけを求められたら、書き換えずに重大な順に指摘する。
書き換えを求められたら、意味と根拠を変えずに直す。
- 文章の立場を一文で要約する。
- 根拠、決定、制約、不確実性が保たれているかを見る。
- 主体、対象、影響範囲を具体化する。
- 段落、見出し、箇条書きを整える。
- 水増し、重複、一般論を削る。
- 最後に語彙、文体、表記を整える。
レビュー出力では、必要に応じて次の形式を使う。
重大度: 高|中|低
箇所: 対象の文または見出し
問題: 何が読み手の理解や判断を妨げるか
理由: なぜそう言えるか
修正方針: どう直すか
セルフチェック
仕上げる前に確認する。
- 読者は、この文章の目的をすぐ理解できるか。
- 立場、根拠、主体が曖昧なまま表現だけを整えていないか。
- 必要な制約や不確実性を削っていないか。
- 実装詳細を入口にしていないか。
- どの文も情報、文脈、判断のいずれかを増やしているか。
- 冒頭と結論が定型文や装飾だけになっていないか。
