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