探索陌生程式碼庫
使用 IBM Bob 快速了解一個陌生的應用程式——包括其用途、專案結構、架構、技術堆疊、關鍵元件、測試涵蓋率和部署模型。無需依賴過時的文件，也不必等待隊友的協助。
在陌生的程式碼庫中提升生產力，通常意味著要花幾個小時閱讀程式碼、尋找文件、向隊友詢問背景資訊。在本教學中，你將使用 Ask 模式下的 Bob 系統地分析 Galaxium Travels 程式碼庫，全面了解這個應用程式：它的用途與架構、技術堆疊、關鍵元件、單元測試與整合測試涵蓋率，以及部署模型。然後切換到 Agent 模式，將 Bob 發現的所有內容儲存到一份持久化的 Markdown 參考文件中，供整個團隊使用。
Galaxium Travels 是一個刻意設計得較為複雜的真實風格應用程式，包含 React 前端、Python FastAPI 後端以及 Java Spring Boot 庫存服務。這使它成為本工作流程的理想範例。
Bob 的輸出會隨程式碼庫的目前狀態而變化。請將本教學中的範例視為具有代表性的起點，而非精確的記錄。利用它們來校準你自己的提示詞並優化結果。
你將學到的核心功能
- Ask 模式：在 Bob 不修改任何檔案的情況下探索和分析程式碼。
- Agent 模式：讓 Bob 自主寫入檔案，將產生的產物持久化到你的專案中。
- 情境提及：使用
@參照特定檔案和資料夾，為 Bob 提供精確的分析範圍。 /init：初始化專案情境，讓 Bob 在你開始提問前就了解程式碼庫的慣例。
先決條件
完成本教學需要以下條件：
設定工作區
開啟範例專案
在 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 模式。切換模式之前，先執行 /init 指令，讓 Bob 讀取專案並產生後續互動中使用的 AGENTS.md 情境檔案。
/init如果自動核准已停用，Bob 會請求讀取檔案和寫入 AGENTS.md 檔案的權限。請核准每個請求。Bob 會在根目錄建立 AGENTS.md，並建立包含模式專屬設定的 .bob/ 資料夾。
查看產生的 AGENTS.md，確認 Bob 正確識別了儲存庫的多服務結構。
切換到 Ask 模式
在聊天輸入框下方的模式選擇器中選擇 Ask，或輸入 /ask 切換模式。Ask 模式嚴格唯讀——Bob 會分析檔案，但無法建立或修改任何內容，這使它成為本教學所有探索工作的正確模式。
了解應用程式用途和專案結構
從最宏觀的問題開始：這個應用程式有什麼用途，程式碼庫是如何組織的？Bob 會讀取專案結構以及 README.md、package.json、requirements.txt、建置檔案和其他設定檔等關鍵檔案。無需手動遍歷每個目錄，Bob 就能綜合出簡潔的摘要。
在 Ask 模式下，輸入以下提示詞：
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 讀取檔案樹和關鍵進入點後，會產生包含以下內容的輸出：
- 應用程式用途
- 頂層目錄職責
- 每個頂層目錄內容的概述
- 高層架構圖
分析技術堆疊
高層結構清晰後，深入了解具體使用的技術。當你需要了解建置工具、評估相依套件選擇或估算升級範圍時，這個提示詞非常有用。
在 Ask 模式下，輸入以下提示詞：
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 檢查每個服務的相依套件和設定檔，產生包含以下內容的輸出：
- 每個服務的詳細技術堆疊分析
- 端對端測試框架識別
- CI/CD 堆疊和部署腳本中的額外工具
- 直觀彙總所有服務和層次技術堆疊的「Stack at a Glance」圖
梳理關鍵元件
了解技術堆疊能告訴你程式碼庫用了什麼；了解關鍵元件則能告訴你它是如何運作的。這個提示詞要求 Bob 追蹤三個服務的元件邊界和資料流，在進行跨服務邊界的變更前尤為有用。
在 Ask 模式下，輸入以下帶情境提及的提示詞，將 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 hold 服務的詳細職責
- 帶有元件互動註解的兩個預訂生命週期流程圖
- 修改程式碼庫前必須了解的五個跨服務契約摘要
- 元件互動圖
評估單元測試涵蓋率
在新增功能或重構之前，你需要了解現有測試套件涵蓋了哪些內容以及存在哪些空白。這個提示詞要求 Bob 在不執行測試的情況下讀取測試檔案並產生涵蓋率評估。
在 Ask 模式下，輸入以下提示詞：
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 尤為重要。
在 Ask 模式下，輸入以下提示詞：
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 模式下，輸入以下提示詞：
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 模式下產生的分析僅存在於聊天工作階段中。切換到 Agent 模式，讓 Bob 將持久化的入職參考文件寫入儲存庫，以便未來的貢獻者從這項工作中受益。
切換到 Agent 模式
在模式選擇器中選擇 Agent，或在聊天輸入框中輸入 /agent。
建立入職參考文件
讓 Bob 將它發現的所有內容整合到一個 Markdown 檔案中。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 hold 服務未體現在技術堆疊分析中，請在提示詞中新增 @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 未反映多服務結構，請檢查以下幾點：
- 工作區根目錄：確認開啟的是
galaxium-travels/而非booking_system_backend/等子目錄作為工作區根目錄。三個服務目錄必須全部在頂層可見。 - 缺少錨定檔案：如果根目錄缺少
README.md或其他 manifest 檔案，/init可讀取的內容很少。請在根目錄新增一個包含簡要專案說明的README.md，然後重新執行/init。
修正根目錄後，重新執行 /init 以重新產生 AGENTS.md 檔案。