IBM Bob
チュートリアル

ドキュメントをコードベースと同期させる

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はソフトウェアAIのライフサイクル全体をサポートするために作られたIDEで、AIコードドキュメントもその一部です。Bobはドキュメント生成をコード変更と並行して行えるほど高速にするため、ドキュメントは遅れることなく最新の状態を維持します。実際にどう機能するかを見てみましょう：

AIドキュメントワークフロー

  1. AIがコードベースを学習する：/initコマンドがリポジトリをスキャンし、大規模言語モデルの知識ベースとして機能する構造化サマリーであるAGENTS.mdファイルを作成する
    2.
  2. AIがドキュメントを生成する：Docs Architectなどのカスタムモードがこのコンテキストを使用して、ユーザー向けドキュメント（README、ガイド、APIドキュメント）を生成する
    3.
  3. レビューと改良を行う：AI生成ドキュメントは出発点；検証し、編集し、コードと一緒にcommitする
    4.
  4. AIが同期を維持する：コード変更後に/initを再実行することでAIの理解が更新され、素早いドキュメント更新が可能になる
    5.

このワークフローはドキュメントを別タスクとして扱うのではなく、開発プロセスに統合します。

実際のシナリオ

このチュートリアルでは遭遇する実践的なシナリオを説明します：
  • 新しいプロジェクトの開始：ゼロからドキュメントをセットアップする
    •
  • 機能の追加：開発しながらドキュメントを更新する
    •
  • コードレビュー：pull requestでドキュメントを確認する
    •
  • オンボーディング：AI生成ドキュメントで新しいチームメンバーを支援する
    •
  • メンテナンス：コードベースが進化するにつれてドキュメントを最新に保つ
    •

シナリオ1：プロジェクトの初期ドキュメント

ドキュメントが最小限のリポジトリを引き継いだ。新しいチームメンバーはコードベースを理解するのに苦労しており、素早く包括的なドキュメントを作成する必要がある。

ワークスペースのセットアップ

  1. リポジトリをIBM Bob IDEで開く。
  2. 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モード固有コンテキスト）

これらのファイルには以下が含まれます：

  • コード構造と主要ディレクトリ
  • テクノロジースタックと依存関係
  • build、test、lintコマンド
  • コードパターンと慣習

なぜ重要か：これらのAGENTS.mdファイルはBobが毎回の会話で参照する知識ベースとして機能します。毎回コードベース全体を再分析する代わりに、Bobはプロジェクトに関する永続的なコンテキストを持ちます。

生成されたコンテキストのレビュー

AGENTS.mdを開いてBobが発見したものを確認する：

cat AGENTS.md

プロジェクトの構造化されたサマリーが表示されます。Bobが重要な詳細（ビジネスルール、デプロイメント慣習、チームの慣行）を見逃した場合、AGENTS.mdを編集してそれらを追加してください。このファイルはカスタマイズするためのものです。

Docs Architectモードの作成

次に、ユーザー向けドキュメントを生成するカスタムモードを作成します。このモードはAGENTS.mdコンテキストを使用して、AIのためではなく人間のためのドキュメントを作成します。

  1. Bobパネルのsettingsアイコンをクリックして設定を開く。
  2. Modesタブを選択。
  3. **+**アイコンをクリックして新しいモードを作成。
  4. 以下の値を入力：
フィールド値
NameDocs Architect
Slugdocs-architect
Role DefinitionYou 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 useUse 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 ToolsRead, 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はDocs Architectモードの設定を含むcustom_modes.yamlファイルを.bobに作成します。将来の変更のためにこのファイルを直接編集することができます。

初期ドキュメントの生成

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がドキュメントファイルを生成します。正確さを確認し、編集し、commitします：

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はシナリオAで実行した/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.

生成されたドキュメントの正確さを確認 — コード例が実際に実装と一致するかチェック — その後すべてを一緒にcommit：

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

結果：機能とドキュメントが一緒に開発され、同じpull requestでcommitされる。

シナリオ3：ドキュメントチェック付きコードレビュー

チームメンバーが新しいAPIエンドポイントを追加するpull requestを提出。ドキュメントが更新されていることを確認する必要がある。

コード変更のレビュー

git diff main feature-branch

新しいAPIエンドポイントが見えるが、ドキュメントの更新はない。

/initが実行されたか確認する

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

AGENTS.mdに変更がない場合、開発者は/initを実行しなかった。以下を依頼する：

  1. /initを実行してAIコンテキストを更新する
  2. 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.

ドキュメント更新をcommit：

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ファイルを生成します。新しい開発者はこれで：

  1. AGENTS.mdを読んでプロジェクト構造を理解できる
  2. README.mdを読んで開始手順を確認できる
  3. 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が実行されドキュメントが更新されているか確認

ドリフト検出の自動化（上級）

CIでドキュメント衛生を強制したいチーム向けに、AGENTS.mdと.bob/が最新であることを確認するpull requestチェックを追加します。チェックはブランチに対して/initを実行し、出力がcommitされたものと異なる場合に失敗します — 開発者がPRを開く前にAIコンテキストの更新を忘れたことを示します。これをベストプラクティスセクションのPRテンプレートチェックリストと組み合わせて、ドキュメント更新をレビュープロセスの必須部分にします。

結果：定期的なメンテナンスによりドキュメントがコードと同期を保つ。

AIコードドキュメントワークフローのベストプラクティス

/initを開発プロセスに統合する

/initをワークフローの定期的な部分にする：
  • 新しいモジュールや機能を追加した後に実行
    •
  • 大規模なリファクタリング後に実行
    •
  • pull requestを作成する前に実行
    •
  • アクティブなプロジェクトでは毎月実行
    •

AIコンテキストとユーザードキュメントを一緒にcommitする

AGENTS.mdファイルは常にユーザー向けドキュメントと一緒にcommitする：

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

これにより両方のレイヤーがバージョン管理システムで同期され、MarkdownソースファイルからAPIドキュメントを生成するMintlifyのようなツールに対してリポジトリが自己文書化されます。

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でコード品質を維持する

docstringとJSDocコメントを追加するためにBobを使用：

 
@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.

これによりコード品質とドキュメントの両方が向上します。

一般的なシナリオのトラブルシューティング

ドキュメントがコードと一致しない

問題：生成されたドキュメントが存在しない機能を説明したり、最近の変更を見逃している。

解決策：
  1. /initを実行してAIコンテキストを更新
    2.
  2. AGENTS.mdの変更を確認してBobが何を検出したか確認
    3.
  3. Docs Architectで影響を受けたドキュメントを再生成
    4.
  4. コード例が動作するか手動で確認
    5.

/initが重要なコンテキストを見逃す

問題：AGENTS.mdにビジネスルールやデプロイメント慣習などのプロジェクト固有の詳細が不足している。

解決策：/initが検出できなかったコンテキストを追加するためにAGENTS.mdを手動で編集します。このファイルはカスタマイズするためのものです。

ドキュメント更新に時間がかかりすぎる

問題：大規模なプロジェクトのドキュメント再生成は時間がかかる。

解決策：特定のセクションを更新するためにコンテキストメンションを使用：

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

チームメンバーがドキュメント更新を忘れる

問題：pull requestにドキュメント更新が不足している。

解決策：
  • PRテンプレートにドキュメントチェックを追加
    •
  • /initが実行されたことを確認するCIチェックをセットアップ
    •
  • ドキュメントレビューをコードレビュープロセスの一部にする
    •

AIが誤ったコード例を生成する

問題：ドキュメントのコードスニペットが動作しないか、非推奨のAPIを使用している。

解決策：
  • 生成されたコード例は常にテスト
    •
  • 現在のコードにBobを向けるためにコンテキストメンションを使用：@src/api/current-implementation.ts
    •
  • 精度を強調するためにDocs Architectモードの指示を更新
    •

次のステップ

IBM Bobを使用してAIコードドキュメントが実際にどう機能するかを学びました。以下の方法を確認できました：
  • 開発ワークフローに/initを統合する
    •
  • カスタムモードを使用してユーザー向けドキュメントを生成する
    •
  • 機能開発とコードレビューを通じてドキュメントを維持する
    •
  • コード変更とドキュメントを同期させる
    •

このワークフローをプロジェクトに適用する

  1. /initから始める：現在のプロジェクトで実行する
    2.
  2. モードを作成する：チームのニーズに合わせてDocs Architectをカスタマイズする
    3.
  3. 開発しながらドキュメント化する：コード変更と一緒にドキュメントを更新する
    4.
  4. PRでレビューする：ドキュメントをコードレビューの一部にする
    5.
  5. 定期的にメンテナンスする：月次の/init実行をスケジュール
    6.
このトピックはいかがですか？

コンテキストウィンドウを管理する

Bob のコンテキストウィンドウを管理して、メモリを維持し、コストを抑え、出力品質を保ちます。

ツール

Bobがファイルの読み取り、コードの編集、コマンドの実行、サブエージェントの生成、MCP統合の使用、モードの切り替えに特殊なツールをどのように使用してコーディング・ワークフローを効率化するかを学びます。

このページ

達成すること前提条件AIコードドキュメントが実際にどう機能するかAIドキュメントワークフロー実際のシナリオシナリオ1：プロジェクトの初期ドキュメントワークスペースのセットアップ/initでAI可読コンテキストを生成する生成されたコンテキストのレビューDocs Architectモードの作成初期ドキュメントの生成シナリオ2：新機能のドキュメント化Bobの助けを借りて機能を書く/initを再実行してAIコンテキストを更新する新機能のドキュメントを生成するシナリオ3：ドキュメントチェック付きコードレビューコード変更のレビュー/initが実行されたか確認する不足しているドキュメントを生成するシナリオ4：新しいチームメンバーのオンボーディング/initを実行させる探索にAskモードを使用するパーソナライズされたオンボーディングドキュメントを生成するシナリオ5：長期的なドキュメントメンテナンスドキュメントのドリフトを検出するドキュメントを体系的に更新するメンテナンススケジュールを確立するドリフト検出の自動化（上級）AIコードドキュメントワークフローのベストプラクティス/initを開発プロセスに統合するAIコンテキストとユーザードキュメントを一緒にcommitするAI生成ドキュメントをドラフトとして扱う精度のためのコンテキストメンションを使用するコードレビューにドキュメントを含めるdocstringでコード品質を維持する一般的なシナリオのトラブルシューティングドキュメントがコードと一致しない/initが重要なコンテキストを見逃すドキュメント更新に時間がかかりすぎるチームメンバーがドキュメント更新を忘れるAIが誤ったコード例を生成する次のステップこのワークフローをプロジェクトに適用する