Claude Code入門｜Pythonコードを段階的に読み解く4ステップ【第8回】

第7回では、Claude Codeへの指示を「作業依頼書」として設計する考え方を扱いました。目的・前提・入力・出力形式・制約の5要素を意識するだけで、返ってくる出力の質は大きく上がります。第3章の2本目となる本記事では、その依頼書を最も頻繁に使う場面――既存のPythonコードをClaude Codeに読ませて理解するシーン――を掘り下げていきます。

Pythonを学んだ経験があると、「サンプルコードは動かせるが、他人が書いた長いスクリプトになると急に読めなくなる」という壁にぶつかりがちです。過去の自分が書いたコードでさえ、半年経つと初見と変わらない、という声もよく聞きます。第8回は、他者のコードや過去の自分のコードを読み解く足がかりとしてClaude Codeを使う方法を、依頼書型プロンプトの実践編として整理します。

この記事のゴール

本記事を読み終えると、次のことができるようになります。

Claude Codeにコードを渡す4通りの方法（貼り付け・ファイルパス指定・ディレクトリ指定・/init）を使い分けられる
関数の機能要約・処理フロー・依存関係・副作用を段階的に引き出せる
読み解き専用にPlan modeやExploreサブエージェントを活用できる
AIの説明を鵜呑みにせず、要点を自分の言葉で確認するリズムを持てる
過去の自分のコード・他者のコード・研究室の共有スクリプトを、実務レベルで読み解ける

本記事の例は、機密情報を含まない架空データや公開スクリプトを想定しています。第6回で扱った「渡してはいけない4種類のデータ」の線引きは、読ませる対象がコードでも変わりません。プロンプトや対象ディレクトリに患者情報・未公開研究データ・APIキー・学生情報が含まれていないかを、読ませる前に必ず確認してください。

なぜコードを「読ませる」ことに独自の型が必要か

Claude Codeは、コードを書く力だけでなく、コードを読む力においても強力です。しかし、ただ「このコードを説明して」と貼るだけでは、次のような残念な出力になりがちです。

1. 一般論の解説で終わる：「これはpandasを使ったCSV集計スクリプトです。read_csvでファイルを読み、groupbyで集計しています」といった、コードを読めば誰でも分かる説明が返ってくるパターンです。読み手が知りたいのは、なぜこの処理順なのか、どの部分に注意すべきか、といった一段深い情報のはずです。

2. 関数間のつながりが見えない：単一ファイルであっても、複数の関数が呼び合っているケースでは、依頼側が「全体のフローを図式で」と明示しない限り、AIは各関数を独立に説明してしまいます。読み手の頭の中にコードの地図ができません。

3. 副作用や隠れた前提が抜ける：ファイル書き込み、グローバル変数の書き換え、外部APIコール、環境依存の挙動など、コードを読むうえで最も注意すべき「副作用」は、AIから明示的に聞かないと出てきません。読み手が「動くコードだ」と誤解する原因になります。

4. 前提知識のミスマッチ：AIは相手の知識レベルを見えていないため、専門用語で押し切ったり、逆に基礎から冗長に説明しすぎたりします。Python学習者に向けた説明と、機械学習研究者に向けた説明では、望ましい粒度が違います。

これらの失敗を避けるためには、第7回で学んだ5要素の依頼書を、「コードを読ませる」用途向けに具体化することが有効です。

コードをClaude Codeに渡す4つの方法

読み解きに入る前に、そもそも「どうやってコードを渡すか」の選択肢を整理しておきます。方法によって、AI側が読める範囲と、依頼側の準備コストが変わります。

方法1：プロンプトに直接貼り付ける

短いコード断片（数十行以内）を検討したいときに向く方法です。プロンプト内にコードブロックとして貼り付け、その下に依頼を続けます。準備コストは最も低く、単一関数の意味確認・エラー原因の相談などに適しています。ただし、貼り付けた範囲しかAIは見られないため、依存する他のファイル・関数の情報が不足すると誤読が起きます。

方法2：ファイルパスを指定する

Claude Codeは、作業ディレクトリ内のファイルパスを依頼文中に書けば、その内容を直接読み込みます。「sales_report.pyを読み、関数の一覧と役割を教えてください」と書くだけで、貼り付けは不要です。単一ファイルの読解では、これが最も基本的なやり方になります。ファイル全体を渡せるので、依頼側の「範囲切り取り」判断が不要になる利点があります。

方法3：ディレクトリを指定する

複数ファイルにまたがるプロジェクトでは、フォルダごと参照させます。「src/配下の全ファイルを読み、全体構成を要約してください」といった依頼で、AIは自ら関連ファイルを開いて読み進めます。ここで注意したいのは、ディレクトリが大きすぎると読み取りに時間がかかり、トークン消費も増える点です。まずは範囲を絞ったサブディレクトリから始めるのが実務的です。

方法4：`/init`でCLAUDE.mdを生成する

Claude Codeには/initというスラッシュコマンドがあります。これは対象プロジェクトを走査し、プロジェクト構成・使用ライブラリ・実行方法・コード規約などをまとめたCLAUDE.mdのたたき台を自動生成する機能です。読み解きの起点として最も効率的で、生成されたCLAUDE.mdを読むだけでも、プロジェクトの俯瞰が得られます。詳細は第12回で扱いますが、コード読解の第一歩として覚えておくと便利です。

コード読解の依頼書テンプレート

4つの渡し方が決まったら、次は依頼書の中身です。第7回の5要素をコード読解用に具体化すると、以下のような型になります。

目的：{何を理解したいのか}（例：sales_report.py の全体像を把握したい／後輩に引き継ぐ準備をしたい）
前提：{読み手の知識レベル}（例：Python基礎は学習済み、pandasは触ったことがある、SQL未経験）
入力：{読ませる対象}（例：sales_report.py 全体）
出力形式：
  1. スクリプトの目的・全体像（3〜5行）
  2. 関数一覧（関数名・引数・戻り値・役割を表形式で）
  3. 処理の流れ（メイン処理から呼ばれる順）
  4. 副作用（ファイル書き込み、グローバル変数、外部API等）
  5. 気になる箇所・改善候補（3個以内）
制約：
  - コードは書き換えない（読解のみ）
  - 不明な箇所は「不明」と明示（推測で断定しない）

この型に沿って依頼すると、AIが「何を答えるべきか」を最初から把握した状態でコードを読み始めます。以降のセクションでは、各出力項目を引き出すコツを個別に見ていきます。

段階1：全体像と関数一覧を引き出す

まずは、スクリプト全体を俯瞰する情報を得ます。ここで依頼するのは「要約」ではなく「地図」です。要約は情報が圧縮されすぎて、後の質問につながりにくくなります。地図（=関数一覧と依存関係）を先に作ると、以降の質問の解像度が上がります。

関数一覧を表形式で頼むのがコツです。「関数名・引数（型を含む）・戻り値・役割の1行説明」を列に指定すると、AIは推測で埋めずに、コードから読み取れる情報だけを整理してくれます。役割の1行説明は、依頼側が読み解きの取っかかりを得るのに最も有効な情報です。

この段階では、AIの説明を「そのまま信じない」姿勢が重要です。表形式で返ってきた関数一覧は、実際にコードと照らし合わせて、名前と役割の対応を1行ずつ目で確認します。表を眺めるだけで、コードを1回通読した程度の理解が得られる状態を目指します。

段階2：処理フローと関数間の依存関係を引き出す

地図ができたら、次は「動線」を描きます。メイン処理から関数がどの順に呼ばれ、それぞれの出力が次にどう渡っていくかです。ここでの依頼のコツは、「箇条書きの処理フロー」または「疑似コード」で返してもらうことです。

「Mermaid記法でシーケンス図を書いて」と頼むと、視覚的な図で返してくれることもあります。ただし、複雑な分岐を持つコードでは図が読みにくくなるので、シンプルな処理には箇条書き、分岐や並行処理があるコードには図、という使い分けが実務的です。

関数間の依存関係で特に注目したいのは、「共有される状態」です。グローバル変数、モジュールレベルの定数、クラスのインスタンス変数など、複数の関数が読み書きする状態は、バグの温床になりやすい箇所です。「関数間で共有されている状態を洗い出し、各関数がそれを読むだけか、書き換えるかを分類してください」と依頼すると、単なる呼び出し関係を超えた深い読解が得られます。

段階3：副作用と隠れた前提を引き出す

コード読解で最も見落としやすいのが、副作用と暗黙の前提です。副作用とは、関数が「値を返す以外にコードの外側に影響を与える動作」で、代表的には次のようなものがあります。

ファイル・データベース・S3等への書き込み
ネットワーク経由の外部API呼び出し
環境変数・OSプロセス状態の変更
グローバル変数・シングルトンの書き換え
ロギング・print出力・標準出力への書き込み

副作用を洗い出す依頼は、明示的に「以下の5種類の副作用について、コード中の該当箇所を列挙してください」とリストを渡すのが確実です。AI側で副作用の定義が揺れないため、抜け漏れが減ります。

隠れた前提としては、「Python 3.11以上前提のシンタックス」「特定のOSでしか動かないパス表記」「ネットワーク接続前提」「特定バージョンのライブラリ依存」などがあります。「このコードが動くために必要な、コード内には書かれていない前提を列挙してください」と頼むと、環境依存のリスクが可視化されます。研究室の共有スクリプトを引き継ぐときに、特に有用な観点です。

段階4：気になる箇所・改善候補を引き出す

読解の最後に、改善候補を軽く聞いておくと、次のリファクタリング回（第10回）につなげやすくなります。ただし、この段階では「改善する」のではなく、「気になる箇所を把握する」のが目的です。修正指示に踏み込まず、以下のような依頼にとどめます。

このコードを読んで、以下の観点で気になった箇所を3個以内で挙げてください。
- 可読性を下げている書き方
- 副作用が見えにくい箇所
- テストが書きにくそうな構造
コードは変更せず、指摘のみお願いします。

3個以内、と数を絞るのがポイントです。数を絞らないと、些末な指摘が並んで焦点がぼやけます。読み手が「次に手を入れるならここ」を1つ選べる状態にするための情報として使います。

Plan modeとExploreサブエージェントの使い分け

Claude Codeには、コード読解専用の機能がいくつか用意されています。第5回で紹介したPlan modeと、公式ドキュメントで案内されているExploreサブエージェントは、読解フェーズと相性がよい代表格です。

Plan modeは、ファイルの読み取りや探索用コマンドの実行は行いつつ、ソースファイルの編集や書き込み系の変更は行わずに、計画を提示するモードです。読解目的でPlan modeを起動しておけば、依頼側が明示的に禁止を書かなくても、AIがコードを書き換えるリスクを構造的に抑えられます。読み解きだけしたい、書き換えは後で自分で判断したい、というシーンで有効です。

Exploreサブエージェントは、コードベース内の情報検索・調査に特化した読み取り専用のサブエージェントで、大きなリポジトリで「Xがどう実装されているか調べて」といった依頼に向いています。メイン会話の文脈を汚さずに、大量の探索的読み取りを別スレッドで行える点が特徴です。読解結果は最終的な要約として返ってくるため、依頼側は結論だけを受け取れます。大規模プロジェクトの初回オンボーディングや、他人が書いたリポジトリの初見理解で、特に真価を発揮します。

読解の目的が「1ファイルの理解」ならPlan modeで十分、「複数ファイルにまたがる仕組みの調査」ならExploreサブエージェントを検討する、という使い分けが実務的です。

よくあるつまずきと、その対処

コード読解でよく起きる3つのつまずきと対処法をまとめます。

関数の役割説明が「もっともらしいが間違っている」：AIは、関数名や変数名から意味を推測して説明することがあります。名前が実装と一致していない場合（リファクタ途中で名前だけ古い、命名が誤解を招く等）、説明が実装から乖離します。対処は、AIの説明を鵜呑みにせず、要所の関数だけは自分でコードを追って確認することです。「不明な箇所は不明と明示してください」を依頼書の制約に入れておくと、断定的な誤りが減ります。

長いファイルの後半だけ要約が薄い：AI側のトークン制約で、長大なファイル全体を均等に扱えないことがあります。1000行を超えるスクリプトでは、後半セクションの説明が急に浅くなるケースがあります。対処は、ファイルを機能別に分割して依頼する、または「後半（600行目以降）に絞って読解してください」と範囲を明示することです。

会話が進むうちにファイル内容とAIの記憶がずれる：長いセッションで同じファイルを何度も読み込むと、AI側で古い版と新しい版が混在することがあります。対処は、大きな読解タスクを終えたら一度セッションを切り、要点だけを新しいセッションに引き継ぐことです。第7回で扱ったセッション整理と同じ考え方が、読解でも役立ちます。

ファーマAIラボ的視点：研究室の共有スクリプトを読み解く

薬学・医療系の研究室では、先輩が書いた解析スクリプト、共同研究先から受け取った前処理コード、退職した研究員が残した実験自動化スクリプトなど、「誰が書いたか分からないが動いている」Pythonコードが日常的に流通しています。ドキュメントは残っていないことがほとんどで、読み解きのコストが新規開発以上にかかる、という声はよく聞きます。

こうした共有スクリプトこそ、Claude Codeの読解機能が最も価値を発揮する場面です。全体像・関数一覧・副作用・隠れた前提を段階的に引き出せば、初見のコードでも数十分で「引き継げるレベル」の理解に到達できます。特に副作用の洗い出しは、既存のデータや測定機器に副作用が及ぶリスクを事前に把握する意味でも重要です。読み解いた結果をCLAUDE.mdや独立したドキュメントとして残しておけば、次の担当者にも役立つ資産になります。研究室の「暗黙知の技術文書化」を、AI支援で加速する現実的な使い方です。

まとめ：段階的に読み解くリズムを持つ

本記事では、既存のPythonコードをClaude Codeに読ませて理解する方法を扱いました。要点をまとめます。

コードを渡す方法は4通り：貼り付け・ファイルパス指定・ディレクトリ指定・/init
読解の依頼書は「地図（関数一覧）→動線（処理フロー）→副作用→改善候補」の4段階で組み立てる
副作用と隠れた前提は明示的にリストを渡して洗い出させる
Plan modeは書き換え防止、Exploreサブエージェントは大規模探索、と使い分ける
AIの説明は鵜呑みにせず、要所は自分の目でコードを確認する

Claude Codeは、コードを読み解くうえでの強力な補助輪ですが、最終的な理解の責任は読み手にあります。段階的な依頼と自己確認のリズムを持てば、初見のスクリプトを実務で扱える段階まで、確実に到達できます。

次回予告

第9回は「PythonエラーをClaude Codeと一緒に解決する」です。エラーメッセージとコード断片をどの粒度でClaude Codeに渡すか、闇雲な再実行ではなく根本原因を特定するデバッグの型、典型的なPythonエラー（ImportError、KeyError、TypeError、IndentationErrorなど）の修正パターンを扱います。第8回で身につけた読解の型を、エラーが出た瞬間に活用する回です。

公式ドキュメント参照のリマインド

Claude Codeのファイル読み取り、/initコマンド、Plan mode、Exploreサブエージェントの仕様は短期間で更新される可能性があります。本記事の内容は2026年7月時点の情報を基に執筆していますが、業務・研究での導入時には、必ずAnthropic公式ドキュメント（https://code.claude.com/docs）とClaude Code製品ページ（https://claude.com/product/claude-code）で最新の仕様を確認してください。モデル名（Claude Opus 4.8、Claude Sonnet 4.6、Claude Haiku 4.5など）や利用条件は変更される場合があります。本文中のモデル名は執筆時点の一例であり、固定情報として扱わず、実際に自分のプラン・環境で利用可能なモデルはClaude Code内の/modelコマンドで確認してください。

参考文献・関連リンク

Anthropic公式：Claude Code Docs（https://code.claude.com/docs）
Anthropic公式：Claude Code 製品ページ（https://claude.com/product/claude-code）
Anthropic公式：Common workflows（コード理解・オンボーディング等の代表的ワークフロー）
本シリーズ第5回：Claude Codeを安全に使うための権限管理入門
本シリーズ第6回：APIキー・個人情報・研究データを守るための注意点
本シリーズ第7回：Claude Codeに良い指示を出す方法
本シリーズ第9回（次回）：PythonエラーをClaude Codeと一緒に解決する
本シリーズ第12回：CLAUDE.mdで作業ルールを伝える
本シリーズの公式コンセプト：claude-code-python-blog-series-plan.md（ファーマAIラボ内部資料）

本記事の位置づけに関する注記

本記事は、Anthropicが公開しているClaude Code関連情報を参考に、Python学習経験のある非エンジニア向けに筆者が独自に構成・解説したものです。AnthropicまたはClaude Codeの公式記事ではありません。仕様、料金、対応環境、利用条件は変更される可能性があるため、最新情報は公式ドキュメントをご確認ください。

制作ノート

本シリーズの記事およびサンプルコードは、Claude Code／Claude Opus 4.7を活用して執筆しています。AI生成情報については、公式ドキュメント・公的機関の公表資料等の一次情報で裏取りした上で掲載しています。読者の皆さまにおかれましても、AIを使って成果物を公開する際は、AI関与の透明化を推奨します。

免責事項

本記事は生成AIを活用して作成しています。内容については十分に精査しておりますが、誤りが含まれる可能性があります。また、Claude Codeおよび関連サービスの仕様・料金は変更される場合があります。最新かつ正確な情報は必ず公式ドキュメントをご確認ください。お気づきの点がございましたら、コメントにてご指摘いただけますと幸いです。なお、本記事の内容に基づいて生じたいかなる損害についても、当サイトは責任を負いかねます。

はじめに：依頼書の次は「読ませ方」を整える