# Tech Writing Review

> テクニカルライティングガイドライン(documents/forTechnicalWriting/technical_writing_guidelines.md)に準拠しているかドキュメントをレビューする。ガイドライン文書・設計書・Markdown記事・依頼/報告文のレビュー依頼時、「テクニカルライティング観点でレビューして」「ライティングレビュー」と言われた時に使用する。

- Skill: `future-architect/tech-writing-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add future-architect/tech-writing-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/future-architect/tech-writing-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: future-architect (https://skillmd.com/u/future-architect)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/future-architect/tech-writing-review

---


# テクニカルライティングレビュー

対象ドキュメントを `documents/forTechnicalWriting/technical_writing_guidelines.md` のルールに照らしてレビューし、指摘と修正案を返す。

## レビュー手順

1. **対象の特定**: 引数・会話からレビュー対象(ファイルパス、diff、貼り付けテキスト)を特定し、全文を読む。長いファイルも省略せず最後まで読むこと。
2. **文書タイプの判定**: 適用するチェックカテゴリを選ぶ。
   - **ガイドライン・設計書・記事など単体で読まれる文書** → カテゴリ A〜F を適用
   - **依頼・報告・相談などのメッセージ文** → カテゴリ A〜F に加えて G も適用
3. **チェック**: 下記チェックリストを上から順に照合する。機械的な違反(指示語リンク、時間依存表現など)は Grep で全数確認する。
4. **報告**: 「指摘の書き方」に従って出力する。修正の実施は指示があるまで行わない(レビューが成果物)。

## 対象外(textlintとの役割分担)

このリポジトリは textlint を併用している。**辞書・ルールで機械検出できるものは textlint の守備範囲**とし、このスキルでは指摘しない。

- 対象外: 文字レベルの表記ゆれ(ヘッダ/ヘッダー、サーバ/サーバー等の長音符・カタカナ揺れ)、句読点・スペースの形式、textlintルールで既にカバーされる文体
- スキルの担当: 意味を読まないと検出できないもの — 概念レベルの用語揺れ(C3)、係り受けの破綻や誤変換(C7)、記号と説明文の矛盾、論理の自己矛盾、壊れたリンクなど

レビュー中に「これはprh辞書に追加すれば機械検出できる」と気づいたものは、指摘リストとは別に textlint への追加候補として1行で報告する。

## 指摘の書き方

ガイドライン自身の「フィードバック技術」に従う。「わかりにくい」だけの指摘は禁止。各指摘には必ず次を含める:

- **場所**: `ファイルパス:行番号` と問題箇所の引用
- **根拠**: ガイドラインのどの節に反するか(下記チェック項目のID or 節名)
- **読み手にどう映るか**: なぜ問題か、読み手視点での影響
- **修正案**: 具体的な書き換え例(機械的に直せるものは必ず提示)

重大度で分類して報告する:

| 重大度 | 基準                                               |
| ------ | -------------------------------------------------- |
| MUST   | ガイドラインへの明確な違反。誤読・保守性低下を招く |
| SHOULD | 改善を推奨。読み手の認知負荷を上げている           |
| NIT    | 好みの範囲。まとめて簡潔に                         |

冒頭にサマリ(対象、指摘件数の内訳、全体所感)を置き、指摘は重大度順に並べる。件数が多い場合、同種の機械的指摘(表記ゆれ等)は1項目にまとめて全該当箇所を列挙する。

## チェックリスト

各IDはガイドラインの節に対応する。判断に迷ったら元のガイドラインの該当節を読むこと。

### A. 構造化

- **A1 構造化の優先**: 構造化可能な情報が散文のまま書かれていないか。表 > ラベル付きリスト > 番号付きリスト > 箇条書き の順で上位フォーマットの適用を検討する。共通の比較軸があるのに箇条書き、はNG
- **A2 番号の意味**: 順序に意味がないのに番号付きリストを使っていないか(並び替えても意味が通じるなら番号を付けない)
- **A3 粒度の統一**: 同一階層の項目で視点(主語)や品詞(文末: 動詞/体言止め)が混在していないか
- **A4 MECE**: 抽象度の違う項目が同列に並んでいないか。ダブりのある具体項目は上位概念の下にネストする
- **A5 導入文**: リストや表の直前に、その役割(前提条件か手順かなど)を説明する一文があるか
- **A6 項目の自立**: リスト・表の項目が単体で意味が通じるか。「これ」「前述の通り」等の指示語や極端な省略がないか
- **A7 細切れ箇条書き**: 文章を短く切って並べただけで論理関係(因果・補足)が消えた箇条書きがないか。役割を示すラベル(【依頼】【補足】等)を付ける
- **A8 因果のネスト禁止**: 「原因→結果」をインデントで表現していないか。1文にするか、ラベル付きで同列に並べる

### B. 簡潔さ

- **B1 件名・見出しの具体性**: 件名・見出しだけで内容が判別できるか。「〜について」のような曖昧な表現はNG
- **B2 主題文**: 冒頭の一文で目的(確認・相談・報告など、何の話か)を明示しているか
- **B3 情報密度**: 削れる修飾語・冗長表現がないか。「〜につきましては」「〜という形となります」等。受動態を能動態にできる箇所がないか
- **B4 一文の長さ**: 一文が50〜60文字を大きく超えていないか。超える場合は削除・分割・構造化する
- **B5 並列要素の埋没**: 複数の並列要素が文中に埋め込まれていないか。箇条書き+体言止めにする
- **B6 一文一義**: 「〜ので」「〜し」で文を繋ぎすぎて、報告と注意喚起などが混在していないか
- **B7 逆接以外の「〜が」**: 「〜ですが、」を単純接続で使っていないか。逆接のみに限定する
- **B8 名詞句・無生物主語**: 長い名詞句の連なりや無生物主語(AI文体)がないか。動詞中心の自然な日本語に書き換える

### C. 表現の正確性

- **C1 読み手の用語**: 読み手が普段使う言葉を選んでいるか(学術的正確さより伝わることを優先)
- **C2 用語の正確性**: 認証/認可のような専門用語を正しく使っているか。公式ドキュメントの定義と乖離していないか
- **C3 概念レベルの用語揺れ**: 同一概念に複数の"別語"(ユーザー/アカウント/お客様 等)を使っていないか。※ヘッダ/ヘッダー等の文字レベルの揺れはtextlintの守備範囲のため対象外
- **C4 略称**: 略称の初出時に正式名称を併記しているか(API等の自明な語を除く)。濫用していないか
- **C5 多義語**: トランザクション、サービス、ユーザー、環境など複数の解釈が可能な用語を、修飾や定義なしで使っていないか。必要なら「何を含まないか」も明記する
- **C6 定性表現の数値化**: 「大容量」「高速」など解釈がブレる表現は数値化するか、代表例を示しているか
- **C7 誤字・日本語の破綻**: 意味を読まないと検出できない誤りがないか。単語の重複(「把握の把握」)、助詞の誤り・脱落(「2通りがの」)、係り受けのねじれ(「〜の使用を〜では許容していない」)、同音誤変換(務める/努める)、外来語の中途半端な翻訳(「Unprocessable エンティティ」)、カタカナ語の欠損(プレフィックス→プレックス)など。※prh辞書に載せられる定型的な誤記はtextlintに委譲する

### D. 具体例

- **D1 必要な例示**: 解釈がブレる抽象表現や、境界値・異常系の定義に具体例が添えられているか
- **D2 不要な例示**: 読み手に自明な事実への例示や、一部項目だけの中途半端な例示(網羅性への誤解を生む)がないか
- **D3 例より構造化**: 複雑な条件分岐を散文の例で説明していないか。決定表・状態遷移図等に置き換える

### E. パターン(ガイドライン・設計書向け)

- **E1 トレードオフ**: 技術選定・方針決定に「なぜ他ではなくこれか」の判断ロジック(メリット/デメリット)が書かれているか。結果のみの記載はNG
- **E2 Appendix分離**: 本筋から逸れる詳細データや検討過程が本文に混ざっていないか
- **E3 要件レベル**: ルールの強制力が MUST(必須)/SHOULD(推奨)で区別されているか。「〜すること」だけで強制力が曖昧なものはNG。例外の適用条件も明記する
- **E4 GOOD/BAD**: 抽象的なルールに推奨例・アンチパターンの具体例がセットで提示されているか
- **E5 背景・不採用案**: 決定事項に背景・制約・不採用案が記録されているか

### F. アンチパターン(ユーザビリティ・保守性)

- **F1 テキストのスクリーンショット**: コマンドや出力をスクリーンショット画像で載せていないか(コピペ・検索不可)。テキスト+コードブロックにする
- **F2 指示語リンク**: 「こちら」「ここ」にリンクを張っていないか。リンクテキストで内容がわかるようにする
- **F3 コードブロックの純度**: コードブロック内にプロンプト記号(`$` `#` `>`)や操作説明テキストが残っていないか。説明はブロック外へ、入出力は分離する
- **F4 時間依存表現**: 「最新」「現在」「近年」など時間経過で意味が変わる表現がないか。バージョンや具体的条件を記載する
- **F5 外部リンク依存**: 「詳細は次のサイトを参照」と外部サイトへ丸投げしていないか。必要部分を引用し出典URLを添える
- **F6 GUI位置依存**: 「右上のボタン」など位置だけの説明がないか。ボタン名・メニュー名を併記する
- **F7 導入の唐突さ**: 冒頭1文が読み手の未知情報から始まっていないか。読み手が同意できる既知情報から書き出す

### G. メッセージ設計(依頼・報告・相談文のみ)

- **G1 5W1H**: 誰に(by-name)・何を・いつまでに(希望期限とデッドライン)・どこで(対象範囲、URL)・どうしてほしいか(共有/選択/承認)が明確か
- **G2 判断材料**: 意思決定を求める場合、影響度・リスク・工数・代替案など判断材料を提示しているか
- **G3 空・雨・傘**: 事実の羅列で止まらず、書き手の見解(傘=取るべきアクション)まで述べているか。純粋な共有なら冒頭で「ご報告ですが」と宣言する
- **G4 PREP/STAR**: 意思決定を求める文は結論から(PREP)、障害エスカレーション等は状況から(STAR)の順になっているか
- **G5 直接回答**: Yes/Noクエスチョンにまず結果から答えているか。「いつ」の問いに状況説明で返していないか
- **G6 文脈の提供**: 間が空いたスレッド・チケットの更新時に、前回までの経緯を冒頭で補足しているか
- **G7 やったことの羅列**: 作業内容・システム挙動の羅列になっていないか。目的(妥当性評価/承認/成果共有)に応じた Why・課題解決の見通し・読み手にとっての価値を書く