Writing Tech Text

---
name: writing-tech-text
description: PR 本文、ADR、design-doc、README、記事、コードコメントなど、第三者が読む文章の新規執筆・改稿・文章レビューに必ず使う。一文の変更や誤字修正にも、変更の規模や種類を問わず適用する。会話相手への直接返信は、明示された場合だけ対象にする。
user-invocable: true
---

# Writing Tech Text

読者が必要な判断に進める文章を書く。
依頼された範囲で、意味、根拠、確信度を保ちながら構成と表現を整える。

## 適用範囲と参照資料

PR 本文、ADR、design-doc など、第三者が読む文章を扱うたびにこの skill を使う。
新規執筆、改稿、一文の変更、誤字修正、文章レビューのいずれも対象とし、変更の規模や種類で省略しない。
会話相手への直接返信は、明示された場合だけ対象にする。

[構成と論証の見直し](references/composition.md)を毎回読み、依頼された範囲に適用する。
日本語の文章を扱う場合は、[日本語の規範](references/ja.md)も読む。
英語固有の規範はまだ持たない。

## 依頼に合わせた使い方

- 短い推敲や表記修正は、その範囲を直接直す。
  全文の再構成や事前メモを必須にしない。
- レビューだけを求められたら、本文を書き換えず、理解や判断を妨げる問題を重大な順に指摘する。
  箇所、理由、修正方針が伝われば、定型の出力項目を埋める必要はない。

規範の参照を理由に、依頼箇所以外の全文を書き換えたり、全観点への回答や定型手順を求めたりしない。

## 保持するもの

- 読者に必要な事実、決定、制約、不確実性を残す。
  短くするために論証や判断の材料を削らない。
- 推測で書き手の意図を補わず、未確認のことを確認済みとして書かない。
  推測、仮説、疑念、反実仮想を断定に変えない。
- 因果や保証を述べるなら根拠と適用条件を示す。
  根拠が支える範囲を超えて主張を強めない。
- ユーザーの文体と確信度を保つ。
  意味を変える判断が必要なら、推敲に紛れ込ませず、確認点として示す。
- 要求された調査量や報告の詳しさを減らさない。
  必要な中身を読者が追える形にする。

## 読者に合わせた表現

文章全体を見直すときは、表記より先に、何を主張し、何が根拠で、誰に何が変わるのかを整える。

- 読者が最初に必要とする文脈から始める。
  実装名や内部の詳細は、理解や作業に必要な分だけ出す。
- 主体、対象、影響範囲を具体化する。
  大きな主語、評価語、一般論だけで説明を済ませない。
- 段落、見出し、箇条書きは、情報の関係を読者が追える形にする。
  個数や長さを揃えるために内容を分割しない。
- 広く理解される語を使い、独自の造語や気取った表現を避ける。
- 読者の判断に情報を加えない予告、総括、称賛、重複を削る。
  機械的な保証や検証の説明も、読者の判断や行動に必要な場合に限る。

## セルフチェック

変更した範囲を読み返し、意味・根拠・制約・確信度が保たれ、読者に必要な情報が伝わることを確かめる。
必要な内容を伝えられた時点で完成とし、チェック結果や定型の総括を本文に付け足さない。