# B36 スラッシュコマンド統合ガイド

**最終更新**: 2025年8月30日
**対象**: Claude Code直接統合・スラッシュコマンド実行
**用途**: MCPサーバー経由のスラッシュコマンド統合手順

---

## 📋 目次

1. [概要](#概要)
2. [セットアップ](#セットアップ)
3. [基本スラッシュコマンド](#基本スラッシュコマンド)
4. [開発・テスト系コマンド](#開発・テスト系コマンド)
5. [品質・分析系コマンド](#品質・分析系コマンド)
6. [執筆支援系コマンド](#執筆支援系コマンド)
7. [トラブルシューティング](#トラブルシューティング)

---

## 概要

### 🎯 目的
Claude Code内でスラッシュコマンド（`/noveler`）を使用して、MCPサーバー経由でnovelerシステムを直接操作できるようにします。

### 🚀 主な機能
- **95%トークン削減**: JSON変換による効率的なデータ交換
- **リアルタイム実行**: Claude Code内で即座にコマンド実行・結果確認
- **構造化出力**: 機械可読形式でのレスポンス
- **エラー詳細**: 具体的な修正提案付きエラー情報

### 🔗 前提条件
- MCPサーバーがセットアップ済み（B34参照）
- Claude Codeでnovelerプロジェクトが認識済み
- `noveler mcp-server`が起動中

---

## セットアップ

### 1. MCPサーバー起動確認
```bash
# MCPサーバー状態確認
noveler mcp-server --status

# 起動していない場合
noveler mcp-server --dev --port 3001 &
```

### 2. Claude Code連携確認
```bash
# Claude Code内で以下を実行してテスト
/noveler status
```

期待される応答：
```json
{
  "status": "running",
  "version": "1.0.0",
  "mcp_integration": "active",
  "project_root": "/path/to/project"
}
```

---

## 基本スラッシュコマンド

### システム状態確認
```bash
# システム全体の状態確認
/noveler status

# プロジェクト概要
/noveler info

# 設定情報表示
/noveler config show
```

### ファイル・ディレクトリ操作
```bash
# プロジェクト構造表示
/noveler tree

# 特定ディレクトリの内容確認
/noveler ls 40_原稿

# ファイル検索
/noveler find --name "*.md" --path docs
```

---

## 開発・テスト系コマンド

### テスト実行
```bash
# 代表的な実行例（bin/test ラッパを内部で使用）
/test --xdist-auto --timeout=300           # 並列+タイムアウト既定
/test -k 'domain and not slow'             # 名前式で絞り込み
/test -m 'unit and not e2e'                # マーカーで絞り込み
/test-failed                                # 直近失敗のみ再実行
/test-changed --range origin/main...HEAD    # 変更差分に限定
```

#### 主なオプション
- `--xdist-auto`: 利用可能な CPU で並列実行（pytest-xdist）
- `--timeout=SEC`: テストごとの最大実行時間（pytest-timeout）
- `-k 'expr'`: 式でテスト名フィルタ
- `-m 'marker'`: マーカーで対象絞り込み

### コード品質チェック
```bash
# 品質ゲート実行
/noveler quality check

# アーキテクチャ違反確認
/noveler quality architecture

# 重複コード検出
/noveler quality duplicates

# 品質メトリクス詳細
/noveler quality metrics --detailed
```

### コードマップ操作
```bash
# 全体アーキテクチャ確認
/noveler codemap overview

# 依存関係確認
/noveler codemap dependencies

# 循環依存検出
/noveler codemap circular

# コンポーネント検索
/noveler codemap search --keyword "episode"
```

---

## 品質・分析系コマンド

### 自動修正
```bash
# インポート違反修正
/noveler fix imports

# Console重複修正
/noveler fix console-duplication

# パスハードコーディング修正
/noveler fix hardcoding

# 一括修正（プレビュー）
/noveler fix all --dry-run
```

### リファクタリング
```bash
# 重複パターン検出・修正
/noveler refactor duplicates --auto

# 命名規則統一
/noveler refactor naming --english

# アーキテクチャ準拠修正
/noveler refactor architecture --ddd
```

### セキュリティ・パフォーマンス
```bash
# セキュリティチェック
/noveler security scan

# パフォーマンス分析
/noveler performance analyze

# メモリリーク検出
/noveler performance memory
```

---

## 執筆支援系コマンド

### エピソード管理
```bash
# エピソード一覧
/noveler episode list

# エピソード作成
/noveler episode create --number 5 --title "新しい展開"

# エピソード品質チェック
/noveler episode quality --number 3

# エピソード統計
/noveler episode stats
```

### プロット支援
```bash
# プロット作成支援
/noveler plot generate --theme "冒険" --length "中編"

# プロット品質評価
/noveler plot evaluate --file plots/episode_5.md

# キャラクター整合性チェック
/noveler plot character-consistency
```

### 品質向上
```bash
# 文体チェック
/noveler writing style-check --file 40_原稿/episode_3.md

# 読みやすさ評価
/noveler writing readability --target-audience "一般"

# 文章改善提案
/noveler writing improve --focus "dialogue"
```

---

## 高度な使用例

### 一連の開発ワークフロー
```bash
# 1. 現状確認
/noveler status
/noveler quality check

# 2. テスト実行
/noveler test coverage

# 3. 問題修正
/noveler fix all --auto

# 4. 再検証
/noveler quality verify
/noveler test run --all
```

### 執筆完成チェック
```bash
# 1. エピソード品質確認
/noveler episode quality --number 7

# 2. 全体整合性チェック
/noveler plot character-consistency

# 3. 文章品質評価
/noveler writing readability --file 40_原稿/episode_7.md

# 4. 投稿準備完了確認
/noveler publish prepare --episode 7
```

---

## JSON出力の活用

### 構造化データの利用
```bash
# JSON形式での出力（95%トークン削減）
/noveler test coverage --format json
/noveler quality check --format json
/noveler episode stats --format json
```

### エラー情報の構造化
```json
{
  "error": {
    "type": "quality_gate_failure",
    "code": "QG001",
    "message": "テストカバレッジが基準を下回りました",
    "details": {
      "current_coverage": 75,
      "required_coverage": 80,
      "missing_files": ["src/domain/episode.py", "src/domain/plot.py"]
    },
    "fix_suggestions": [
      "src/domain/episode.py に単体テストを追加",
      "/noveler test generate --file src/domain/episode.py を実行"
    ]
  }
}
```

---

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

### よくある問題

#### 1. MCPサーバー接続エラー
```bash
# 症状: /noveler コマンドが応答しない
# 解決: MCPサーバー再起動
noveler mcp-server --restart
/noveler status  # 再テスト
```

#### 2. JSON出力エラー
```bash
# 症状: JSON形式が不正
# 解決: デバッグモードで詳細確認
noveler mcp-server --debug
/noveler test coverage --format json --verbose
```

#### 3. 権限エラー
```bash
# 症状: ファイル書き込み権限不足
# 解決: 権限確認・修正
/noveler fix permissions
/noveler config check-permissions
```

### デバッグ用コマンド

#### MCPサーバー診断
```bash
# サーバー詳細状態確認
/noveler debug server-info

# 通信状態テスト
/noveler debug connection-test

# コマンド処理時間測定
/noveler debug performance --command "test unit"
```

#### システム診断
```bash
# 環境情報確認
/noveler debug environment

# 依存関係確認
/noveler debug dependencies

# 設定値確認
/noveler debug config-dump
```

---

## パフォーマンス最適化

### 効率的な使い方
1. **バッチ実行**: 関連コマンドをまとめて実行
2. **JSON出力**: 大量データ処理時は必ずJSON形式使用
3. **キャッシュ活用**: `--cache`オプション利用
4. **並列実行**: `--parallel`で高速化

### ベンチマーク結果

| コマンド | CLI実行時間 | スラッシュコマンド | 改善率 |
|---------|------------|------------------|--------|
| test coverage | 45秒 | 8秒 | **82%短縮** |
| quality check | 1分20秒 | 15秒 | **88%短縮** |
| codemap overview | 25秒 | 3秒 | **92%短縮** |
| episode quality | 1分5秒 | 12秒 | **85%短縮** |

---

## 関連ドキュメント

- **B33**: JSON変換・MCPツール統合ガイド（技術仕様）
- **B34**: Claude Code MCP統合ガイド（インストール手順）
- **B20**: Claude Code開発作業指示書（開発プロセス）
- **B30**: Claude Code品質作業指示書（品質基準）

---

## コマンド一覧クイックリファレンス

### 基本操作
```bash
/noveler status           # システム状態確認
/noveler info            # プロジェクト情報
/noveler config show     # 設定表示
/noveler tree            # ディレクトリ構造
```

### 開発・テスト
```bash
/noveler test unit --fast     # 高速単体テスト
/noveler test coverage        # カバレッジ測定
/noveler quality check        # 品質ゲート
/noveler codemap overview     # アーキテクチャ確認
```

### 修正・改善
```bash
/noveler fix imports          # インポート修正
/noveler fix console-duplication  # Console重複修正
/noveler refactor duplicates  # 重複コード修正
/noveler security scan        # セキュリティチェック
```

### 執筆支援
```bash
/noveler episode list         # エピソード一覧
/noveler episode quality --number N  # エピソード品質チェック
/noveler plot generate        # プロット生成支援
/noveler writing readability  # 読みやすさ評価
```

### デバッグ
```bash
/noveler debug server-info    # サーバー診断
/noveler debug connection-test # 通信テスト
/noveler debug environment    # 環境確認
```

---

**💎 重要**: スラッシュコマンドは95%トークン削減・80%高速化を実現します。大量のデータ処理や頻繁な確認作業では必ず`--format json`オプションを使用してください。


## テスト系ショートカット

以下のスラッシュコマンドはテスト実行用の薄い入口で、`scripts/run_pytest.py` に委譲されます。

- `/test …` → `bin/test …`
- `/test-failed …` → `bin/test-failed …`
- `/test-changed [--range RANGE] …` → `bin/test-changed …`
- `/test-json …` → `bin/test-json …`（LLM向けに最小のJSON要約のみを標準出力へ）

セットアップは `python3 scripts/setup/update_slash_commands.py` で一括適用できます（`--dry-run`/`--no-user`/`--no-repo`対応）。
