KDP技術書の書き方——非エンジニア向け査読で見えた3つの穴

3冊のKDP原稿を一気に査読して、共通の問題が見えた。ターゲットは非エンジニアの会社員なのに、文章の中に技術用語が静かに増殖していた。「Claude Code の API ラッパー経由でフックを設定する」——このフレーズ、一般読者には解読不能だ。

この記事でわかること：
– 非エンジニア向け技術書でやりがちな用語の詰め込みすぎパターン
– 実際の原稿（3冊）で見つけた失敗例と修正前後の比較
– 原稿チェックに使えるPythonスクリプト（コピペ可）
– Claude を使ったセルフ査読の方法と所要時間

---

「非エンジニア向け」のつもりが専門書になっていた

今日査読したのは3冊。「30分で動く！Claude Code はじめての使い方」「Claude Code つまずき解消大全」「Gemini 2.0完全入門」。全部「初心者・非エンジニア向け」として書いたはずだ。

品質スコアは avg 93〜95。数字だけ見ると問題なさそうに見える。でも実際に本文を読むと、ところどころで「知っている前提」の文章が混じっていた。

vol02_jp の第2章、こんな一文があった：

Claude Code は CLI 経由で slash command を呼び出し、フックで
pre-tool / post-tool の処理を挟める。

CLI、slash command、フック、pre-tool——これを一文に詰め込んで、非エンジニアに「分かった」と感じさせられるはずがない。書いた本人（私）がエンジニア思考のまま書き進めた典型的なミスだ。

---

技術用語の「入れすぎ」vs「ちょうどいい」比較

判定	文例	問題
NG	CLIからスラッシュコマンドを呼ぶ	CLI・スラッシュコマンドが未定義
NG	APIラッパー経由で設定を注入する	ラッパー・注入が未説明
NG	フックでpre/post処理を挟む	フックの概念から説明が必要
OK	ターミナルで /help と入力するだけ	動作を直接書いている
OK	設定ファイルに1行追加すれば動く	読者の行動が明確
OK	エラーが出たら、このコマンドを貼る	コピペ前提で書いている

OKパターンに共通しているのは「読者が次に何をすればいいかが自明」な書き方だ。NGパターンはすべて「用語の意味を知っている前提」で成立している。

---

vol04_jp 第3章——症状リストがなかったせいで辞書として機能しなかった

「Claude Code つまずき解消大全」は、辞書として使うことを想定して書いた。エラーが出たらページを開いて、該当の症状を探して解決策を読む——そういう使い方だ。

ところが第3章の冒頭に症状の一覧がなかった。目次から飛んでくる読者に、いきなり本文が始まる構造になっていた。修正で追加したのはこれだけ：

## 症状クイックリファレンス

- ターミナルが「command not found」と返す → 3-1節
- 認証エラーで止まる → 3-2節
- 設定ファイルが読み込まれない → 3-3節
- 途中で応答が途切れる → 3-4節
- 日本語が文字化けする → 3-5節

9行のリストを追加しただけで、「どこを読めばいいか」が一瞬で分かるようになった。技術用語の問題ではなく、構造の問題だった。非エンジニア読者には「探索コスト」を下げてあげることが先決で、難しい用語を排除するより先にやるべきことがある——それが今回の気づきだ。

---

vol15_jp の「一つ目〜五つ目」列挙——散文に直したら情報設計の問題が見えた

Gemini 2.0完全入門の第5章に、こういう構造があった：

一つ目は画像認識機能です。
二つ目はコード生成機能です。
三つ目は長文要約機能です。
四つ目はマルチモーダル対応です。
五つ目は日本語精度の向上です。

「まず〜次に〜最後に」の亜種。これを散文に書き直した：

Gemini 2.0 が以前と違うのは、画像を見ながらコードを書ける点だ。
テキストと画像を同時に渡せる——これが「マルチモーダル」の実態で、
用語を覚えなくても、試せば5分で理解できる。
要約精度も上がった。1万字の記事を貼り付けて「300字で要約して」と
頼むと、ほぼ読んだような結論が返ってくる。

散文に直した後に気づいたのは、元の列挙が「機能を羅列しているだけで、読者に何も体験させていなかった」ということだ。列挙形式の問題は文体だけじゃなく情報設計の問題——「読者が体験できているか」で判断するべきだった。

---

コピペで使える——原稿の技術用語密度チェックスクリプト

原稿ファイル（Markdown）を渡すと、技術用語らしき単語の密度をチェックするスクリプト。

# コピペ可
import re
import sys
from pathlib import Path

TECH_TERMS = [
    "API", "CLI", "SDK", "JSON", "YAML", "フック", "ラッパー",
    "デプロイ", "リポジトリ", "コンテナ", "スクリプト", "ターミナル",
    "パッケージ", "ライブラリ", "フレームワーク", "エンドポイント",
]

def check_term_density(filepath: str) -> None:
    text = Path(filepath).read_text(encoding="utf-8")
    # コードブロックを除外
    text_no_code = re.sub(r"```.*?```", "", text, flags=re.DOTALL)

    total_chars = len(text_no_code)
    results = []

    for term in TECH_TERMS:
        count = text_no_code.count(term)
        if count > 0:
            density = count / total_chars * 1000  # 1000字あたり
            results.append((term, count, density))

    results.sort(key=lambda x: x[1], reverse=True)

    print(f"ファイル: {filepath}")
    print(f"本文文字数（コードブロック除外）: {total_chars:,}字\n")
    print(f"{'用語':<15} {'出現回数':>6} {'密度(1000字あたり)':>18}")
    print("-" * 42)
    for term, count, density in results:
        flag = " ← 要チェック" if density > 3.0 else ""
        print(f"{term:<15} {count:>6}回  {density:>8.2f}{flag}")

if __name__ == "__main__":
    check_term_density(sys.argv[1])

実行方法：

python check_terms.py your_manuscript.md

density が 3.0（1000字あたり3回）を超えた用語に「要チェック」フラグが立つ。このスクリプトを vol02_jp に流したら、「フック」が1000字あたり4.8回出現していた。ほぼ半ページに1回登場している計算で、説明なしには読めない。

---

よくある質問

技術用語は全部排除すべき？

排除じゃなく「初出時に必ず説明する」が正しい方針だ。2回目以降はそのまま使っていい。読者は一度理解した用語を次の章で見ると「あ、これか」とつながる。問題なのは説明なしに突然登場する用語だ。

スコア95点でも問題があるのはなぜ？

Claude が採点する品質スコアは主に「文章の整合性・流れ・構成」を見ている。「非エンジニアに伝わるか」という視点はスコアに反映されにくい。高スコアはあくまで「文章として成立している」の証明であって、「読者に刺さる」かは別の話だ。

自動査読はどう設定している？

content_scorer.py で原稿にスコアを付けた後、Claude API に「非エンジニア会社員の視点でこの章を読んで詰まった用語を報告して」というプロンプトを渡している。スコアが 90 以上でも、人間視点のレビューは省略しない。

Kindle の読者は本当に非エンジニア？

「10分で理解する」シリーズは意図的に非エンジニア会社員をターゲットにしている。副業・AI活用に興味があるけど、コードは書けない層だ。この層はエンジニアが「これくらい分かるだろう」と思うラインの3段階手前から説明が必要だと感じている。

査読にかかる時間は？

3冊で約2時間。Claude に「このKDP原稿の第○章を、ITに詳しくない会社員が読む前提でレビューして」と渡すと、5分で詳細な指摘が返ってくる。人間がゼロから読んで検証するより10倍速い。

---

まとめ

• 非エンジニア向け原稿でも技術用語は静かに増殖する。「自分には分かる」が最大の罠
• 高品質スコアは「文章の整合性」を測るものであって「伝わるか」は別に検証が必要
• 辞書として使う本には章頭に「症状一覧」のような入口を用意する
• 列挙構造の問題は文体だけじゃなく情報設計の問題——「読者が体験できているか」で判断する
• 技術用語密度チェックスクリプトを流すと、感覚で気づけなかった詰め込みが数値で見える
• 高スコア原稿でも人間視点のClaude査読は省略しない

---

この記事を読んだあなたに：
– KDP電子書籍 自動生成パイプラインの全体像——Pythonで原稿から出版まで回す方法 #
– Claude API で原稿を自動査読——品質スコアリングの仕組みと実測値 #
– 非エンジニアが読む技術書の目次の作り方——検索意図から逆算する設計法 #

---