| name | document-review |
| description | ドキュメントのレビューを行う場合にこのスキルを使用してください。
技術的正確性、完全性、最新性、可読性、保守性の観点から問題点を特定するための手順と観点を提供します。
|
ドキュメントレビュースキル
このスキルは、技術文書や運用文書をレビューし、誤り、抜け漏れ、古くなった記述、伝わりにくい構成を特定するための観点を提供します。
レビューの前提
- 関連スキルである
document-write をベースラインとして、記述方針、構成、同期方針とのズレを確認する
- 実装や設定との整合性確認が必要な場合は、関連コードや一次情報を読んで根拠を取る
- レビューの主目的は、文書をその場で書き直すことではなく、問題点、根拠、影響を明確にすることにある
有効化するタイミング
- ユーザーがドキュメントレビューを依頼した場合
- 文書が現在の実装や運用手順に追従しているか確認したい場合
- リリース前に README、設計書、手順書、API 文書の抜け漏れを確認したい場合
- 既存文書の読みやすさや保守性に問題がないか確認したい場合
進め方
- レビュー対象と、その文書が依拠している実装、設定、外部仕様を特定する
- 周辺文書を読み、対象文書の責務と前提知識の置き方を把握する
- 実装、コマンド、設定例、図、リンクを突き合わせて事実関係を確認する
- 正確性、完全性、最新性、可読性、保守性の観点で問題点を洗い出す
- 指摘ごとに根拠、影響、優先度を整理して返す
技術的正確性
- 実装、設定、公開 API、CLI 挙動と文書の説明が一致している
- コード例、コマンド例、設定例が現在の手順で再現可能である
- 図やシーケンスが、実際の責務分担やデータフローを誤って表現していない
- 外部仕様を前提にしている場合、一次情報への参照が妥当である
完全性
- 読者が作業や判断に必要な前提条件、制約、手順、例外事項が揃っている
- 更新した実装に伴って必要になる関連文書の追従漏れがない
- 新しい設定値、環境変数、権限、依存関係、運用手順が追加された場合に記述されている
- 失敗時の挙動、注意点、移行条件など、運用上必要な情報が落ちていない
最新性
- 現在のブランチや対象リリース時点の実装状態を反映している
- 廃止済みの手順、古い画面、旧 API、旧設定値が残っていない
- 他の文書と比較して、片方だけ古い説明になっていない
一貫性と構成
- 用語、記法、見出し構成、文体が周辺文書と整合している
- 文書の責務が明確で、別文書との重複や責務衝突が大きくない
- 見出し階層が破綻しておらず、情報の流れを追いやすい
- リンク、相互参照、関連文書への導線が不足していない
可読性と実用性
- 対象読者に対して前提知識の置き方が適切である
- 段落、箇条書き、表、図の使い分けが内容に合っている
- 重要な制約や注意点が埋もれていない
- 読者が作業手順を上から順にたどって実行できる構成になっている
保守性
- 将来の更新箇所が推測しやすく、変更点が文書内に散らばりすぎていない
- 自動生成できる内容と手書きで維持すべき内容が適切に分かれている
- 実装変更のたびに壊れやすい記述が多すぎない
- 生成物をレビュー対象に含む場合、生成元や更新手順が追跡できる
指摘の整理
重大
- 誤った操作や障害につながる誤記
- セキュリティ、データ消失、運用事故につながる説明不足
- 現行実装と矛盾する断定的な記述
要対応
- 前提条件や手順の抜け漏れ
- 関連文書との不整合
- 古い情報の残存
- 読者が誤解しやすい構成や表現
改善
- 用語の揺れ
- 冗長な説明
- 導線不足
- 将来の更新を難しくする構成
フィードバックの形式
- 各指摘には、対象文書、該当箇所、何が問題か、根拠、想定される影響を含める
- 実装や一次情報を確認できていない箇所は、その制約を明記する
- 変更提案を添える場合も、まず問題発見と根拠提示を優先する
注意点
- レビュー依頼では、修正より先に問題発見を優先する
- 文書単体だけで断定せず、必要に応じて実装、設定、履歴、関連文書を確認する
- 読みやすさの好みと、実害のある問題を区別して扱う