1. Claude Codeは「設計の相談相手」として使った

このプロジェクトでは、Claude Codeにただコードを書かせたわけではない。 むしろ、処理の流れや設計方針を相談する相手として使った時間が長かった。

最初から「このコードを書いて」と頼むのではなく、まずは次のようなことを一緒に整理した。

• どの形式で出力するか
• どのOCRエンジンを使うか
• 途中で失敗したときに再開できるようにするか
• ページ番号やルビをどう扱うか
• NotebookLMに読み込ませやすい構造にするにはどうするか

いきなり実装に入らず、先に要件を整理したことで、あとから大きく迷う場面が減った。

2. 効いた指示の出し方

Claude Codeを使っていて特に効果があったのは、指示を細かく分けることだった。

たとえば、最初は次のように頼んだ。

日本語の書籍スキャンPDFをOCRして、NotebookLMにアップロードできるMarkdownにしたい。 実装する前に、要件として決めるべき項目を洗い出してほしい。ただし、実装はまだしないで。

ここで大事なのは、「実装はまだしないで」と明示したことだった。

ただし、あとから振り返ると、この場面ではClaude Codeの AskUserQuestion をもっと積極的に使わせてもよかったと思う。

AskUserQuestionは、AI側が作業を進める前に、人間に確認したいことを質問するための仕組みだ。 今回でいえば、出力形式、ページ区切りの扱い、見出し推定の有無、OCR結果の保存方法など、 先に決めておくべき項目をClaude Code側から質問させることができたはずだ。

実際にはこちらから要件整理を依頼したが、最初の段階で「不明点があればAskUserQuestionで確認してから進めて」と伝えておけば、 AIが勝手に前提を置いて実装に進むリスクをさらに減らせたと思う。

生成AIは、放っておくとすぐにコードを書き始めることがある。 しかし、方針が決まっていない段階で実装に入ると、あとから修正が大きくなる。

そのため、次のように段階を分けて進めた。

1. まず要件を整理する
2. 次に最小限の構成を作る
3. 少ないページ数で試す
4. 問題が出たら原因を切り分ける
5. 必要に応じてOCRエンジンを比較する
6. うまくいった設計判断をドキュメントに残す

3. 「やってほしいこと」より「やらないでほしいこと」が大事

Claude Codeに指示するときは、やってほしいことだけでなく、 変えてはいけない範囲を伝えることが重要だった。

たとえば、PaddleOCRからNDLOCR-Liteへ切り替えるときは、次のような境界を伝えた。

• OCR結果のデータ構造は変えない
• Markdownを作る上位処理には手を入れない
• 旧PaddleOCR時代の出力は削除しない
• NDLOCR-Liteは別のPython環境で動かす

こうしておくと、AIが良かれと思って余計なリファクタリングを始めるのを防ぎやすい。

生成AIとの開発では、便利さと同じくらい「勝手に広げすぎる怖さ」もある。 だからこそ、変更してよい範囲と、触ってはいけない範囲を先に決めておくことが大切だと感じた。

4. うまくいった理由を残す

今回、かなり役に立ったのが、設計判断の理由をドキュメントに残すことだった。

たとえば、次のような判断にはすべて理由がある。

• 見出しの自動推定を入れない
• PaddleOCRからNDLOCR-Liteに乗り換える
• OCR用のPython環境を分ける
• OCRはページごとではなく、まとめて処理する
• 縦中横のオプションは標準では使わない

こうした判断は、コードを読んだだけではわかりにくい。 なぜそうしたのかを残しておかないと、後日また同じ議論を繰り返すことになる。

特に、Claude Codeのようなコーディングエージェントを継続的に使う場合は、 「なぜこの設計にしたのか」を残すことが大事だと思う。

5. Claude Codeに任せすぎた反省

一方で、反省点もある。

今回の開発中、私はコードをほとんど自分で読んでいなかった。 Claude Codeが説明してくれるので、なんとなく理解した気になっていた。

しかし、コードを読んでいないと、次のような問題が起きる。

• どのファイルを直せばいいのか判断できない
• 問題の原因を自分で切り分けにくい
• AIに毎回、事実確認から始めさせてしまう
• 変更してはいけない場所を明確に伝えられない
• 「動いた」ことしか確認できない

これは、AIを使う上でかなり重要な落とし穴だと思う。

AIに任せることと、自分が理解しなくていいことは同じではない。 特に、継続して使うツールや、仕事で使うコードであれば、 最低限の構造は自分でも把握しておく必要がある。

6. それでも、コードをあまり読まずに成果物ができた意味は大きい

ただし、今回の体験は反省だけでは終わらない。

私はソフトウェアエンジニアではない。 それでも、縦書きの書籍PDFをOCRし、Markdownに変換してNotebookLMに読み込ませるパイプラインを作ることができた。しかも、OCR処理後のテキストデータを確認した時間を除けば、4時間程度の作業だったと思う。

これは少し前なら、かなり難しかったことだ。

今回の目的は、きれいなコードを書くことではなく、郷土史をAIで扱える形にすることだった。 その意味では、成果物の品質を確認できれば、コードの細部をすべて理解していなくても前に進める。

つまり、プロジェクトの性質によって、コードをどこまで読むべきかは変わる。

AIを使えば、コードを書けない人でも、自分に必要な小さなツールを作れる時代になってきた。 ただし、その自由には、どこまで自分が理解するかを判断する責任もついてくる。

7. Claude Codeと開発するときの実用的なコツ

今回の経験から、Claude Codeに作業を頼むときは、次のようにすると進めやすいと感じた。

• いきなり実装させず、まず要件を整理させる
• 「実装はまだしないで」と明示する
• 不明点がある場合は、Claude CodeにAskUserQuestionで確認してから進めるように伝える
• 変更してよい範囲と、触ってはいけない範囲を伝える
• 完了条件を先に決める
• 問題が起きたら、症状だけでなく実際の出力例を渡す
• 大きな変更の前には、まず変更計画を出させる
• 判断の理由をドキュメントに残させる
• 人間側も、主要なファイルくらいは自分で読む

要するに、Claude Codeを魔法の道具として使うより、 同僚に仕事を渡すくらいの感覚で使う方がうまくいく。

■ 前提、制約、完了条件を伝える。
■ 変更してよい範囲を決める。
■ 不明点はAskUserQuestionで確認させる。
■ 判断の理由を残す。

これはAIへの指示というより、人に仕事を頼むときの基本に近い。

まとめ

今回のOCRパイプライン開発では、Claude Codeを設計の相談相手として使うことを意識した。

いきなり実装に入らず、要件を整理し、試運転を行い、問題を切り分けながら進めたことで、 PaddleOCRからNDLOCR-Liteへの移行も比較的スムーズに進めることができた。

一方で、コードをClaude Codeに任せすぎ、自分ではあまり読んでいなかったという反省もある。 AIが説明してくれると、理解した気になってしまう。 効率よく指示を出すためには、人間側にも最低限の理解が必要だということも痛感した。vibeコーディングができたと素直には喜べない。

とはいえ、コードをすべて自分で書けなくても、自分に必要なツールを作れるようになったことは大きい。 特に個人の実験や、成果物を得ることが目的のプロジェクトでは、AIとの対話だけでかなり前に進める。

大事なのは、プロジェクトの性質に応じて、AIに任せる範囲と自分で理解する範囲を決めることだと思う。

趣味なら、成果物の確認を重視すればよい。 継続して使うツールなら、主要な構造は把握した方がよい。 仕事や他人に関わるコードなら、AIを使っても最終的な責任は人間側に残る。

Claude Codeは、うまく使えばかなり強力な相棒になる。 ただし、その力を活かすには、丸投げではなく、前提・制約・完了条件をきちんと伝えることが必要だ。