# A32_執筆コマンドガイド（CLIレガシー・参照用）

重要（廃止告知）: 旧レガシーCLIである `novel` コマンドは廃止済みです。以後は `noveler`（統合CLI）および MCP ツールをご利用ください。本ドキュメントは歴史的資料として保持されます。最新の移行手順は [migration guide](migration/novel_to_noveler.md) を参照してください。

**役割**: 技術的操作方法（x2 - 作業ガイド）

小説執筆支援システムの統合CLIコマンド`noveler`のリファレンスです。本ドキュメントはCLI時代のガイドを歴史的資料として保持しています。標準はMCPツール運用（Claude Code連携）へ移行済みです。最新の運用は以下を参照してください。

- B33_MCPツール統合ガイド.md
- [MCPツール活用ベストプラクティス](mcp/tools_usage_best_practices.md)
- A31_新システム利用ガイド（MCP版）

## MCP移行の対応表（抜粋）



> 重要: CLI 役割分離（現行）
> - `noveler check` は品質『評価』の導線（スコア算出・軽量オートフィクス）。
> - `noveler polish` は推敲『改稿』の導線（Stage2/Stage3、`dry_run`で適用制御）。
> - 内部ステート/テンプレ管理は ProgressiveCheckManager に統合。
<!-- CLI_SPLIT_A32 -->

| 旧CLIコマンド | 現在のMCPツール/ラッパー |
|---|---|
| `noveler check 1` | `run_quality_checks`（`format: summary`推奨） |
| `noveler check 1 --auto-fix` | `fix_quality_issues`（`dry_run: false`） |
| style拡張機能（opt-in） | `fix_style_extended`（`dry_run: true`デフォルト） |
| `noveler write 1` | `get_writing_tasks`/`execute_writing_step`（段階実行） |
| `noveler complete-episode 1` | `export_quality_report` 等で成果物出力 |
| `noveler watch` | MCP経由のツール実行 + CI/タスクランナー連携 |

## 🌐 グローバルコマンド対応（2025年9月1日追加）

**新機能**: `/noveler` グローバルコマンドにより、任意の場所から小説執筆支援機能を利用可能。

### インストール方法
```bash
python scripts/install_global_command.py
```

### 使用例
```bash
# 任意のディレクトリから実行可能
/noveler write 1           # 第1話執筆
/noveler check 1           # 第1話品質チェック
/noveler status            # プロジェクト状況確認
/noveler init my-novel     # 新規プロジェクト作成
```

> **執筆段階基本フロー（FLOW）は**: [A30_執筆ワークフロー.md](A30_執筆ワークフロー.md)
> **品質管理チェック（CHECK）は**: [A33_執筆品質管理チェック.md](A33_執筆品質管理チェック.md)
> **統合ワークフロー実装は**: [A34_一気通貫実践ガイド.md](A34_一気通貫実践ガイド.md)
> **詳細プロンプト実装は**: [A38_執筆プロンプトガイド.md](A38_執筆プロンプトガイド.md)

**前提**: A33_執筆品質管理チェック理解済み
**対象**: CLI操作・自動化・システム活用
**成果物**: 効率的な執筆支援システム活用

> **最終更新**: 2025年8月8日（Deep Mode分析・完全最新化版）
> **初心者向けガイド**: [01_クイックスタート](01_クイックスタート.md)

## ✅ 実装状況更新（2025年8月8日最新化）

**現在の実装状況**: 主要システムが完全実装され、高度なワークフローが完全に動作します。

### 🚀 完全実装済みコマンド（2025年8月8日最新版）
- `novel --help` - メインヘルプ表示
- **`novel check` - Smart Auto-Enhancement品質チェック（🆕デフォルト・完全自動化）**
- `novel check --prompt` - Claude分析プロンプト生成（🆕自己トリガー機能付き）
- `novel check --standard` - 従来段階的品質チェック（レガシーモード）
- `novel claude-export` - Claude向けエラー情報エクスポート
- `novel watch` - リアルタイムファイル監視
- `novel health` - システムヘルス管理・診断
- `novel backup` - バックアップ管理・復元
- **`novel plot episode` - 話別プロット生成（7モード対応・完全実装）**
- **`novel create` - 新規プロジェクト作成（完全動作）**
- **`novel write` - 執筆開始（完全動作）**
- **`novel complete-episode` - エピソード完成処理（完全実装）**

### 🔧 部分実装・開発継続中
- `novel analyze` - アクセス分析（未実装）
- `novel scene` - 重要シーン管理（部分実装）

### 🆕 新機能（2025年8月8日追加）
- **段階的プロンプト生成システム**: Stage 1-5による段階的品質向上
- **統合コンテキスト分析**: A31全項目統合分析システム
- **双方向実行システム**: 前話分析＋動的プロンプト生成統合

---

## 📚 コマンド一覧（カテゴリ別）

### 🔧 動作確認済みコマンド（実装完了・2025年8月8日更新）
| コマンド | 説明 | 主な用途 | 実装状況 |
|---------|------|---------|----------|
| **`novel check`** | **🆕 Smart Auto-Enhancement（デフォルト）** | **ワンコマンド全工程完了** | ✅ **完全実装** |
| `novel check --prompt` | 🆕 Claude分析プロンプト生成 | プロンプト生成+自己トリガー | ✅ **完全実装** |
| `novel check --standard` | 従来段階的品質チェック（レガシー） | 段階的実行モード | ✅ 完全実装 |

> 📚 **詳細ガイド**: [A33_執筆品質管理チェック.md](A33_執筆品質管理チェック.md)
| `novel claude-export` | Claude向けエラー情報エクスポート | エラー構造化出力 | ✅ 完全実装 |
| `novel watch` | ファイル監視（自動エラーチェック） | リアルタイム品質監視 | ✅ 完全実装 |
| `novel complete-episode` | エピソード完成処理 | ステータス更新 | ✅ 完全実装 |
| `novel health` | システムヘルス管理 | システム診断・監視 | ✅ 完全実装 |
| `novel backup` | バックアップ管理 | データ保護・復元 | ✅ 完全実装 |
| `novel test` | テスト実行 | システムテスト | ✅ 動作確認済み |
| `novel create` | 新規プロジェクト作成 | プロジェクト初期化 | ✅ 完全実装 |
| `novel write` | 執筆作業開始 | 執筆チェックリスト表示 | ✅ 完全実装 |
| `novel plot` | プロット管理 | プロット作成・管理 | ✅ 完全実装 |

### ⚠️ 開発中・修正必要コマンド
| コマンド | 説明 | 問題点 | 対応状況 |
|---------|------|--------|----------|
| `novel analyze` | アクセス分析 | 未実装 | ❌ 開発待ち |
| `novel scene` | 重要シーン管理 | 部分実装 | 🔧 開発中 |

---

## 🎯 主要コマンド詳細

### `novel create` - 新規プロジェクト作成（旧：`novel new`）

#### 目的
新しい小説プロジェクトを作成し、標準的なフォルダ構造とテンプレートファイルを自動生成します。

#### 構文
```bash
novel create <プロジェクト名> [オプション]
```

#### 引数
- `<プロジェクト名>`: 作成するプロジェクトの名前（必須）

#### オプション
| オプション | 説明 | 例 |
|-----------|------|-----|
| `--genre <ジャンル>` | ジャンル指定 | `--genre fantasy` |
| `--author <作者名>` | 作者名設定 | `--author "山田太郎"` |
| `--template <名前>` | テンプレート選択 | `--template light_novel` |

#### 事前条件
- プロジェクト名のフォルダが存在しないこと
- 書き込み権限があること

#### 事後条件
- プロジェクトフォルダが作成される
- 標準的なフォルダ構造が生成される
- プロジェクト設定.yamlが作成される

#### 実行例
```bash
# 基本的な作成
novel create "転生魔法学園"

# ジャンル指定での作成
novel create "異世界冒険記" --genre fantasy --author "作者名"

# 旧コマンドでも動作（互換性維持）
novel new "転生魔法学園"
```

---

### `novel write` - 執筆作業

#### 目的
新規エピソードの作成または既存エピソードの編集を行い、自動的に品質チェックと記録を実行します。
**2025年7月更新**: A31原稿執筆チェックリストが自動表示されるようになりました。

#### 構文
```bash
novel write <エピソード番号>
```

#### 引数
- `<エピソード番号>`: 執筆するエピソードの番号（必須）
  - 例: `1`, `2`, `10` など
  - 新規エピソードの場合も番号を指定
  - 既存エピソードの場合は継続執筆

**注意**: 現在の実装では、`novel write`コマンドはエピソード番号のみを引数として受け取ります。タイトルはプロットから自動取得されます。

#### 自動表示機能（新機能）
- **執筆開始時**: Phase 1（設計・下書き段階）のチェックリストを自動表示
- **エディタ起動後**: Phase 2-5（執筆～完成処理）のチェックリストを自動表示
- A31_原稿執筆チェックリスト.mdの内容に基づいたガイダンス

#### 事前条件
- プロジェクトフォルダ内で実行
- 40_原稿フォルダが存在

#### 事後条件
- 原稿ファイルが作成/更新される
- 話数管理.yamlが更新される
- 品質チェックが実行される
- 品質記録が保存される
- 執筆チェックリストが表示される
- プロットからタイトルが自動取得される（新規時）

#### 実行例
```bash
# 第1話の執筆開始（新規または継続）
novel write 1

# 第5話の執筆開始
novel write 5

# 第10話の執筆開始
novel write 10
```

---

### `novel check` - 品質チェック（旧：`novel quality`）

#### 目的
原稿の品質を多角的にチェックし、文章の問題点を検出・修正します。
**2025年7月更新**: 品質チェック設定ファイルが自動生成されるようになりました。

#### 構文
```bash
novel check <話数またはファイル名> [オプション]
```

#### 引数
- `<話数またはファイル名>`: チェックする話数（1, 2, 3...）または原稿ファイル（省略時は最新話）
  - 話数指定: `1`, `2`, `10` など（話数管理.yamlから自動解決）
  - ファイル名: `第001話_タイトル.md`, `40_原稿/第001話_タイトル.md`

#### オプション
| オプション | 説明 | デフォルト |
|-----------|------|-----------|
| `--auto-fix` | 自動修正を実行 | false |
| `--protagonist <名前>` | 主人公名を指定 | なし |
| `--config <YAMLファイル>` | 設定ファイル指定 | プロジェクト設定 |
| `--checker <種類>` | 特定チェッカーのみ | all |
| `--verbose` | 詳細出力 | false |
| `--threshold <数値>` | 合格基準スコア | 60 |
| `--no-color` | 色なし出力 | false |
| `--include-a31` | A31チェックリスト評価を含める | false |
| `--a31-only` | A31評価のみを実行 | false |
| `--show-review` | A31詳細レビューを表示 | false |
| `--review-verbosity <レベル>` | レビュー詳細度 (none/basic/standard/verbose) | standard |

#### 自動生成機能（新機能）
- **初回実行時**: 品質チェック設定.yamlが自動生成
- **ジャンル別カスタマイズ**: プロジェクトのジャンルに応じた最適設定
- **保存場所**: `50_管理資料/品質チェック設定.yaml`

#### チェッカー種類
- `basic`: 基本文章作法
- `composition`: 文章構成
- `invalid_kanji`: 無効な漢字
- `viewpoint`: 視点一貫性
- `emotion`: 感情表現

#### 事前条件
- 対象ファイルが存在
- 読み取り権限がある

#### 事後条件
- 品質スコアが表示される
- 問題点がリスト表示される
- --auto-fix時は修正される
- 品質記録.yamlが更新される
- 設定ファイルが存在しない場合は自動生成される

#### 実行例
```bash
# 基本的な品質チェック
novel check 1

# A31評価を含めた統合チェック（推奨）
novel check "異世界転生記" 1 --include-a31

# A31評価のみを実行
novel check "異世界転生記" 1 --a31-only --show-review

# 詳細なA31レビューを表示
novel check "異世界転生記" 1 --a31-only --review-verbosity verbose

# 従来の自動修正付きチェック
novel check 1 --auto-fix

# 主人公指定でチェック
novel check 1 --protagonist "レオン"

# キャラクター設定から自動取得
novel check 1 --config 30_設定集/キャラクター.yaml

# 特定のチェッカーのみ
novel check 1 --checker basic --verbose

# 旧コマンドでも動作（互換性維持）
novel quality 1 --auto-fix
```

---

### `novel complete` - エピソード完成処理（旧：`novel complete-episode`）

#### 目的
エピソードの執筆完了を記録し、ステータス更新と各種統計処理を実行します。

#### 構文
```bash
novel complete <話数またはファイル名> [オプション]
```

#### 引数
- `<話数またはファイル名>`: エピソード番号（1, 2, 3...）またはファイル名（必須）

#### オプション
| オプション | 説明 | デフォルト |
|-----------|------|-----------|
| `--status <状態>` | 設定するステータス | "執筆済" |
| `--enhanced` | 拡張機能を使用 | false |
| `--writing-time <分>` | 執筆時間を記録 | なし |
| `--show-suggestions` | 改善提案を表示 | false |
| `--show-trend` | 品質トレンド表示 | false |
| `--quality-score <点>` | 品質スコア指定 | 自動計算 |

#### ステータス値
- `未着`: まだ書いていない（完全形: 未着手）
- `執筆中`: 執筆作業中
- `執筆済`: 初稿完成（完全形: 執筆済み）
- `推敲済`: 推敲完了（完全形: 推敲済み）
- `公開済`: なろうに公開（完全形: 公開済み）

※ 短縮形（3文字）での指定が推奨されます

#### 事前条件
- プロジェクト設定.yamlが存在（自動検出）
- 対象エピソードが存在
- 話数管理.yamlが存在

#### 事後条件
- ステータスが更新される
- 文字数が自動計算される
- 完成日時が記録される
- 品質記録が保存される（--enhanced時）

#### 実行例
```bash
# 基本的な完成処理（話数指定）
novel complete 1

# ファイル名指定
novel complete 第001話_始まりの物語.md

# ステータス指定（短縮形推奨）
novel complete 1 --status 推敲済

# 完全形でも指定可能
novel complete 1 --status 推敲済み

# 拡張機能付き
novel complete 1 --enhanced --show-suggestions

# 執筆時間も記録
novel complete 1 --writing-time 120

# 旧コマンドでも動作（互換性維持）
novel complete-episode 1 --status 推敲済
```

---

### `novel analyze` - アクセス分析

#### 目的
なろうAPIを使用して読者のアクセスデータを分析し、離脱率や読者動向を把握します。

#### 構文
```bash
novel analyze [オプション]
```

#### オプション
| オプション | 説明 | デフォルト |
|-----------|------|-----------|
| `--config <YAMLファイル>` | プロジェクト設定 | プロジェクト設定.yaml |
| `--threshold <数値>` | 離脱率警告閾値 | 15.0 |
| `--output <ファイル>` | 出力先指定 | dropout_analysis_report.md |
| `--format <形式>` | 出力形式 | markdown |
| `--period <期間>` | 分析期間 | all |

#### 事前条件
- プロジェクト設定.yamlにncodeが設定済み
- インターネット接続が可能
- なろうに公開済み

#### 事後条件
- 分析レポートが生成される
- アクセス分析.yamlが更新される
- 問題のあるエピソードが特定される

#### 実行例
```bash
# 基本的な分析
novel analyze

# 離脱率20%以上を警告
novel analyze --threshold 20.0

# 特定期間のみ分析
novel analyze --period "2024-01"
```

---

### `novel plot` - プロット管理

#### 目的
マスタープロットや章別プロットの作成・管理を行います。

#### 構文
```bash
novel plot <サブコマンド> [引数] [オプション]
```

#### サブコマンド
| サブコマンド | 説明 | 用途 |
|-------------|------|------|
| `master` | マスタープロット作成 | 全体構成（**統合機能**：伏線・シーン自動作成） |
| `chapter` | 章別プロット作成 | 章の詳細（**統合機能**：細かな伏線・詳細シーン追加） |
| `episode` | 話別プロット作成 | 各話の構成（**🆕 Claude Code統合**：AI生成プロット） |
| `foreshadowing` | 伏線抽出 | 章別プロットから細かな伏線を抽出 |
| `scenes` | シーン抽出 | 章別プロットから詳細シーンを抽出 |
| `status` | プロット進捗確認 | 作成状況・推奨ステップ表示 |
| `check` | プロット確認 | 整合性チェック |
| `create` | AI支援作成 | AIでプロット生成 |

#### 実行例
```bash
# マスタープロット作成（統合機能で伏線・シーンも自動作成）
novel plot master                # デフォルト：既存内容とマージ
novel plot master --replace      # 既存ファイルを完全に上書き

# 第1章のプロット作成（統合機能で細かな伏線・詳細シーンも自動追加）
novel plot chapter 1             # デフォルト：既存内容とマージ
novel plot chapter 1 --replace   # 既存ファイルを完全に上書き

# 話数別プロット作成
novel plot episode 1             # デフォルト：既存内容とマージ
novel plot episode 1 --replace   # 既存ファイルを完全に上書き

# 🆕 Claude Code統合プロット生成（2025年8月4日実装）
novel plot episode 7 --mode claude    # Claude Code AI生成プロット
novel plot episode 7 --mode auto      # 自動判定（Claude Code内なら統合生成）
novel plot episode 7 --mode template  # 従来のテンプレート生成

# 🆕 プロット進捗確認（新機能）
novel plot status

# 🆕 手動での伏線・シーン抽出（個別実行）
novel plot foreshadowing    # 章別プロットから細かな伏線を抽出
novel plot scenes          # 章別プロットから詳細シーンを抽出

# プロット整合性チェック
novel plot check
```

#### 🆕 安全なマージ機能（2025年7月20日追加）
プロットコマンドは**デフォルトで既存内容とマージ**する安全仕様になりました：
- 既存のカスタムフィールドや編集内容を保持
- 新規テンプレート内容を統合
- `--replace`オプションで従来の上書き動作も可能

---

## 🚀 `novel plot episode` - 完全実装済み（2025年8月8日確認）

［重要: 既存ファイルとの衝突時の挙動（2025-09-27 仕様）］
- ドメイン層既定: 既存出力ファイルが存在する場合は実行を停止し、上書き可否の確認を要求します（auto_confirm=False）。
- アプリ/CLI 層: 実装により `auto_confirm` の既定が異なる場合があります。安全運用では、明示フラグ（例: `--auto-confirm` または `--no-auto-confirm`）を用いて挙動を固定してください。
- マージ戦略（MERGE/REPLACE）は衝突検出後の処理方針であり、確認要求の発生可否には影響しません。

### 生成システムの完全実装

`novel plot episode`コマンドは**完全に実装済み**で、高度な機能を提供します：

#### 生成モード（7種類対応）
| モード | 説明 | 動作 | 実装状況 |
|--------|------|------|----------|
| `template` | テンプレートベース | 基本的なテンプレート構造のみ | ✅ 完全実装 |
| `auto` | 完全自動生成 | 章プロット情報から自動生成 | ✅ 完全実装 |
| `interactive` | 半自動・対話式 | ユーザー入力を交えた段階的生成 | ✅ 完全実装 |
| `claude` | Claude Code統合 | AI生成による高品質プロット | ✅ 完全実装 |
| `enhanced` | SPEC-PLOT-004拡張 | コンテキスト駆動高品質生成 | ✅ 完全実装 |
| `prompt-generation` | A24プロンプト生成 | Claude Code最適化プロンプト生成 | ✅ 完全実装 |
| `advanced` | 双方向実行システム | 前話分析+動的生成統合（デフォルト） | ✅ 完全実装 |

#### Claude Code統合の特徴
- **高品質生成**: 手動作成レベルの創作品質
- **詳細構成**: 三幕構成での7-8シーン展開
- **キャラクター成長**: 直人・あすかの心理描写
- **技術要素統合**: DEBUGログ能力の効果的活用
- **伏線設置**: 次話への適切な伏線配置
- **自動YAML変換**: 既存テンプレート互換形式

#### 実行環境検出
Claude Code統合は実行環境を自動検出します：
- Claude Code内実行: 統合AI生成を実行
- 外部CLI実行: 手動連携モードまたはフォールバック

#### 事前条件
- プロジェクト内での実行
- エピソード番号の指定（1以上）
- Claude Code環境（--mode claude指定時）

#### 事後条件
- `第XXX話_タイトル_Claude生成.yaml`ファイル作成
- 詳細プロット内容（約6000文字相当）
- メタデータ自動記録（生成日時、生成者等）
- 既存テンプレート構造との完全互換性

#### 実行例（双方向実行システム詳細版）
```bash
# 🔄 双方向実行システム（デフォルト・全機能有効）
novel plot episode 7                    # 前話分析+動的生成+適応的調整

# 🎯 双方向実行システム完全版（明示的）
novel plot episode 7 --mode advanced \
    --with-previous \                   # 前話分析有効
    --save-analysis \                   # 分析結果保存
    --save-prompt                       # 生成プロンプト保存

# 📊 品質重視双方向実行（高品質モード）
novel plot episode 7 --mode advanced \
    --quality-focused \                 # 品質最優先
    --target-word-count 6000           # 詳細プロット

# 🚀 時短双方向実行（効率重視）
novel plot episode 7 --mode advanced \
    --time-limit 30min                 # 30分制限

# 🔄 継続双方向実行（前回から継続）
novel plot episode 7 --mode advanced --continue

# 🎨 カスタム双方向実行
novel plot episode 7 --mode advanced \
    --context-level 完全 \              # 最大コンテキスト
    --stage 2                          # Stage 2から開始

# 他のモード（非双方向）
novel plot episode 7 --mode claude     # Claude統合のみ
novel plot episode 7 --mode auto       # シンプル自動生成
novel plot episode 7 --mode template   # 基本テンプレート
```

#### 生成ファイル例
```yaml
# 第7話プロット（Claude Code生成）
episode_number: 7
title: "第7話_AIによる詳細プロット"
chapter: 1
word_count_target: 3800

synopsis: |
  Claude Code AIによって生成された詳細なエピソードプロット。
  三幕構成での展開、キャラクター成長描写、技術要素の
  自然な組み込みを特徴とする高品質な創作内容。

scenes:
  - scene_number: 1
    title: "オープニング"
    location: "魔法学園・教室"
    purpose: "状況設定と導入"
    content: |
      - 直人の日常的な魔法授業風景
      - 新しい課題の提示
      - DEBUGログでの異常検出
      # ... 詳細な6000文字レベルの内容

generation_metadata:
  generated_by: "Claude Code"
  generation_timestamp: "2025-08-04T15:30:00+09:00"
  source_chapter_number: 1
```

#### トラブルシューティング
- **環境検出失敗**: `--mode claude`を明示的に指定
- **生成エラー**: フォールバック機能により基本プロットを生成
- **品質確認**: 生成後に`novel plot check`で整合性確認

---

### `novel scene` - 重要シーン管理

#### 目的
クライマックスシーンなど、重要な場面の詳細設計と管理を行います。

#### 構文
```bash
novel scene <サブコマンド> [引数] [オプション]
```

#### サブコマンド
| サブコマンド | 説明 | 用途 |
|-------------|------|------|
| `init` | 初期化 | シーン管理開始 |
| `add` | シーン追加 | 新規シーン登録 |
| `list` | 一覧表示 | 登録シーン確認 |
| `show` | 詳細表示 | 特定シーン確認 |
| `checklist` | チェックリスト | 執筆用リスト |
| `validate` | 検証 | データ整合性確認 |

#### カテゴリ
- `climax_scenes`: クライマックスシーン
- `emotional_scenes`: 感情的重要シーン
- `romance_scenes`: ロマンスシーン
- `mystery_scenes`: ミステリー・サスペンス
- `horror_scenes`: ホラー・緊張シーン

#### 実行例
```bash
# 初期化
novel scene init

# クライマックスシーン追加
novel scene add climax_scenes "第10話_最終決戦"

# シーン一覧
novel scene list

# 特定シーンの詳細
novel scene show climax_scenes "第10話_最終決戦"
```

---

### `novel claude-export` - Claude向けエラー情報エクスポート

#### 目的
品質チェックで検出されたエラーを構造化された形式でエクスポートし、Claude Codeでの効率的な修正作業をサポートします。

#### 構文
```bash
novel claude-export [オプション]
```

#### オプション
| オプション | 説明 | デフォルト |
|-----------|------|-----------|
| `--file <パス>` | 特定ファイルのみチェック | 全体 |
| `--output <パス>` | 出力ファイルパス | 自動生成 |
| `--format <形式>` | 出力形式（json/markdown） | json |
| `--priority <優先度>` | 優先度フィルタ（high/medium/low） | すべて |
| `--no-suggestions` | 修正提案を除外 | false |

#### 事前条件
- Pythonファイルが存在
- 品質チェックツール（Python, Ruff）が利用可能

#### 事後条件
- エラー情報がJSON/Markdown形式で出力される
- `temp/`フォルダに保存される
- エラー統計が表示される

#### 実行例
```bash
# 全体の品質チェックとエクスポート
novel claude-export

# 特定ファイルのみ
novel claude-export --file scripts/domain/entities/episode.py

# Markdown形式で出力
novel claude-export --format markdown --output temp/errors.md

# 重要エラーのみ抽出
novel claude-export --priority high

# エラー情報のみ（修正提案なし）
novel claude-export --no-suggestions
```

---

### `novel watch` - ファイル監視（自動エラーチェック）

#### 目的
ファイルの変更をリアルタイムで監視し、自動的にClaude向けエラーチェックを実行します。

#### 構文
```bash
novel watch [オプション]
```

#### オプション
| オプション | 説明 | デフォルト |
|-----------|------|-----------|
| `--dir <ディレクトリ>` | 監視対象ディレクトリ | scripts |
| `--oneshot` | ワンショット監視（10秒間のみ） | false |
| `--no-auto-export` | 自動エクスポートを無効化 | false |
| `--debounce <秒>` | デバウンス間隔 | 0.5 |
| `--verbose` | 詳細ログ出力 | false |

#### 監視対象
- **対象**: `*.py`ファイル（Pythonファイル）
- **除外**: `__pycache__/`, `temp/`, `backup/`, `.pytest_cache/`

#### 自動ワークフロー
1. **ファイル保存** → 2. **変更検出** → 3. **デバウンス待機** → 4. **品質チェック実行** → 5. **Claude向けエクスポート**

#### 事前条件
- watchdogライブラリがインストール済み（`pip install watchdog`）
- 監視対象ディレクトリが存在

#### 事後条件
- ファイル変更時に自動でエラーチェック実行
- エクスポートファイルが`temp/`に自動保存
- 継続監視モードではCtrl+Cで停止

#### 実行例
```bash
# 基本使用（scriptsフォルダの継続監視）
novel watch

# 特定ディレクトリを監視
novel watch --dir src

# ワンショット監視（テスト用）
novel watch --oneshot

# 変更検出のみ（エクスポートなし）
novel watch --no-auto-export

# デバウンス間隔調整（大量変更時）
novel watch --debounce 2.0

# 詳細ログ付き
novel watch --verbose
```

---

## 🔄 実際に動作するワークフロー（2025年8月4日更新）

### ✅ A31品質チェック・改善ワークフロー（推奨）
```bash
# 1. A31統合品質チェック（プロジェクト名は環境変数から自動取得）
novel check 1 --a31

# 2. 詳細レビューの確認
novel check 1 --a31-only --show-review

# 3. 自動修正の実行
novel check 1 --auto-fix

# 4. エピソード完成処理
novel complete-episode 1
```

### ✅ Claude Code統合開発ワークフロー
```bash
# 1. システムヘルス確認
novel health check

# 2. ファイル監視開始（リアルタイム品質監視）
novel watch

# 3. Claude向けエラー情報エクスポート
novel claude-export

# 4. バックアップ作成
novel backup create --compression
```

### 🔧 部分実装・開発継続中のワークフロー
以下のワークフローは部分実装または未実装です：

```bash
# 🔧 部分実装
novel write 1                    # 基本機能実装済み・拡張機能開発中
novel analyze --threshold 15.0  # 未実装

# ✅ 完全利用可能（以前は利用不可と記載）
novel plot episode 1 --mode claude  # 完全実装済み
novel plot episode 1 --mode advanced  # 双方向実行システム実装済み
```

### 🚀 プロット作成の推奨フロー（2025年8月8日最新版）
```bash
# 1. マスタープロット（自動で伏線・シーン管理も作成）
novel plot master

# 2. 章別プロット（自動で細かな伏線・詳細シーンも追加）
novel plot chapter 1
novel plot chapter 2

# 3. 🆕 話別プロット（双方向実行システム・推奨）
novel plot episode 1 --mode advanced    # 前話分析+動的生成
novel plot episode 2 --mode advanced    # 統合品質システム

# 4. 🆕 段階的高品質プロット（必要に応じて）
novel plot episode 3 --mode prompt-generation --save-prompt  # A24段階的生成

# 5. 進捗確認・整合性チェック
novel plot status
novel plot check
```

### 🤖 Claude統合ワークフロー（🆕 2025年1月28日実装）
```bash
# 🔍 Phase 1: 即効性対応 - 手動エクスポート
# 1. コード品質チェックとClaude向けエクスポート
novel claude-export

# 2. 重要エラーのみ抽出
novel claude-export --priority high --format markdown

# 3. 特定ファイルの詳細チェック
novel claude-export --file scripts/domain/entities/episode.py

# 🤖 Phase 2: 自動化 - リアルタイム監視
# 1. 継続的ファイル監視開始
novel watch

# 2. テスト用ワンショット監視
novel watch --oneshot --verbose

# 3. 特定ディレクトリの監視
novel watch --dir scripts/domain --debounce 1.0

# 📂 自動生成ファイルの確認
ls temp/claude_export*.json
```

---

### `novel check` - 品質チェック

#### 基本構文
```bash
novel check <エピソード番号> [オプション]
```

#### 🎯 主要モード
| モード | 実行例 | 用途 |
|-------|-------|------|
| **デフォルト** | `novel check 4` | 総合品質チェック（推奨） |
| **プロンプト生成** | `novel check 4 --prompt` | AI執筆支援 |
| **従来モード** | `novel check 4 --standard` | 段階的制御 |

#### 主要オプション
| オプション | 効果 | 使用場面 |
|-----------|------|----------|
| `--prompt` | AI執筆支援プロンプト生成 | 執筆改善 |
| `--show-review` | 詳細レビュー表示 | 改善点確認 |
| `--auto-fix` | 自動修正実行 | 効率化 |
| `--rhythm-analysis` | 文章リズム分析 | 流れ改善 |

#### 実行例
```bash
# 基本的な品質チェック（推奨）
novel check 4

# AI支援による執筆改善
novel check 4 --prompt

# 詳細分析
novel check 4 --show-review --rhythm-analysis

# 自動修正付き
novel check 4 --auto-fix
```
## 🚀 `novel check` シナリオ別推奨コマンド

### 初心者・日常使用
```bash
# 最もシンプル - まずはこれから始める
novel check 4

# プロンプト生成を試したい場合
novel check 4 --prompt
```

### 詳細分析が欲しい場合
```bash
# 詳細レビューも表示
novel check 4 --show-review

# リズム分析も含めた総合分析
novel check 4 --rhythm-analysis --show-review
```

### 問題解決・トラブル対応
```bash
# 基本チェックのみ実行
novel check 4 --skip-a31 --skip-claude

# A31評価のみ実行
novel check 4 --skip-basic --skip-claude

# Claude分析のみ実行
novel check 4 --skip-basic --skip-a31
```

### 自動修正機能
```bash
# 安全な自動修正
novel check 4 --auto-fix

# 積極的な自動修正（上級者向け）
novel check 4 --auto-fix --fix-level aggressive
```

## 📋 `novel check` オプション早見表

| オプション | 目的 | 使用場面 |
|-----------|------|----------|
| `--prompt` | ✅ **最新機能** プロンプト生成 | AI執筆改善 |
| `--show-review` | 詳細レビュー表示 | 具体的改善点確認 |
| `--standard` | 従来の段階的実行 | 細かい制御 |
| `--skip-*` | 特定段階スキップ | トラブル解析 |
| `--auto-fix` | 自動修正実行 | 効率化 |
| `--rhythm-analysis` | リズム分析詳細 | 文章流れ改善 |

## ⚠️ `novel check` よくある混乱と解決法

### Q: オプションが多すぎて何を使えばいいかわからない
**A**: まずは `novel check 4` （デフォルト）から始める
- 慣れたら `--prompt` や `--show-review` を追加
- 問題がある場合のみ `--skip-*` を使用

### Q: プロンプト生成機能はどういう時に使う？
**A**: `--prompt` オプションが最新のAI執筆支援機能
- Claude AIによる品質分析・改善提案
- 執筆の壁にぶつかった時に特に有効

### Q: エラーが出た時はどうする？
**A**: 段階的に原因を特定
```bash
novel check 4 --standard          # 従来モードで試す
novel check 4 --skip-claude       # Claude分析をスキップ
novel check 4 --skip-a31         # A31評価をスキップ
```

## 📈 `novel check` 品質スコア改善テクニック

### 低スコア（40-59点）からの脱出
```bash
# 1. 基本チェックで問題点特定
novel check 4 --skip-a31 --skip-claude

# 2. 自動修正で即効改善
novel check 4 --auto-fix

# 3. 効果確認
novel check 4
```

### 中スコア（60-79点）からの向上
```bash
# 1. リズム分析で流れ改善
novel check 4 --rhythm-analysis

# 2. 詳細レビューで具体的改善点確認
novel check 4 --show-review

# 3. プロンプト生成でAI支援改善
novel check 4 --prompt
```

### 高スコア（80点以上）の維持
```bash
# 定期的な総合チェック
novel check 4

# 月1回の詳細分析
novel check 4 --rhythm-analysis --show-review
```

#### 事前条件
- プロジェクトが存在する
- 指定エピソードファイルが存在する

#### 事後条件
- 品質スコアが表示される
- 問題点がリスト表示される
- --auto-fix時は修正される

---

## ⚠️ 注意事項

### KASASAGIの制約
- 直近2日間のデータは集計中のため不正確
- 新規公開エピソードは2-3日後に分析推奨
- PV=0のエピソードは自動除外される

### ファイルパス
- 相対パスは現在のプロジェクトフォルダ基準
- 日本語ファイル名は""で囲む
- スペースを含むパスは引用符必須

### 品質スコア
- 60点以上が合格ライン
- 自動修正で10-20点程度の改善が期待できる
- 主人公名の指定で視点チェックの精度向上

---

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

### コマンドが見つからない
```bash
# パスを確認
which novel

# 直接実行
/path/to/00_ガイド/bin/novel
```

### YAMLエラー
```bash
# 診断実行
novel diagnose

# 構文チェック
novel configure validate
```

### 品質スコアが低い
```bash
# 詳細分析
novel check ファイル名 --verbose

# 改善提案
novel complete XXX --enhanced --show-suggestions
```

### Claude統合エラー（🆕）
```bash
# watchdogライブラリ不足
pip install watchdog

# エクスポートファイルが見つからない
ls temp/claude_export*.json

# ファイル監視が停止しない
novel watch --oneshot  # ワンショットモードで確認

# 大量ファイル変更でパフォーマンス低下
novel watch --debounce 2.0 --dir scripts/domain  # 調整
```

---

---

## 🔄 動詞ベース改善の詳細効果（2025年7月統合版）

### ユーザーエクスペリエンス向上の実例

#### Before（改善前）
```bash
$ novel check 2
novel: error: argument command: invalid choice: 'check'
# ユーザー混乱：「なぜcheckが使えないの？」

$ novel quality --help
# 「quality」が品質チェックとは直感的でない
```

#### After（改善後）
```bash
$ novel check 2
# 直感的に動作

$ novel --help
利用可能なコマンド（動詞ベース）:
  check           品質をチェックする (quality)
  create          プロジェクトを作成する (new)
  complete        エピソードを完成させる (complete-episode)
※ カッコ内は従来の互換性維持コマンド
```

### ヘルプメッセージの改善

#### 動詞ベースのヘルプ表示

```
利用可能なコマンド（動詞ベース）:
  【プロジェクト管理】
  create          プロジェクトを作成する (new)
  show            プロジェクト状態を表示する (status)
  diagnose        システムを診断する (doctor)

  【執筆作業】
  write           執筆・編集する
  complete        エピソードを完成させる (complete-episode)

  【品質管理】
  check           品質をチェックする (quality)
  analyze         離脱率を分析する
  test            テストを実行する
```

### 学習コスト削減効果

**Before:**
- 「品質チェックしたい」→「qualityコマンドを覚える必要がある」
- 「エピソード完成させたい」→「complete-episodeの長いコマンドを覚える必要がある」

**After:**
- 「品質チェックしたい」→「novel check」（直感的）
- 「エピソード完成させたい」→「novel complete」（短くて覚えやすい）

### 移行ガイド

#### 既存ユーザー向け段階的移行

**段階的移行推奨:**
1. **学習フェーズ**: 従来コマンドを使いながら動詞ベースを覚える
2. **移行フェーズ**: 新しい動詞ベースコマンドを少しずつ使用
3. **定着フェーズ**: 動詞ベースコマンドを主に使用

**移行例:**
```bash
# Phase 1: 従来通り
novel quality 第002話.md

# Phase 2: 動詞ベースを試す
novel check 第002話.md      # ←新しいコマンドを試す

# Phase 3: 動詞ベースが主流
novel check 第002話.md      # ←自然に使用
```

#### スクリプト・自動化への影響

**既存スクリプトは変更不要:**
```bash
#!/bin/bash
# 既存スクリプトはそのまま動作
novel quality *.md --auto-fix
novel complete-episode 1
novel new "新プロジェクト"
```

**新規スクリプトは動詞ベース推奨:**
```bash
#!/bin/bash
# 新規作成時は動詞ベース推奨
novel check *.md --auto-fix
novel complete 1
novel create "新プロジェクト"
```

---

## 📊 現在の実装状況サマリー（2025年8月8日最新）

### ✅ 完全実装済みコマンド（10個）
- `novel check` - Smart Auto-Enhancement品質チェック（A31統合）
- `novel claude-export` - Claude向けエラー情報エクスポート
- `novel watch` - リアルタイムファイル監視・品質監視
- `novel complete-episode` - エピソード完成処理（完全実装）
- `novel health` - システムヘルス管理・診断
- `novel backup` - バックアップ管理・復元
- `novel test` - テスト実行
- **`novel plot episode` - 話別プロット生成（7モード・完全実装）**
- **`novel create` - 新規プロジェクト作成（完全実装）**
- **`novel write` - 執筆開始システム（完全実装）**

### 🔧 部分実装・開発継続中（2個）
- `novel scene` - 重要シーン管理（部分実装・機能拡張中）
- `novel analyze` - アクセス分析（未実装・設計完了）

### 🎯 推奨される使用方法（2025年8月8日更新）

**フル機能活用型使用（推奨）:**
1. **統合プロット作成** - `novel plot episode --mode advanced`による双方向実行
2. **A31統合品質管理** - `novel check --a31`による統合品質チェック
3. **Claude Code統合開発** - `novel claude-export`, `novel watch`を使用
4. **段階的品質向上** - Stage 1-5による段階的プロンプト生成活用

**基本使用型:**
1. **品質チェック中心** - `novel check`を中心とした品質管理
2. **シンプルプロット作成** - `novel plot episode --mode auto`による自動生成
3. **システム監視** - `novel health`, `novel backup`による安定性確保

---

## 🆕 新機能詳細（2025年8月8日追加）

### 🔄 双方向実行システム（advanced mode）詳細機能

#### **Phase 1: 前話分析統合**
- **キャラクター状態追跡**: 前話の感情状態・成長段階を詳細分析
- **未解決要素管理**: unresolved_elementsの次話継続・解決計画
- **comprehensive分析**: 包括的な前話コンテキスト抽出

#### **Phase 2: 動的プロンプト生成**
- **コンテキスト駆動生成**: 前話分析結果に基づく最適プロンプト自動構築
- **品質閾値連動**: 目標品質スコアに応じた生成戦略調整
- **実行時間予測**: プロンプト複雑度による処理時間事前予測

#### **Phase 3: 適応的品質調整**
- **Stage間双方向移動**: 品質不足時の自動戻り・再調整
- **9段階revision_history**: 複数回にわたる品質改善プロセス
- **警告システム統合**: potential issuesの事前検出・回避策提示

#### **自動保存機能**
- **前話分析結果**: `60_プロンプト/前話分析結果/第XXX話_前話分析.md`
- **双方向プロンプト**: `60_プロンプト/話別プロット/第XXX話_タイトル_双方向実行システム.md`
- **調整履歴記録**: revision履歴・品質スコア推移の完全ログ

### 段階的プロンプト生成システム
- **Stage 1-5実行**: 基本骨格→構造展開→シーン肉付け→統合要素→品質確認
- **A31品質ゲート統合**: 各段階でのA31チェックリスト適用
- **品質向上保証**: 80+点の安定達成を目標とした段階的改善

### 統合コンテキスト分析
- **全68項目統合**: A31チェックリスト全項目の統合的分析
- **クロスリファレンス**: 項目間関係の自動分析と最適化提案
- **コンテキスト保持**: 分析結果の段階的蓄積と活用

---

## 📚 関連ドキュメント

### 📋 コマンド詳細ガイド
- **[A33_執筆品質管理チェック.md](A33_執筆品質管理チェック.md)** - `novel check`の詳細使い方・実践例・トラブルシューティング

### ✍️ 執筆・品質管理
- [A38_執筆プロンプトガイド.md](A38_執筆プロンプトガイド.md) - AI協創執筆詳細プロンプト統合ガイド
- [A33_執筆品質管理チェック.md](A33_執筆品質管理チェック.md) - 品質管理のチェックリスト
- [A36_AI協創執筆ガイド.md](A36_AI協創執筆ガイド.md) - AI活用執筆手法

### 🔧 システム開発・品質管理
- [B30_Claude_Code品質作業指示書.md](B30_Claude_Code品質作業指示書.md) - 品質管理統合版
- [DEVELOPER_GUIDE](../guides/developer_guide.md) - システム開発者向けガイド
- [CLAUDE.md](../CLAUDE.md) - Claude Code開発規約・統合ガイド


## 🆕 Progressive Check（12ステップ段階チェック）
12ステップの品質チェックは、ライトウェイトの `noveler check` とは別導線です。MCPツールを直接呼び出すか、将来の `noveler progressive-check`（計画中）を使用します。

### MCP 例
```bash
# 初回呼び出しで session_id を払い出し
noveler mcp call progressive_check.get_tasks '{"episode_number":1}'
# -> {"session_id":"QC_EP001_...", ...}

noveler mcp call progressive_check.execute_step '{"episode_number":1,"step_id":1}'
noveler mcp call progressive_check.get_status '{"episode_number":1}'
```

- `progressive_check.start_session` は廃止済み。呼び出すと `progressive_check.get_tasks` の利用を促すエラーメッセージが返る。
- テンプレート: `templates/quality/checks/check_step01-12`（Schema v2）。
- 保存先: `.noveler/checks/{session_id}/`（I/O, manifest）／`.noveler/artifacts/`（大きな生成物）。
- 反復: `iteration_policy` で回数・時間・合格停止を制御（詳細は SPEC-QUALITY-110 参照）。
