MUSUHI実践ガイド - Agentic AIで実現する仕様駆動開発の実践

第1章 はじめに

1.1 本ガイドの目的

本ガイドは、MUSUHI（むすひ［産霊］）の20種の専門AIエージェントを実践的に活用するためのリファレンスマニュアルです。開発経験者を対象に、仕様駆動開発（SDD）のワークフロー全体における各エージェントの使いどころと連携方法を解説します。

対象読者:

• ソフトウェア開発の基本的な知識を持つ実務者
• MUSUHIを導入して実プロジェクトで活用したい開発者
• 仕様駆動開発のワークフローを理解し、効率化を図りたいチーム

本ガイドで学べること:

• 開発フェーズごとの最適なエージェント選択
• エージェント間の連携パターン
• 実践的なユースケースと使用例
• プロジェクトメモリ（Steering System）の効果的な活用

1.2 MUSUHIとは

MUSUHIは、仕様駆動開発（SDD）専用のAgentic AIシステムです。Claude Code、GitHub Copilot、Cursor、Windsurf IDE、AI CLI（Gemini、Codex、Qwen）をサポートし、要件分析からデプロイ・保守まで、ソフトウェア開発ライフサイクル全体を20個の専門AIエージェントで支援します。

Agentic AIとは

Agentic AI（エージェンティックAI）は、明確な目標や役割を持ち、自律的にタスクを実行するAIシステムです。MUSUHIでは、各エージェントが専門領域を持ち、構造化された対話を通じて成果物を生成します。複数のエージェントが連携することで、複雑な開発タスクを段階的に完成させます。

MUSUHIの主な特徴

• 🎯 20個の専門エージェント - 各エージェントが明確な役割と専門性を持つAgentic AI
• 🧭 プロジェクトメモリシステム - 全エージェントが共有する「プロジェクトの記憶」で一貫性を保つ
• 🔄 ステアリング自動更新 - エージェントが作業完了後に自動的にプロジェクトメモリを更新
• 🤝 エージェント間連携 - Orchestratorによる複数エージェントの調整と協働
• 📝 EARS形式サポート - 検証可能な要件定義（Easy Approach to Requirements Syntax）
• 📐 SDDワークフローテンプレート - 要件、設計、タスク、調査の包括的なテンプレート
• 🎭 自律的なタスク実行 - 各エージェントが構造化された対話で成果物を生成

1.3 仕様駆動開発（SDD）とは

仕様駆動開発は、詳細な仕様書が開発プロセス全体をガイドする体系的アプローチです。

8段階のワークフロー:

調査 → 要件定義 → 設計 → タスク化 → 実装 → テスト → デプロイ → 監視

MUSUHIがサポートする主要プロセス:

1. 明確な要件定義 - Requirements Analystが包括的な仕様書を作成
2. 堅牢なアーキテクチャ設計 - System ArchitectとAPI Designerがスケーラブルなソリューションを計画
3. 品質の高い実装 - Software DeveloperがSOLID原則とベストプラクティスにしたがって開発
4. セキュリティとパフォーマンスの保証 - Security AuditorとPerformance Optimizerが品質を検証
5. 確実なデプロイ - DevOps EngineerとCloud Architectがインフラを管理
6. 継続的改善 - Orchestratorが全エージェントを調整して卓越性を維持

1.4 最初の一歩

最初に MUSUHI をプロジェクトディレクトリにインストールします。

# プロジェクトディレクトリで実行
npx musuhi

初回実行時、インタラクティブに設定を行います。

? Which AI coding tool are you using?
  ❯ GitHub Copilot (.github/copilot-instructions.md)
    Claude Code (.claudeignore, .claude/)
    Cursor (.cursorrules)
    Windsurf IDE (.windsurfrules)
    Gemini CLI (.gemini/)
    Codex CLI (.codex/)
    Qwen Code (.qwenrules)

次に、MUSUHIを使って最初のアプリケーションを作成してみましょう。Orchestratorに依頼すれば、要件定義から実装まで自動的に進めてくれます。GitHub Copilot から

例: ToDoアプリを作成する

@orchestrator

シンプルなToDoアプリを作成してください。
要件:
- タスクの追加、編集、削除
- 完了/未完了のステータス管理
- 技術スタック: TypeScript + React + Node.js + SQLite

要件定義から実装、テストまで完成させてください。

Orchestratorが以下を自動実行します。

1. Requirements Analyst → EARS形式の要件定義書を作成
2. System Architect → アーキテクチャ設計（Clean Architecture）
3. API Designer → REST API仕様（OpenAPI）
4. Database Schema Designer → データベース設計（ER図、DDL）
5. Software Developer → フロントエンド・バックエンド実装
6. Test Engineer → ユニット・統合・E2Eテスト作成
7. Code Reviewer → コード品質チェック
8. Technical Writer → README、APIドキュメント作成

成果物: 完全に動作するToDoアプリケーション（ソースコード、テスト、ドキュメント一式）

より細かく制御したい場合

個別エージェントを順次呼び出すことも可能です。

# 1. 要件定義
@requirements-analyst ToDoアプリの要件を定義

# 2. アーキテクチャ設計
@system-architect requirements.md に基づいてアーキテクチャを設計

# ...以下、必要なエージェントを順次実行

第2章 プロジェクトメモリ（Steering System）

2.1 プロジェクトメモリとは

プロジェクトメモリは、全エージェントが共有するプロジェクトの「記憶」です。steering/ ディレクトリに格納された3つのコアファイルで構成され、各エージェントが作業完了後に自動的に更新します（v0.4.9以降）。

3つのコアファイル:

ファイル	内容	自動更新するエージェント
structure.md	アーキテクチャパターン、ディレクトリ構成、命名規則	System Architect、Software Developer
tech.md	技術スタック、フレームワーク、開発ツール、技術的制約	API Designer、Database Designer、DevOps Engineer、Security Auditor
product.md	ビジネスコンテキスト、製品目的、対象ユーザー、コア機能	Requirements Analyst、UI/UX Designer、Project Manager

重要: プロジェクトメモリは事前の初期化は不要です。各エージェントが実行されると、自動的に該当するステアリングファイルを作成・更新します。

2.2 プロジェクトメモリの利点

✅ 一貫したアーキテクチャ - すべてのエージェントが同じパターンに従う
✅ 技術スタックの認識 - エージェントがプロジェクトのフレームワークとツールを使用
✅ ビジネスコンテキスト - 製品目標に沿った開発
✅ コンテキストスイッチの削減 - セッション間でプロジェクト知識が永続化
✅ チームの整合性 - プロジェクト構造と決定事項の共通理解

2.3 プロジェクトメモリの自動更新

エージェント実行後の自動更新（v0.4.9以降）

各エージェントは作業完了後、関連するステアリングファイルを自動的に更新します。ユーザーが手動で初期化や更新する必要はありません。

例: Requirements Analystを実行

@requirements-analyst ToDoアプリの要件を定義

# Requirements Analystが作業完了後、自動的に以下を実行:
# - steering/product.md を作成/更新（機能要件、対象ユーザー等）
# - steering/product.ja.md を作成/更新（日本語版）

例: System Architectを実行

@system-architect requirements.md に基づいてアーキテクチャを設計

# System Architectが作業完了後、自動的に以下を実行:
# - steering/structure.md を作成/更新（アーキテクチャパターン、ディレクトリ構成）
# - steering/structure.ja.md を作成/更新（日本語版）

例: API Designerを実行

@api-designer REST API仕様を作成

# API Designerが作業完了後、自動的に以下を実行:
# - steering/tech.md を作成/更新（APIスタック、フレームワーク）
# - steering/tech.ja.md を作成/更新（日本語版）

プロジェクトメモリの確認と手動同期

通常は不要ですが、プロジェクトメモリの内容を確認したい場合や、手動で同期したい場合は@steeringを使用できます。

レビュー（Review）

@steering

# 現在のプロジェクトメモリを表示

手動同期（Sync）

@steering

# コードベースとステアリングファイルの乖離を検出し、手動で更新

2.4 エージェント別の更新内容

各エージェントが自動的に更新するステアリングファイルの詳細：

エージェント	更新ファイル	更新内容
Requirements Analyst	product.md	機能要件、対象ユーザー、ビジネス目的
System Architect	structure.md	アーキテクチャパターン、レイヤー構成、モジュール設計
API Designer	tech.md	APIフレームワーク、エンドポイント構成、認証方式
Database Schema Designer	tech.md	データベースエンジン、ORM、スキーマ設計パターン
Cloud Architect	tech.md + structure.md	クラウドサービス、IaC、インフラ構成
UI/UX Designer	product.md	デザインシステム、UIコンポーネント、ユーザーペルソナ
Project Manager	product.md	プロジェクトタイムライン、マイルストーン、優先順位
Software Developer	structure.md	コーディング規約、ディレクトリ構成、命名規則
DevOps Engineer	tech.md	CI/CDツール、デプロイ戦略、監視ツール
Test Engineer	tech.md	テストフレームワーク、テスト戦略
Security Auditor	tech.md	セキュリティツール、コンプライアンス要件
Database Administrator	tech.md	DB構成、バックアップ戦略、パフォーマンスチューニング
AI/ML Engineer	tech.md	MLフレームワーク、モデル管理、MLOpsパイプライン
Quality Assurance	tech.md	QAプロセス、品質メトリクス

自動更新のメリット:

• ✅ 常に最新 - プロジェクトメモリが実際の作業と同期
• ✅ 手動更新不要 - エージェントが自動的にステアリングを更新
• ✅ 一貫性の維持 - 後続のエージェントが最新のプロジェクト状態を把握
• ✅ 監査証跡 - 各エージェントがプロジェクトメモリに追加した内容を確認可能

第3章 ワークフロー別エージェント活用

本章では、開発フェーズごとに使用するエージェントを整理し、実践的な使い方を解説します。

MUSUHIの各エージェントはAgentic AIとして設計されており、以下の特徴を持ちます。

• 明確な役割と専門性: 各エージェントは特定の開発フェーズに特化
• 構造化された対話: 5段階の質問フローで必要な情報を段階的に収集
• 自律的な成果物生成: 収集した情報をもとに、仕様書やコード、設計図などを自動生成
• プロジェクトメモリの活用: 全エージェントがsteeringファイルを参照し、一貫性を保つ
• 自動更新: 作業完了後、自動的にプロジェクトメモリを更新（v0.4.9以降）

3.1 フェーズ0: プロジェクトメモリ管理（オプション）

🧭 Steering Agent（ステアリングエージェント）

役割: プロジェクトメモリの確認と手動同期

重要: 通常は使用不要です。各エージェントが自動的にプロジェクトメモリを更新するため、Steering Agentを手動で実行する必要はありません。

いつ使うか（オプション）:

• プロジェクトメモリの内容を確認したいとき（Reviewモード）
• コードベースとステアリングファイルの乖離をチェックしたいとき（Syncモード）
• 既存プロジェクトにMUSUHIを導入し、はじめてステアリングファイルを生成するとき（Bootstrapモード）

3つのモード:

1. Bootstrap（初回生成）: コードベースを分析してsteeringファイルを作成
2. Sync（更新・同期）: 既存steeringとコードベースの乖離を検出・修正
3. Review（レビュー）: 現在のsteeringコンテキストを確認

使用例:

# 既存プロジェクトへの初回導入時（Bootstrapモード）
@steering

# プロジェクトメモリの確認（Reviewモード）
@steering

# コードベースとの乖離チェック（Syncモード）
@steering

注意: @steeringを実行すると、どのモードで実行するか対話形式で質問されます。

参照ファイル:

• steering/structure.md - 各エージェントが自動更新
• steering/tech.md - 各エージェントが自動更新
• steering/product.md - 各エージェントが自動更新

3.2 フェーズ1: 調査・要件定義

📋 Requirements Analyst（要件アナリスト）

役割: 要件分析、ユーザーストーリー作成、仕様定義、EARS形式の受入基準

いつ使う:

• 新機能開発の最初のステップ
• ステークホルダーからの要望を仕様化するとき
• 曖昧な要求を明確化するとき

専門領域:

• 機能要件・非機能要件の定義
• ユーザーストーリー作成
• EARS形式の受入基準
• MoSCoW優先順位付け

使用例:

@requirements-analyst タスク管理機能の要件を定義したい

対話フロー（5段階）:

【質問 1/5】この機能の目的は何ですか？
👤 ユーザー: チームメンバーがタスクを作成・管理できるようにしたい

【質問 2/5】対象ユーザーは誰ですか？
👤 ユーザー: 開発チームのメンバー（5-20人規模）

【質問 3/5】主要な機能を教えてください
👤 ユーザー: タスク作成、編集、削除、ステータス変更、担当者割り当て

【質問 4/5】非機能要件はありますか？（パフォーマンス、セキュリティ等）
👤 ユーザー: 100件以上のタスクでも快適に動作、ロールベースのアクセス制御

【質問 5/5】受入基準で特に重視する点は？
👤 ユーザー: すべての操作が1秒以内に完了すること

成果物:

docs/requirements/srs/
├── task-management-srs-v1.0.md        # 英語版
└── task-management-srs-v1.0.ja.md     # 日本語版

ドキュメント内容:

• 機能要件（EARS形式）
• 非機能要件（パフォーマンス、セキュリティ、スケーラビリティ）
• ユーザーストーリー（受入基準付き）
• 要件トレーサビリティマトリックス

EARS形式の例:

## 機能要件

### REQ-001: タスク作成
**WHEN** user clicks "Create Task" button, the Task Management System **SHALL** display task creation form

### REQ-002: タスク検証
**IF** required fields are missing, **THEN** the System **SHALL** display "Required field" error message

### REQ-003: パフォーマンス
**The** Task List **SHALL** render within 1 second for up to 1000 tasks

📋 Project Manager（プロジェクトマネージャー）

役割: プロジェクト計画、スケジューリング、リスク管理、進捗管理

いつ使う:

• プロジェクト立ち上げ時
• タスク分解とスケジュール作成
• リスク評価が必要なとき

専門領域:

• WBS（Work Breakdown Structure）作成
• ガントチャート作成
• リスク管理（リスクレジスタ）
• リソース配分

使用例:

@project-manager requirements-specification.md に基づいてプロジェクト計画を作成

成果物:

• プロジェクト計画書
• WBS
• ガントチャート
• リスクレジスタ

3.3 フェーズ2: アーキテクチャ・設計

🏗️ System Architect（システムアーキテクト）

役割: アーキテクチャ設計、C4モデル図、ADR作成、トレードオフ分析

いつ使う:

• 新規プロジェクトのアーキテクチャ設計
• 既存システムのリアーキテクト
• 技術選定の意思決定

専門領域:

• アーキテクチャパターン（Layered、Hexagonal、Microservices等）
• C4モデル図（Context、Container、Component、Code）
• ADR（Architecture Decision Record）
• 分散システム設計（CAP定理、PACELC）
• セキュリティアーキテクチャ（Zero Trust）

使用例:

@system-architect task-management-srs-v1.0.md に基づいてアーキテクチャを設計

対話フロー:

【質問 1/5】アーキテクチャパターンの優先事項は？
a) シンプルさ（Layered Architecture）
b) テスタビリティ（Hexagonal/Clean Architecture）
c) スケーラビリティ（Microservices）

👤 ユーザー: b

【質問 2/5】技術スタックの制約はありますか？
👤 ユーザー: TypeScript + React + PostgreSQL

...（以下、スケーラビリティ要件、セキュリティ要件等を確認）

成果物:

docs/architecture/
├── architecture-design-task-mgmt-20250114.md      # 英語版
├── architecture-design-task-mgmt-20250114.ja.md   # 日本語版
└── diagrams/
    ├── c4-context.mmd          # C4 Context図
    ├── c4-container.mmd        # C4 Container図
    └── c4-component.mmd        # C4 Component図

C4モデル図の例（Mermaid）:

🔌 API Designer（API設計者）

役割: REST/GraphQL/gRPC API設計、OpenAPI仕様、エンドポイント文書化

いつ使う:

• バックエンドAPIの設計
• フロントエンドとバックエンドの契約定義
• API仕様書作成

専門領域:

• REST API設計（リソース設計、HTTPメソッド）
• OpenAPI 3.0仕様
• GraphQLスキーマ設計
• gRPCサービス定義
• APIバージョニング戦略

使用例:

@api-designer タスク管理APIのREST仕様を作成

成果物:

docs/api/
├── openapi-task-api-v1.0.yaml          # OpenAPI仕様
├── api-design-task-api-v1.0.md         # API設計ドキュメント
└── api-design-task-api-v1.0.ja.md      # 日本語版

OpenAPI仕様の例:

openapi: 3.0.0
info:
  title: Task Management API
  version: 1.0.0

paths:
  /tasks:
    get:
      summary: List tasks
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
    post:
      summary: Create task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'

🗄️ Database Schema Designer（DB設計者）

役割: ER図、正規化、DDL生成、インデックス戦略

いつ使う:

• データベーススキーマ設計
• データモデリング
• パフォーマンス最適化のためのインデックス設計

専門領域:

• ER図作成（Mermaid ERD）
• 正規化（第1～第3正規形、BCNF）
• DDL生成（PostgreSQL、MySQL、SQL Server）
• インデックス戦略
• マイグレーション計画

使用例:

@database-schema-designer api-design-task-api-v1.0.md に基づいてデータベーススキーマを設計

成果物:

docs/database/
├── db-schema-task-mgmt-v1.0.md         # スキーマ設計書
├── db-schema-task-mgmt-v1.0.ja.md      # 日本語版
├── erd-diagram.mmd                     # ER図（Mermaid）
└── migrations/
    └── 001_initial_schema.sql          # DDL

ER図の例（Mermaid）:

🎨 UI/UX Designer（UI/UX設計者）

役割: ユーザーインターフェイス設計、ワイヤーフレーム、デザインシステム

いつ使う:

• UIデザイン作成
• ユーザーフロー設計
• デザインシステム構築

専門領域:

• ワイヤーフレーム、モックアップ
• デザインシステム（Atomic Design）
• アクセシビリティ（WCAG 2.1）
• ユーザビリティテスト計画

使用例:

@ui-ux-designer タスク管理画面のUIを設計

成果物:

• ワイヤーフレーム（Figma、Adobe XD等の形式）
• デザインシステムドキュメント
• ユーザーフロー図
• アクセシビリティチェックリスト

3.4 フェーズ3: 実装

💻 Software Developer（ソフトウェア開発者）

役割: 多言語コード実装、SOLID原則、デザインパターン、クリーンアーキテクチャ

いつ使う:

• コード実装
• リファクタリング
• ベストプラクティスに従った開発

専門領域:

• 言語: TypeScript/JavaScript, Python, Java, C#, Go, Rust等
• Frontend: React, Vue.js, Angular, Svelte
• Backend: Express, NestJS, FastAPI, Django, Spring Boot
• SOLID原則: 単一責任、開放閉鎖、リスコフの置換、インターフェイス分離、依存性逆転
• デザインパターン: Factory, Strategy, Observer, Decorator, Dependency Injection
• TDD: Red-Green-Refactorサイクル

使用例:

@software-developer TypeScriptでタスク作成APIエンドポイントを実装

対話フロー:

【質問 1/5】実装する機能を教えてください
👤 ユーザー: POST /tasks エンドポイント

【質問 2/5】参照する設計ドキュメントはありますか？
👤 ユーザー: docs/api/api-design-task-api-v1.0.md

【質問 3/5】使用する技術スタック
（steeringから自動検出: TypeScript, NestJS, Prisma）

【質問 4/5】テストコードも作成しますか？
👤 ユーザー: はい、ユニットテストをお願いします

【質問 5/5】特別な実装要件は？
👤 ユーザー: バリデーション、エラーハンドリングを含めてください

成果物:

src/
├── tasks/
│   ├── tasks.controller.ts          # Controller
│   ├── tasks.service.ts             # Service (ビジネスロジック)
│   ├── tasks.repository.ts          # Repository (データアクセス)
│   ├── dto/
│   │   ├── create-task.dto.ts       # DTO (Data Transfer Object)
│   │   └── task-response.dto.ts
│   └── tests/
│       ├── tasks.controller.spec.ts # ユニットテスト
│       └── tasks.service.spec.ts

実装例:

// tasks.service.ts
@Injectable()
export class TasksService {
  constructor(private readonly tasksRepository: TasksRepository) {}

  async create(createTaskDto: CreateTaskDto, userId: string): Promise<Task> {
    // バリデーション
    if (!createTaskDto.title || createTaskDto.title.trim().length === 0) {
      throw new BadRequestException('Title is required');
    }

    // ビジネスロジック
    const task = await this.tasksRepository.create({
      ...createTaskDto,
      userId,
      status: TaskStatus.TODO,
      createdAt: new Date(),
    });

    return task;
  }
}

3.5 フェーズ4: テスト・品質保証

🧪 Test Engineer（テストエンジニア）

役割: ユニット、統合、E2Eテストの設計と実装

いつ使う:

• テストコード作成
• テスト戦略策定
• カバレッジ向上

専門領域:

• ユニットテスト: Jest, Vitest, Pytest, JUnit
• 統合テスト: Supertest, Spring Test
• E2Eテスト: Cypress, Playwright, Selenium
• TDD: Red-Green-Refactor
• BDD: Given-When-Then形式

使用例:

@test-engineer task-management-srs-v1.0.md からテストケースを生成

成果物:

tests/
├── unit/
│   ├── tasks.service.spec.ts
│   └── tasks.controller.spec.ts
├── integration/
│   └── tasks.api.spec.ts
└── e2e/
    └── task-management.e2e.spec.ts

EARS要件からテストへのマッピング:

// REQ-001: WHEN user clicks "Create Task", System SHALL display form
describe('Task Creation', () => {
  it('should display task creation form when create button is clicked', () => {
    cy.visit('/tasks');
    cy.get('[data-testid="create-task-btn"]').click();
    cy.get('[data-testid="task-form"]').should('be.visible');
  });
});

// REQ-002: IF required fields missing, THEN show error
it('should show error when required fields are missing', async () => {
  const response = await request(app)
    .post('/tasks')
    .send({ title: '' });

  expect(response.status).toBe(400);
  expect(response.body.message).toContain('Title is required');
});

// REQ-003: System SHALL render within 1 second for 1000 tasks
it('should render task list within 1 second for 1000 tasks', async () => {
  const start = Date.now();
  await page.goto('/tasks');
  const duration = Date.now() - start;

  expect(duration).toBeLessThan(1000);
});

👁️ Code Reviewer（コードレビュアー）

役割: 品質、セキュリティ、SOLID原則、パフォーマンス、ベストプラクティスのレビュー

いつ使う:

• プルリクエスト前のコードレビュー
• コード品質チェック
• リファクタリング提案

専門領域:

• コード品質（可読性、保守性）
• SOLID原則遵守
• セキュリティ脆弱性検出
• パフォーマンス問題検出
• ベストプラクティス確認

使用例:

@code-reviewer src/tasks/ のコードをレビュー

レビュー観点:

• ✅ SOLID原則の遵守
• ✅ エラーハンドリングの適切性
• ✅ セキュリティ（SQL Injection、XSS等）
• ✅ パフォーマンス（N+1問題等）
• ✅ テストカバレッジ

成果物:

reviews/
└── code-review-tasks-module-20250114.md

レビューレポートの例:

## Code Review: Tasks Module

### ✅ Strengths
- SOLID principles well-applied
- Comprehensive error handling
- Good test coverage (85%)

### ⚠️ Issues Found

#### 1. Performance Issue (Medium Priority)
**File**: `tasks.service.ts:45`
**Issue**: N+1 query problem when loading tasks with user data

**Current Code**:
```typescript
const tasks = await this.tasksRepository.findAll();
for (const task of tasks) {
  task.user = await this.usersRepository.findById(task.userId);
}

Recommendation:

const tasks = await this.tasksRepository.findAllWithUsers();

2. Security Issue (High Priority)

File: tasks.controller.ts:23
Issue: Missing input sanitization for title field

### 🔍 Quality Assurance（品質保証）

**役割:** QA戦略、テスト計画、品質メトリクス

**いつ使う:**
- QA戦略策定
- テスト計画作成
- リリース品質チェック

**使用例:**

@quality-assurance タスク管理機能のQA計画を作成

### 🐛 Bug Hunter（バグハンター）

**役割:** バグ調査、根本原因分析、体系的デバッグ

**いつ使う:**
- バグ発生時の原因究明
- 断続的な問題の調査
- パフォーマンス問題のデバッグ

**使用例:**

@bug-hunter タスク作成時に断続的に発生する500エラーを調査

**成果物:**
- バグレポート（根本原因、再現手順、修正案）

---

## 3.6 フェーズ5: セキュリティ・パフォーマンス最適化

### 🔐 Security Auditor（セキュリティ監査者）

**役割:** OWASP Top 10チェック、認証認可レビュー、脆弱性検出

**いつ使う:**
- セキュリティ監査
- 認証・認可実装のレビュー
- 本番リリース前のセキュリティチェック

**専門領域:**
- OWASP Top 10（SQL Injection、XSS、CSRF等）
- 認証・認可（OAuth 2.0、JWT）
- 暗号化（TLS、データ暗号化）
- セキュアコーディング

**使用例:**

@security-auditor 認証・認可実装をセキュリティ監査

**成果物:**

security/
├── security-audit-report-20250114.md # 監査レポート
└── remediation-plan.md # 修正計画

**監査レポートの例:**
```markdown
## Security Audit Report

### 🔴 Critical Issues
1. **SQL Injection Vulnerability**
   - Location: `tasks.repository.ts:67`
   - Issue: Raw SQL query with unsanitized user input
   - Remediation: Use parameterized queries

### 🟡 Medium Issues
2. **Weak Password Policy**
   - Location: `auth.service.ts:34`
   - Issue: Minimum password length is 6 characters
   - Recommendation: Increase to 12 characters

### ✅ Passed Checks
- HTTPS enforced
- JWT tokens properly signed
- CSRF protection enabled

⚡ Performance Optimizer（パフォーマンス最適化）

役割: パフォーマンス分析、ボトルネック検出、最適化戦略

いつ使う:

• パフォーマンス問題の調査
• 最適化施策の実施
• ベンチマーク実施

専門領域:

• プロファイリング
• データベースクエリ最適化
• キャッシング戦略
• フロントエンドパフォーマンス（Core Web Vitals）

使用例:

@performance-optimizer タスク一覧表示のパフォーマンスを最適化

成果物:

performance/
├── performance-analysis-20250114.md       # 分析レポート
├── optimization-plan.md                   # 最適化計画
└── benchmarks/
    └── before-after-comparison.md         # ベンチマーク結果

3.7 フェーズ6: インフラ・デプロイ

☁️ Cloud Architect（クラウドアーキテクト）

役割: Azure/AWS/GCPアーキテクチャ、IaC（Terraform/Bicep）、コスト最適化

いつ使う:

• クラウドインフラ設計
• IaCコード作成
• コスト最適化

専門領域:

• AWS/Azure/GCP設計
• Infrastructure as Code（Terraform、Bicep、CloudFormation）
• Kubernetes、ECS、AKS
• コスト最適化戦略

使用例:

@cloud-architect AWSでタスク管理アプリのインフラを設計

成果物:

infrastructure/
├── architecture-diagram.mmd               # アーキテクチャ図
├── terraform/
│   ├── main.tf                            # Terraform設定
│   ├── variables.tf
│   └── outputs.tf
└── docs/
    └── cloud-architecture-aws-20250114.md

Terraformの例:

# main.tf
resource "aws_ecs_cluster" "task_mgmt" {
  name = "task-management-cluster"
}

resource "aws_ecs_service" "task_api" {
  name            = "task-api-service"
  cluster         = aws_ecs_cluster.task_mgmt.id
  task_definition = aws_ecs_task_definition.task_api.arn
  desired_count   = 2
}

resource "aws_db_instance" "postgres" {
  engine               = "postgres"
  instance_class       = "db.t3.micro"
  allocated_storage    = 20
  db_name              = "taskmgmt"
}

🚀 DevOps Engineer（DevOpsエンジニア）

役割: CI/CDパイプライン、Docker/Kubernetesデプロイ、監視設定

いつ使う:

• CI/CDパイプライン構築
• コンテナー化
• デプロイ自動化

専門領域:

• CI/CD（GitHub Actions、GitLab CI、Jenkins）
• Docker、Kubernetes
• インフラ自動化
• 監視・ロギング（Prometheus、Grafana、ELK）

使用例:

@devops-engineer GitHub ActionsでCI/CDパイプラインを構築

成果物:

.github/
└── workflows/
    ├── ci.yml                             # CI パイプライン
    └── cd.yml                             # CD パイプライン

docker/
├── Dockerfile
└── docker-compose.yml

k8s/
├── deployment.yaml
├── service.yaml
└── ingress.yaml

GitHub Actions CI/CDの例:

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run lint
      - run: npm run test
      - run: npm run build

🗃️ Database Administrator（データベース管理者）

役割: データベース運用、パフォーマンスチューニング、バックアップ/リカバリ

いつ使う:

• DB運用設計
• パフォーマンスチューニング
• 高可用性設計

使用例:

@database-administrator PostgreSQLのパフォーマンスチューニングとバックアップ戦略を設計

3.8 フェーズ7: ドキュメント・特殊領域

📚 Technical Writer（テクニカルライター）

役割: 技術文書、APIドキュメント、ユーザーガイド、README作成

いつ使う:

• APIドキュメント作成
• ユーザーガイド作成
• README作成

使用例:

@technical-writer OpenAPI仕様に基づいてAPIドキュメントを作成

成果物:

• APIドキュメント
• ユーザーガイド
• README.md
• 運用マニュアル

🤖 AI/ML Engineer（AI/MLエンジニア）

役割: 機械学習モデル開発、トレーニング、評価、MLOps

いつ使う:

• ML機能の実装
• モデル開発・評価
• MLOpsパイプライン構築

使用例:

@ai-ml-engineer タスク優先度予測モデルを開発

3.9 フェーズ8: オーケストレーション

🎭 Orchestrator（統括管理者）

役割: 複数エージェントの管理・調整、タスク分解、結果統合

OrchestratorはMUSUHIのAgentic AIシステムの中核として機能します。ユーザーの要求を分析し、最適なエージェントを選択、実行順序を調整、各エージェントの成果物を統合します。いわば「エージェントを管理するエージェント」として、複雑なタスクを自律的に完遂します。

いつ使う:

• 複雑な複数フェーズにまたがるタスク
• どのエージェントを使うか分からないとき
• エージェント間の連携が必要なとき

専門領域:

• エージェント選択とワークフロー調整
• タスク分解と依存関係管理
• 結果統合と品質保証
• マルチエージェント協働の制御

使用例:

@orchestrator ユーザー認証機能を要件定義から実装まで完成させてください

実行フロー:

Orchestrator が自動的に以下を実行:
1. Requirements Analyst → 要件定義
2. System Architect → アーキテクチャ設計
3. API Designer → API設計
4. Database Schema Designer → DB設計
5. Software Developer → 実装
6. Test Engineer → テスト作成
7. Security Auditor → セキュリティ監査
8. 結果を統合して報告

言語選択:
初回起動時に、コンソール出力の言語（英語または日本語）を選択できます。

🎭 Orchestrator AI

Welcome! / ようこそ!

Which language would you like to use for console output?
コンソール出力にどちらの言語を使用しますか？

Please select / 選択してください:
a) English
b) 日本語 (Japanese)

第4章 実践シナリオ

4.1 基本シナリオ: タスク管理Web APIの開発（全フェーズ）

新規プロジェクトとして「タスク管理Web API」を、要件定義から実装・デプロイまで完成させるシナリオです。

ステップ1: プロジェクトメモリの初期化

@steering Web APIの開発

対話:

【質問 1/5】プロジェクトのルートディレクトリはどこですか？
👤 ユーザー: .

【質問 2/5】主要な技術スタック（既に使用中のもの）を確認します。
分析結果: (新規プロジェクトのため空)
使用予定の技術スタックを教えてください。

👤 ユーザー: TypeScript, NestJS, Prisma, PostgreSQL

【質問 3/5】プロジェクトの目的・ビジョンを教えてください
👤 ユーザー: 中小企業向けのシンプルなタスク管理システム

【質問 4/5】対象ユーザー・ドメイン
👤 ユーザー: 5-20人規模の開発チーム

【質問 5/5】追加の重要情報
👤 ユーザー: RESTful API、JWT認証、ロールベースアクセス制御

成果物:

• steering/structure.md - アーキテクチャパターン（後で更新）
• steering/tech.md - TypeScript, NestJS, Prisma, PostgreSQL
• steering/product.md - タスク管理システム、対象ユーザー

ステップ2: 要件定義

@requirements-analyst タスク管理APIの要件を定義

成果物:

docs/requirements/srs/task-management-api-srs-v1.0.md

主要な要件（EARS形式）:

### REQ-001: タスク作成
WHEN user sends POST /tasks with valid data, the API SHALL create task and return 201 Created

### REQ-002: タスク一覧取得
WHEN user sends GET /tasks, the API SHALL return all tasks within 500ms for up to 1000 tasks

### REQ-003: 認証
The API SHALL require valid JWT token for all endpoints except /auth/login

### REQ-004: 権限チェック
IF user is not task owner, THEN the API SHALL return 403 Forbidden for PUT/DELETE operations

ステップ3: アーキテクチャ設計

@system-architect task-management-api-srs-v1.0.md に基づいてアーキテクチャを設計

成果物:

docs/architecture/architecture-design-task-api-20250114.md

選択されたパターン:

• Clean Architecture（Hexagonal Architecture）
• レイヤー: Presentation → Application → Domain → Infrastructure

C4 Container図:

ステップ4: API設計

@api-designer task-management-api-srs-v1.0.md に基づいてREST APIを設計

成果物:

docs/api/openapi-task-api-v1.0.yaml
docs/api/api-design-task-api-v1.0.md

主要エンドポイント:

POST   /auth/login          # ログイン
POST   /auth/register       # ユーザー登録

GET    /tasks               # タスク一覧
POST   /tasks               # タスク作成
GET    /tasks/:id           # タスク詳細
PUT    /tasks/:id           # タスク更新
DELETE /tasks/:id           # タスク削除
PATCH  /tasks/:id/status    # ステータス変更

ステップ5: データベース設計

@database-schema-designer api-design-task-api-v1.0.md に基づいてデータベーススキーマを設計

成果物:

docs/database/db-schema-task-api-v1.0.md
docs/database/migrations/001_initial_schema.sql

スキーマ:

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  name VARCHAR(100) NOT NULL,
  role VARCHAR(50) DEFAULT 'member',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE tasks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  title VARCHAR(200) NOT NULL,
  description TEXT,
  status VARCHAR(50) DEFAULT 'todo',
  priority VARCHAR(50) DEFAULT 'medium',
  due_date TIMESTAMP,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_tasks_user_id ON tasks(user_id);
CREATE INDEX idx_tasks_status ON tasks(status);

ステップ6: 実装

@software-developer タスク作成APIエンドポイント（POST /tasks）を実装

成果物:

src/tasks/
├── tasks.controller.ts
├── tasks.service.ts
├── tasks.repository.ts
├── dto/create-task.dto.ts
└── tests/tasks.service.spec.ts

実装例（Service層）:

@Injectable()
export class TasksService {
  constructor(
    private readonly tasksRepository: TasksRepository,
    private readonly prisma: PrismaService,
  ) {}

  async create(
    createTaskDto: CreateTaskDto,
    userId: string,
  ): Promise<TaskResponseDto> {
    // バリデーション
    this.validateCreateTaskDto(createTaskDto);

    // タスク作成
    const task = await this.prisma.task.create({
      data: {
        ...createTaskDto,
        userId,
        status: TaskStatus.TODO,
      },
      include: { user: true },
    });

    return this.toResponseDto(task);
  }

  private validateCreateTaskDto(dto: CreateTaskDto): void {
    if (!dto.title || dto.title.trim().length === 0) {
      throw new BadRequestException('Title is required');
    }
    if (dto.title.length > 200) {
      throw new BadRequestException('Title must be 200 characters or less');
    }
  }
}

ステップ7: テスト作成

@test-engineer task-management-api-srs-v1.0.md からテストケースを作成

成果物:

tests/
├── unit/tasks.service.spec.ts
├── integration/tasks.api.spec.ts
└── e2e/task-management.e2e.spec.ts

テストケース例:

// REQ-001: タスク作成
describe('POST /tasks', () => {
  it('should create task and return 201 when valid data is provided', async () => {
    const response = await request(app)
      .post('/tasks')
      .set('Authorization', `Bearer ${token}`)
      .send({
        title: 'Test Task',
        description: 'Test Description',
      });

    expect(response.status).toBe(201);
    expect(response.body).toHaveProperty('id');
    expect(response.body.title).toBe('Test Task');
  });

  // REQ-003: 認証チェック
  it('should return 401 when JWT token is missing', async () => {
    const response = await request(app)
      .post('/tasks')
      .send({ title: 'Test Task' });

    expect(response.status).toBe(401);
  });
});

ステップ8: セキュリティ監査

@security-auditor 認証・認可実装をセキュリティ監査

成果物:

security/security-audit-report-20250114.md

ステップ9: CI/CDパイプライン構築

@devops-engineer GitHub ActionsでCI/CDパイプラインを構築

成果物:

.github/workflows/
├── ci.yml
└── cd.yml

docker/
├── Dockerfile
└── docker-compose.yml

ステップ10: デプロイ

@cloud-architect AWSでタスク管理APIをデプロイ

成果物:

infrastructure/
└── terraform/
    ├── main.tf
    ├── ecs.tf
    ├── rds.tf
    └── vpc.tf

4.2 個別ユースケース

ユースケース1: 既存コードのリファクタリング

シナリオ: レガシーコードをクリーンアーキテクチャにリファクタリング

# ステップ1: コードレビューで問題点を特定
@code-reviewer src/legacy-module/ をレビューしてリファクタリング候補を特定

# ステップ2: リファクタリング実装
@software-developer legacy-module をクリーンアーキテクチャにリファクタリング

# ステップ3: テストカバレッジ向上
@test-engineer リファクタリング後のコードにテストを追加してカバレッジ80%以上を達成

ユースケース2: パフォーマンス改善

シナリオ: 遅いAPIエンドポイントの最適化

# ステップ1: パフォーマンス分析
@performance-optimizer GET /tasks エンドポイントのパフォーマンスを分析

# ステップ2: データベースクエリ最適化
@database-administrator N+1問題を解決し、インデックスを最適化

# ステップ3: キャッシング実装
@software-developer Redis キャッシュを実装

# ステップ4: ベンチマーク
@performance-optimizer 最適化前後のパフォーマンスを比較

ユースケース3: 新機能追加（複数エージェント連携）

シナリオ: タスクコメント機能の追加

方法1: Orchestratorに一括依頼

@orchestrator タスクコメント機能を要件定義から実装まで完成させてください

Orchestratorが自動的に以下を実行:

1. Requirements Analyst → 要件定義
2. System Architect → 既存アーキテクチャとの整合性確認
3. API Designer → コメントAPIエンドポイント設計
4. Database Schema Designer → commentsテーブル追加
5. Software Developer → 実装
6. Test Engineer → テスト作成

方法2: 手動で各エージェントを順次呼び出し

# ステップ1: 要件定義
@requirements-analyst タスクコメント機能の要件を定義

# ステップ2: API設計
@api-designer task-comment-requirements.md に基づいてコメントAPIを設計

# ステップ3: DB設計
@database-schema-designer commentsテーブルを追加

# ステップ4: 実装
@software-developer コメント機能を実装

# ステップ5: テスト
@test-engineer コメント機能のテストを作成

ユースケース4: セキュリティ脆弱性対応

シナリオ: セキュリティ監査で発見された脆弱性の修正

# ステップ1: セキュリティ監査
@security-auditor 全エンドポイントのセキュリティ監査を実施

# ステップ2: 脆弱性修正
@software-developer security-audit-report-20250114.md の脆弱性を修正

# ステップ3: 再監査
@security-auditor 修正後のコードを再監査

ユースケース5: ドキュメント整備

シナリオ: 既存プロジェクトのドキュメント整備

# ステップ1: プロジェクトメモリ作成（ドキュメントのベース）
@steering

# ステップ2: APIドキュメント作成
@technical-writer コードベースからAPIドキュメントを作成

# ステップ3: ユーザーガイド作成
@technical-writer エンドユーザー向けのユーザーガイドを作成

# ステップ4: README更新
@technical-writer README.mdを包括的に更新

第5章 エージェント連携パターン

5.1 基本的な連携パターン

パターン1: 順次実行（Sequential）

要件定義 → 設計 → 実装 → テスト

@requirements-analyst [要件定義]
↓
@system-architect [設計]
↓
@software-developer [実装]
↓
@test-engineer [テスト]

使いどころ: 新機能開発、明確なフェーズがあるタスク

パターン2: 並列実行（Parallel）

複数の独立したタスクを同時に進める

@api-designer [API設計]  +  @ui-ux-designer [UI設計]
↓
統合

使いどころ: フロントエンドとバックエンドの並行開発

パターン3: レビュー・改善サイクル（Review Cycle）

実装 → レビュー → 修正 → 再レビュー

@software-developer [実装]
↓
@code-reviewer [レビュー]
↓
@software-developer [修正]
↓
@security-auditor [セキュリティチェック]

使いどころ: 品質重視の開発、本番リリース前

パターン4: Orchestrator主導（Orchestrated）

複雑なタスクをOrchestratorに一括依頼

@orchestrator [包括的な依頼]
↓
Orchestratorが自動的に複数エージェントを調整

使いどころ: どのエージェントを使うべきか不明、複雑な連携が必要

5.2 高度な連携パターン

パターン5: 段階的リファクタリング

1. @code-reviewer [問題点の特定]
2. @system-architect [リファクタリング計画]
3. @software-developer [段階的実装]
4. @test-engineer [リグレッションテスト]
5. @performance-optimizer [パフォーマンス確認]

パターン6: セキュリティファースト開発

1. @requirements-analyst [要件定義（セキュリティ要件含む）]
2. @security-auditor [脅威モデリング]
3. @system-architect [セキュアアーキテクチャ設計]
4. @software-developer [セキュアコーディング実装]
5. @security-auditor [セキュリティ監査]

第6章 Tips & ベストプラクティス

6.1 効果的なエージェント活用のコツ

Tip 1: Steering Agentを最初に実行

プロジェクト開始時、または大きな変更後は必ず @steering を実行してプロジェクトメモリを更新しましょう。

理由:

• すべてのエージェントがプロジェクトコンテキストを共有
• 技術スタックやアーキテクチャの一貫性が保たれる
• エージェント間の引継ぎがスムーズ

Tip 2: EARS形式を活用

Requirements Analystには必ずEARS形式で要件を作成してもらいましょう。

メリット:

• 要件が明確で曖昧性がない
• テストケースに直接変換可能
• 実装時の判断に迷わない

Tip 3: ドキュメント参照を明示

エージェントに依頼する際、参照すべきドキュメントを明示しましょう。

Good:

@software-developer api-design-task-api-v1.0.md に基づいてPOST /tasksエンドポイントを実装

Bad:

@software-developer タスク作成APIを実装して

Tip 4: 複雑なタスクはOrchestratorに

どのエージェントを使うべきか不明な場合、または複数フェーズにまたがる場合は、Orchestratorに依頼しましょう。

@orchestrator ユーザー認証機能を要件定義から実装・テストまで完成させてください

Tip 5: Code ReviewerとSecurity Auditorを定期的に実行

実装後は必ずCode ReviewerとSecurity Auditorでチェックしましょう。

@code-reviewer src/new-feature/ をレビュー
@security-auditor src/auth/ のセキュリティ監査

6.2 よくある質問（FAQ）

Q1: エージェントの選択に迷ったらどうすればいい？

A: Orchestratorに依頼してください。Orchestratorが最適なエージェントを選択します。

@orchestrator [やりたいこと]

Q2: プロジェクトメモリ（Steering）はいつ更新すべき？

A: 以下のタイミングで更新してください。

• プロジェクト開始時（Bootstrap）
• 技術スタック変更時
• 大きなアーキテクチャ変更後
• 定期的（週次や月次）

エージェントがv0.4.9以降の場合、作業完了後に自動更新されますが、定期的に @steering でSync（同期）を実行することを推奨します。

Q3: 英語版と日本語版の両方が生成されるが、どちらを参照すべき？

A: 英語版（.md）を参照してください。日本語版（.ja.md）は翻訳版です。

理由:

• 英語版がプライマリドキュメント
• エージェント間での参照が統一される
• コード内での参照も英語版を使用

Q4: 複数のエージェントを同時に使える？

A: はい、Orchestratorが複数エージェントを調整します。手動で順次実行することも可能です。

Q5: 既存プロジェクトにMUSUHIを導入できる？

A: はい。以下のステップで導入できます。

# 1. MUSUHIインストール
npx musuhi install --tool claude-code

# 2. Steering Agentでプロジェクトメモリ作成
@steering

# 3. 必要に応じてドキュメント整備
@technical-writer 既存コードベースからドキュメントを作成

6.3 トラブルシューティング

問題1: エージェントが期待通りの出力をしない

解決策:

1. Steering Agentでプロジェクトメモリを更新
2. 参照すべきドキュメントを明示的に指定
3. より具体的な指示を与える

問題2: プロジェクトメモリが古い

解決策:

@steering

で最新のコードベースと同期してください。

問題3: EARS形式の要件が生成されない

解決策:
Requirements Analystに明示的に依頼してください。

@requirements-analyst EARS形式で[機能]の要件を定義

第7章 まとめ

7.1 MUSUHIの開発ワークフロー

MUSUHIを活用した理想的な開発ワークフローは以下の通りです。

1. プロジェクト基盤構築
   └─ @steering (プロジェクトメモリ作成)

2. 要件定義
   └─ @requirements-analyst (EARS形式の要件定義)

3. 設計
   ├─ @system-architect (アーキテクチャ設計)
   ├─ @api-designer (API設計)
   ├─ @database-schema-designer (DB設計)
   └─ @ui-ux-designer (UI設計)

4. 実装
   └─ @software-developer (コード実装)

5. テスト・品質保証
   ├─ @test-engineer (テスト作成)
   ├─ @code-reviewer (コードレビュー)
   ├─ @security-auditor (セキュリティ監査)
   └─ @performance-optimizer (パフォーマンス最適化)

6. インフラ・デプロイ
   ├─ @cloud-architect (クラウドインフラ設計)
   ├─ @devops-engineer (CI/CD構築)
   └─ @database-administrator (DB運用設計)

7. ドキュメント整備
   └─ @technical-writer (技術文書作成)

8. 運用・改善
   ├─ @bug-hunter (バグ調査)
   └─ @steering (プロジェクトメモリ更新)

7.2 次のステップ

1. 実際に使ってみる: 小さな機能から始めて、MUSUHIのエージェントに慣れましょう
2. ワークフローのカスタマイズ: プロジェクトに合わせてエージェントの使い方を調整しましょう
3. チーム展開: チーム全体でMUSUHIを活用し、開発プロセスを標準化しましょう
4. 継続的改善: プロジェクトメモリを定期的に更新し、品質を維持しましょう

7.3 リソース

• 公式リポジトリ: https://github.com/nahisaho/musuhi
• README: https://github.com/nahisaho/musuhi/blob/main/README.ja.md
• Issue報告: https://github.com/nahisaho/musuhi/issues

MUSUHIで、仕様駆動開発をより効率的に、より高品質に。