はじめに

前回の記事で、Everything Claude Code (ECC) 環境で初めて本格的な開発を始めた 10 日間のことを書きました。git も知らなかった初心者が、PDCAサイクルを何度も回しながら開発を覚えていく話でした。

今回は、その 10 日間の後半で作った pdf2anki というツールの話をします。

アプリではなくコンテンツが問題だった

G検定の勉強のために、忘却曲線に基づく出題アプリを作りました。Python/Streamlit で Web 版、Swift/SwiftUI で iOS 版。ECC 環境の TDD で実装し、ADR で意思決定を記録しながら、2 週間で動くものができました。

できてから気づきました。自分が作っていたのは Anki の再発明だったのです。

20 年以上の歴史を持つ Anki と同じものを 2 週間で作り直す意味はありません。しかし開発の過程で、本当のボトルネックが見えました。アプリではなくコンテンツです。

iOS 版では PDF からテキスト化したデータを正規表現と LLM で 410 問の問答ペアに抽出するアルゴリズムを実装しました。しかし、表記揺れや章構造の不一致で精度が安定しませんでした。「第 1 章」と「第1章」（スペースの有無）でマッチングが壊れるような世界です。

「どんなテキストからでも高品質な Anki カードを自動生成する」ツールがあれば、アプリ本体は Anki に任せられます。

そうして作り始めたのが pdf2anki です。

$ pdf2anki convert textbook.pdf -o cards.tsv

PDF、テキスト、Markdown を入力すると、Claude API でフラッシュカード（TSV/JSON）を出力する CLI ツールです。

この記事では、pdf2anki を作る過程で踏んだ 6 つの落とし穴 と、その防御策を書きます。Claude API をこれから使う人が同じ穴を踏まずに済むように。

前回の記事で書いた「しつこく質問する」姿勢は、今回も変わりません。Claude Code に「なぜこうするのか？」「他の方法はないのか？」と聞き続けました。その質問と回答の中から見えてきた設計判断を、できるだけ正直に書きます。

1. LLM の出力 JSON は壊れる前提で設計する

起きたこと

Claude API にカード生成を依頼すると、返ってくる JSON がそのままパースできないことがあります。

プロンプトに「JSON だけを返せ」と書いても、マークダウンの ```json ``` で囲んでくることがあります。配列の途中に説明テキストが混じることもあります。カンマが余分だったり、閉じ括弧が足りなかったりします。

LLM の出力は確率的です。「こう返せ」と指示しても、100% の保証はありません。

失敗した対応

最初は json.loads() で一括パースし、失敗したら全体をリトライしていました。10 枚のカードのうち 1 枚だけフォーマットが壊れていても、10 枚全部を再生成します。API コストが無駄に膨らみました。

防御策: カード単位でバリデーションし、部分的な成功を許容する

for i, item in enumerate(data):
    try:
        card = AnkiCard.model_validate(item)
        cards.append(card)
    except (ValidationError, TypeError) as e:
        logger.warning("Skipping invalid card at index %d: %s", i, e)

10 枚中 1 枚が壊れていても、残り 9 枚は救います。

「全か無か」ではなく「部分的な成功を許容する」設計。 これは LLM を組み込むツール全般に通用する原則だと思います。

JSON のラッピング（```json ```）は正規表現で事前に剥がしてからパースに回します。泥臭い前処理ですが、こういう小さな防御の積み重ねが LLM 連携の安定性を支えています。

持ち帰り: LLM の出力パースは「壊れる前提」で書く。全体リトライではなく、個別スキップ＋ログで回復力を持たせる。

2. LLM が生成したカードの品質はバラバラ

起きたこと

JSON が正しくパースできても、中身の品質は保証されません。

実際に出てきた問題カードの例です:

表面が「説明してください」だけ。何を説明するのかわからない
裏面が 500 文字超。カードではなくレポート
1 枚に 3 つの概念が詰め込まれている。Anki のカードは 1 枚 1 概念が原則
リスト問題なのに QA 形式で出力されている。穴埋めにすべき

「LLM に任せたから大丈夫」は危険な前提でした。

失敗した対応

全カードを LLM に再評価させる方式を最初に試しました。生成にも評価にも API を叩くので、コストが単純に倍になります。100 枚のカードを作るたびに 200 回の API コール。現実的ではありません。

防御策: 3 層パイプラインで品質を担保する

第 1 層（コード判定・LLM 不要）: ヒューリスティックスコアリング

6 つの軸で 0〜1 のスコアを付け、重み付き合計が 0.90 以上なら合格。LLM は呼びません。

軸	重み	チェック内容
表面の質	25%	10〜200 文字、疑問符の有無
裏面の質	25%	5〜200 文字、簡潔さ
カード種別の適合	15%	リスト内容なのに QA になっていないか
Bloom レベル	10%	認知レベルが内容に合っているか
タグの質	10%	階層タグが付いているか
原子性	15%	1 枚 1 概念になっているか

原子性の判定が面白かったです。裏面を句点で分割し、文数が多ければ「複数概念が混在している」と判定します。

# 裏面が 3 文以上 → 複数概念の疑い
sentences = [s for s in _SENTENCE_SPLIT_RE.split(back) if s.strip()]
if len(sentences) >= 3:
    score = max(0.3, 1.0 - len(sentences) * 0.15)

# 「また、」「さらに」→ 追加情報の接続詞 → さらに減点
if _MULTI_CONCEPT_RE.search(back):
    score = max(0.2, score - 0.15)

「また、」「さらに」が出てきたら、1 枚のカードに情報を詰め込みすぎている可能性が高いです。人間が見ても「これは分割したほうがいいな」と思うカードを、コードで検出できます。

第 2 層（LLM 使用）: 0.90 未満のカードだけを Claude に批評させる

批評結果は 3 択: improve（書き直し）、split（分割）、remove（削除）。最大 2 ラウンドです。

ポイントは 全カードに LLM を使わない こと。スコア 0.90 以上のカードは第 1 層で素通りさせます。実測では生成カードの 60〜70% が第 1 層を通過しました。LLM 批評が必要なのは 30〜40% です。

第 3 層（コード判定・LLM 不要）: 重複検出

文字バイグラムの Jaccard 類似度で重複を検出します。表面の類似度が 0.7 を超えたら重複フラグを立てます。

前回の記事で書いた ECC の TDD と同じ発想です。テストを先に書くように、品質の基準を先に定義する。基準がなければ「良くなった気がする」で終わります。

持ち帰り: 「LLM で判定できること」と「コードで判定できること」を分ける。コードで済む判定に LLM を使うのは、精度ではなくコストの問題。

3. API コストは「見えない」と怖い

起きたこと

Claude API は従量制です。Sonnet で入力 $3/M tokens、出力 $15/M tokens。

100 ページの PDF を処理したらいくらかかるか。実行してみるまでわかりません。

初期テスト中、うっかり長い PDF を処理して $2 近く使ったことがあります。学習用の個人ツールでこの出費は痛いです。

防御策は 3 つ

① 実行前のコスト見積もり

preview コマンドで、API を叩かずに見積もりを出します。

$ pdf2anki preview textbook.pdf
Estimated cost: $0.42 (Sonnet) / $0.11 (Haiku)
Sections: 12 | Chunks: 8 | Tokens: ~45,000

ユーザーが「これなら OK」と判断してから convert を実行する流れにしました。

② budget_limit で暴走防止

CostTracker に予算上限（デフォルト $1.00）を設定し、API コールのたびに累積コストをチェックします。超えたらそこで止まります。

@dataclass(frozen=True, slots=True)
class CostTracker:
    budget_limit: float = 1.00
    records: tuple[CostRecord, ...] = ()

frozen=True で不変にしています。前回の記事で触れた「不変性の原則」がここで効きました。API コールのたびに新しい CostTracker インスタンスを返します。途中で値が書き換わる心配がなく、「いまいくら使ったか」を常に正確に追跡できます。

③ テキスト量に応じたモデル自動選択

短いテキスト（10,000 文字未満、30 枚未満）ならコストが約 1/4 の Haiku を使い、多ければ Sonnet にルーティングします。

_SONNET_TEXT_THRESHOLD = 10_000   # 文字数
_SONNET_CARD_THRESHOLD = 30      # カード枚数

単純な閾値分岐ですが、短いテキストの処理コストが大幅に下がります。

持ち帰り: 従量制 API を使うツールには「実行前の見積もり」「実行中の上限」「モデルの使い分け」の 3 点セットを入れる。ユーザーの財布を守るのは開発者の責任。

4. 長文 PDF の分割を間違えると、カードの文脈が壊れる

起きたこと

Claude の入力トークン上限は約 200K ですが、一度に大量のテキストを投げるとカードの品質が落ちます。分割が必要です。

失敗した対応

最初はテキストを文字数で均等に切っていました。当然、章の途中で切れます。

「第 3 章の後半」と「第 4 章の前半」が混ざったチャンクから生成されたカードは、文脈がおかしくなりました。ある章の用語定義が別の章の概念と混同されます。

防御策: セクション分割 + breadcrumb で文脈を保持する

Markdown の見出し（#、##、###）で論理的に分割する方式に変えました。

各セクションに breadcrumb（パンくずリスト） を付与します。Web サイトの「ホーム > 製品 > iPhone」のような、いま全体のどの階層にいるかを示すナビゲーションです。

breadcrumb: "本論 > 第1章 論書名の意味 > 1.1 語源"

Claude はこの breadcrumb を見て「いま第 1 章の語源の話をしている」と理解できます。チャンクの先頭にこのコンテキストがあるだけで、生成されるカードの文脈が格段に正確になりました。

見出し階層は heading_stack という辞書で追跡します。H2 が出現したら、それ以下の H3 情報をクリアします。

heading_stack: dict[int, str] = {}
# H2 出現 → H3 をクリア
keys_to_remove = [k for k in heading_stack if k >= level]

1 セクションが 30,000 文字を超えたら段落単位でサブ分割し、見出しに (cont.) を付けて連続セクションだと示します。

日本語テキスト特有の罠

2 つあります。

1 つ目。Markdown 見出しがないテキストへの対応です。日本語の書籍なら「第一章」「（1）」「一、」といったパターンで見出しを検出するフォールバックを入れました。

2 つ目。トークン推定の誤差です。CHARS_PER_TOKEN = 4 という定数は英語基準です。日本語は 1 トークンあたり 2〜3 文字なので、コスト推定が実際の半分程度になります。これは既知の未修正問題です。日本語を扱うなら係数を 2.5 程度に修正する必要があります。

持ち帰り: 長文を LLM に渡すときは「意味の境界」で切る。機械的な文字数分割は文脈を壊す。分割後のチャンクに「いまどこの話か」のメタ情報を付与すると、出力品質が大きく改善する。

5. 画像対応はコストとの闘い

起きたこと

PDF にはテキストだけでなく図やチャートもあります。

Claude API にはテキストだけでなく 画像も入力できる機能（Vision） があります。写真や図を送ると、Claude が「この画像に何が写っているか」を理解して回答してくれます。これを使えば、教科書の図表からもカードを生成できます。

「全ページを画像として Vision に投げれば完璧では？」と思いました。

コストを計算して目が覚めました。

画像のトークンコストは (幅 × 高さ) ÷ 750 です。100 ページを全ページ画像化すると画像だけで約 15 万トークン。テキストと合わせて 30 万トークン、約 $1。テキストだけなら $0.15 程度です。7 倍のコスト差です。

防御策: 3 つの閾値で画像処理を制御する

① 画像カバレッジ閾値: 20%

pymupdf でページ内の画像面積を計算し、ページ面積の 20% 以上を画像が占めるページだけ Vision に回します。テキスト主体のページはテキスト抽出で十分です。

② DPI: 150 に固定

Vision の制約は長辺 1568px、最大 1.15 メガピクセルです。

300 DPI: きれいだがトークンが倍。1 画像 3,000 トークン超
72 DPI: 安いが図中の文字が潰れる
150 DPI: 文字が読める最低限の解像度。1 画像 1,500 トークン程度

③ 1 ページ最大 5 画像

5 枚 × 1,500 トークン = 7,500 トークン。budget_limit と組み合わせれば暴走しません。

この 3 つの妥協で、Vision ありの処理コストをテキストのみの 1.5〜2 倍に抑えました。7 倍にはなりません。

持ち帰り: Vision は強力だが高い。「全部画像で投げれば楽」という誘惑に負けず、テキスト抽出で済む部分はテキストで処理する。画像は本当に必要なページだけに絞る。

6. プロンプト変更の効果が測れないと、改善が博打になる

起きたこと

プロンプトを書き換えたとき、カードの品質が上がったのか下がったのかわかりません。「良くなった気がする」では心許ないです。LLM の出力は非決定的で、同じプロンプトでも毎回違う結果が出ます。

防御策: 期待カードとのキーワードマッチで品質を自動テストする

LLM 開発では、出力品質の自動評価を Eval（エバル） と呼びます。

pdf2anki では「このテキストからはこういうカードが生成されるべき」という期待値を YAML で定義し、実際の出力と照合する方式を採りました。

- id: "dl-001"
  text: |
    過学習（オーバーフィッティング）とは、訓練データに対して
    過度に適合し、未知のデータに対する汎化性能が低下する現象である。
    対策としてドロップアウト、早期終了、データ拡張などがある。
  expected_cards:
    - front_keywords: ["過学習", "何"]
      back_keywords: ["訓練データ", "汎化性能", "低下"]
      card_type: qa
    - front_keywords: ["過学習", "対策"]
      back_keywords: ["ドロップアウト", "早期終了", "データ拡張"]
      card_type: qa

生成されたカードにキーワードが含まれているかで一致度を計算し、Recall（網羅率）・Precision（正確率）・F1（両者のバランス指標）を出力します。

$ pdf2anki eval --dataset evals/dataset.yaml
Recall: 0.78 | Precision: 0.85 | F1: 0.81

キーワードマッチは完璧ではありません。「ニューラルネットワーク」と「神経回路網」を同一視できません。

しかし重要なのは「プロンプト変更で回帰（＝前より悪くなること）が起きていないか」の検知です。完璧な意味理解ではありません。プロンプトを変えるたびに pdf2anki eval を回して F1 が下がっていないか確認する。これだけで改善が博打ではなくなります。

ECC の TDD で学んだことと同じです。テストがあれば、リファクタリングしても安心できます。Eval があれば、プロンプトを書き換えても安心できます。

持ち帰り: LLM の出力品質は「テストケース」で管理する。完璧な自動評価でなくていい。「回帰を検知できる」だけで、プロンプト改善の生産性が大きく変わる。

おわりに

pdf2anki を作る過程は、妥協の連続でした。

やりたかったこと	現実	妥協点
LLM に完璧な JSON を返させたい	出力は壊れる	個別スキップで部分的成功を許容
全カードを LLM で品質評価したい	コストが倍になる	ヒューリスティックで 60〜70% をフィルタ
コストを気にせず使いたい	従量制は怖い	見積もり + 上限 + モデル選択
テキストを均等に分割したい	文脈が壊れる	セクション分割 + breadcrumb
全ページ画像で投げたい	7 倍のコスト	カバレッジ閾値 + DPI + 枚数制限
プロンプト改善を感覚で判断	回帰に気づけない	キーワードマッチ Eval

どれも「理想の設計」ではなく「現実との折り合い」の産物です。

開発全体を通して効いた判断基準が一つあります。「これをやらない場合、同じ時間で何ができるか」 を常に問うことです。

途中で「OpenAI にも対応すべきでは」と考えました。$10 クレジットが残っていたからです。実装を見積もると 1,000 行、10 時間。$10 回収のために時給 $1 で働く計算になります。同じ 10 時間で画像カード生成、TUI、Eval フレームワークが作れました。

前回の記事で書いた ECC の PDCA サイクルが、ここでも回っています。

Plan: Claude Code に「なぜこうするのか？」をしつこく質問し、設計の背景を理解する
Do: TDD でテストを先に書き、実装する
Check: Eval でプロンプトの品質を測定し、ヒューリスティックでカードの品質を検証する
Act: ADR で「なぜ OpenAI 対応を捨てたか」「なぜ画像閾値を 20% にしたか」を記録する

Claude API は強力なツールです。しかし「API を叩けば解決する」と思った瞬間に、コストが膨らみ、品質が不安定になり、デバッグが困難になります。API の力を引き出すのは、その周辺に積み上げる防御的な設計です。

この記事が、同じ道を歩く人の参考になれば幸いです。

pdf2anki は GitHub で公開しています。