了解如何使用 IBM Bob 的 init 命令和自定义 Docs Architect 模式，在功能开发、代码审查、入职培训和持续维护等真实开发场景中，将技术文档与代码库保持同步。

在软件开发中，文档通常被视为事后才想到的事情——在代码"完成"之后才去做。但实际上，文档需要与代码一起持续演进。本教程展示了在使用 IBM Bob 的实际开发工作流中，AI 代码文档是如何真正运作的。

与其专注于理论，你将看到如何将 Bob 的文档功能集成到日常开发流程中：从初始项目设置，到功能开发、代码审查和发布。你将使用 /init 命令建立 AI 可读的上下文，并创建一个自定义 Docs Architect 模式，在开发的每个阶段生成人类可读的文档。

你将实现什么

在本教程中，你将学习如何：

将 AI 代码文档设置为开发工作流的一部分

使用 /init 创建和维护 AI 可读的项目上下文

构建自定义 Docs Architect 模式来生成面向用户的文档

将文档更新集成到功能开发周期

通过代码审查和 pull request 维护文档

在版本控制中保持文档与代码变更同步

前提条件

完成本教程需要以下内容：

已安装 Bob IDE。

你想要记录的 Git 仓库。任何本地项目或开源仓库都可以。

AI 代码文档在实践中如何运作

传统的文档工作流将编写代码和编写文档分开。开发者编写代码，然后（可能）在后面更新文档。这造成了文档落后、变得不准确、最终被忽略的差距。

IBM Bob 是一个为支持完整软件开发生命周期而构建的 IDE——这包括 AI 代码文档。Bob 让文档生成足够快，可以与代码变更同步进行，让文档保持最新而不是落后。以下是实践中的工作方式：

AI 文档工作流

AI 学习你的代码库：/init 命令扫描你的仓库并创建 AGENTS.md 文件——结构化摘要，作为大型语言模型的知识库

AI 生成文档：像 Docs Architect 这样的自定义模式使用此上下文生成面向用户的文档（README、指南、API 文档）

你审查和完善：AI 生成的文档是起点；你验证、编辑并与代码一起提交

AI 保持同步：代码变更后重新运行 /init 会更新 AI 的理解，使快速文档更新成为可能

此工作流将文档集成到开发流程中，而不是将其视为单独的任务。

真实世界场景

本教程涵盖你会遇到的实际场景：

启动新项目：从零开始设置文档

添加功能：开发时更新文档

代码审查：检查 pull request 中的文档

入职培训：使用 AI 生成的文档帮助新团队成员

维护：随着代码库发展保持文档最新

场景 1：项目初始文档

你接手了一个文档最少的仓库。新团队成员难以理解代码库，你需要快速创建全面的文档。

设置工作区

在 IBM Bob IDE 中打开仓库。
打开 Bob 聊天界面：Option + Command + B（macOS）或 Ctrl + Alt + B（Windows）

使用 /init 生成 AI 可读的上下文

第一步是给 Bob 提供关于你的项目的知识。切换到 Agent 模式 并运行：

/init

Bob 扫描你的仓库并生成：

仓库根目录中的 AGENTS.md（主要项目上下文）
.bob/rules-code/AGENTS-code.md（Agent 模式特定上下文）
.bob/rules-plan/AGENTS-plan.md（Plan 模式特定上下文）
.bob/rules-ask/AGENTS-ask.md（Ask 模式特定上下文）

这些文件包含：

代码结构和关键目录
技术栈和依赖项
构建、测试和 lint 命令
代码模式和约定

为什么重要：这些 AGENTS.md 文件作为知识库，Bob 在每次对话中都会引用。Bob 拥有关于你项目的持久上下文，而不是每次都重新分析整个代码库。

审查生成的上下文

打开 AGENTS.md 并查看 Bob 发现了什么：

cat AGENTS.md

你会看到项目的结构化摘要。如果 Bob 遗漏了重要细节（业务规则、部署约定、团队实践），请编辑 AGENTS.md 添加它们。这个文件是用来自定义的。

创建 Docs Architect 模式

现在创建一个生成面向用户文档的自定义模式。此模式将使用 AGENTS.md 上下文为人类创建文档，而不是为 AI。

点击 Bob 面板中的 settings 图标打开设置。
选择 Modes 选项卡。
点击 + 图标创建新模式。
填写以下值：

字段	值
Name	Docs Architect
Slug	docs-architect
Role Definition	You are a documentation architect and writer who creates user-facing documentation. You work alongside AGENTS.md files (created by /init) which provide AI-readable technical context. Your role is to create human-readable documentation that complements, not duplicates, the AGENTS.md content. You focus on user needs: getting started guides, conceptual overviews, tutorials, and onboarding materials. Include code snippets with clear explanations. Add JSDoc comments (JavaScript) or Javadoc (Java) and docstrings where helpful to improve code quality.
When to use	Use this mode for writing and maintaining user-facing documentation such as READMEs, onboarding guides, and API docs. Not for writing or modifying application code.
Available Tools	Read, Edit

对于 Mode-specific Custom Instructions 字段，复制并粘贴以下内容：

When documenting a project:
1. Review AGENTS.md files to understand project structure and technical details
2. Create user-facing documentation (READMEs, getting started guides, tutorials)
3. Avoid duplicating technical details from AGENTS.md (build commands, code patterns)
4. Focus on user workflows, conceptual overviews, and practical code examples
5. Include code blocks with clear explanations
6. Add docstrings and JSDoc comments to improve code quality

Generate:
- README.md explaining project purpose and navigation
- CONTRIBUTING.md with onboarding steps for new contributors
- Getting started guide with code snippets
- Conceptual documentation explaining architectural decisions

点击保存。

Bob 在 .bob 中创建一个包含 Docs Architect 模式配置的 custom_modes.yaml 文件。你可以直接编辑此文件进行未来的更改。

生成初始文档

切换到 Docs Architect 模式并输入提示词：

I've run /init to establish project context. Please create comprehensive documentation for this project:

1. Review AGENTS.md to understand the project structure
2. Create a README.md with:
   - Project overview and purpose
   - Quick start guide with code examples
   - Project structure explanation
   - Links to additional documentation
3. Create CONTRIBUTING.md with:
   - Development setup instructions
   - How to run tests
   - How to submit a pull request
   - Code style guidelines
4. Identify gaps in the codebase that need better documentation (missing docstrings, unclear functions)

Focus on making the technical details from AGENTS.md accessible to new developers.

Bob 生成文档文件。检查准确性，进行编辑，然后提交：

git add AGENTS.md .bob/ README.md CONTRIBUTING.md
git commit -m "docs: initial project documentation with AI assistance"

结果：几分钟而不是几小时内，从最少的文档变成了全面的文档。

场景 2：为新功能编写文档

你刚刚实现了一个新功能。代码可以运行，但你的 README、贡献指南和 API 文档仍然描述项目的旧状态。这是文档最常落后的地方——功能已完成，但文档没有跟上。

以下是如何使用 Bob 弥合这个差距。

借助 Bob 的帮助编写功能

开发时，切换到 Agent 模式，让 Bob 协助实现。因为 Bob 已经拥有来自场景 1 中运行的 /init 的项目上下文，它理解你的代码结构、依赖项和约定——让其建议比从零开始更相关。

像平常一样编写功能，使用 Bob 进行代码补全、重构，或询问关于现有代码库的问题。

重新运行 /init 更新 AI 上下文

功能实现后，Bob 的上下文已过期——它是在你的新代码存在之前生成的。更新它：

/init

Bob 重新扫描仓库并更新 AGENTS.md 以反映变化——新模块、更新的依赖项，以及它检测到的任何新代码模式。

确认更新捕获了你的变更：

git diff AGENTS.md .bob/

如果 diff 显示你的新功能，Bob 就准备好生成准确的文档了。如果遗漏了重要内容，在继续之前手动编辑 AGENTS.md。

为新功能生成文档

现在切换到 Docs Architect 模式。由于你刚刚更新了 AGENTS.md，Bob 拥有新功能的准确情况，可以生成反映真实实现的文档——而不是猜测。

提示 Bob 需要更新什么：

I've added a new feature to the project. Please update the documentation:

1. Add a section to README.md explaining:
   - What the feature does
   - How to configure and use it
   - A code snippet showing basic usage
2. Update CONTRIBUTING.md if the development workflow has changed
3. Create a dedicated docs page that covers:
   - How the feature works
   - Relevant API endpoints or interfaces
   - Code examples for common use cases
   - Code explanations for non-obvious logic
   - Troubleshooting tips

Include code blocks with clear explanations. Add docstrings to any functions that lack them.

审查生成的文档的准确性——确认代码示例实际上与你的实现一致——然后将所有内容一起提交：

git add src/ AGENTS.md .bob/ README.md CONTRIBUTING.md docs/
git commit -m "feat: add [feature name] with documentation"

结果：你的功能和文档一起开发，并在同一个 pull request 中提交。

场景 3：带文档检查的代码审查

团队成员提交了一个添加新 API 端点的 pull request。你需要确保文档已更新。

审查代码变更

git diff main feature-branch

你看到新的 API 端点但没有文档更新。

检查是否运行了 /init

git diff main feature-branch -- AGENTS.md .bob/

如果 AGENTS.md 没有变更，开发者没有运行 /init。请他们：

运行 /init 更新 AI 上下文
使用 Docs Architect 更新面向用户的文档

生成缺少的文档

如果你在审查 PR，可以自己生成文档：

git checkout feature-branch

在 Bob 中运行 /init，然后切换到 Docs Architect 模式：

I'm reviewing a pull request that adds new API endpoints. Please update the documentation:

1. Review the new endpoints in src/api/
2. Update README.md with a brief mention of the new endpoints
3. Update docs/api.md with:
   - Endpoint descriptions
   - Request/response examples with code blocks
   - Authentication requirements
   - Error codes
4. Add JSDoc comments to the endpoint handlers if missing

Focus on making the API easy to understand for other developers.

提交文档更新：

git add AGENTS.md .bob/ README.md docs/api.md src/api/
git commit -m "docs: add documentation for new API endpoints"
git push

结果：文档是代码审查流程的一部分，而不是事后的补充。

场景 4：新团队成员入职

新开发者加入你的团队。他们需要快速了解代码库。

让他们运行 /init

新开发者克隆仓库并运行：

/init

Bob 生成反映代码库当前状态的新 AGENTS.md 文件。新开发者现在可以：

阅读 AGENTS.md 了解项目结构
阅读 README.md 获取入门说明
阅读 CONTRIBUTING.md 了解开发工作流

使用 Ask 模式进行探索

新开发者可以使用 Bob 的 Ask 模式探索代码库：

@src/auth Explain how authentication works in this project

@src/api What API endpoints are available and what do they do?

@tests How do I run tests for a specific module?

Bob 使用 AGENTS.md 中的上下文和实际源代码来回答。

生成个性化入职文档

如果你的项目缺少入职文档，使用 Docs Architect：

Create an onboarding guide for new developers joining this project:

1. Prerequisites (tools, accounts, access)
2. Initial setup steps with code blocks
3. How to run the project locally
4. How to run tests
5. Overview of the codebase structure
6. Common development tasks with examples
7. Where to find help

Make it practical and include code snippets for each step.

结果：新团队成员可以在几小时而不是几天内上手。

场景 5：长期维护文档

你的项目已经开发了数月。代码发生了重大变化，文档开始出现偏差。

检测文档偏差

运行 /init 查看变化：

/init

查看 diff：

git diff AGENTS.md .bob/

大量变更表明代码有显著进化。这是面向用户的文档需要更新的信号。

系统性地更新文档

使用 Docs Architect 刷新文档：

I've run /init and noticed significant changes to the project structure. Please review and update the documentation:

1. Review AGENTS.md changes to understand what's different
2. Update README.md to reflect current project structure
3. Update CONTRIBUTING.md if development workflow has changed
4. Identify any new features that lack documentation
5. Remove documentation for deprecated features
6. Update code examples to match current API

Focus on accuracy—make sure documentation matches the current codebase.

建立维护计划

将文档更新添加到常规工作流中：

每月：运行 /init 并查看变更
发布前：更新所有文档
重大重构后：重新生成受影响的文档
代码审查中：检查是否运行了 /init 以及文档是否已更新

重大重构后运行

创建 pull request 前运行

活跃项目每月运行

一起提交 AI 上下文和用户文档

始终将 AGENTS.md 文件与面向用户的文档一起提交：

git add AGENTS.md .bob/ README.md docs/
git commit -m "docs: update for [feature/change]"

这使两个层次在版本控制系统中保持同步，并使你的仓库对像 Mintlify 这样从 Markdown 源文件生成 API 文档的工具实现自文档化。

将 AI 生成的文档视为草稿

AI 驱动的代码文档工具生成起点，而不是最终产品。始终：

审查准确性

检查代码示例是否有效

验证技术细节

调整语气和风格

添加 AI 可能遗漏的上下文

使用上下文提及来精确

更新文档的特定部分时，使用 @ 提及：

@src/auth @docs/authentication.md Update the authentication documentation to reflect the new OAuth flow

这有助于 Bob 专注于相关代码和文档。

在代码审查中包含文档

向 pull request 模板添加文档检查：

## Documentation Checklist
- [ ] Ran `/init` to update AGENTS.md
- [ ] Updated README if user-facing changes
- [ ] Updated API docs if endpoints changed
- [ ] Added code examples for new features
- [ ] Verified all code snippets work

用 docstring 维护代码质量

使用 Bob 添加 docstring 和 JSDoc 注释：

@src/api Review all functions in this directory and add JSDoc comments to any that lack them. Include parameter types, return types, and usage examples.

这既提高了代码质量，也改善了文档。

常见场景故障排除

文档与代码不匹配

问题：生成的文档描述了不存在的功能或遗漏了最近的变更。

解决方案：

运行 /init 更新 AI 上下文

查看 AGENTS.md 变更，了解 Bob 检测到了什么

使用 Docs Architect 重新生成受影响的文档

手动验证代码示例是否有效

/init 遗漏了重要上下文

问题：AGENTS.md 缺少项目特定细节，如业务规则或部署约定。

解决方案：手动编辑 AGENTS.md 添加 /init 无法检测的上下文。这个文件是用来自定义的。

文档更新耗时太长

问题：为大型项目重新生成文档耗时。

解决方案：使用上下文提及更新特定部分：

@docs/api.md @src/api/users.ts Update only the user API documentation to reflect the new endpoints

团队成员忘记更新文档

问题：pull request 缺少文档更新。

解决方案：

在 PR 模板中添加文档检查

设置 CI 检查以验证是否运行了 /init

将文档审查作为代码审查流程的一部分

AI 生成了错误的代码示例

问题：文档中的代码片段无法运行或使用了已弃用的 API。

解决方案：

始终测试生成的代码示例

使用上下文提及将 Bob 指向当前代码：@src/api/current-implementation.ts

更新 Docs Architect 模式说明以强调准确性

下一步

你已经学习了如何使用 IBM Bob 在实践中进行 AI 代码文档工作。你了解了如何：

将 /init 集成到开发工作流中

使用自定义模式生成面向用户的文档

通过功能开发和代码审查维护文档

保持文档与代码变更同步

将此工作流应用到你的项目

从 /init 开始：在当前项目上运行它

创建你的模式：根据团队需求自定义 Docs Architect

开发时记录文档：与代码变更一起更新文档

在 PR 中审查：将文档作为代码审查的一部分

定期维护：计划每月运行 /init

保持文档与代码库同步

本页内容