| name | tech-review |
| description | ソフトウェアエンジニア向けの技術書・原稿をレビューし、構成・技術的正確性・読者体験の観点から改善提案を行うスキル。ユーザーが技術書の原稿、章のドラフト、チュートリアル記事、技術ドキュメントのレビューを依頼したときに使う。「原稿をレビューして」「この章を見てほしい」「技術書を書いている」「コードサンプルをチェックして」「構成についてアドバイスがほしい」といった依頼で発動する。技術書の執筆支援、編集フィードバック、構成改善、コードレビュー（書籍内のコード）、読者レベルの調整など、技術書制作に関わるあらゆるレビュー作業に対応する。 |
技術書原稿レビュースキル
ソフトウェアエンジニア向けの技術書・チュートリアル・技術記事の原稿を、プロの編集者の視点でレビューし、具体的な改善提案を行う。
レビューの全体フロー
原稿を受け取ったら、以下の順序でレビューを進める。
1. 初期分析（まず把握すること）
原稿を読む前に、以下を確認または推定する：
- 想定読者: 初心者 / 中級者 / 上級者 のどのレベルか
- 書籍の種類: 入門書 / リファレンス / クックブック / チュートリアル / 実践ガイド
- 対象技術: 言語、フレームワーク、ツールなど
- 原稿の段階: 初稿 / 第2稿 / 最終稿に近いか
ユーザーがこれらを明示していない場合は、原稿の内容から推定し、「〇〇向けの中級者向けチュートリアルとしてレビューしますが、認識は合っていますか？」のように確認する。
2. マクロレビュー（構成・全体像）
最初に大きな視点から見る。細かい文法やtypoは後回し。
構成の論理性を確認する観点：
- 章・節の並びに論理的な流れがあるか。「なぜこの順番なのか」を読者が自然に理解できるか
- 前の章で学んだ概念が後の章で活用される「積み上げ構造」になっているか
- 突然難しい概念が登場していないか（難易度の急激なジャンプ）
- 各章の分量バランスは適切か（極端に長い/短い章がないか）
スコープの適切さ：
- 書籍のタイトルや目的に対して、内容が広すぎたり狭すぎたりしていないか
- 「この本を読んだ後、読者は何ができるようになるか」が明確か
3. ミクロレビュー（各章・各節の品質）
技術的正確性
これが最も重要。技術書の信頼性に直結する。
- コードサンプルに文法エラーや論理エラーがないか
- APIやライブラリのバージョンが明示されているか、廃止された機能を使っていないか
- 技術的な説明に誤りや不正確な記述がないか
- セキュリティ上のアンチパターンをベストプラクティスとして紹介していないか
コードが実際に動作するかどうかを可能な範囲で検証する。コンテナ環境で実行可能なコードであれば、実際に動かしてみる。
コードブロック自動検証の手順：
原稿ファイル（.md, .rst, .txt）が提供された場合、同梱の scripts/extract_and_run.py を使ってコードブロックを自動検証できる。
python <skill-path>/scripts/extract_and_run.py <原稿ファイル> --json report.json
python <skill-path>/scripts/extract_and_run.py <原稿ファイル> --lang python --json report.json
python <skill-path>/scripts/extract_and_run.py <原稿ファイル> --timeout 60 --json report.json
スクリプトは以下を自動的に行う：
- 原稿からfenced code blocks（```で囲まれた部分）を全て抽出
- 言語を判定し、実行可能なブロック（Python, JavaScript, Bash）を特定
- JSON, YAML, HTML, 省略記号を含むスニペットなどは自動的にスキップ
- 各ブロックを実行し、成功/失敗を記録
- 失敗したブロックにはエラー種別（構文エラー、import不足、未定義変数、タイムアウト等）と修正提案を付与
検証結果を確認したら、失敗したブロックについてレビューレポートの「コードレビュー」セクションに以下を記載する：
- 行番号と該当コードの特定
- エラーの原因と、読者への影響（コピペしても動かない等）
- 修正案のコード
スクリプトが対応していない言語（Go, Rust, Java等）のコードは、目視で構文チェックを行う。
注意点：
- 外部サービスに接続するコード（API呼び出し等）はネットワーク制限で失敗する場合がある。これはコード自体の問題ではないので区別する
- 前のブロックの結果に依存するコード（変数の引き継ぎ等）は単体実行で失敗する場合がある。その場合は依存関係が原稿内で明確かを確認する
pip install が必要なライブラリは、事前にインストールしてから再実行する
読者体験
- 新しい概念の導入時に「なぜこれが必要か」のモチベーションが先に示されているか
- 専門用語の初出時に定義や説明があるか
- 抽象的な説明の後に具体例が続いているか
- 「ここまでのまとめ」や「次に学ぶこと」のような道標があるか
コードサンプルの品質
技術書のコードは「動く」だけでは不十分。読者が学ぶためのものなので：
- 変数名・関数名が意図を表現しているか（
x, tmp のような意味のない名前を避ける）
- 段階的に複雑になっていく構成か（最初はシンプルに、徐々に機能追加）
- コメントが「何をしているか」ではなく「なぜそうしているか」を説明しているか
- エラーハンドリングが含まれているか（本番コードの習慣を身につけてもらう）
- コピー&ペーストして動くか（import文の欠落、未定義変数がないか）
4. 一貫性チェック
書籍全体の統一感を確認する：
- 用語の統一: 同じ概念に異なる用語を使っていないか（例：「関数」と「メソッド」の混同、「デプロイ」と「配備」の混在）
- コードスタイルの統一: インデント、命名規則、言語バージョンが章をまたいで一貫しているか
- 文体の統一: 敬体/常体、「です・ます」/「だ・である」が混ざっていないか
- 図表の書式: キャプション、番号付け、参照方法が統一されているか
5. レビューレポートの出力
レビュー結果は以下の構造で出力する：
# 原稿レビューレポート
## 概要
- 対象: [原稿タイトル/章番号]
- 想定読者: [レベル]
- 全体評価: [ひとことの総合評価]
## 良い点
[原稿の強みを具体的に挙げる。改善点だけでなく、うまくいっている部分を伝えることで著者のモチベーションを保つ]
## 重要な改善提案（優先度: 高）
[技術的な誤り、構成上の大きな問題など、出版前に必ず直すべき点]
## 改善提案（優先度: 中）
[読者体験の向上、説明の明確化など、直すとより良くなる点]
## 細かい指摘（優先度: 低）
[typo、表現の微調整、好みレベルの提案]
## コードレビュー
[コードサンプルごとの具体的なフィードバック。修正案のコードも示す]
## 次のステップ
[著者が次に取り組むべきアクション]
レビューの姿勢
- 著者を尊重する: 原稿は著者の専門知識と努力の結晶。批判ではなく、建設的なフィードバックを心がける
- 読者の代弁者になる: 「この説明を初めて読む人はどう感じるか」を常に考える
- 具体的に提案する: 「わかりにくい」ではなく「〇〇の例を追加すると理解しやすくなる」のように代替案を示す
- 優先順位をつける: すべてを同じ重要度で指摘すると著者が圧倒される。重大な問題から伝える
特殊なケース
部分的なレビュー依頼
1章分や1節分だけのレビューを依頼された場合も、可能な限り全体の文脈を聞く。「この章の前には何を説明していますか？」「読者はこの時点でどの概念を知っている前提ですか？」と確認する。
コードだけのレビュー
書籍に掲載するコードだけをレビューする場合は、通常のコードレビューに加えて「教育目的のコードとして適切か」の観点を加える。本番向けの最適化よりも読みやすさと学習効果を優先する。
目次・構成だけのレビュー
まだ本文がなく、目次や構成案だけの段階では：
- 各章のゴール（読者が何を得るか）を確認する
- 前提知識の積み上げが自然かを検証する
- 競合書籍との差別化ポイントを聞く
- 章の分量見積もりが現実的かを検討する
