Roo Code / IBM Bob で実践するAI時代の開発フレームワーク：SDD × Context Engineering × Runbooks

Last updated at 2026-04-16Posted at 2026-03-23

本記事は、以下のQiita記事で提唱された統合アーキテクチャを、Roo CodeとIBM Bobの両方で実運用可能な形に落とし込んだ実践ガイドです。

参考記事：AI時代の開発フレームワーク：Spec-Driven Development × Context Engineering × Runbooks 統合実践編

IBM Bobを無料で始めてみましょう
30日間の無料トライアルでは、IBM Bobの利用に必要なクレジット”Bobコイン”を、40Bobコイン分ご利用いただけます。
お申し込みはこちらから行えます。
Bobコインの追加が必要な場合は、こちらから少額よりご購入いただけます。

📝 TL;DR（要約）

この記事で分かること

SDD、Context Engineering、Runbooksの3つの手法の正しい理解
Roo CodeとIBM Bobにおける実装方法の違い
実際に動くディレクトリ構造と設定例
よくある失敗パターンと回避方法

3つの手法の役割

手法	役割	問い	実装場所
SDD	何を作るか	WHAT	`docs/spec/`
Context Engineering	どう作るか	HOW	`AGENTS.md` + `rules/`
Runbooks	誰でも再現可能	WHO	`skills/` + `commands/` + Custom Mode + MCP Server

1. なぜ統合が必要なのか

1.1 単一手法の限界

AI時代の開発では、単一の手法だけでは限界があります：

シナリオ1：仕様はあるのに、AIが理解できない

仕様書（SDD）はあるが、プロジェクトコンテキスト（CE）が欠如
AIが既存アーキテクチャと整合性のないコードを生成

シナリオ2：コンテキストはあるのに、一貫性がない

コンテキスト（CE）はあるが、標準化された仕様（SDD）と共有可能なワークフロー（Runbooks）が欠如
レビュー時に「なぜ2つの異なるエラーハンドリングパターンがあるのか？」

シナリオ3：すべてが揃っているのに、スケールしない

完璧な仕様書、詳細なコンテキスト、素晴らしいワークフロー
しかし、チームが10人になったら「どの仕様が最新？」「このコンテキストは誰が管理？」「ワークフローが人によって違う...」

1.2 統合の必要性

これら3つの問題を解決するには、3つの手法を統合する必要があります：

2. 3つの手法の正しい理解

2.1 Spec-Driven Development (SDD)

役割: 何を作るか（WHAT）を定義

目的:

仕様を正本（Source of Truth）として管理
AIが理解できる形式で要件を記述
仕様の曖昧さを排除

書くべき内容:

ビジョン
ユースケース
非機能要件
ドメイン制約

書かない内容:

実装方法
コーディング規約
デプロイ手順

2.2 Context Engineering (CE)

役割: どう作るか（HOW）の制約を伝える

目的:

AIの判断軸を提供
暴走を防止
プロジェクト固有のパターンを共有

2つのレイヤー:

方針レイヤー（AGENTS.md）

判断に迷ったときの羅針盤
優先順位（例：安全性 > 速度）
破壊的変更に対する姿勢

制約レイヤー（rules/）

常に適用される最小限のガードレール
Yes/Noで判定できるルール
短く明確に（10〜20行程度）

2.3 Runbooks

役割: 誰でも再現可能（WHO）にする

目的:

チーム全体で共有・再利用可能な仕組み
人によって品質がバラバラ → Runbooksで標準化
知識の属人化を防ぐ

4つの実装方法:

Agent Skills

長い手順を定義
分岐や条件判断を含む
業界標準（30+製品対応）
マークダウンファイルのみで実装可能

Slash Commands

短いワークフローを起動
引数を受け取れる
チャットから即座に実行
マークダウンファイルのみで実装可能

Custom Mode

特定タスクに特化したペルソナ
ツールアクセス制御
ファイル編集制限
YAMLファイルで設定

MCP Server

複雑なロジックを実装
外部APIとの連携
TypeScript/Pythonで実装
複数プロジェクトで再利用可能

3. 統合のメリット

観点	手法単体	統合後
仕様の曖昧さ	仕様が曖昧になりがち	仕様 + コンテキストで明確化
AIの制御	AIが制約を無視する	コンテキストで制御
品質のバラつき	人によって品質がバラバラ	Runbooksで標準化
知識の属人化	知識が属人化する	すべてが再利用可能
スケール性	スケールしない	チーム全体で共有

4. Roo Code と IBM Bob における実装

4.1 完全な機能対応表

項目	Roo Code	IBM Bob	備考
SDD（仕様）	`docs/spec/`	`docs/spec/`	両者共通
CE（方針）	`AGENTS.md`	`AGENTS.md`	両者共通
CE（制約）	`.roo/rules/`	`.bob/rules/`	ディレクトリ名のみ異なる
CE（単一ファイル）	`.roorules`	`.bobrules`	両者共通の形式
Runbooks（Skills）	`.roo/skills/`	`.bob/skills/`	Agent Skills（業界標準）
Runbooks（Commands）	`.roo/commands/`	`.bob/commands/`	スラッシュコマンド
Runbooks（Custom Mode）	✅ あり	✅ あり	両者とも対応
Runbooks（MCP Server）	✅ あり	✅ あり	両者とも対応（MCP標準）
Ignoreファイル	`.rooignore`	`.bobignore`	両者共通の形式
Mode	Code / Ask / Architect / Debug / Orchestrator / TestMode	Code / Plan / Ask / Advanced / Orchestrator	名称と役割が異なる
Marketplace	✅ Roo Code Marketplace	❌ なし	Roo Code独自

4.2 主要な違い

Mode の違い

Roo Code:

Architect: 設計特化（markdown編集のみ）
TestMode: テスト特化

IBM Bob:

Plan: 計画特化（markdown編集のみ）
Advanced: 全ツールアクセス

独自機能

Roo Code:

Marketplace（コミュニティモード共有）
グローバルコマンド（~/.roo/commands/）

IBM Bob:

より詳細なツールアクセス制御
ファイル編集制限（fileRegex）

5. 実装ガイド

5.1 ディレクトリ構造

Roo Code

project/
├── docs/
│   └── spec/                    # SDD: 仕様の正本
│       ├── VISION.md
│       ├── USE_CASES.md
│       └── NON_FUNCTIONAL.md
├── AGENTS.md                    # CE: 方針
├── .rooignore                   # アクセス制御
├── .roo/
│   ├── rules/                   # CE: 制約
│   │   ├── security.md
│   │   └── coding-style.md
│   ├── skills/                  # Runbooks: Agent Skills
│   │   └── deploy-workflow/
│   │       ├── SKILL.md
│   │       └── references/
│   └── commands/                # Runbooks: Commands
│       └── deploy.md
└── .roo-custom-modes.yaml       # Runbooks: Custom Mode

IBM Bob

project/
├── docs/
│   └── spec/                    # SDD: 仕様の正本
│       ├── VISION.md
│       ├── USE_CASES.md
│       └── NON_FUNCTIONAL.md
├── AGENTS.md                    # CE: 方針
├── .bobignore                   # アクセス制御
├── .bobmodes                    # Runbooks: Custom Mode
└── .bob/
    ├── rules/                   # CE: 制約
    │   ├── security.md
    │   └── bob_skills.md        # Agent Skills登録
    ├── skills/                  # Runbooks: Agent Skills
    │   └── deploy-workflow/
    │       ├── SKILL.md
    │       └── references/
    └── commands/                # Runbooks: Commands
        └── deploy.md

5.2 SDD: 仕様の正本

保存場所: docs/spec/

VISION.md の例:

# プロジェクトビジョン

## 目的
セキュアで保守性の高いWebアプリケーションを提供する

## 対象ユーザー
- エンタープライズ企業の開発チーム
- 月間アクティブユーザー: 10,000人規模

## 成功指標
- セキュリティインシデント: 0件
- 平均応答時間: 200ms以下
- 可用性: 99.9%以上

USE_CASES.md の例:

# ユースケース

## UC-001: ユーザー登録
**アクター**: 新規ユーザー
**前提条件**: メールアドレスを持っている
**正常フロー**:
1. ユーザーがメールアドレスを入力
2. システムが確認メールを送信
3. ユーザーがメール内のリンクをクリック
4. システムがアカウントを有効化

**例外フロー**:
- メールアドレスが既に登録済み → エラーメッセージ表示
- 確認メールが24時間以内に確認されない → リンク無効化

5.3 Context Engineering: 方針

AGENTS.md の例:

# プロジェクト方針

## 目的
本プロジェクトは、セキュアで保守性の高いWebアプリケーションを提供します。

## 優先順位
1. セキュリティ
2. 保守性
3. パフォーマンス
4. 開発速度

## 基本姿勢
- 破壊的変更は必ず事前承認を得る
- 仕様の正本は `docs/spec/` を参照
- テストなしでのコミットは禁止
- セキュリティ脆弱性は最優先で対応

## 仕様参照
- ビジョン: `docs/spec/VISION.md`
- ユースケース: `docs/spec/USE_CASES.md`
- 非機能要件: `docs/spec/NON_FUNCTIONAL.md`

5.4 Context Engineering: 制約

Roo Code: `.roo/rules/security.md`

IBM Bob: `.bob/rules/security.md`

# セキュリティルール

## 禁止事項
- APIキーやパスワードをコードに直接記述しない
- 環境変数は `.env` ファイルで管理
- `.env` ファイルは `.gitignore` に追加必須

## 必須事項
- 外部APIへのリクエストは必ずHTTPSを使用
- ユーザー入力は必ずバリデーション
- SQLインジェクション対策を実施
- XSS対策を実施

## 推奨事項
- 認証にはOAuth 2.0またはJWTを使用
- パスワードはbcryptでハッシュ化

5.5 Runbooks: Agent Skills

SKILL.md の例

Roo Code: .roo/skills/deploy-workflow/SKILL.md
IBM Bob: .bob/skills/deploy-workflow/SKILL.md

# デプロイワークフロー

## 概要
本番環境へのデプロイを安全に実行します。

## 前提条件
- テストが全て成功していること
- PRがマージされていること
- デプロイ権限があること

## 実行フロー

### 1. 事前確認（`references/step1-pre-check.md`）
- テスト結果の確認
- PRステータスの確認
- デプロイ対象ブランチの確認

### 2. ステージングデプロイ（`references/step2-staging.md`）
- ステージング環境へのデプロイ
- 動作確認
- ログ確認

### 3. 本番デプロイ（`references/step3-production.md`）
- 本番環境へのデプロイ
- ヘルスチェック
- ロールバック準備

### 4. 事後確認（`references/step4-post-check.md`）
- メトリクス確認
- エラーログ確認
- 通知送信

## エラーハンドリング
各ステップでエラーが発生した場合：
1. エラー内容を分析
2. 自動修正を試行
3. 修正できない場合はロールバック
4. ユーザーに報告

IBM Bob での Agent Skills 登録

.bob/rules/bob_skills.md:

====

AVAILABLE_SKILLS

<available_skills>
<skill>
<name>deploy-workflow</name>
<description>本番環境へのデプロイを安全に実行します。ステージング確認、本番デプロイ、事後確認を順次実行します。</description>
<location>/path/to/project/.bob/skills/deploy-workflow</location>
</skill>
</available_skills>

<mandatory_skill_check>
REQUIRED PRECONDITION

Before producing ANY user-facing response, you MUST:
- Evaluate the user's request against ALL available skills
- If applicable, execute the selected skill according to its SKILL.md
</mandatory_skill_check>

5.6 Runbooks: Slash Commands

Roo Code: `.roo/commands/deploy.md`

IBM Bob: `.bob/commands/deploy.md`

---
description: 本番環境へデプロイ
argument-hint: <environment>
---

環境「$1」へのデプロイを実行してください。
デプロイ前のチェックリストを確認し、安全にデプロイを進めてください。

使用方法:

/deploy production

5.7 Runbooks: Custom Mode

Roo Code: `.roo-custom-modes.yaml`

customModes:
  - slug: deploy-mode
    name: 🚀 Deploy
    roleDefinition: You are a deployment specialist focused on safe production releases.
    whenToUse: Use this mode for production deployments.
    customInstructions: |
      - Always verify tests pass before deployment
      - Follow the deployment checklist in .roo/skills/deploy-workflow/
      - Document all changes in CHANGELOG.md
      - Never skip staging environment
    groups:
      - read
      - - edit
        - fileRegex: \.(yml|yaml|tf|sh)$
          description: Deployment config files only
      - command

IBM Bob: `.bobmodes`

customModes:
  - slug: deploy-mode
    name: 🚀 Deploy
    roleDefinition: You are a deployment specialist focused on safe production releases.
    whenToUse: Use this mode for production deployments.
    customInstructions: |
      - Always verify tests pass before deployment
      - Follow the deployment checklist in .bob/skills/deploy-workflow/
      - Document all changes in CHANGELOG.md
      - Never skip staging environment
    groups:
      - read
      - - edit
        - fileRegex: \.(yml|yaml|tf|sh)$
          description: Deployment config files only
      - command

5.8 Runbooks: MCP Server

MCPサーバーは、複雑なロジックや外部API連携が必要な場合に使用します。

向いているケース:

複雑なビジネスロジックを実装
外部APIとの連携（GitHub、Slack、AWS等）
データベース操作
複数プロジェクトで再利用したい処理

実装言語:

TypeScript（推奨）
Python

基本構造:

// src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  {
    name: "deploy-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// ツールの定義
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "deploy_to_production",
      description: "本番環境へのデプロイを実行",
      inputSchema: {
        type: "object",
        properties: {
          environment: {
            type: "string",
            description: "デプロイ先環境",
          },
          version: {
            type: "string",
            description: "デプロイするバージョン",
          },
        },
        required: ["environment", "version"],
      },
    },
  ],
}));

// ツールの実装
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "deploy_to_production") {
    const { environment, version } = request.params.arguments;
    
    // デプロイロジックを実装
    const result = await deployToProduction(environment, version);
    
    return {
      content: [
        {
          type: "text",
          text: `デプロイ完了: ${environment} (${version})`,
        },
      ],
    };
  }
  
  throw new Error(`Unknown tool: ${request.params.name}`);
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main();

設定ファイル（Roo Code / IBM Bob共通）:

MCPサーバーの設定は、各製品の設定ファイルに記載します。

Roo Code: VS Codeの設定
IBM Bob: VS Codeの設定

{
  "mcpServers": {
    "deploy-server": {
      "command": "node",
      "args": ["/path/to/deploy-server/build/index.js"]
    }
  }
}

使用方法:

MCPサーバーを起動すると、AIエージェントが自動的にツールを認識し、必要に応じて呼び出します。

ユーザー: 本番環境にバージョン1.2.3をデプロイして

AI: deploy_to_production ツールを使用します
    - environment: production
    - version: 1.2.3
    
    デプロイ完了: production (1.2.3)

Agent Skills vs MCP Server の使い分け:

観点	Agent Skills	MCP Server
実装言語	マークダウン	TypeScript/Python
複雑度	シンプルな手順	複雑なロジック
外部連携	難しい	容易
再利用性	プロジェクト内	複数プロジェクト
学習コスト	低い	高い
保守性	高い（マークダウン）	中（コード）

推奨:

まずAgent Skillsで実装
複雑になったらMCPサーバーに移行

6. 統合アーキテクチャの全体像

7. よくある失敗と回避原則

7.1 失敗例

失敗1: 仕様にコーディング規約を書く

# ❌ 悪い例（docs/spec/VISION.md）
## 実装方針
- インデントは4スペース
- 変数名はcamelCase
- 関数名はPascalCase

問題: 仕様（WHAT）と実装方法（HOW）が混在

正しい場所: .roo/rules/coding-style.md または .bob/rules/coding-style.md

失敗2: Runbooksにビジネスロジックを書く

# ❌ 悪い例（.roo/skills/user-registration/SKILL.md）
## ユーザー登録の仕様
- メールアドレスは必須
- パスワードは8文字以上
- 確認メールを送信

問題: 仕様（WHAT）とワークフロー（WHO）が混在

正しい場所: docs/spec/USE_CASES.md

失敗3: rulesにすべてを書こうとする

# ❌ 悪い例（.roo/rules/everything.md）
# すべてのルール（500行）
- セキュリティルール
- コーディング規約
- デプロイ手順
- テスト手順
- ...

問題: 制約（HOW）とワークフロー（WHO）が混在、長すぎて読めない

正しい分割:

.roo/rules/security.md（制約）
.roo/rules/coding-style.md（制約）
.roo/skills/deploy-workflow/（ワークフロー）
.roo/skills/test-workflow/（ワークフロー）

7.2 回避原則

原則1: What / How / Who を分離する

区分	内容	場所
WHAT	何を作るか	`docs/spec/`
HOW	どう作るか	`AGENTS.md` + `rules/`
WHO	誰でも再現可能	`skills/` + `commands/` + Custom Mode + MCP Server

原則2: 短く明確に書く

AGENTS.md: 1ページ以内
rules/: 1ファイル10〜20行
SKILL.md: 必要に応じて長くてもOK（referencesで分割）

原則3: 段階的に強化する

まず最小限のAGENTS.mdとrulesから始める
必要に応じてrulesを追加
繰り返し作業が発生したらRunbooksを作成

8. 実践例：新規プロジェクトの立ち上げ

ステップ1: SDD（仕様の正本）を作成

mkdir -p docs/spec

docs/spec/VISION.mdを作成し、プロジェクトの目的を明確化。

ステップ2: Context Engineering（方針）を定義

AGENTS.mdを作成し、優先順位と基本姿勢を定義。

ステップ3: Context Engineering（制約）を追加

# Roo Code
mkdir -p .roo/rules

# IBM Bob
mkdir -p .bob/rules

最小限のセキュリティルールを追加。

ステップ4: 開発開始

AIエージェントに指示を出し、コードを生成。

ステップ5: 繰り返し作業を発見したらRunbooksを作成

デプロイ作業が繰り返し発生したら、Agent Skillsを作成。

9. まとめ

9.1 3つの手法の役割

SDD: 何を作るか（WHAT）を定義
Context Engineering: どう作るか（HOW）の制約を伝える
Runbooks: 誰でも再現可能（WHO）にする

9.2 Roo Code と IBM Bob の共通点

基本的な設計思想は同じ
AGENTS.md、rules、Agent Skills、Commandsをサポート
Custom Modeで特化したペルソナを作成可能
MCP Serverで複雑なロジックを実装可能

9.3 Roo Code と IBM Bob の違い

ディレクトリ名（.roo/ vs .bob/）
Modeの名称と役割
Roo CodeはMarketplace、IBM BobはAdvanced Mode

9.4 統合の本質

統合とは、
すべてを一か所に集めることではなく、責務を分離した上で正しく接続することである。

参考資料

参考記事

AI時代の開発フレームワーク：Spec-Driven Development × Context Engineering × Runbooks 統合実践編