既存コードの理解

Verdent for VS Code は、自然言語による質問と自動探索を通じて、未知のコードベースを理解する手助けをします。組み込みの Explorer サブエージェントが、メインのコンテキストウィンドウを消費せずに、ファイルの検索、コードパターンの検索、アーキテクチャに関する質問への回答を素早く行います。

学べること

Explorer サブエージェントを使って未知のコードベースを探索する
コードの構造や実装について質問する
関数、クラス、モジュールの詳細な説明を得る
既存コードからドキュメントを生成する
プロジェクトのアーキテクチャとデータフローを理解する
新しいチームメンバーを効率的にオンボーディングする

前提条件

Verdent を使ってコードを理解する前に、次を準備してください。

Verdent 拡張機能をインストールした Visual Studio Code
VS Code で開いているコードベースまたはプロジェクトワークスペース
利用可能なクレジットがあるアクティブな Verdent サブスクリプション

未知のコードベースを探索する

コードベースの構造について質問したり、ファイル検索を要求したりすると、Verdent は自動的に Explorer サブエージェント（@Explorer）に委任します。これは高速なコードベース探索に最適化された、トークン効率の高い専門エージェントです。

Explorer サブエージェントは次のことを素早く行います。

パターンや名前に一致するファイルを検索する
特定のキーワードや関数をコード内で検索する
コードベースに関するアーキテクチャの質問に回答する
機能が実装されている場所を特定する

探索質問の例:

What is the structure of this project?

Where is user authentication handled?

Find all API endpoint definitions

Show me where database queries are defined

Explorer はバックグラウンドで効率的に動作し、メインのコンテキストウィンドウを消費せずに高速な回答を提供します。Verdent は、関連するファイルパスとコードスニペットとともに調査結果を提示します。

複雑なタスクのための並列探索:

複雑な探索タスクでは、複数の Explorer エージェントを並列に実行して時間を節約でき、それぞれがコードベースの異なる側面を同時に調査します。その後、Verdent が調査結果をまとまりのある要約に統合します。

例:

Use the Explorer agent to find all places where we manually validate email addresses

これにより、Verdent はコードベース全体のすべての箇所を体系的に発見し、インスタンスを見逃すことがありません。

コードについて質問する

Verdent は、自然言語を使ってコードベースに関するほぼあらゆる質問に回答します。AI はコンテキストを理解し、詳細な説明、分析、洞察を提供します。

特定の機能がどのように動作するかを質問します。

Explain how authentication works in this project

What does the calculateTotal function do?

How are API requests handled?

Verdent は関連するコードを分析し、実行フローを追跡し、特定のファイルや行番号を参照しながら実装を説明します。

アプリケーションの全体像を理解します。

What is the overall architecture of this application?

How do the components communicate with each other?

What design patterns are used in this codebase?

Verdent はプロジェクト構造を調査し、パターンを特定し、アーキテクチャ上の判断を説明します。

技術的な判断に関する洞察を得ます。

Why do you think Redux was chosen instead of Context API for state management?

What would happen if I changed the API timeout from 30s to 60s?

Is this validateUserInput function redundant?

Verdent はコードのコンテキストを分析し、プロジェクトのパターンや業界のベストプラクティスに基づいた根拠のある説明を提供します。

特定の機能や依存関係を見つけます。

Where is user data validated?

Show me all database queries in the project

What dependencies does this project have?

Explorer サブエージェントは、grep（コンテンツ検索）や glob（ファイルパターンマッチング）などのツールを使って効率的な検索を行い、メインのコンテキストを消費せずに関連する結果を返します。

アルゴリズムやパターンを理解します。

How does the quicksort algorithm work in the sortItems function?

What are the best practices for error handling in React components?

Explain the Observer pattern implementation in the EventEmitter class

Verdent は、コードベース内の特定の実装を参照しながら明確な説明を提供します。

関数とクラスを説明する

Verdent は、特定の関数やクラスの実装、パラメータ、戻り値、コードベース全体での使われ方を分析し、詳細な説明を提供します。

例:

Explain the UserAuth class

What does the processPayment function do?

Break down the ApiService class methods

Verdent が説明する内容:

目的: その関数やクラスが達成すること
パラメータ: 入力の型、期待される値、制約
戻り値の型: 出力の型と取り得る戻り値
内部ロジック: 実装がステップごとにどう動作するか
依存関係: 使用している外部モジュール、関数、サービス
使用例: その関数/クラスがコード内の他の場所でどう使われているか

Verdent はコードの実行フローを追跡し、エッジケースを特定し、実装上の選択の理由を説明します。

ドキュメントを生成する

Verdent は、インラインコードコメント（JSDoc、Python docstring など）、README ファイル、API ドキュメント、アーキテクチャガイドなど、複数の形式でドキュメントを生成します。

ドキュメント生成に Plan Mode を使う

Plan Mode では、Verdent は次のことができます。

既存のドキュメントを分析して、そのスタイルと密度に合わせる
書式の好み（コメントスタイル、詳細レベル、例の含め方）について確認の質問をする
コードベースを分析して現在のドキュメントパターンを把握する
何をどのようなスタイルでドキュメント化するかを示すドキュメント計画を提示する

例:

Generate JSDoc comments for all functions in the utils folder

Verdent は、プロジェクト内の既存の JSDoc コメントを調査し、好み（パラメータの説明、使用例の含め方）について質問したうえで、確立された規約に合ったドキュメントを生成します。

サポートされているドキュメント形式:

インラインコメント: JSDoc、Python docstring、Javadoc、XML ドキュメントコメント
README ファイル: プロジェクト概要、セットアップ手順、使用ガイド
API ドキュメント: エンドポイントの説明、リクエスト/レスポンス形式、認証の詳細
アーキテクチャガイド: システム設計の説明、コンポーネントの関係、データフロー図

大量のドキュメントを生成するときは Plan Mode を使ってください。Verdent は既存のドキュメントスタイルを確認し、生成されるドキュメントがプロジェクトの規約に合うように確認の質問をします。

複数のファイルのドキュメントを生成するときは Plan Mode を使い、コミット前にドキュメント構造を確認してください。

ファイルとモジュールを要約する

Verdent は、コードを読み、その構造を理解し、目的をわかりやすい言葉で説明することで、ファイルやモジュールを分析・要約します。

例:

Summarize what the authMiddleware.js file does

Explain the purpose of the UserService module

What's the main responsibility of the PaymentController?

Verdent が提供する内容:

主な目的: そのファイル/モジュールがシステム内で達成すること
主要な関数: 主要な関数やメソッドとその役割
依存関係: 使用している外部モジュールやサービス
エクスポート: 公開されている API と、システムの他の部分がアクセスできるもの
パターン: 使用されているデザインパターンやアーキテクチャ手法
統合ポイント: プロジェクトの他の部分とどう連携しているか

Verdent はファイルを読み、主要な関数を特定し、依存関係を追跡し、そのコードがより大きなプロジェクトアーキテクチャにどう収まるかを説明します。

アーキテクチャを理解する

Verdent は、詳細なテキスト説明、コンポーネントの関係、データフローの説明を通じてアーキテクチャを解説します。グラフィカルな図を直接生成することはできませんが、レンダリング可能な ASCII アート図や Mermaid 図のコードを作成できます。

例:

Explain the architecture of this application and show component relationships

Verdent は次のような ASCII 表現を生成することがあります。

Frontend (React)
    ↓
API Layer (Express)
    ↓
Service Layer (Business Logic)
    ↓
Database Layer (PostgreSQL)

あるいは、レンダリング用に Mermaid コードを生成します。

graph TD
    A[React Frontend] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[User Service]
    C --> E[Database]
    D --> E

アーキテクチャの説明に含まれる内容:

コンポーネントの相互作用: システムの各部がどう通信するか
データフロー: アプリケーション内を情報がどう移動するか
アーキテクチャパターン: MVC、マイクロサービス、レイヤードアーキテクチャなど
技術スタック: フロントエンド、バックエンド、データベース、外部サービス
統合ポイント: API、メッセージキュー、Webhook、サードパーティサービス
スケーラビリティパターン: ロードバランシング、キャッシング、データベースのシャーディング

Verdent はプロジェクト構造を分析し、import や依存関係を追跡し、パターンを特定し、システム設計の背後にあるアーキテクチャ上の判断を説明します。

新しいチームメンバーをオンボーディングする

Verdent は、コードベースに関する質問への回答、アーキテクチャ上の判断の説明、主要なファイルやパターンの特定、新メンバーがプロジェクト構造や規約を理解するのに役立つドキュメントの生成を通じて、新しいチームメンバーのオンボーディングを支援します。

Plan Mode では、Verdent は確認の質問をして、新しいチームメンバーの役割にとってコードベースのどの側面が最も関連するかを把握したうえで、パーソナライズされたオンボーディングガイドを作成できます。

オンボーディング質問の例:

What's the best starting point for understanding this codebase?

How does data flow from the API to the frontend?

Where should I look to understand the authentication system?

What are the naming conventions and code style guidelines used here?

Verdent が生成できるもの:

オンボーディングガイド: コードベースアーキテクチャのステップごとの解説
コンポーネントマップ: コンポーネント間の関係を示すビジュアルまたはテキストベースのガイド
共通パターン: 頻繁に使われるパターンや規約のドキュメント
セットアップ手順: 開発環境の設定方法とプロジェクトの実行方法
最初のタスク: 慣れるための簡単な初回貢献の提案

新しいチームメンバーは、対話形式でコードベースを探索でき、シニア開発者の手を煩わせたり何時間もコードを読み込んだりせずに、すぐに回答を得られます。

Verdent の Explorer サブエージェントは、新メンバーによるコードベースの発見を効率化します。「すべての React コンポーネントを表示して」のような広い質問でも、「エラーログはどこで実装されている?」のような具体的な質問でも、すぐに正確な回答を得られます。

ベストプラクティス

広い質問から始めて、徐々に掘り下げる

特定の実装に踏み込む前に、「アーキテクチャはどうなっている?」のような高レベルの質問から始めてください。これにより、コンテキストが段階的に構築されます。

包括的な検索には Explorer サブエージェントを明示的に使う

コードベース全体を徹底的に検索するには、Explorer エージェントを明示的に指定して、インスタンスを見逃さないようにします。例: 「Explorer を使ってすべての認証チェックを見つけて」

「何を」だけでなく「なぜ」を質問する

判断の背後にある根拠を理解することは、多くの場合、実装を理解すること以上に価値があります。「このコードは何をする?」と並んで「なぜこのパターンが選ばれた?」と質問してください。

ドキュメント生成に Plan Mode を活用する

ドキュメントを生成するときは、Plan Mode を使って Verdent のアプローチを確認し、自分のスタイルに合っていることを確かめ、実行前に計画を調整してください。

焦点を絞った説明には @メンションを使う

詳細な説明が欲しいときは特定のファイルを参照します。「@components/UserProfile.tsx このコンポーネントを説明して」とすれば、Verdent が正しいコードに集中します。

変更を依頼する前にコンテキストを構築する

変更を加える前に、Verdent に現在の実装を説明してもらいます。これにより、Verdent は既存のパターンに沿ったより良い提案ができます。

気軽にフォローアップの質問をする

Verdent は会話のコンテキストを維持するため、確認の質問をしたり、より深い説明を求めたり、関連トピックを探ったりしても、コンテキストを繰り返す必要はありません。