musubix 3.3.4 → 3.3.6

package/docs/MUSUBIv2.2.0-USERGUIDE.md

@@ -0,0 +1,2079 @@
+# MUSUBIX v2.2.0 ユーザーガイド
+
+**バージョン**: 2.2.0  
+**最終更新**: 2026-01-09  
+**対象**: 開発者、AIコーディングエージェント
+
+---
+
+## 目次
+
+1. [はじめに](#1-はじめに)
+2. [インストール](#2-インストール)
+3. [Phase 1: プロジェクト初期化](#3-phase-1-プロジェクト初期化)
+4. [Phase 2: 要件定義（EARS形式）](#4-phase-2-要件定義ears形式)
+5. [Phase 3: 設計（C4モデル）](#5-phase-3-設計c4モデル)
+6. [Phase 4: タスク分解](#6-phase-4-タスク分解)
+7. [Phase 5: コード生成](#7-phase-5-コード生成)
+8. [Phase 6: セキュリティ分析](#8-phase-6-セキュリティ分析)
+9. [Phase 7: 形式検証](#9-phase-7-形式検証)
+10. [Phase 8: テスト生成](#10-phase-8-テスト生成)
+11. [Phase 9: トレーサビリティ](#11-phase-9-トレーサビリティ)
+12. [高度な機能（v2.2.0）](#12-高度な機能v220)
+13. [プロジェクトサマリー](#13-プロジェクトサマリー)
+14. [その他の機能](#14-その他の機能)
+- [付録A: 9条憲法](#付録a-9条憲法)
+- [付録B: CLIコマンド一覧](#付録b-cliコマンド一覧)
+- [付録C: ファイル構成](#付録c-ファイル構成)
+- [付録D: EARSパターン早見表](#付録d-earsパターン早見表)
+
+---
+
+## 1. はじめに
+
+### 1.1 MUSUBIXとは
+
+**MUSUBIX**（ムスビックス）は、**Neuro-Symbolic AI統合システム**です。LLM（大規模言語モデル）の創造性とシンボリック推論の精密性を融合し、高品質なソフトウェア開発を支援します。
+
+### 1.2 主要な特徴
+
+| 特徴 | 説明 |
+|------|------|
+| **EARS形式要件** | 形式的な要件記述（5パターン） |
+| **C4モデル設計** | 4レベルのアーキテクチャ設計 |
+| **9条憲法** | 開発プロセスを統治する不変ルール |
+| **完全トレーサビリティ** | 要件→設計→コード→テストの100%追跡 |
+| **形式検証** | Z3 SMTソルバによる数学的検証 |
+| **セキュリティ分析** | OWASP Top 10/CWE Top 25対応 |
+| **自己学習** | パターン学習と適応的推論 |
+
+### 1.3 このガイドについて
+
+このガイドでは、**Medical Appointment System（医療予約管理システム）** を題材に、MUSUBIXの全機能を使った開発プロセスを実演します。
+
+---
+
+## 2. インストール
+
+### 2.1 npmからインストール
+
+```bash
+# 全パッケージを一括インストール
+npm install musubix
+
+# または個別パッケージ
+npm install @nahisaho/musubix-core
+```
+
+### 2.2 システム要件
+
+| 項目 | 要件 |
+|------|------|
+| Node.js | >= 20.0.0 |
+| npm | >= 10.0.0 |
+| OS | Windows, macOS, Linux |
+
+### 2.3 インストール確認
+
+```bash
+npx musubix --version
+# 出力: 2.2.0
+```
+
+---
+
+## 3. Phase 1: プロジェクト初期化
+
+### 3.1 `musubix init` コマンド
+
+MUSUBIXプロジェクトを初期化します。
+
+```bash
+npx musubix init medical-appointment-system --name "Medical Appointment System"
+```
+
+### 3.2 実行結果
+
+```json
+{
+  "success": true,
+  "projectPath": "/tmp/medical-appointment-system",
+  "filesCreated": [
+    "steering/",
+    "steering/rules/",
+    "storage/",
+    "storage/specs/",
+    "storage/archive/",
+    "storage/changes/",
+    ".github/",
+    ".github/prompts/",
+    ".github/skills/",
+    "musubix.config.json",
+    "steering/rules/constitution.md",
+    "steering/product.md",
+    "steering/tech.md",
+    "steering/structure.md",
+    "AGENTS.md"
+  ],
+  "message": "MUSUBIX project 'Medical Appointment System' initialized successfully!"
+}
+```
+
+### 3.3 生成されるディレクトリ構造
+
+```
+medical-appointment-system/
+├── steering/                 # プロジェクトメモリ
+│   ├── rules/
+│   │   └── constitution.md   # 9条憲法
+│   ├── product.md            # プロダクトコンテキスト
+│   ├── tech.md               # 技術スタック
+│   └── structure.md          # アーキテクチャパターン
+├── storage/                  # 成果物ストレージ
+│   ├── specs/                # 要件・設計・タスク
+│   ├── archive/              # アーカイブ
+│   └── changes/              # 変更履歴
+├── .github/
+│   ├── prompts/              # AIエージェント用プロンプト
+│   └── skills/               # AIスキル定義
+├── musubix.config.json       # 設定ファイル
+└── AGENTS.md                 # AIエージェント向けガイド
+```
+
+### 3.4 MUSUBIXの処理内容
+
+`musubix init` は以下の処理を実行します：
+
+1. **ディレクトリ構造の作成** - SDD方法論に準拠したフォルダ構造
+2. **9条憲法の配置** - 開発ルールを `steering/rules/constitution.md` に生成
+3. **プロジェクトメモリの初期化** - AIエージェントが参照する設定ファイル
+4. **AIスキルの配置** - GitHub Copilot/Claude用のスキル定義
+
+---
+
+## 4. Phase 2: 要件定義（EARS形式）
+
+### 4.1 EARS形式とは
+
+**EARS (Easy Approach to Requirements Syntax)** は、自然言語の曖昧さを排除した形式的な要件記述方法です。
+
+### 4.2 5つのEARSパターン
+
+| パターン | 構文 | 用途 |
+|---------|------|------|
+| **Ubiquitous** | `THE [system] SHALL [requirement]` | 常に満たすべき要件 |
+| **Event-driven** | `WHEN [event], THE [system] SHALL [response]` | イベント発生時の要件 |
+| **State-driven** | `WHILE [state], THE [system] SHALL [response]` | 特定状態での要件 |
+| **Unwanted** | `THE [system] SHALL NOT [behavior]` | 禁止動作 |
+| **Optional** | `IF [condition], THEN THE [system] SHALL [response]` | 条件付き要件 |
+
+### 4.3 要件ドキュメントの作成
+
+`storage/specs/REQ-MAS-requirements.md` に EARS形式で要件を記述します。
+
+#### 例: 予約作成要件
+
+```markdown
+### REQ-MAS-008: 予約作成
+**パターン**: Event-driven  
+**優先度**: P0
+
+WHEN a patient selects an available time slot, THE system SHALL create 
+an appointment within 3 seconds, mark the slot as booked, and return 
+a unique appointment ID.
+
+**事前条件**: Time slot is available, patient has no conflicting appointment  
+**事後条件**: Appointment status='confirmed', time slot status='booked'  
+**トレース**: DES-MAS-003
+```
+
+### 4.4 要件検証コマンド
+
+```bash
+npx musubix requirements validate storage/specs/REQ-MAS-requirements.md
+```
+
+### 4.5 検証結果
+
+```json
+{
+  "success": true,
+  "valid": true,
+  "issues": [],
+  "summary": { "errors": 0, "warnings": 0, "info": 0 },
+  "message": "✅ All 20 requirements are valid"
+}
+```
+
+### 4.6 MUSUBIXの処理内容
+
+`musubix requirements validate` は以下の処理を実行します：
+
+1. **EARS構文解析** - 5パターンのキーワード（WHEN, WHILE, SHALL, SHALL NOT, IF...THEN）を検出
+2. **構文検証** - 各パターンの文法ルールに準拠しているか確認
+3. **優先度チェック** - P0/P1/P2の優先度が設定されているか確認
+4. **トレーサビリティリンク検出** - DES-*, TSK-* への参照を抽出
+5. **測定可能性分析** - 具体的な数値・時間制約があるか評価
+
+### 4.7 Medical Appointment System の要件一覧
+
+| 要件ID | 名称 | パターン | 優先度 |
+|--------|------|----------|--------|
+| REQ-MAS-001 | 患者新規登録 | Event-driven | P0 |
+| REQ-MAS-002 | 患者プロフィール更新 | Event-driven | P1 |
+| REQ-MAS-003 | 個人情報暗号化 | Ubiquitous | P0 |
+| REQ-MAS-004 | 患者データアクセス制御 | Ubiquitous | P0 |
+| REQ-MAS-005 | 医師専門分野 | Ubiquitous | P0 |
+| REQ-MAS-006 | 医師時間枠設定 | Event-driven | P0 |
+| REQ-MAS-007 | 医師検索 | Event-driven | P1 |
+| REQ-MAS-008 | 予約作成 | Event-driven | P0 |
+| REQ-MAS-009 | 重複予約防止 | Unwanted | P0 |
+| REQ-MAS-010 | 予約キャンセル可能期間 | State-driven | P0 |
+| REQ-MAS-011 | 予約キャンセル不可 | State-driven | P0 |
+| REQ-MAS-012 | 予約変更 | Event-driven | P1 |
+| REQ-MAS-013 | 予約確認メール | Event-driven | P1 |
+| REQ-MAS-014 | 予約アクセス制御 | Ubiquitous | P0 |
+| REQ-MAS-015 | JWT認証 | Ubiquitous | P0 |
+| REQ-MAS-016 | パスワードハッシュ化 | Ubiquitous | P0 |
+| REQ-MAS-017 | 監査ログ | Ubiquitous | P0 |
+| REQ-MAS-018 | 認証失敗ロックアウト | State-driven | P1 |
+| REQ-MAS-019 | API応答時間 | Ubiquitous | P1 |
+| REQ-MAS-020 | 同時ユーザー数 | Ubiquitous | P1 |
+
+### 4.8 レビュープロセス
+
+MUSUBIXでは、各フェーズ終了時にセルフレビューを実施します。
+
+#### レビュー観点
+
+| 観点 | チェック内容 |
+|------|--------------|
+| EARS形式準拠 | 5パターンの構文に準拠しているか |
+| 優先度設定 | P0/P1/P2が適切に設定されているか |
+| 測定可能性 | 具体的な数値・時間制約があるか |
+| 網羅性 | 機能・非機能・セキュリティ要件が揃っているか |
+| 一貫性 | 要件間で矛盾がないか |
+| トレーサビリティ | 設計要素へのリンクがあるか |
+
+#### レビュー結果の表示形式
+
+```
+📋 **レビュー結果**
+
+| 観点 | 状態 | 詳細 |
+|------|------|------|
+| EARS形式準拠 | ✅ OK | 全20件がEARS構文に準拠 |
+| 優先度設定 | ✅ OK | P0: 13件, P1: 7件 |
+| 測定可能性 | ✅ OK | 時間制約・エラーコード明示 |
+| ...  | ...  | ... |
+
+👉 **次のアクション:**
+- 「修正」→ 指摘箇所を修正して再提示
+- 「承認」→ 次フェーズへ進む
+```
+
+---
+
+## 5. Phase 3: 設計（C4モデル）
+
+### 5.1 C4モデルとは
+
+**C4モデル**は、ソフトウェアアーキテクチャを4つのレベルで視覚化する手法です。
+
+| レベル | 名称 | 説明 |
+|--------|------|------|
+| Level 1 | **System Context** | システム境界と外部アクター |
+| Level 2 | **Container** | 技術スタックとコンテナ構成 |
+| Level 3 | **Component** | コンテナ内部のコンポーネント |
+| Level 4 | **Code** | 実装詳細（クラス図等） |
+
+### 5.2 `musubix design generate` コマンド
+
+要件ドキュメントからC4モデル設計を自動生成します。
+
+```bash
+npx musubix design generate storage/specs/REQ-MAS-requirements.md
+```
+
+### 5.3 実行結果
+
+```json
+{
+  "success": true,
+  "design": {
+    "level": "component",
+    "title": "Component Diagram",
+    "elements": 19,
+    "relationships": 34
+  },
+  "patterns": [
+    { "name": "Factory", "category": "creational" },
+    { "name": "Singleton", "category": "creational" },
+    { "name": "Observer", "category": "behavioral" }
+  ],
+  "traceability": [
+    { "requirement": "REQ-MAS-001", "designElement": "PatientService" },
+    { "requirement": "REQ-MAS-008", "designElement": "AppointmentService" },
+    ...
+  ],
+  "message": "Generated component design with 19 elements"
+}
+```
+
+### 5.4 MUSUBIXの処理内容
+
+`musubix design generate` は以下の処理を実行します：
+
+1. **要件解析** - EARS要件からドメイン概念を抽出
+2. **コンポーネント識別** - 責務に基づいてコンポーネントを分類
+3. **パターン検出** - 適用可能な設計パターン（GoF）を提案
+4. **関係性マッピング** - コンポーネント間の依存関係を定義
+5. **トレーサビリティリンク生成** - REQ-* → DES-* の対応を自動生成
+
+### 5.5 生成される設計要素
+
+#### Level 2: Container Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                       Medical Appointment System                        │
+│                                                                         │
+│  ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────────┐   │
+│  │   Web Client    │   │  Mobile Client  │   │   Admin Dashboard   │   │
+│  │   (React SPA)   │   │  (React Native) │   │      (React)        │   │
+│  └────────┬────────┘   └────────┬────────┘   └──────────┬──────────┘   │
+│           │                     │                        │              │
+│           └─────────────────────┴────────────────────────┘              │
+│                                 │                                       │
+│                                 ▼                                       │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                        API Gateway                               │   │
+│  │                      (Node.js/Express)                           │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                 │                                       │
+│       ┌─────────────────────────┼─────────────────────────┐             │
+│       ▼                         ▼                         ▼             │
+│  ┌─────────────┐   ┌─────────────────────┐   ┌─────────────────────┐   │
+│  │ Auth Service│   │ Appointment Service │   │ Notification Service│   │
+│  └──────┬──────┘   └──────────┬──────────┘   └──────────┬──────────┘   │
+│         │                     │                         │               │
+│         └─────────────────────┴─────────────────────────┘               │
+│                               │                                         │
+│                               ▼                                         │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                       PostgreSQL Database                        │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+#### Level 3: Component Diagram（一部）
+
+```
+DES-MAS-APPT: Appointment Service
+├── DES-MAS-APPT-001: AppointmentController
+│   └── トレース: REQ-MAS-008, REQ-MAS-010, REQ-MAS-011, REQ-MAS-012
+├── DES-MAS-APPT-002: AppointmentService
+│   └── トレース: REQ-MAS-008, REQ-MAS-009, REQ-MAS-010, REQ-MAS-012
+├── DES-MAS-APPT-005: DuplicateBookingValidator
+│   └── トレース: REQ-MAS-009
+└── DES-MAS-APPT-008: AppointmentFactory (Factory Pattern)
+    └── トレース: REQ-MAS-008
+```
+
+### 5.6 適用設計パターン
+
+MUSUBIXは、要件の特性に基づいて適切な設計パターンを自動提案します。
+
+| パターン | カテゴリ | 適用箇所 | 目的 |
+|----------|----------|----------|------|
+| **Factory** | 生成 | AppointmentFactory | オブジェクト生成のカプセル化 |
+| **Singleton** | 生成 | AuditLogger | 監査ログの一元管理 |
+| **Observer** | 振る舞い | NotificationObserver | イベント駆動の通知配信 |
+
+### 5.7 設計ドキュメントの構成
+
+```
+storage/design/
+└── DES-MAS-design.md
+    ├── 1. 概要
+    ├── 2. C4モデル
+    │   ├── Level 1: System Context
+    │   ├── Level 2: Container Diagram
+    │   └── Level 3: Component Diagram
+    ├── 3. 適用設計パターン
+    ├── 4. データモデル
+    │   ├── エンティティ定義
+    │   └── Value Objects
+    ├── 5. インターフェース設計
+    │   ├── REST API エンドポイント
+    │   └── エラーコード設計
+    ├── 6. セキュリティ設計
+    └── 7. トレーサビリティマトリクス
+```
+
+### 5.8 トレーサビリティマトリクス（抜粋）
+
+| 要件 | 設計コンポーネント | パターン |
+|------|-------------------|----------|
+| REQ-MAS-001 | DES-MAS-PATIENT-001, 002, 004 | - |
+| REQ-MAS-008 | DES-MAS-APPT-001, 002, 003, 004, 008 | Factory |
+| REQ-MAS-009 | DES-MAS-APPT-005 | - |
+| REQ-MAS-013 | DES-MAS-NOTIFY-001, 002, 003, 004 | Observer |
+| REQ-MAS-017 | DES-MAS-AUTH-006 | Singleton |
+
+### 5.9 レビュー観点
+
+| 観点 | チェック内容 |
+|------|--------------|
+| C4レベル網羅 | Context/Container/Componentが揃っているか |
+| SOLID準拠 | 単一責任・開放閉鎖原則に従っているか |
+| パターン適用 | 設計パターンの適用理由が明確か |
+| トレーサビリティ | 全要件が設計要素にリンクされているか |
+| インターフェース定義 | API・エラーコードが明確か |
+| セキュリティ設計 | 認証・暗号化の設計が適切か |
+
+---
+
+## 6. Phase 4: タスク分解
+
+### 6.1 タスク分解とは
+
+設計ドキュメントから実装可能な単位のタスクに分解するフェーズです。
+
+> **重要**: MUSUBIXでは、タスク分解は**自然言語による指示**で実行します。AIエージェントが設計ドキュメントを解析し、適切な粒度のタスクに分解します。
+
+### 6.2 自然言語指示によるタスク分解
+
+MUSUBIXのタスク分解は、専用CLIコマンドではなく、**AIエージェントへの自然言語指示**で行います。
+
+```
+ユーザー: 「設計ドキュメントからタスクを分解してください」
+
+AIエージェント:
+1. 設計ドキュメント（DES-MAS-design.md）を解析
+2. コンポーネントを実装単位に分解
+3. 依存関係を特定
+4. 見積もりを算出
+5. TSK-MAS-tasks.md を生成
+```
+
+**この設計思想の理由:**
+- タスク分解は**コンテキスト依存**が強い（プロジェクト特性、チーム構成、技術スタック）
+- AIエージェントが**設計意図を理解**した上で分解することで、より適切な粒度を実現
+- **対話的な調整**が可能（「もっと細かく分解して」「認証サービスを優先して」など）
+
+### 6.3 タスク分解の原則
+
+| 原則 | 説明 |
+|------|------|
+| **粒度** | 1タスク = 2〜4時間の作業量 |
+| **依存関係** | 明確な実行順序を定義 |
+| **テスト先行** | 各タスクにテストタスクを含む |
+| **トレーサビリティ** | DES-* → TSK-* のリンクを維持 |
+
+### 6.3 タスクID命名規則
+
+```
+TSK-{プロジェクト}-{カテゴリ番号}{連番}
+
+例:
+TSK-MAS-001  → 共通基盤タスク#1
+TSK-MAS-101  → 認証サービスタスク#1（100系）
+TSK-MAS-201  → 患者サービスタスク#1（200系）
+TSK-MAS-301  → 医師サービスタスク#1（300系）
+TSK-MAS-401  → 予約サービスタスク#1（400系）
+TSK-MAS-501  → 通知サービスタスク#1（500系）
+TSK-MAS-901  → 統合タスク#1（900系）
+```
+
+### 6.4 Medical Appointment System のタスク構成
+
+| カテゴリ | タスク数 | 合計見積もり |
+|----------|----------|--------------|
+| 共通基盤 | 4 | 9h |
+| 認証サービス | 7 | 17h |
+| 患者サービス | 7 | 18h |
+| 医師サービス | 7 | 18h |
+| 予約サービス | 9 | 27h |
+| 通知サービス | 5 | 11h |
+| 統合・最終 | 6 | 17h |
+| **合計** | **45タスク** | **117h** |
+
+### 6.5 実行順序（クリティカルパス）
+
+```
+Phase A: 基盤構築（Week 1）
+──────────────────────────
+TSK-MAS-001 → TSK-MAS-002 → TSK-MAS-003
+                    ↓
+              TSK-MAS-004
+
+Phase B: コアサービス並行開発（Week 2-3）
+────────────────────────────────────────
+[認証]           [患者]           [医師]
+TSK-MAS-101      TSK-MAS-201      TSK-MAS-301
+    ↓                ↓                ↓
+   ...              ...              ...
+    ↓                ↓                ↓
+TSK-MAS-107      TSK-MAS-207      TSK-MAS-307
+
+Phase C: 予約・通知サービス（Week 3-4）
+─────────────────────────────────────
+[予約]                    [通知]
+TSK-MAS-401 → ... → 409   TSK-MAS-501 → ... → 505
+
+Phase D: 統合・検証（Week 5）
+──────────────────────────
+TSK-MAS-901 → 902 → 903 → 904 → 905 → 906
+```
+
+### 6.6 タスク詳細の構成要素
+
+各タスクは以下の要素を含みます：
+
+```markdown
+### TSK-MAS-XXX: タスク名
+
+**見積もり**: Xh  
+**依存**: TSK-MAS-YYY  
+**トレース**: DES-MAS-ZZZ, REQ-MAS-WWW
+
+**完了条件**:
+- [ ] 実装項目1
+- [ ] 実装項目2
+- [ ] テスト作成
+
+**受け入れ基準**:
+\`\`\`typescript
+// テストコード例
+expect(result.isOk()).toBe(true);
+\`\`\`
+```
+
+### 6.7 トレーサビリティマトリクス（抜粋）
+
+| 要件 | 設計 | タスク |
+|------|------|--------|
+| REQ-MAS-001 | DES-MAS-PATIENT-001,002,004 | TSK-MAS-201,205,206 |
+| REQ-MAS-008 | DES-MAS-APPT-001,002,003,004,008 | TSK-MAS-401,402,405,407,408 |
+| REQ-MAS-009 | DES-MAS-APPT-005 | TSK-MAS-403,904 |
+| REQ-MAS-015 | DES-MAS-AUTH-001,002,003 | TSK-MAS-102,105,106 |
+
+### 6.8 MUSUBIXの処理内容
+
+タスク分解では以下の処理を実行します：
+
+1. **コンポーネント分析** - 設計コンポーネントから実装単位を特定
+2. **依存関係解析** - コンポーネント間の依存関係をタスク順序に変換
+3. **見積もり算出** - コンポーネントの複雑度に基づいて工数を見積もり
+4. **テストタスク生成** - 各サービスにテストタスクを自動追加
+5. **トレーサビリティリンク** - DES-* → TSK-* の対応を生成
+
+### 6.9 レビュー観点
+
+| 観点 | チェック内容 |
+|------|--------------|
+| タスク粒度 | 1タスク2〜4時間の範囲内か |
+| 依存関係 | 循環依存がないか、順序が妥当か |
+| 網羅性 | 全設計コンポーネントがタスク化されているか |
+| テスト先行 | 各サービスにテストタスクがあるか |
+| トレーサビリティ | REQ→DES→TSKのリンクが完全か |
+| 見積もり妥当性 | 合計工数が現実的か |
+
+---
+
+## 7. Phase 5: コード生成
+
+### 7.1 コード生成とは
+
+設計ドキュメントからTypeScriptのスケルトンコードを自動生成するフェーズです。
+
+### 7.2 `musubix codegen generate` コマンド
+
+```bash
+npx musubix codegen generate storage/design/DES-MAS-design.md --output src/
+```
+
+### 7.3 実行結果
+
+```
+✅ Code generated in /tmp/medical-appointment-system/src
+```
+
+### 7.4 MUSUBIXの処理内容
+
+`musubix codegen generate` は以下の処理を実行します：
+
+1. **設計解析** - C4コンポーネント図からクラス/インターフェースを抽出
+2. **パターン検出** - Factory, Singleton, Observer等の設計パターンを識別
+3. **スケルトン生成** - TypeScriptコードの基本構造を生成
+4. **トレーサビリティ注入** - `@トレース` アノテーションをコメントに追加
+5. **ベストプラクティス適用** - BP-CODE-*, BP-DESIGN-* パターンを自動適用
+
+### 7.5 生成されるコード構造
+
+```
+src/
+├── common/               # 共通モジュール
+│   ├── result.ts         # Result<T, E> 型定義
+│   ├── errors.ts         # エラー型・エラーコード
+│   └── id-generator.ts   # ID生成ユーティリティ
+├── auth/                 # 認証サービス
+│   └── audit-logger.ts   # 監査ログ（Singleton）
+├── patient/              # 患者サービス
+├── doctor/               # 医師サービス
+├── appointment/          # 予約サービス
+│   ├── appointment.entity.ts           # エンティティ定義
+│   ├── appointment.factory.ts          # Factory Pattern
+│   ├── duplicate-booking.validator.ts  # 重複予約検証
+│   └── cancellation-policy.enforcer.ts # キャンセルポリシー
+└── notification/         # 通知サービス
+    └── notification.observer.ts        # Observer Pattern
+```
+
+### 7.6 コード例：Result型（BP-CODE-005）
+
+```typescript
+/**
+ * Result型 - 失敗可能な操作の戻り値
+ * @トレース BP-CODE-005
+ */
+
+export type Result<T, E> = Ok<T> | Err<E>;
+
+export interface Ok<T> {
+  readonly _tag: 'Ok';
+  readonly value: T;
+}
+
+export interface Err<E> {
+  readonly _tag: 'Err';
+  readonly error: E;
+}
+
+export function ok<T>(value: T): Ok<T> {
+  return { _tag: 'Ok', value };
+}
+
+export function err<E>(error: E): Err<E> {
+  return { _tag: 'Err', error };
+}
+```
+
+### 7.7 コード例：ID生成（BP-CODE-002）
+
+```typescript
+/**
+ * ID生成ユーティリティ
+ * @トレース BP-CODE-002
+ * 形式: PREFIX-YYYYMMDD-NNN
+ */
+
+export function createPatientId(): Result<PatientId, ValidationError> {
+  return ok({ value: generateId('PAT') });
+  // 例: PAT-20260108-001
+}
+
+export function createAppointmentId(): Result<AppointmentId, ValidationError> {
+  return ok({ value: generateId('APT') });
+  // 例: APT-20260108-001
+}
+```
+
+### 7.8 コード例：ステータス遷移マップ（BP-DESIGN-001）
+
+```typescript
+/**
+ * ステータス遷移マップ
+ * @トレース BP-DESIGN-001, REQ-MAS-010, REQ-MAS-011
+ */
+export const validStatusTransitions: Record<AppointmentStatus, AppointmentStatus[]> = {
+  pending: ['confirmed', 'cancelled'],
+  confirmed: ['completed', 'cancelled', 'no_show'],
+  cancelled: [], // 終端状態
+  completed: [], // 終端状態
+  no_show: [],   // 終端状態
+};
+```
+
+### 7.9 コード例：Factory Pattern
+
+```typescript
+/**
+ * Appointment Factory (Factory Pattern)
+ * @トレース DES-MAS-APPT-008, DES-PAT-001, REQ-MAS-008
+ */
+export function createAppointmentFactory(): AppointmentFactory {
+  return {
+    create(input: CreateAppointmentInput): Result<Appointment, ValidationError> {
+      // バリデーション
+      if (!input.patientId?.value) {
+        return err(new ValidationError('Patient ID is required', 'patientId'));
+      }
+      // ... 
+      return ok(appointment);
+    },
+  };
+}
+```
+
+### 7.10 コード例：Observer Pattern
+
+```typescript
+/**
+ * Notification Observer (Observer Pattern)
+ * @トレース DES-MAS-NOTIFY-004, DES-PAT-003, REQ-MAS-013
+ */
+export interface AppointmentEventObserver {
+  onAppointmentCreated(appointment: Appointment): Promise<void>;
+  onAppointmentCancelled(appointment: Appointment): Promise<void>;
+  onAppointmentRescheduled(old: Appointment, new: Appointment): Promise<void>;
+}
+```
+
+### 7.11 コード例：形式仕様アノテーション
+
+```typescript
+/**
+ * Duplicate Booking Validator
+ * @トレース DES-MAS-APPT-005, REQ-MAS-009
+ * 
+ * 形式仕様:
+ * ∀ slot ∈ TimeSlots: slot.status = 'booked' → ¬∃ new_appointment(slot)
+ */
+export function createDuplicateBookingValidator(
+  timeSlotRepo: TimeSlotRepository,
+): DuplicateBookingValidator {
+  return {
+    async validate(timeSlotId, patientId): Promise<Result<void, AppError>> {
+      const timeSlot = await timeSlotRepo.findById(timeSlotId);
+      
+      // 形式仕様の実装: slot.status = 'booked' → reject
+      if (timeSlot.status === 'booked') {
+        return err(SLOT_ALREADY_BOOKED);
+      }
+      return ok(undefined);
+    },
+  };
+}
+```
+
+### 7.12 トレーサビリティアノテーション
+
+生成されたすべてのコードには、`@トレース` アノテーションが付与されます：
+
+| ファイル | トレース先 |
+|----------|------------|
+| `result.ts` | BP-CODE-005 |
+| `errors.ts` | REQ-MAS-009, REQ-MAS-011, REQ-MAS-018 |
+| `id-generator.ts` | BP-CODE-002 |
+| `appointment.entity.ts` | DES-MAS-APPT-004, REQ-MAS-008 |
+| `appointment.factory.ts` | DES-MAS-APPT-008, DES-PAT-001, REQ-MAS-008 |
+| `duplicate-booking.validator.ts` | DES-MAS-APPT-005, REQ-MAS-009 |
+| `cancellation-policy.enforcer.ts` | DES-MAS-APPT-006, REQ-MAS-010, REQ-MAS-011 |
+| `audit-logger.ts` | DES-MAS-AUTH-006, DES-PAT-002, REQ-MAS-017 |
+| `notification.observer.ts` | DES-MAS-NOTIFY-004, DES-PAT-003, REQ-MAS-013 |
+
+---
+
+## 8. Phase 6: セキュリティ分析
+
+### 8.1 セキュリティ分析とは
+
+生成したコードに対してセキュリティ脆弱性をスキャンするフェーズです。MUSUBIXは**OWASP Top 10**および**CWE Top 25**に対応した検出ルールを提供します。
+
+### 8.2 `musubix codegen security` コマンド
+
+```bash
+npx musubix codegen security src/
+```
+
+### 8.3 実行結果
+
+```json
+{
+  "success": true,
+  "vulnerabilities": [],
+  "summary": { "critical": 0, "high": 0, "medium": 0, "low": 0 },
+  "score": 100,
+  "message": "✅ Security score: 100/100 - No critical issues"
+}
+```
+
+### 8.4 MUSUBIXの処理内容
+
+`musubix codegen security` は以下の処理を実行します：
+
+1. **パターンマッチング** - 既知の脆弱性パターンを検出
+2. **テイント解析** - ユーザー入力のトレース
+3. **シークレット検出** - ハードコードされた認証情報の検出
+4. **依存関係チェック** - 既知の脆弱性を持つライブラリの検出
+
+### 8.5 検出対象の脆弱性カテゴリ
+
+#### OWASP Top 10 (2021)
+
+| ランク | カテゴリ | MUSUBIXの対応 |
+|--------|----------|---------------|
+| A01 | Broken Access Control | アクセス制御パターンの検証 |
+| A02 | Cryptographic Failures | 弱い暗号化アルゴリズムの検出 |
+| A03 | Injection | SQL/NoSQL/コマンドインジェクションの検出 |
+| A04 | Insecure Design | 設計レベルのセキュリティレビュー |
+| A05 | Security Misconfiguration | 設定ミスの検出 |
+| A06 | Vulnerable Components | 脆弱なライブラリの検出 |
+| A07 | Auth Failures | 認証・セッション管理の問題検出 |
+| A08 | Software Integrity | 整合性検証の欠如を検出 |
+| A09 | Logging Failures | ログ・監視の問題検出 |
+| A10 | SSRF | サーバーサイドリクエストフォージェリ検出 |
+
+#### CWE Top 25 (抜粋)
+
+| CWE ID | 名称 | 検出方法 |
+|--------|------|----------|
+| CWE-79 | XSS | HTMLエスケープの欠如 |
+| CWE-89 | SQLi | パラメータ化クエリの不使用 |
+| CWE-287 | 認証バイパス | 認証チェックの欠如 |
+| CWE-798 | ハードコードされた認証情報 | 正規表現パターンマッチ |
+| CWE-502 | 安全でないデシリアライゼーション | eval/Function使用 |
+
+### 8.6 静的コード解析
+
+セキュリティスキャンに加えて、静的コード解析も実行できます。
+
+```bash
+npx musubix codegen analyze src/
+```
+
+#### 解析結果
+
+```json
+{
+  "success": true,
+  "issues": [
+    {
+      "file": "src/auth/audit-logger.ts",
+      "line": 38,
+      "severity": "info",
+      "rule": "no-console",
+      "message": "Console statements should be removed in production code."
+    }
+    // ... 他の info レベルの警告
+  ],
+  "metrics": {
+    "files": 11,
+    "lines": 742,
+    "complexity": 74,
+    "maintainabilityIndex": 100
+  },
+  "summary": { "errors": 0, "warnings": 0, "info": 24 },
+  "message": "✅ Analyzed 11 files - No errors found"
+}
+```
+
+### 8.7 Medical Appointment System のセキュリティ対策
+
+#### 認証・認可（REQ-MAS-015, REQ-MAS-016, REQ-MAS-018）
+
+```typescript
+/**
+ * Password Hasher
+ * @トレース DES-MAS-AUTH-004, REQ-MAS-016
+ * 
+ * セキュリティ要件:
+ * - bcryptアルゴリズム使用
+ * - cost factor = 12
+ */
+export function createPasswordHasher(): PasswordHasher {
+  const COST_FACTOR = 12;  // OWASP推奨値
+  // ...
+}
+```
+
+#### データ暗号化（REQ-MAS-003）
+
+```typescript
+/**
+ * Personal Info Encryptor
+ * @トレース DES-MAS-PATIENT-005, REQ-MAS-003
+ * 
+ * セキュリティ要件:
+ * - AES-256-GCM暗号化（認証付き暗号）
+ * - 暗号化キーは環境変数から取得（CWE-798対策）
+ */
+const ALGORITHM = 'aes-256-gcm';  // NIST推奨
+```
+
+#### 監査ログ（REQ-MAS-017）
+
+```typescript
+/**
+ * Audit Logger
+ * @トレース DES-MAS-AUTH-006, REQ-MAS-017
+ * 
+ * 記録対象:
+ * - ログイン試行（成功/失敗）
+ * - データアクセス
+ * - 権限変更
+ */
+export interface AuditEntry {
+  readonly timestamp: Date;
+  readonly userId: string;
+  readonly action: string;
+  readonly resource: string;
+  readonly ip?: string;
+}
+```
+
+### 8.8 セキュリティスコアの解釈
+
+| スコア | 評価 | 説明 |
+|--------|------|------|
+| 90-100 | 優秀 | 重大な脆弱性なし |
+| 70-89 | 良好 | 軽微な問題のみ |
+| 50-69 | 注意 | 中程度の脆弱性あり |
+| 0-49 | 危険 | 重大な脆弱性あり |
+
+### 8.9 レビュー観点
+
+| 観点 | チェック内容 |
+|------|--------------|
+| セキュリティスコア | 90点以上であること |
+| Critical/High | 0件であること |
+| 暗号化 | AES-256-GCM/bcrypt使用 |
+| 認証情報 | ハードコードされていないこと |
+| 監査ログ | 必要なイベントが記録されること |
+| アクセス制御 | 適切な認可チェックがあること |
+
+---
+
+## 9. Phase 7: 形式検証
+
+### 9.1 形式検証とは
+
+**形式検証**は、ソフトウェアの正しさを数学的に証明する手法です。MUSUBIXは**Z3 SMTソルバ**を使用して、EARS要件の論理的整合性を検証します。
+
+### 9.2 MUSUBIXの形式検証機能
+
+| 機能 | 説明 |
+|------|------|
+| **EARS→SMT変換** | EARS要件をSMT-LIB2形式に自動変換 |
+| **事前条件検証** | 関数の入力条件の充足可能性を検証 |
+| **事後条件検証** | Hoareトリプル {P} C {Q} の検証 |
+| **安全性検証** | システムが安全でない状態に到達しないことを証明 |
+
+### 9.3 SMT（Satisfiability Modulo Theories）とは
+
+SMTは、命題論理に加えて**整数・実数・配列・ビットベクトル**などの理論を扱える充足可能性判定問題です。
+
+```
+例: 「x > 0 かつ y > 0 かつ x + y = 10」を満たす x, y は存在するか？
+→ sat (充足可能): x=5, y=5 など
+```
+
+### 9.4 EARS要件からSMT-LIB2への変換
+
+#### 例: REQ-MAS-009（重複予約防止）
+
+**EARS要件:**
+```
+THE system SHALL NOT allow booking an already booked time slot.
+```
+
+**形式仕様:**
+```
+∀ slot ∈ TimeSlots: slot.status = 'booked' → ¬∃ new_appointment(slot)
+```
+
+**SMT-LIB2変換結果:**
+```smt2
+; MUSUBIX Formal Verification
+; Requirement: REQ-MAS-009 - 重複予約防止
+; @トレース REQ-MAS-009, DES-MAS-APPT-005
+
+(set-logic ALL)
+
+; TimeSlot状態: 0=available, 1=booked, 2=blocked
+(declare-const slot_status Int)
+(declare-const booking_attempted Bool)
+(declare-const booking_success Bool)
+
+; slot_statusは0, 1, 2のいずれか
+(assert (and (>= slot_status 0) (<= slot_status 2)))
+
+; 安全性: 予約済みスロットへの予約は失敗すべき
+; slot.status = 'booked' ∧ booking_attempted → ¬booking_success
+(assert (=> (and (= slot_status 1) booking_attempted)
+            (not booking_success)))
+
+(check-sat)
+```
+
+### 9.5 キャンセルポリシーの形式検証
+
+#### REQ-MAS-010, REQ-MAS-011
+
+**EARS要件:**
+- REQ-MAS-010: 24時間以上前 → キャンセル可能
+- REQ-MAS-011: 24時間以内 → キャンセル不可
+
+**SMT-LIB2:**
+```smt2
+(set-logic QF_LRA)
+
+; 予約時刻までの残り時間（時間単位）
+(declare-const hours_until_appointment Real)
+(declare-const cancel_attempted Bool)
+(declare-const cancel_success Bool)
+
+(define-const CANCELLATION_WINDOW Real 24.0)
+
+; REQ-MAS-010: 24時間以上前ならキャンセル可能
+(assert (=> (and cancel_attempted 
+                 (>= hours_until_appointment CANCELLATION_WINDOW))
+            cancel_success))
+
+; REQ-MAS-011: 24時間以内はキャンセル不可
+(assert (=> (and cancel_attempted 
+                 (< hours_until_appointment CANCELLATION_WINDOW))
+            (not cancel_success)))
+
+(check-sat)
+```
+
+### 9.6 検証結果の解釈
+
+| 結果 | 意味 |
+|------|------|
+| **sat** | 充足可能 - 条件を満たす値が存在 |
+| **unsat** | 充足不可能 - 条件を満たす値は存在しない |
+| **unknown** | 判定不能 - タイムアウトまたは複雑すぎる |
+
+#### 安全性検証の場合
+
+```
+仕様: 「危険な状態に到達できる」
+結果: unsat → 安全性が保証される（危険な状態に到達不可能）
+結果: sat   → 反例あり（危険な状態に到達可能）
+```
+
+### 9.7 Hoareトリプル検証
+
+**Hoareトリプル**: `{P} C {Q}`
+- **P**: 事前条件（Precondition）
+- **C**: コマンド（Command）
+- **Q**: 事後条件（Postcondition）
+
+```typescript
+// 例: 残高からの引き出し
+// {P} balance >= amount && amount > 0
+// {C} balance_new := balance - amount
+// {Q} balance_new == balance - amount && balance_new >= 0
+```
+
+### 9.8 形式検証ファイルの構成
+
+```
+storage/formal-verify/
+├── FV-MAS-009-duplicate-booking.smt2   # 重複予約防止
+├── FV-MAS-010-011-cancellation.smt2    # キャンセルポリシー
+└── verification-report.json             # 検証結果レポート
+```
+
+### 9.9 検証レポート例
+
+```json
+{
+  "requirement": "REQ-MAS-009",
+  "description": "重複予約防止",
+  "formalSpec": "∀ slot ∈ TimeSlots: slot.status = 'booked' → ¬∃ new_appointment(slot)",
+  "verification": {
+    "status": "verified",
+    "result": "unsat",
+    "interpretation": "安全性が数学的に証明された",
+    "duration": 45
+  },
+  "traceability": {
+    "design": "DES-MAS-APPT-005",
+    "code": "src/appointment/duplicate-booking.validator.ts"
+  }
+}
+```
+
+### 9.10 レビュー観点
+
+| 観点 | チェック内容 |
+|------|--------------|
+| 変換精度 | EARS要件が正確にSMT-LIB2に変換されているか |
+| 検証結果 | 安全性要件が unsat（証明済み）か |
+| カバレッジ | 重要な要件が形式検証されているか |
+| 反例分析 | sat の場合、反例が妥当か |
+
+---
+
+## 10. Phase 8: テスト生成
+
+### 10.1 テスト生成コマンド
+
+```bash
+# 特定ファイルのテスト生成
+npx musubix test generate src/appointment/appointment.entity.ts
+
+# 出力
+✅ Tests generated: src/appointment/__tests__/appointment.entity.test.ts (0 test cases)
+   - Framework: vitest
+   - Style: unit
+```
+
+### 10.2 テストファイル構成
+
+```
+src/
+├── appointment/
+│   ├── appointment.entity.ts
+│   └── __tests__/
+│       ├── appointment.entity.test.ts    # 158行, 10テスト
+│       └── appointment.factory.test.ts   # Factory Pattern
+├── auth/
+│   └── __tests__/
+│       └── audit-logger.test.ts          # 110行, 9テスト（Singleton）
+└── notification/
+    └── __tests__/
+        └── notification.observer.test.ts # 138行, 9テスト（Observer）
+```
+
+**合計**: 4ファイル, 406行, 28テストケース
+
+### 10.3 テストのベストプラクティス
+
+#### BP-TEST-001: Test Counter Reset
+
+```typescript
+import { beforeEach } from 'vitest';
+import { resetAppointmentCounter } from '../appointment.entity';
+
+beforeEach(() => {
+  resetAppointmentCounter(); // IDカウンターをリセット
+});
+```
+
+#### BP-TEST-004: Result Type Test Pattern
+
+```typescript
+import { isOk, isErr } from '../../common/result';
+
+describe('createAppointment', () => {
+  // 成功ケース
+  it('should create a valid appointment', () => {
+    const result = createAppointment({ ... });
+    expect(isOk(result)).toBe(true);
+    if (isOk(result)) {
+      expect(result.value.status).toBe('scheduled');
+    }
+  });
+
+  // 失敗ケース
+  it('should reject invalid duration', () => {
+    const result = createAppointment({ durationMinutes: 0, ... });
+    expect(isErr(result)).toBe(true);
+  });
+});
+```
+
+#### BP-TEST-005: Status Transition Testing
+
+```typescript
+describe('Status Transitions', () => {
+  it('should only allow valid status transitions', () => {
+    const validTransitions: Record<AppointmentStatus, AppointmentStatus[]> = {
+      scheduled: ['confirmed', 'cancelled'],
+      confirmed: ['completed', 'no_show', 'cancelled'],
+      completed: [],
+      cancelled: [],
+      no_show: [],
+    };
+
+    // 有効な遷移
+    expect(validTransitions['scheduled']).toContain('confirmed');
+    // 無効な遷移
+    expect(validTransitions['scheduled']).not.toContain('completed');
+  });
+});
+```
+
+### 10.4 Singleton Patternのテスト
+
+```typescript
+describe('AuditLogger (Singleton)', () => {
+  // 同一インスタンスの確認
+  it('should return the same instance', () => {
+    const instance1 = AuditLogger.getInstance();
+    const instance2 = AuditLogger.getInstance();
+    expect(instance1).toBe(instance2);
+  });
+
+  // 状態の共有確認
+  it('should maintain state across getInstance calls', () => {
+    logger.log({ action: 'CREATE', ... });
+    const sameLogger = AuditLogger.getInstance();
+    expect(sameLogger.getLogs()).toHaveLength(1);
+  });
+});
+```
+
+### 10.5 Observer Patternのテスト
+
+```typescript
+describe('Notification Observer Pattern', () => {
+  it('should notify all observers', () => {
+    const emailSpy = vi.spyOn(emailObserver, 'update');
+    const smsSpy = vi.spyOn(smsObserver, 'update');
+
+    subject.attach(emailObserver);
+    subject.attach(smsObserver);
+
+    const event: NotificationEvent = {
+      type: 'APPOINTMENT_CONFIRMED',
+      appointmentId: 'APPT-001',
+      patientId: 'PAT-001',
+      message: 'Your appointment has been confirmed',
+      timestamp: new Date(),
+    };
+
+    subject.notify(event);
+
+    expect(emailSpy).toHaveBeenCalledWith(event);
+    expect(smsSpy).toHaveBeenCalledWith(event);
+  });
+});
+```
+
+### 10.6 要件トレーサビリティ
+
+各テストファイルにはトレーサビリティコメントを含めます：
+
+```typescript
+/**
+ * Appointment Entity テスト
+ * @トレース REQ-MAS-001, REQ-MAS-009, REQ-MAS-010, REQ-MAS-011
+ */
+```
+
+| テストファイル | トレース先要件 |
+|---------------|----------------|
+| appointment.entity.test.ts | REQ-MAS-001, 009, 010, 011 |
+| audit-logger.test.ts | REQ-MAS-019 |
+| notification.observer.test.ts | REQ-MAS-006, 007 |
+
+### 10.7 テスト実行
+
+```bash
+# 全テスト実行
+npx vitest run
+
+# ウォッチモード
+npx vitest
+
+# カバレッジ計測
+npx vitest run --coverage
+```
+
+---
+
+## 11. Phase 9: トレーサビリティ
+
+### 11.1 トレーサビリティとは
+
+**トレーサビリティ**は、要件→設計→実装→テストの全ての成果物間の対応関係を追跡可能にすることです。MUSUBIXは憲法条項V（Traceability）に基づき、100%の追跡可能性を要求します。
+
+### 11.2 トレーサビリティコマンド
+
+```bash
+# マトリクス生成
+npx musubix trace matrix
+
+# 出力例
+{
+  success: true,
+  entries: [...],
+  statistics: {
+    requirements: 20,
+    designs: 5,
+    tasks: 0,
+    implementations: 0,
+    tests: 0,
+    coverage: 0
+  },
+  message: 'Generated traceability matrix with 25 entries (0.0% coverage)'
+}
+```
+
+### 11.3 トレーサビリティ検証
+
+```bash
+# リンク検証
+npx musubix trace validate
+
+# 出力例
+{
+  success: true,
+  valid: true,
+  issues: [
+    {
+      type: 'orphan',
+      severity: 'warning',
+      source: 'REQ-MAS-001',
+      message: 'Requirement REQ-MAS-001 has no implementation'
+    },
+    ...
+  ],
+  summary: { total: 100, valid: 100, broken: 0, orphans: 20 },
+  message: '⚠️ Found 20 issues (0 broken links, 20 orphans)'
+}
+```
+
+### 11.4 影響分析（Impact Analysis）
+
+```bash
+# 特定要件の影響範囲を分析
+npx musubix trace impact REQ-MAS-009
+
+# 出力例
+{
+  success: true,
+  sourceId: 'REQ-MAS-009',
+  impacts: [
+    {
+      id: 'DES-MAS-001',
+      type: 'design',
+      impactLevel: 'direct',
+      description: 'Design element'
+    },
+    ...
+  ],
+  riskLevel: 'medium',
+  message: 'Found 5 impacted items (Risk: medium)'
+}
+```
+
+### 11.5 トレーサビリティマトリクス
+
+#### 要件 → 設計 マッピング
+
+| 要件ID | 要件名 | 設計ID | 設計コンポーネント |
+|--------|--------|--------|-------------------|
+| REQ-MAS-001 | 予約作成 | DES-MAS-APPT-001 | AppointmentService |
+| REQ-MAS-006 | 予約確認通知 | DES-MAS-NOTIFY-001 | NotificationService |
+| REQ-MAS-009 | 重複予約防止 | DES-MAS-APPT-005 | DuplicateBookingValidator |
+| REQ-MAS-010 | 24h前キャンセル可 | DES-MAS-APPT-006 | CancellationPolicyEnforcer |
+| REQ-MAS-015 | 患者情報暗号化 | DES-MAS-PAT-001 | PersonalInfoEncryptor |
+| REQ-MAS-019 | 監査ログ | DES-MAS-AUTH-006 | AuditLogger |
+
+#### 設計 → 実装 マッピング
+
+| 設計ID | コンポーネント | 実装ファイル |
+|--------|---------------|--------------|
+| DES-MAS-APPT-001 | AppointmentEntity | appointment.entity.ts |
+| DES-MAS-APPT-008 | AppointmentFactory | appointment.factory.ts |
+| DES-MAS-AUTH-006 | AuditLogger | audit-logger.ts |
+| DES-MAS-PAT-001 | PersonalInfoEncryptor | personal-info-encryptor.ts |
+| DES-MAS-NOTIFY-004 | NotificationObserver | notification.observer.ts |
+
+#### 実装 → テスト マッピング
+
+| 実装ファイル | テストファイル | テスト数 |
+|-------------|---------------|----------|
+| appointment.entity.ts | appointment.entity.test.ts | 10 |
+| audit-logger.ts | audit-logger.test.ts | 9 |
+| notification.observer.ts | notification.observer.test.ts | 9 |
+
+### 11.6 カバレッジサマリー
+
+| カテゴリ | 総数 | 設計済み | 実装済み | テスト済み | カバレッジ |
+|---------|------|---------|---------|-----------|-----------|
+| 予約管理 | 5 | 5 | 3 | 1 | 60% |
+| 通知 | 3 | 3 | 1 | 1 | 33% |
+| セキュリティ | 8 | 8 | 3 | 1 | 37% |
+| レポート | 1 | 1 | 0 | 0 | 0% |
+| **合計** | **20** | **20** | **11** | **4** | **55%** |
+
+### 11.7 コード内トレーサビリティ
+
+ソースコード内に `@トレース` コメントを追加して追跡性を確保：
+
+```typescript
+/**
+ * 予約エンティティ
+ * @トレース REQ-MAS-001, REQ-MAS-009
+ * @設計 DES-MAS-APPT-001
+ */
+export interface Appointment {
+  // ...
+}
+```
+
+### 11.8 トレーサビリティファイル
+
+```
+storage/traceability/
+└── trace-matrix.md   # 完全なトレーサビリティマトリクス
+```
+
+---
+
+## 12. 高度な機能（v2.2.0）
+
+### 12.1 自己学習システム
+
+MUSUBIXは開発パターンを学習し、プロジェクト固有の推奨を提供します。
+
+#### パターン登録
+
+```bash
+# デザインパターンを登録
+npx musubix learn add-pattern "Factory Pattern" \
+  --category code \
+  --confidence 0.95 \
+  --action prefer \
+  --content "Use Factory pattern for entity creation with validation" \
+  --language typescript
+
+# 出力
+✓ Pattern created: PAT-306D4DBC
+  Name: Factory Pattern
+  Category: code
+  Action: prefer
+  Confidence: 95.0%
+```
+
+#### フィードバック記録
+
+```bash
+# 要件へのフィードバック
+npx musubix learn feedback REQ-MAS-001 \
+  --type accept \
+  --artifact-type requirement \
+  --reason "Well-defined EARS requirement"
+
+# 出力
+✓ Feedback recorded: FB-84B8AD1F
+  Type: accept
+  Artifact: requirement/REQ-MAS-001
+```
+
+#### パターン一覧表示
+
+```bash
+npx musubix learn patterns
+
+# 出力
+Learned Patterns:
+────────────────────────────────────────────────────────────────
+  PAT-306D4DBC - Factory Pattern
+    Category: code, Action: prefer
+    Confidence: 95.0%, Occurrences: 1
+
+  PAT-93076A30 - Result Type Error Handling
+    Category: code, Action: prefer
+    Confidence: 95.0%, Occurrences: 1
+
+  PAT-6942ADA5 - Singleton Pattern
+    Category: design, Action: prefer
+    Confidence: 90.0%, Occurrences: 1
+
+  PAT-5910460B - Observer Pattern
+    Category: design, Action: prefer
+    Confidence: 90.0%, Occurrences: 1
+
+Total: 4 patterns
+```
+
+#### 学習ステータス
+
+```bash
+npx musubix learn status
+
+# 出力
+# MUSUBIX Learning Status Report
+
+## Summary
+- Total Feedback: 1
+- Total Patterns: 4
+- Average Confidence: 92.5%
+
+## Feedback by Type
+- Accept: 1
+- Reject: 0
+- Modify: 0
+
+## High Confidence Patterns (≥70%)
+- Factory Pattern (95.0%)
+- Result Type Error Handling (95.0%)
+- Singleton Pattern (90.0%)
+- Observer Pattern (90.0%)
+```
+
+#### 学習データのエクスポート/インポート
+
+```bash
+# エクスポート
+npx musubix learn export --output storage/learning/patterns-export.json
+
+# インポート
+npx musubix learn import storage/learning/patterns-export.json
+```
+
+**エクスポート形式:**
+```json
+{
+  "feedback": [
+    {
+      "id": "FB-84B8AD1F",
+      "timestamp": "2026-01-08T14:28:56.411Z",
+      "type": "accept",
+      "artifactType": "requirement",
+      "artifactId": "REQ-MAS-001",
+      "reason": "Well-defined EARS requirement"
+    }
+  ],
+  "patterns": [
+    {
+      "id": "PAT-306D4DBC",
+      "name": "Factory Pattern",
+      "category": "code",
+      "action": { "type": "prefer", "content": "..." },
+      "confidence": 0.95,
+      "occurrences": 1
+    }
+  ]
+}
+```
+
+### 12.2 Neural Search（プログラムAPI）
+
+v2.2.0では、コード検索のためのNeural Search APIが追加されました。
+
+```typescript
+import {
+  ContextAwareEmbedder,
+  HybridRanker,
+  EmbeddingCache,
+  createTrajectoryLogger,
+} from '@nahisaho/musubix-neural-search';
+
+// 検索軌跡のロギング
+const logger = createTrajectoryLogger();
+logger.logBranch({ depth: 1, score: 0.85, action: 'expand' });
+logger.logBranch({ depth: 2, score: 0.92, action: 'select' });
+
+// Parquet形式でエクスポート
+const parquet = logger.export('parquet');
+
+// ハイブリッドランキング（BM25 + ベクトル類似度）
+const ranker = new HybridRanker();
+const results = ranker.rank(query, candidates, {
+  bm25Weight: 0.3,
+  vectorWeight: 0.7,
+});
+```
+
+### 12.3 Library Learner（プログラムAPI）
+
+APIパターンの学習とバージョン管理を提供します。
+
+```typescript
+import {
+  SemanticChunker,
+  PatternVersionManager,
+  createMetricsExporter,
+} from '@nahisaho/musubix-library-learner';
+
+// パターンバージョン管理
+const versionManager = new PatternVersionManager();
+versionManager.commit(pattern, 'Added validation logic');
+const history = versionManager.getHistory(patternId);
+
+// メトリクスエクスポート
+const exporter = createMetricsExporter(library);
+const markdown = exporter.export('markdown');
+const summary = exporter.getSummary();
+// { healthStatus: 'good', patternCount: 42, avgConfidence: 0.87 }
+```
+
+### 12.4 Program Synthesis（プログラムAPI）
+
+例題からプログラムを合成します。
+
+```typescript
+import {
+  createMetaLearningEngine,
+  createExampleAnalyzer,
+  createExplanationGenerator,
+} from '@nahisaho/musubix-synthesis';
+
+// 例題品質分析
+const analyzer = createExampleAnalyzer();
+const quality = analyzer.analyze([
+  { input: 'hello', output: 'HELLO' },
+  { input: 'world', output: 'WORLD' },
+]);
+// { coverage: 0.8, diversity: 0.6, complexity: 'low' }
+
+// プログラム合成
+const engine = createMetaLearningEngine();
+const program = await engine.synthesize(examples);
+
+// 説明生成
+const explainer = createExplanationGenerator();
+const explanation = explainer.generate(program);
+const summary = explainer.summarize(program);
+// "Converts input string to uppercase"
+```
+
+### 12.5 学習データファイル
+
+```
+storage/learning/
+└── patterns-export.json   # 学習データエクスポート
+    - feedback: フィードバック履歴
+    - patterns: 学習済みパターン
+```
+
+---
+
+## 13. プロジェクトサマリー
+
+### 13.1 Medical Appointment System 完成状況
+
+本ガイドで構築した **Medical Appointment System** の最終成果物です。
+
+#### プロジェクト統計
+
+| 項目 | 数値 |
+|------|------|
+| **EARS要件** | 20件（5カテゴリ） |
+| **設計コンポーネント** | 19件（C4モデル） |
+| **実装タスク** | 45件（117時間） |
+| **TypeScriptファイル** | 11件（742行） |
+| **テストファイル** | 4件（406行、28テスト） |
+| **設計パターン** | 3種（Factory, Singleton, Observer） |
+| **学習パターン** | 4件（92.5%平均信頼度） |
+
+#### フェーズ別成果物
+
+| Phase | 成果物 | ファイル |
+|-------|--------|---------|
+| 1 | プロジェクト初期化 | `musubix.config.json` |
+| 2 | EARS要件定義 | `storage/specs/REQ-MAS-requirements.md` |
+| 3 | C4モデル設計 | `storage/design/DES-MAS-design.md` |
+| 4 | タスク分解 | `storage/tasks/TSK-MAS-tasks.md` |
+| 5 | コード生成 | `src/**/*.ts`（11ファイル） |
+| 6 | セキュリティ分析 | スコア 100/100 |
+| 7 | 形式検証 | `storage/formal-verify/*.smt2` |
+| 8 | テスト生成 | `src/**/__tests__/*.test.ts` |
+| 9 | トレーサビリティ | `storage/traceability/trace-matrix.md` |
+| 10 | 学習データ | `storage/learning/patterns-export.json` |
+
+#### ディレクトリ構造
+
+```
+/tmp/medical-appointment-system/
+├── musubix.config.json
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── common/
+│   │   ├── result.ts
+│   │   ├── errors.ts
+│   │   └── id-generator.ts
+│   ├── appointment/
+│   │   ├── appointment.entity.ts
+│   │   ├── appointment.factory.ts
+│   │   ├── duplicate-booking.validator.ts
+│   │   ├── cancellation-policy.enforcer.ts
+│   │   └── __tests__/
+│   │       ├── appointment.entity.test.ts
+│   │       └── appointment.factory.test.ts
+│   ├── auth/
+│   │   ├── audit-logger.ts
+│   │   ├── password-hasher.ts
+│   │   └── __tests__/
+│   │       └── audit-logger.test.ts
+│   ├── patient/
+│   │   └── personal-info-encryptor.ts
+│   └── notification/
+│       ├── notification.observer.ts
+│       └── __tests__/
+│           └── notification.observer.test.ts
+└── storage/
+    ├── specs/
+    │   └── REQ-MAS-requirements.md
+    ├── design/
+    │   └── DES-MAS-design.md
+    ├── tasks/
+    │   └── TSK-MAS-tasks.md
+    ├── formal-verify/
+    │   ├── FV-MAS-009-duplicate-booking.smt2
+    │   └── FV-MAS-010-011-cancellation.smt2
+    ├── traceability/
+    │   └── trace-matrix.md
+    └── learning/
+        └── patterns-export.json
+```
+
+### 13.2 使用したMUSUBIXコマンド
+
+```bash
+# Phase 1: 初期化
+npx musubix init /tmp/medical-appointment-system
+
+# Phase 2: 要件検証
+npx musubix requirements validate storage/specs/REQ-MAS-requirements.md
+
+# Phase 5: コード生成
+npx musubix codegen generate storage/design/DES-MAS-design.md
+
+# Phase 6: セキュリティ分析
+npx musubix codegen security src/
+npx musubix codegen analyze src/
+
+# Phase 8: テスト生成
+npx musubix test generate src/appointment/appointment.entity.ts
+
+# Phase 9: トレーサビリティ
+npx musubix trace matrix
+npx musubix trace validate
+npx musubix trace impact REQ-MAS-009
+
+# Phase 10: 自己学習
+npx musubix learn add-pattern "Factory Pattern" --category code --action prefer
+npx musubix learn feedback REQ-MAS-001 --type accept --artifact-type requirement
+npx musubix learn patterns
+npx musubix learn status
+npx musubix learn export --output storage/learning/patterns-export.json
+```
+
+### 13.3 品質メトリクス
+
+| メトリクス | 値 | 基準 |
+|-----------|-----|------|
+| セキュリティスコア | 100/100 | ≥80 |
+| 脆弱性検出 | 0件 | 0 |
+| EARS準拠率 | 100% | 100% |
+| トレーサビリティカバレッジ | 55% | ≥80%（目標） |
+| パターン信頼度 | 92.5% | ≥70% |
+
+---
+
+## 14. その他の機能
+
+本ガイドで使用しなかったMUSUBIXの機能を紹介します。
+
+### 14.1 要件分析の自動化
+
+#### 自然言語からEARS変換
+
+```bash
+# 自然言語の要件をEARS形式に自動変換
+npx musubix requirements analyze "ユーザーはログインできる必要がある"
+
+# 出力例
+THE system SHALL allow users to login with valid credentials.
+Pattern: Ubiquitous
+```
+
+#### オントロジーマッピング
+
+```bash
+# 要件を知識グラフにマッピング
+npx musubix requirements map storage/specs/REQ-*.md
+
+# 関連要件の検索
+npx musubix requirements search "authentication"
+```
+
+#### 対話的要件作成
+
+```bash
+# 対話形式で要件を作成
+npx musubix requirements new "user-authentication"
+```
+
+### 14.2 設計自動生成
+
+#### 要件から設計を生成
+
+```bash
+# 要件ファイルから設計を自動生成
+npx musubix design generate storage/specs/REQ-MAS-requirements.md
+
+# C4ダイアグラム生成
+npx musubix design c4 storage/design/DES-MAS-design.md
+
+# SOLID準拠検証
+npx musubix design validate storage/design/DES-MAS-design.md
+```
+
+#### パターン検出
+
+```bash
+# コンテキストに適したパターンを検出
+npx musubix design patterns "notification system with multiple channels"
+
+# 出力例
+Recommended patterns:
+- Observer Pattern (confidence: 95%)
+- Strategy Pattern (confidence: 78%)
+```
+
+#### ADR生成
+
+```bash
+# Architecture Decision Record を生成
+npx musubix design adr "Use Observer pattern for notifications"
+```
+
+### 14.3 説明・可視化
+
+#### 決定理由の説明
+
+```bash
+# なぜその決定がされたかを説明
+npx musubix explain why DES-MAS-NOTIFY-004
+
+# 出力例
+Decision: Use Observer Pattern
+Reason: Multiple notification channels (Email, SMS, Push) require
+        loose coupling and independent notification delivery.
+Trace: REQ-MAS-006 → REQ-MAS-007 → REQ-MAS-008
+```
+
+#### 推論グラフ生成
+
+```bash
+# 推論の過程をグラフとして可視化
+npx musubix explain graph REQ-MAS-009 --output reasoning.svg
+```
+
+### 14.4 オントロジー操作
+
+#### 知識グラフ検証
+
+```bash
+# 知識グラフの整合性検証
+npx musubix ontology validate -f storage/knowledge/kg.ttl
+
+# 循環依存チェック
+npx musubix ontology check-circular -f storage/knowledge/kg.ttl
+
+# 統計表示
+npx musubix ontology stats -f storage/knowledge/kg.ttl
+```
+
+### 14.5 KGPR（Knowledge Graph Pull Request）
+
+知識を他のプロジェクトと共有するための機能です。
+
+```bash
+# KGPRの作成
+npx musubix kgpr create -t "Medical Appointment Patterns"
+
+# 差分プレビュー
+npx musubix kgpr diff
+
+# KGPR一覧
+npx musubix kgpr list
+
+# 送信
+npx musubix kgpr submit <id>
+
+# 詳細表示
+npx musubix kgpr show <id>
+
+# クローズ
+npx musubix kgpr close <id>
+```
+
+### 14.6 プロジェクトスキャフォールド
+
+#### DDDプロジェクト生成
+
+```bash
+# ドメイン駆動設計プロジェクトを生成
+npx musubix scaffold domain-model medical-system \
+  -e "Patient,Appointment,Doctor" \
+  -d MEDICAL
+
+# 最小構成プロジェクト
+npx musubix scaffold minimal my-project
+
+# APIサービス
+npx musubix scaffold api-service user-service
+```
+
+### 14.7 プログラム合成
+
+例題からプログラムを自動合成します。
+
+```bash
+# 例題ファイルからプログラム合成
+npx musubix synthesize examples.json
+
+# examples.json の形式
+[
+  { "input": "hello", "output": "HELLO" },
+  { "input": "world", "output": "WORLD" }
+]
+
+# 出力: function transform(input) { return input.toUpperCase(); }
+```
+
+### 14.8 対話的REPL
+
+```bash
+# 対話的シェルを起動
+npx musubix repl
+
+# REPLコマンド例
+musubix> requirements validate REQ-001
+musubix> trace impact REQ-001
+musubix> learn status
+musubix> .exit
+```
+
+### 14.9 パフォーマンスベンチマーク
+
+```bash
+# パフォーマンス計測
+npx musubix perf benchmark
+
+# 出力例
+Benchmark Results:
+- Requirements validation: 45ms
+- Design generation: 230ms
+- Code analysis: 180ms
+```
+
+### 14.10 追加の学習コマンド
+
+```bash
+# コンテキストベースの推奨
+npx musubix learn recommend --artifact-type code --language typescript
+
+# 未使用パターンの減衰
+npx musubix learn decay --threshold 30 --factor 0.9
+
+# 学習データのインポート
+npx musubix learn import shared-patterns.json --merge-strategy merge
+
+# パターン削除
+npx musubix learn remove-pattern PAT-XXXXXX
+```
+
+### 14.11 タスク管理
+
+```bash
+# タスク一覧
+npx musubix tasks list
+
+# タスク検証
+npx musubix tasks validate storage/tasks/TSK-*.md
+```
+
+### 14.12 パターンライブラリ
+
+```bash
+# ライブラリ統計
+npx musubix library stats
+
+# パターン検索
+npx musubix library query "error handling"
+
+# コードからパターン学習
+npx musubix library learn src/
+```
+
+### 14.13 GitHub Agent Skills
+
+```bash
+# スキル一覧
+npx musubix skills list
+
+# スキル追加
+npx musubix skills add pattern-recognition
+```
+
+---
+
+## 付録
+
+### 付録A: 9条憲法
+
+| 条項 | 名称 | 概要 |
+|-----|------|------|
+| I | Library-First | 機能は独立ライブラリとして開始 |
+| II | CLI Interface | すべてのライブラリはCLI公開必須 |
+| III | Test-First | Red-Green-Blueサイクルでテスト先行 |
+| IV | EARS Format | 要件はEARS形式で記述 |
+| V | Traceability | 要件↔設計↔コード↔テストの100%追跡 |
+| VI | Project Memory | steering/を参照してから決定 |
+| VII | Design Patterns | 設計パターン適用の文書化 |
+| VIII | Decision Records | すべての決定をADRで記録 |
+| IX | Quality Gates | フェーズ移行前の品質検証 |
+
+
+### 付録B: CLIコマンド一覧
+
+| コマンド | 説明 |
+|---------|------|
+| `musubix init` | プロジェクト初期化 |
+| `musubix requirements analyze` | 要件分析（自然言語→EARS） |
+| `musubix requirements validate` | 要件検証 |
+| `musubix design generate` | 設計生成 |
+| `musubix design patterns` | パターン検出 |
+| `musubix codegen generate` | コード生成 |
+| `musubix codegen analyze` | 静的解析 |
+| `musubix codegen security` | セキュリティスキャン |
+| `musubix test generate` | テスト生成 |
+| `musubix trace matrix` | トレーサビリティマトリクス |
+| `musubix trace validate` | リンク検証 |
+| `musubix trace impact` | 影響分析 |
+| `musubix learn add-pattern` | パターン登録 |
+| `musubix learn feedback` | フィードバック記録 |
+| `musubix learn patterns` | パターン一覧 |
+| `musubix learn status` | 学習ステータス |
+| `musubix learn export` | 学習データエクスポート |
+
+### 付録C: ファイル構成
+
+```
+storage/
+├── specs/           # EARS要件定義
+│   └── REQ-*.md
+├── design/          # C4モデル設計
+│   └── DES-*.md
+├── tasks/           # タスク分解
+│   └── TSK-*.md
+├── formal-verify/   # SMT-LIB2形式検証
+│   └── FV-*.smt2
+├── traceability/    # トレーサビリティマトリクス
+│   └── trace-matrix.md
+└── learning/        # 学習データ
+    └── patterns-export.json
+```
+
+### 付録D: EARSパターン早見表
+
+| パターン | 構文 | 例 |
+|---------|------|-----|
+| Ubiquitous | `THE [system] SHALL [action]` | THE system SHALL encrypt all patient data |
+| Event-driven | `WHEN [event], THE [system] SHALL [action]` | WHEN appointment is confirmed, THE system SHALL send notification |
+| State-driven | `WHILE [state], THE [system] SHALL [action]` | WHILE user is logged in, THE system SHALL maintain session |
+| Unwanted | `THE [system] SHALL NOT [action]` | THE system SHALL NOT allow duplicate bookings |
+| Optional | `IF [condition], THEN THE [system] SHALL [action]` | IF cancellation is within 24h, THEN THE system SHALL reject |
+
+---
+
+**Document Version**: 1.0.0  
+**Generated**: 2026-01-09  
+**MUSUBIX Version**: 2.2.0  
+**Project**: Medical Appointment System