見慣れないコードベースを調査する
IBM Bob を使って、見慣れないアプリケーションの目的、プロジェクト構造、アーキテクチャ、tech stack、主要コンポーネント、テストカバレッジ、デプロイメントモデルを素早く理解します。古いドキュメントや同僚の助けを借りる必要はありません。
見慣れないコードベースで生産性を上げるには、通常コードを読んだり、ドキュメントを探したり、 同僚にコンテキストを聞いたりする何時間もの作業が必要です。このチュートリアルでは、Ask mode で Bob を使って Galaxium Travels のコードベースを 体系的に調査し、アプリケーションの全体像を把握します。具体的には、目的とアーキテクチャ、tech stack、 主要コンポーネント、ユニットテストと統合テストのカバレッジ、そしてデプロイメントモデルです。 その後、Agent mode に切り替えて、Bob が発見したすべての内容をチーム全体で活用できる 永続的な Markdown リファレンスに保存します。
Galaxium Travels は、React フロントエンド、Python FastAPI バックエンド、Java Spring Boot 在庫サービスを備えた、意図的に複雑な実世界スタイルのアプリケーションです。このため、 このワークフローに最適な候補となっています。
Bob の出力はコードベースの現在の状態によって異なります。このチュートリアルの例は、 正確なトランスクリプトではなく、代表的な出発点として扱ってください。自分のプロンプトを 調整し、結果を改善するための参考として使用してください。
学べる主な機能
- Ask mode: Bob がファイルを変更することなく、 コードを探索・分析します。
- Agent mode: Bob が自律的にファイルを書き込み、 生成した成果物をプロジェクトに保存します。
- コンテキストメンション:
@を使って特定の ファイルやフォルダを参照し、Bob に正確な分析スコープを与えます。 /init: 質問を始める前に Bob がコードベースの 規約を理解できるよう、プロジェクトコンテキストを初期化します。
前提条件
このチュートリアルを完了するには、以下が必要です。
- Bob IDE がインストールされていること。
- Git がローカルにインストールされていること。
- Bob の基本的な操作に慣れていること。Bob が初めての場合は、先に クイックスタートチュートリアル を完了してください。
ワークスペースのセットアップ
Galaxium Travels リポジトリをクローンする
ターミナルで、サンプルリポジトリをクローンします。
git clone https://github.com/IBM/galaxium-travels.gitサンプルプロジェクトを開く
Bob IDE で、クローンした galaxium-travels フォルダを開きます。Bob が
「Do you trust the authors of the files in the folder?」と尋ねた場合は、
Yes, I trust the authors をクリックしてください。
Bob のチャットインターフェースを開く
チャットインターフェースがまだ開いていない場合は、ナビゲーションバーの Bob アイコンをクリックするか、 ショートカット Option + Command + B（Mac）または Ctrl + Alt + B（Windows）を使用します。
プロジェクトコンテキストを初期化する
Bob は起動時にデフォルトで Agent mode になっています。モードを切り替える前に、/init
コマンドを実行して、Bob がプロジェクトを読み込み、以降のインタラクションで使用する
AGENTS.md コンテキストファイルを生成します。
/init自動承認が無効になっている場合、Bob はファイルの読み込みと AGENTS.md ファイルの書き込みの
許可を求めます。各リクエストを承認してください。Bob はルートレベルの AGENTS.md と、
モード固有の設定を含む .bob/ フォルダを作成します。
生成された AGENTS.md を確認し、Bob がリポジトリのマルチサービス構造を正しく識別したことを確かめてください。
Ask mode に切り替える
チャット入力フィールドの下にあるモードセレクターで Ask を選択するか、/ask と入力して
モードを切り替えます。Ask mode は厳密に読み取り専用です。Bob はファイルを分析しますが、
何も作成・変更することはできません。そのため、このチュートリアルのすべての探索作業に
適したモードです。
アプリケーションの目的とプロジェクト構造を把握する
最も広い質問から始めましょう。このアプリケーションは何をするもので、コードベースはどのように
構成されているか？Bob はプロジェクト構造と、README.md、package.json、requirements.txt、
ビルドファイル、その他の設定ファイルなどの主要なファイルを読み込みます。Bob は各ディレクトリを
手動でトレースすることなく、簡潔なサマリーを合成します。
Ask mode で次のプロンプトを入力します。
What is the purpose of this application? Describe the project structure,
the high-level architecture, and the main responsibilities of each top-level
directory.Bob はファイルツリーと主要なエントリーポイントを読み込み、次の内容を含む出力を生成します。
- アプリケーションの目的
- トップレベルディレクトリの責務
- 各トップレベルディレクトリの内容のまとめ
- 高レベルアーキテクチャ図
Tech stack を分析する
高レベルの構造が明確になったら、使用されている技術を詳しく調べます。このプロンプトは、 ビルドツールを理解したり、依存関係の選択を評価したり、アップグレードの範囲を見積もる 必要がある場合に役立ちます。
Ask mode で次のプロンプトを入力します。
Analyze the tech stack for the entire application. For each service, list the
programming language, runtime version requirements, framework, key libraries,
database, and build/test tooling.Bob は各サービスの依存関係と設定ファイルを調べ、次の内容を含む出力を生成します。
- 各サービスの詳細な tech stack 分析
- エンドツーエンドテストフレームワークの特定
- CI/CD スタックとデプロイメントスクリプトの追加ツール
- すべてのサービスとレイヤーにわたる tech stack を視覚的にまとめた「Stack at a Glance」図
主要コンポーネントをマッピングする
tech stack を理解すると、コードベースが何を使用しているかがわかります。主要コンポーネントを 理解すると、どのように機能しているかがわかります。このプロンプトは、サービス境界を越えた 変更を行う前に特に役立ち、3 つのサービス全体のコンポーネント境界とデータフローを トレースするよう Bob に求めます。
Ask mode で、最も関連性の高いファイルに Bob を向けるコンテキストメンション付きの 次のプロンプトを入力します。
Identify the key components of this application and explain how they interact.
Reference @booking_system_frontend/src/services,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/models.py,
and @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Describe the component responsibilities, the data flow for the booking
lifecycle, and any cross-service contracts I need to know before modifying
the codebase.Bob はインタラクションチェーンをトレースし、次の内容を含む出力を生成します。
- フロントエンド、バックエンド API、データベースレイヤー、Java ホールドサービスの詳細な責務
- コンポーネントのインタラクションが注釈付きで示された 2 つの予約ライフサイクルフローの図
- 変更前に知っておくべき 5 つのサービス間コントラクトのまとめ
- コンポーネントインタラクションマップ
ユニットテストカバレッジを評価する
機能を追加したりリファクタリングしたりする前に、既存のテストスイートが何をカバーしており、 どこにギャップがあるかを把握する必要があります。このプロンプトは、テストを実行せずに テストファイルを読み込んでカバレッジ評価を生成するよう Bob に求めます。
Ask mode で次のプロンプトを入力します。
Analyze the unit test suites across all three services. Reference
@booking_system_backend/tests,
@booking_system_inventory_hold_service/src/test,
and @booking_system_frontend/src.
For each service, describe what is tested, which testing framework is used,
what the test structure looks like, and identify any obvious gaps where
critical logic appears to be untested.Bob はテストファイルを読み込み、次の内容を含む詳細なテストスイート分析を生成します。
- 各サービスのテストフレームワーク、テスト対象クラス、クラスごとのテスト数、クラスごとに 検証される内容
- テストの重大なギャップ
- 重要なビジネスロジックの欠落しているテストカバレッジ
統合テストとエンドツーエンドテストのカバレッジを評価する
ユニットテストは個々のコンポーネントが単独で動作するかを確認します。統合テストと エンドツーエンドテストは、サービスが連携して正しく動作するかを確認します。Galaxium Travels では、予約確認フローが 3 つのサービスすべてにわたるため、これが特に重要です。
Ask mode で次のプロンプトを入力します。
Analyze the end-to-end and integration test coverage. Reference
@tests_e2e and any cross-service test fixtures you can identify.
Describe which cross-service flows are covered, which are not, what test
infrastructure is required to run the suite, and what the tests assert
at the boundary level.Bob はエンドツーエンドテストスイートを読み込み、次の内容を含む詳細なカバレッジ分析を生成します。
- スイートを実行するためのテストインフラと要件
- スモークテスト
- 主要なインフラの決定事項
- カバーされているサービス間フローとカバーされていないサービス間フロー
- 境界レベルでのテストアサーション
デプロイメントモデルを確認する
アプリケーションのデプロイ方法（ターゲットプラットフォーム、コンテナ化戦略、インフラ自動化）を 理解することは、コントリビューターとして参加する前や、自分のラップトップ以外の環境で アプリケーションを実行する前に不可欠です。
Ask mode で次のプロンプトを入力します。
Analyze the deployment model for this application. Reference
@docker-compose.yml, @deployment_scripts, @terraform, @.github/workflows,
and the deployment documentation in @docs.
Describe the supported deployment targets, how each service is containerized,
what infrastructure is provisioned, and how CI/CD is configured.Bob はデプロイメントの成果物を読み込み、デプロイメントモデル分析を生成します。分析には 以下が含まれます。
- サポートされているデプロイメントターゲット
- 各サービスのコンテナ化戦略
- インフラプロビジョニングの詳細
- CI/CD ワークフロー
- 主要なデプロイメントの制約とギャップ
調査結果をリポジトリに保存する
Ask mode で生成した分析はチャットセッションにのみ存在します。Agent mode に切り替えて、 将来のコントリビューターがこの作業から恩恵を受けられるよう、永続的なオンボーディング リファレンスドキュメントをリポジトリに書き込むよう Bob に依頼します。
Agent mode に切り替える
モードセレクターで Agent を選択するか、チャット入力フィールドに /agent と入力します。
オンボーディングリファレンスを作成する
Bob が発見したすべての内容を 1 つの Markdown ファイルにまとめるよう Bob に依頼します。 Bob は会話の完全なコンテキストを持っており、すべてのファイルを再読み込みすることなく 調査結果を合成します。
Create a file called docs/ONBOARDING.md.
Create one section for each of these topics:
1. Application overview: purpose, project structure, high-level architecture, and the main responsibilities of each top-level directory.
2. Tech stack analysis, including a "Stack at a Glance" diagram.
3. Key components and their interactions, including a component interaction map.
4. Unit test coverage analysis.
5. End-to-end test coverage analysis.
6. Deployment model analysis.
Populate each section with everything you discovered in this session.
Use clear headings, Mermaid diagrams, and tables where appropriate. Keep the tone concise and technical.Bob がファイルを書き込みます。自動承認が無効になっている場合は、Bob が
docs/ONBOARDING.md の書き込み許可を求めた際に Approve をクリックしてください。
出力を確認する
エディターで docs/ONBOARDING.md を開き、ドキュメントに期待するすべての内容が含まれていることを
確認します。Bob にプレビューを依頼することもできます。
Show me a preview of docs/ONBOARDING.mdBob はチャットインターフェースに Markdown をレンダリングします。コミットする前に、内容の 正確さと完全性を確認してください。
ファイルをコミットする
お好みの Git ワークフローを使用して、docs/ONBOARDING.md をリポジトリにコミットします。
これで、すべてのコントリビューターと Bob 自身が今後のセッションでドキュメントを活用できます。
トラブルシューティング
Bob の分析が浅い、またはサービスが抜けている
デフォルトでは、Bob はプロジェクト構造と主要なファイルの一部を読み込みます。サービスが 抜けていたり、期待より詳細が少ない場合は、明示的なコンテキストメンションを追加して Bob のフォーカスを絞り込みます。
たとえば、Java ホールドサービスが tech stack 分析に反映されていない場合は、
@booking_system_inventory_hold_service/pom.xml をプロンプトに追加します。
Analyze the tech stack for @booking_system_inventory_hold_service/pom.xml
and add the Java hold service to the tech stack summary you produced earlier.Bob がテストファイルを見つけられない
Bob がテストファイルを見つけられないと報告した場合は、コンテキストメンションを使用して テストディレクトリを直接指定します。
Analyze the test coverage in @booking_system_backend/tests and
@tests_e2e. List every test file and summarize what each one covers.Bob のデプロイメント分析でターゲットが抜けている
AWS、IBM Cloud、ローカルのデプロイメント成果物は複数のトップレベルディレクトリに分散しています。 Bob のデプロイメントサマリーが不完全な場合は、特定のディレクトリを指定します。
Review @deployment_scripts/aws, @terraform, @deployment_scripts/ibm, and
@.github/workflows. Update the deployment model summary to include all three
deployment targets./init が空または不正確な AGENTS.md を生成する
ワークスペースのルートで、/init コマンドは README.md、package.json、requirements.txt、
pom.xml、Makefile などのアンカーファイルを読み込んでプロジェクトコンテキストを構築します。
これらのファイルがルートに存在しない場合、またはワークスペースのルートがサブディレクトリに
設定されている場合、Bob はプロジェクトの一部しか見えず、疎らまたは不正確な AGENTS.md
を生成します。
生成された AGENTS.md がマルチサービス構造を反映していない場合は、以下を確認してください。
- ワークスペースのルート:
booking_system_backend/などのサブディレクトリではなく、galaxium-travels/がワークスペースのルートとして開かれていることを確認してください。 3 つのサービスディレクトリすべてがトップレベルに表示されている必要があります。 - アンカーファイルの欠如: ルートに
README.mdやその他のマニフェストがない場合、/initは読み込むものが少なくなります。簡単なプロジェクト説明を記載したルートレベルのREADME.mdを追加してから、/initを再実行してください。
ルートを修正した後、/init を再実行して AGENTS.md ファイルを再生成してください。