探索陌生代码库
使用 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 文件。