- Cursorで要件定義がエラいスムーズになった話
- （続）Cursorで「詳細設計→ガントチャート草稿」作成がめっちゃ楽になった話
- 「Cursor」×「A5:SQL Mk-2」でテーブル定義書をリッチにする
- 「Cursor」×「Obsidian」内部リンク生成＆最適化プロンプト
- 「Cursor」で「難解コード」のリーディングがめちゃ楽になった話 ←本稿こちら
はじめに
「Cursor擦り倒すシリーズ」も、気がつけば第5弾。
要件定義に始まり、詳細設計、テーブル定義書、Obsidian 連携――過去 4 本の記事で私は「AI × 開発フロー」の接点を片っ端から試し、その度に“自分の手ごたえ”と“チームの変化”を率直に書き留めてきました。
今回のテーマは、コードリーディング――「Cursor」で「難解コード」のリーディング」のリーディング」 です。
振り返れば、私たちは日々“書くこと”以上に“読むこと”に時間を費やしているはずです。にもかかわらず、「どう読めば本質に辿り着けるのか」を真面目に言語化したドキュメントは意外と少ない。
そこに Cursor が加わったことで、私の中で一つのピラミッド型フレームが定着しました。本稿では、その 手順・プロンプト を余すことなく共有します。
複雑なソースコードに立ち向かう際、やみくもに読み進めるのではなく、体系的なアプローチを取ることが効率的な理解への近道です。このガイドでは、人間の認知プロセスに沿った段階的なフローを提示し、各ステップでAI（CursorのようなAI支援コーディングツール）をどのように活用すれば理解を深められるか、具体的なプロンプト例と共に解説します。
1. ソースコード理解フローの全体像：理解のピラミッド
ソースコードの理解は、積み木のように段階を踏んで深まります。以下のピラミッドは、そのプロセスを視覚化したものです。
- 土台（⓪ 準備する）： まず、コードを読むための最低限の「地図」を手に入れます。
- 第1層（① 概要をわかったつもりになる）： 森全体を遠くから眺め、大まかな形や広がりを把握します。
- 第2層（② 詳細をわかる）： 森の中に入り、個々の木々や道筋を詳しく観察します。
- 頂点（③ 深く理解する）： 森の生態系や歴史、なぜそのような形になったのかを深く考察します。
- その先（④ 活用する）： 得た知識を元に、新しい地図を作ったり、森をより良くするための行動を起こします。
この各段階でAIに適切な質問（プロンプト）を投げかけることで、効率的に情報を引き出し、理解を加速させることができます。
フロー図にするとこうなる
2. 各理解ステップとプロンプト
ステップ⓪：準備する (コンテキスト把握)
目的: コードの詳細に立ち入る前に、そのコードが存在する「背景」や「文脈」を掴みます。これが理解の土台となります。
このステップで目指すこと:
- コードの目的や役割の把握
- 基本的な入出力のイメージ
- 利用されるシナリオの理解
- 関連する他のコード部分との関係性の把握
AIへのプロンプト例 (Cursor / AIチャット用):
該当の[ファイル名/クラス名/関数名]について、基本的な情報を教えてください。
- 主な目的や役割は何ですか？
- どのような情報（入力）を受け取り、何を（出力）しますか？
- どのような場面（ユースケースやシナリオ）で使われますか？
- 関連する他の主要なファイルやモジュールがあれば教えてください。
プロンプトの意図: コードの「なぜ？」と「何と関わっているか？」を知り、全体像の中での位置づけを明確にします。
ステップ①：概要をわかったつもりになる (全体像・雰囲気掴み)
目的: コードの細部にはこだわらず、「全体として何をしているのか」「大まかな流れはどうか」「主要な登場人物（クラスや関数）は何か」といった鳥瞰的な視点でコードを捉えます。「なんとなくこんな感じかな」という感覚を掴むことが重要です。
このステップで目指すこと:
- コードの核心機能の把握
- 主要な処理ステップのリスト化
- 主要なクラス/関数の役割分担の理解
- 大まかなデータの流れのイメージ
- 視覚的な処理フローの理解（図など）
AIへのプロンプト例:
該当のソースコードの概要を説明してください。
- このコード[ブロック/関数/クラス]は、一言で言うと何をしていますか？
- 主要な処理ステップを箇条書きで（3～5つ程度で）教えてください。
- コード内の主要なクラスや関数と、それぞれの簡単な役割をリストアップしてください。
- データがどのように入力され、処理され、出力されるのか、簡単な言葉で説明してください。
- この処理の入力と出力について、型や簡単な具体例もあれば教えてください。
- [可能であれば] この処理全体の流れを簡単なMermaidのフローチャートかシーケンス図で表現してください。
コードハイライト時のプロンプト例:
@selection
この選択範囲のコードは何をしようとしていますか？
主要な処理の流れと、入力・出力を簡単に説明してください。
プロンプトの意図: コードの「骨格」を理解し、詳細に入る前の地図を手に入れます。視覚的な情報は直感的な理解を助けます。
ステップ②：詳細をわかる (ロジック、データフローの追跡)
目的: 概要を掴んだ上で、コードの具体的な動作、各部分の役割、データの詳細な流れ、条件分岐の意図などを深く掘り下げます。個々の命令が何をし、それらがどう連携して機能するのかを正確に理解します。
このステップで目指すこと:
-
A. 特定の関数/メソッドの完全理解:
・役割、各引数、戻り値、重要な変数、副作用 -
B. 特定のコードブロック/ロジックの意図理解:
・ループ、条件分岐、関数呼び出しの目的 -
C. データの流れの追跡:
・変数の変化を具体的データで追う
AIへのプロンプト例:
A. 特定の関数/メソッドの詳細:
関数/メソッド「[関数名/メソッド名]」について詳細を教えてください。
- 具体的な役割は何ですか？
- 各引数について、意味、型、なぜ必要なのか、具体的なサンプル値を教えてください。
- 戻り値について、型、意味、具体的なデータ構造のサンプルを教えてください。
- 内部で使われる重要な変数があれば、その役割と変化の様子を説明してください。
- 複雑なロジックやアルゴリズムがあれば、平易な言葉で解説してください。
- 副作用（クラスの内部状態の変更、DBアクセスなど）はありますか？
B. 特定のコードブロック/ロジックの詳細:
以下のコードブロックは何をしていますか？
- この[ループ処理/条件分岐/変数代入/関数呼び出し]の目的と動作を説明してください。
C. データの流れ追跡:
変数「[変数名]」が、このコードブロック内でどのように変化していくか、初期値、途中の変更箇所、最終値を具体的なサンプルデータと共に追跡してください。
コードハイライト時のプロンプト例 (A, B, C共通で対象に応じて調整):
@selection
この[関数/コードブロック]の詳細を教えてください。
特に、[引数/戻り値/ループ/条件分岐/変数「X」の変化]について説明してください。
プロンプトの意図: コードの「肉付け」を行い、各部分がどのように機能し、データがどう処理されるかを具体的に理解します。特にデータ構造のサンプルは、抽象的な説明を具体化する上で非常に重要です。
ステップ③：深く理解する (本質・設計思想の把握、応用・改善)
目的: コードの表面的な動作だけでなく、「なぜこのような設計なのか」「どのような背景や意図があるのか」「他の選択肢は？」といった、より本質的・抽象的なレベルでコードを捉えます。これにより、コードの改善提案や類似課題への応用が可能になります。
このステップで目指すこと:
- 設計や実装の背景・理由の理解
- 実装のメリット・デメリット（トレードオフ）の考察
- 他の実装方法との比較、現実装の選択理由の推測
- 外部ライブラリやモジュールへの依存理由の理解
- 改善点（可読性、パフォーマンス、保守性）の発見
- 潜在的なエラーやエッジケースへの対応の考察
- コードの歴史的経緯の把握（可能であれば）
AIへのプロンプト例:
この[クラス/モジュール/一連の処理]について、設計思想や背景を考察・解説してください。
- このような設計/実装になっている背景や理由はありますか？ (例: ビジネス要件、パフォーマンス考慮、技術的制約など)
- この実装のメリットとデメリット（トレードオフ）は何だと思いますか？
- 他に考えられる実装方法はありましたか？もしあれば、それと比較して現在の実装が選ばれた理由を推測してください。
- このコードが依存している外部ライブラリやモジュールがあれば、その依存関係の理由を説明してください。
- このコードを改善するとしたら、どのような点が考えられますか？（可読性、パフォーマンス、保守性などの観点から）
- このコードに関連する可能性のあるエラーやエッジケース、それらへの対応について教えてください。
- [もしあれば] このコードの歴史的経緯や、過去の大きな変更点について何か知見はありますか？
コードハイライト時のプロンプト例:
@selection
このコードの設計について考察してください。
- なぜこのような実装になっていると考えられますか？
- この実装のメリット・デメリットは何ですか？
- 改善点や代替案はありますか？
プロンプトの意図: コードの「魂」に触れ、表面的な知識から一歩進んだ本質的な理解を目指します。
ステップ④：活用する (ドキュメント生成、リファクタリング支援など)
目的: これまでのステップで得た理解を元に、具体的なアクションに繋げます。コード理解は、多くの場合、ドキュメント化、保守、機能追加、改善といった次の活動のための手段となります。
このステップで目指すこと:
-
A. ドキュメント生成:
・DocString や Markdown などの自動生成 -
B. リファクタリング提案:
・可読性・パフォーマンス・保守性向上の具体案
AIへのプロンプト例:
A. ドキュメント生成:
以下のコード[ブロック/関数/クラス]について、適切なコメント（例: [言語名]のDocString形式）を生成してください。
- 関数の概要
- 各引数の説明（型、意味）
- 戻り値の説明（型、意味）
- [必要であれば] 使用例
または
この処理全体の動作を説明するMarkdown形式のドキュメントを作成してください。
- 目的
- 主な処理フロー
- 入出力
- 重要な注意点
B. リファクタリング提案:
以下のコードブロックについて、リファクタリングの提案をしてください。
可読性、パフォーマンス、保守性の観点から、改善できる点があれば具体的に示してください。
変更前と変更後のコード例も提示してもらえると助かります。
コードハイライト時のプロンプト例:
@selection
このコードに適切なコメントを[言語のDocString形式]で追加してください。 / このコードの処理内容を説明するMarkdownドキュメントを生成してください。
@selection
このコードをリファクタリングするとしたら、どのような改善案がありますか？具体的なコード例も示してください。
プロンプトの意図: AIの力を借りて、理解した内容を形にし、コードの価値を高める活動を効率化します。
3. AI活用プロンプト利用時のTips
- 具体的に質問する: 曖昧な質問より、具体的な箇所や知りたいポイントを明示する方が、AIは的確に回答できます。
- 段階的に深掘りする: 一度に全てを理解しようとせず、上記のフローを意識し、徐々に質問を重ねていきましょう。
- 対話を続ける: AIの回答に対し、「それはなぜ？」「具体的には？」と深掘りする質問をすることで、より深い理解に繋がります。
- コード選択機能をフル活用する: Cursorなどのツールでは、コードの一部を選択してAIに質問する機能が非常に強力です。
- 前提知識を提供する: プロジェクト固有の用語や背景知識があれば、最初にAIに伝えることで回答の精度が向上します。
- 期待する出力形式を指定する: 「箇条書きで」「Mermaidで」「Markdownで」のように、出力形式を指定すると便利です。
このステップガイドとAI活用術が、あなたが複雑なソースコードの迷宮を抜け出し、その本質を掴むための一助となれば幸いです。重要なのは、AIを賢いアシスタントとして活用しつつ、最終的には自分自身の頭で情報を整理・再構築し、理解を積み上げていくことです。
「どうやってわかったつもりにさせるか」「どうやったらインプットした情報から行動が起こせるようになるか」、この辺りは自他ともに成長という観点で外せない要素です。そして Cursor（AIエージェント） は、私の内省プロセスを“対話”として可視化し、結果的にチーム内へも知識を還流させる媒介にもなっているように思います。
引き続き、“擦り倒し”の先にある風景を、一緒に覗いていただければ幸いです。
Views: 0
