了解如何使用 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

保持文件與程式碼庫同步

本頁內容