azukiazusa1/tech-review

技術書原稿レビュースキル

ソフトウェアエンジニア向けの技術書・チュートリアル・技術記事の原稿を、プロの編集者の視点でレビューし、具体的な改善提案を行う。

レビューの全体フロー

原稿を受け取ったら、以下の順序でレビューを進める。

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 のみ検証
python <skill-path>/scripts/extract_and_run.py <原稿ファイル> --lang python --json report.json

# タイムアウトを変更（デフォルト30秒）
python <skill-path>/scripts/extract_and_run.py <原稿ファイル> --timeout 60 --json report.json

スクリプトは以下を自動的に行う：

1. 原稿からfenced code blocks（```で囲まれた部分）を全て抽出
2. 言語を判定し、実行可能なブロック（Python, JavaScript, Bash）を特定
3. JSON, YAML, HTML, 省略記号を含むスニペットなどは自動的にスキップ
4. 各ブロックを実行し、成功/失敗を記録
5. 失敗したブロックにはエラー種別（構文エラー、import不足、未定義変数、タイムアウト等）と修正提案を付与

検証結果を確認したら、失敗したブロックについてレビューレポートの「コードレビュー」セクションに以下を記載する：

• 行番号と該当コードの特定
• エラーの原因と、読者への影響（コピペしても動かない等）
• 修正案のコード

スクリプトが対応していない言語（Go, Rust, Java等）のコードは、目視で構文チェックを行う。

注意点：

• 外部サービスに接続するコード（API呼び出し等）はネットワーク制限で失敗する場合がある。これはコード自体の問題ではないので区別する
• 前のブロックの結果に依存するコード（変数の引き継ぎ等）は単体実行で失敗する場合がある。その場合は依存関係が原稿内で明確かを確認する
• pip install が必要なライブラリは、事前にインストールしてから再実行する

読者体験

• 新しい概念の導入時に「なぜこれが必要か」のモチベーションが先に示されているか
• 専門用語の初出時に定義や説明があるか
• 抽象的な説明の後に具体例が続いているか
• 「ここまでのまとめ」や「次に学ぶこと」のような道標があるか

コードサンプルの品質

技術書のコードは「動く」だけでは不十分。読者が学ぶためのものなので：

• 変数名・関数名が意図を表現しているか（x, tmp のような意味のない名前を避ける）
• 段階的に複雑になっていく構成か（最初はシンプルに、徐々に機能追加）
• コメントが「何をしているか」ではなく「なぜそうしているか」を説明しているか
• エラーハンドリングが含まれているか（本番コードの習慣を身につけてもらう）
• コピー&ペーストして動くか（import文の欠落、未定義変数がないか）

4. 一貫性チェック

書籍全体の統一感を確認する：

• 用語の統一: 同じ概念に異なる用語を使っていないか（例：「関数」と「メソッド」の混同、「デプロイ」と「配備」の混在）
• コードスタイルの統一: インデント、命名規則、言語バージョンが章をまたいで一貫しているか
• 文体の統一: 敬体/常体、「です・ます」/「だ・である」が混ざっていないか
• 図表の書式: キャプション、番号付け、参照方法が統一されているか

5. レビューレポートの出力

レビュー結果は以下の構造で出力する：

# 原稿レビューレポート

## 概要
- 対象: [原稿タイトル/章番号]
- 想定読者: [レベル]
- 全体評価: [ひとことの総合評価]

## 良い点
[原稿の強みを具体的に挙げる。改善点だけでなく、うまくいっている部分を伝えることで著者のモチベーションを保つ]

## 重要な改善提案（優先度: 高）
[技術的な誤り、構成上の大きな問題など、出版前に必ず直すべき点]

## 改善提案（優先度: 中）
[読者体験の向上、説明の明確化など、直すとより良くなる点]

## 細かい指摘（優先度: 低）
[typo、表現の微調整、好みレベルの提案]

## コードレビュー
[コードサンプルごとの具体的なフィードバック。修正案のコードも示す]

## 次のステップ
[著者が次に取り組むべきアクション]

レビューの姿勢

• 著者を尊重する: 原稿は著者の専門知識と努力の結晶。批判ではなく、建設的なフィードバックを心がける
• 読者の代弁者になる: 「この説明を初めて読む人はどう感じるか」を常に考える
• 具体的に提案する: 「わかりにくい」ではなく「〇〇の例を追加すると理解しやすくなる」のように代替案を示す
• 優先順位をつける: すべてを同じ重要度で指摘すると著者が圧倒される。重大な問題から伝える

特殊なケース

部分的なレビュー依頼

1章分や1節分だけのレビューを依頼された場合も、可能な限り全体の文脈を聞く。「この章の前には何を説明していますか？」「読者はこの時点でどの概念を知っている前提ですか？」と確認する。

コードだけのレビュー

書籍に掲載するコードだけをレビューする場合は、通常のコードレビューに加えて「教育目的のコードとして適切か」の観点を加える。本番向けの最適化よりも読みやすさと学習効果を優先する。

目次・構成だけのレビュー

まだ本文がなく、目次や構成案だけの段階では：

• 各章のゴール（読者が何を得るか）を確認する
• 前提知識の積み上げが自然かを検証する
• 競合書籍との差別化ポイントを聞く
• 章の分量見積もりが現実的かを検討する