# 📚 A00_総合実践ガイド（執筆ハブ / MCP版）

<!-- meta: title="A00 総合実践ガイド（執筆ハブ / MCP）"; tags="writing,hub,mcp"; updated="2025-09-21"; status="active" -->

> **最終更新**: 2025年9月14日（MCP移行注記追加）
> 本ガイドは MCP ツール運用（Claude Code 連携）を前提とします。旧CLIの例は廃止し、MCPの呼び出し方法に統一しました。
> **対象**: システムの実践的活用から問題解決まで総合サポート
> **A番号体系について**: [A02_番号体系定義・運用ガイド.md](A02_番号体系定義・運用ガイド.md)

## 🎯 このガイドの目的

小説執筆支援システムの**実践的な使用方法**から**トラブル対処**まで、執筆者が日常的に必要とする情報を一元化した総合ガイドです。

## 📑 ガイドの使い方

```yaml
利用パターン:
  初回利用者: セクション1（クイックスタート）から順に読む
  中級者: セクション2（実践シナリオ）で具体例を確認
  トラブル時: セクション3（問題解決）で症状から解決法を検索
  効率化: セクション4（最適化）で作業の自動化を学ぶ
```

***

## 📌 セクション1: MCP最短導線（執筆者向け）

### 🧪 品質チェック（要約）
```bash
noveler mcp call run_quality_checks '{"episode_number": 1, "additional_params": {"format": "summary"}}'
```

### ✨ 原稿の整形（ドライラン）
```bash
noveler mcp call polish_manuscript '{"episode_number": 1, "file_path": "40_原稿/第001話_サンプル.md", "stages": ["stage2"], "dry_run": true}'
```

### 📦 アーティファクト一覧
```bash
noveler mcp call list_artifacts '{"episode_number": 1}'
```

### 🔎 テスト結果（LLM要約）の見方（参考）
- 実行: `make test`（既定でLLM要約ON）
- 最小出力（推奨）: `bin/test-json -q` または `python3 scripts/run_pytest.py --json-only -q`
- 出力: `reports/llm_summary.{jsonl,txt}` と STDOUTタグ `LLM:BEGIN ... LLM:END`

***

## 📖 セクション2: 実践シナリオ集

### シナリオ1: 新規プロジェクトの立ち上げ

#### 状況
新しい作品「異世界カフェの魔法使い」を始めたい。

#### 手順

**方法1: 専用コマンドを使用（推奨）**
```bash
# 1. 新規プロジェクト作成（自動化）
create-project "02_異世界カフェの魔法使い"

# 完了！ディレクトリ構造・設定ファイル・環境変数がすべて自動設定されます
```

**方法2: 手動作成**
```bash
# 1. プロジェクトフォルダーを作成
mkdir "02_異世界カフェの魔法使い"
cd "02_異世界カフェの魔法使い"

# 2. 基本構造を設定
mkdir -p 10_企画 20_プロット 30_設定集 40_原稿 50_管理資料

# 3. プロジェクト設定を作成
cp ../00_ガイド/templates/プロジェクト設定テンプレート.yaml プロジェクト設定.yaml
```

#### プロジェクト設定.yaml の編集例
```yaml
project:
  name: "異世界カフェの魔法使い"
  genre: "異世界ファンタジー"
  target_audience: "20-30代女性"

narou:
  ncode: "n1234ab"  # 投稿後に追加

quality:
  min_word_count: 4000
  max_word_count: 6000
  quality_threshold: 80
```

### シナリオ2: 第1話の執筆と品質チェック

#### 状況
第1話「魔法のカプチーノ」を執筆し、品質を確認したい。

#### 手順
```bash
# 1. 話数管理を初期化
cp ../00_ガイド/templates/話数管理テンプレート.yaml 50_管理資料/話数管理.yaml

# 2. 第1話を執筆
nano 40_原稿/第001話_魔法のカプチーノ.md
```

#### 原稿の例（第001話_魔法のカプチーノ.md）
```markdown
# 第001話　魔法のカプチーノ

　目が覚めると、そこは見知らぬ木造の建物の中だった。
　
「ここは……？」
　
　慌てて起き上がろうとすると、エプロンをつけた金髪の少女が心配そうにこちらを覗き込んでいた。
　
「あ、目が覚めたんですね！　よかった……」
　
　少女の安堵の表情を見て、俺は状況を把握しようと周囲を見回した。カウンター、テーブル、椅子……どうやらここはカフェのようだ。
```

#### 品質チェックの実行
```bash
# 3. 基礎文章チェック
cd "02_異世界カフェの魔法使い"
noveler check 1

# 4. 構成チェック（詳細モード）
noveler check 1 --verbose

# 5. 統合チェック（自動修正付き）
noveler check 1 --auto-fix
```

#### DDD準拠チェック
```bash
# プロジェクト全体のDDDコンプライアンスを確認
noveler ddd validate --path . --threshold 85
```

### シナリオ3: 離脱率分析と改善

#### 状況
10話まで公開したが、第3話で離脱率が30%を超えている。

#### 手順
```bash
# 1. 離脱率分析を実行
cd ../00_ガイド/scripts
python3 analysis/analyze_dropout_rate.py --config ../../02_異世界カフェの魔法使い/プロジェクト設定.yaml

# 2. レポートを確認
cat ../../02_異世界カフェの魔法使い/50_管理資料/dropout_analysis_report.md
```

#### 分析結果の例
```markdown
## 🚨 要対策エピソード（離脱率20%以上）

### 第003話_異世界の掟（離脱率: 32.5%）
- **前話からのPV減少**: -450 PV
- **推定原因**:
  - 設定説明が長すぎる
  - アクションシーンがない
  - 主人公の見せ場が不足
```

#### 改善作業
```bash
# 3. 第3話を修正
nano ../../02_異世界カフェの魔法使い/40_原稿/第003話_異世界の掟.md

# 修正ポイント：
# - 冒頭に緊張感のあるシーンを追加
# - 設定説明を会話に組み込む
# - 主人公の活躍シーンを追加

# 4. 修正後の品質確認
noveler check 3 --auto-fix
```

### シナリオ4: AI協創執筆（高品質仕上げ）

#### 状況
クライマックスシーン（第20話）を高品質に仕上げたい。

#### 手順
```bash
# 1. 執筆記録を作成
cd ../00_ガイド/scripts
python3 management/integrated_record_manager.py create 020 "最後の魔法"

# 2. Phase 2テンプレートを確認
cat ../A_執筆ガイド/A30_原稿執筆/templates/Phase2執筆記録テンプレート.yaml
```

#### AI協創の進め方
```yaml
# Phase2執筆記録_第020話.yaml の記入例
phase2_ai_writing:
  step1_initial_draft:
    prompt_engineering:
      base_prompt: |
        第20話「最後の魔法」のクライマックスシーン。
        主人公がカフェを守るため、禁断の魔法を使う決意をする。
      yaml_elements_incorporated:
        - 主人公の成長
        - カフェへの愛着
        - 仲間との絆
```

### シナリオ5: キャラクター一貫性チェック

#### 状況
20話まで書いたが、キャラクターの口調がブレていないか確認したい。

#### 手順
```bash
# 1. キャラクター設定を整備
nano ../../02_異世界カフェの魔法使い/30_設定集/キャラクター.yaml
```

#### キャラクター.yaml の例
```yaml
characters:
  主人公:
    name: "田中太郎"
    speech_pattern:
      sentence_endings: ["だ", "だな", "か？"]
      first_person: "俺"
      characteristics:
        - 敬語は使わない
        - 短い文で話す

  ヒロイン:
    name: "エリィ"
    speech_pattern:
      sentence_endings: ["です", "ます", "ですね"]
      first_person: "私"
      characteristics:
        - 丁寧語を使う
        - 時々異世界の言葉を混ぜる
```

#### 一貫性チェック
```bash
# 2. キャラクター一貫性をチェック
cd "02_異世界カフェの魔法使い"
noveler check character-consistency
```

### シナリオ6: 定期メンテナンス作業

#### 状況
毎週土曜日に行う定期的な品質管理作業。

#### 手順
```bash
# 1. 全話の品質スコアを更新
cd 02_異世界カフェの魔法使い
for file in 40_原稿/*.md; do
  echo "Checking: $file"
  python3 ../00_ガイド/src/noveler/quality/check_all_quality.py "$file"
done

# 2. 品質記録を確認
cat 50_管理資料/品質記録.yaml | grep "total_score"

# 3. 文字数を更新
python3 ../00_ガイド/src/noveler/management/update_word_count.py .
```

### シナリオ7: 投稿前の最終チェック

#### 状況
第21話を投稿する前の最終確認。

#### 手順
```bash
# 1. 投稿前チェックリスト
cd ../00_ガイド/scripts

# 品質スコア80点以上を確認
python3 quality/check_all_quality.py ../../02_異世界カフェの魔法使い/40_原稿/第021話_新たな始まり.md

# 文字数確認（4000-6000文字）
wc -m ../../02_異世界カフェの魔法使い/40_原稿/第021話_新たな始まり.md

# 前話との繋がり確認
diff ../../02_異世界カフェの魔法使い/40_原稿/第020話_最後の魔法.md \
     ../../02_異世界カフェの魔法使い/40_原稿/第021話_新たな始まり.md

# 2. 話数管理を更新
python3 management/complete_episode.py 021
```

***

## 🔍 セクション3: トラブルシューティング・問題解決

### エラー別対処法

#### 1. ModuleNotFoundError

**症状**
```
ModuleNotFoundError: No module named 'yaml'
ModuleNotFoundError: No module named 'common.config_loader'
```

**原因**
- Pythonパッケージがインストールされていない
- 実行ディレクトリが正しくない

**解決方法**
```bash
# 1. 必要なパッケージをインストール
cd 00_ガイド/scripts
pip install pyyaml janome tqdm chardet

# 2. プロジェクトディレクトリから実行
cd [プロジェクト]
noveler check 1
```

#### 2. FileNotFoundError: プロジェクト設定.yaml

**症状**
```
FileNotFoundError: プロジェクト設定.yaml が見つかりません
ValueError: プロジェクトルートが見つかりません
```

**原因**
- プロジェクト設定ファイルが存在しない
- 実行場所が正しくない

**解決方法**
```bash
# 1. プロジェクト設定ファイルを作成
cp 00_ガイド/templates/プロジェクト設定テンプレート.yaml プロジェクト設定.yaml

# 2. 環境変数で指定
export PROJECT_ROOT="/path/to/your/project"

# 3. コマンドラインで明示的に指定
python3 analyze_dropout_rate.py --config ../../プロジェクト/プロジェクト設定.yaml
```

#### 3. YAMLエラー

**症状**
```
yaml.scanner.ScannerError: while scanning a simple key
yaml.parser.ParserError: expected <block end>, but found '-'
```

**原因**
- YAML構文エラー（インデント、記号など）
- 文字エンコーディングの問題

**解決方法**
```bash
# 1. YAML構文をチェック
python3 -c "from scripts.infrastructure.utils.yaml_utils import check_yaml_syntax; print(check_yaml_syntax('話数管理.yaml'))"

# 2. よくある構文エラー
# ❌ 間違い
episodes:
第001話:  # コロンの後にスペースがない
  title: タイトル

# ✅ 正しい
episodes:
  第001話:  # インデントとコロン後のスペース
    title: タイトル

# 3. テンプレートからやり直し
cp templates/話数管理テンプレート.yaml 50_管理資料/話数管理.yaml
```

#### 4. novelerコマンドが見つからないエラー

**症状**
```
noveler: command not found
/bin/bash: line 1: noveler: command not found
```

**原因**
- novelerコマンドのPATHが設定されていない
- インストールが完了していない

**解決方法**

**方法1: インストールスクリプトを実行（推奨）**
```bash
# ガイドディレクトリからインストールスクリプトを実行
cd 00_ガイド
./bin/install.sh
```

**方法2: PATHを手動で設定**
```bash
# ~/.bashrc に以下を追加
echo 'export PATH="/path/to/00_ガイド/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 例：
echo 'export PATH="/mnt/c/Users/bamboocity/OneDrive/Documents/9_小説/00_ガイド/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**動作確認**
```bash
# PATH設定後の確認
which noveler
noveler --help

# プロジェクトディレクトリで動作確認
cd [プロジェクトディレクトリ]
noveler plot chapter 1
```

#### 5. Claude Code実行エラー

**症状**
```
{"type": "error", "subtype": "error_max_turns", "num_turns": 10}
❌ Claude Code実行エラー: 最大ターン数制限に到達しました（10ターン）
💰 実行コスト: $0.8192
⏱️ 実行時間: 58453ms
```

**🚀 自動解決機能（v2.0新機能）**
**システムが以下を自動実行します：**
```yaml
段階的ターン数拡張:
  第1段階: 10ターン (デフォルト)
  第2段階: 15ターン (自動拡張)
  第3段階: 20ターン (最大限界)

自動処理:
  - エラー検出時の自動再試行
  - タイムアウト600秒（10分）適用
  - プロンプト最適化を自動実行
```

**✅ 通常は自動回復**
ほとんどの場合、**手動での対処は不要**です：
- 10ターン制限到達 → 自動的に15ターンで再実行
- 15ターン制限到達 → 自動的に20ターンで再実行
- 段階的拡張により約80%以上が自動解決

**🔧 手動対処法（自動解決失敗時のみ）**
```bash
# 方法1: プロンプトを簡潔にして再実行
noveler write [話数] --prompt-optimize

# 方法2: 手動でターン数を最大に指定
export CLAUDE_CODE_MAX_TURNS=20
noveler write [話数]

# 方法3: タスクを分割して段階的に実行
noveler write [話数] --step-by-step
```

#### 6. 文字コードエラー

**症状**
```
UnicodeDecodeError: 'utf-8' codec can't decode byte
chardet.UniversalDetector Warning
```

**解決方法**
```bash
# 1. 文字コードを確認
file -i ファイル名.md

# 2. UTF-8に変換
iconv -f SHIFT-JIS -t UTF-8 original.md > converted.md

# 3. エディタの設定を確認
# VS Code: 右下のステータスバーでUTF-8を選択
```

#### 7. 権限エラー

**症状**
```
PermissionError: [Errno 13] Permission denied
OSError: [Errno 30] Read-only file system
```

**解決方法**
```bash
# 1. 権限を確認・修正
ls -la ファイル名
chmod 644 ファイル名

# 2. OneDriveの場合
# - 同期が完了するまで待つ
# - オフラインで利用可能にする
# - ローカルにコピーして作業
```

### トラブルシューティングの基本手順

#### Step 1: エラーメッセージを読む
```bash
# エラーの最後の行を確認
# 例: KeyError: 'quality_check'
# → quality_checkというキーが存在しない
```

#### Step 2: ファイルの存在・内容を確認
```bash
# ファイルが存在するか
ls -la ファイル名

# YAMLの構造を確認
cat ファイル名.yaml | head -20
```

#### Step 3: テンプレートと比較
```bash
# テンプレートと比較して差分を確認
diff templates/テンプレート.yaml 実際のファイル.yaml
```

#### Step 4: 最小構成で動作確認
```bash
# 最小限のテストファイルで動作確認（プロジェクト内で）
echo "テスト文章です。" > temp/test.md
noveler check 1 --file temp/test.md
```

### 完全リセット方法
```bash
# 設定をテンプレートから作り直し
cd プロジェクトルート
rm -rf 50_管理資料/*.yaml
cp -r ../00_ガイド/templates/*.yaml 50_管理資料/
# 各YAMLを編集し直す
```

***

## 💡 セクション4: 効率化・最適化

### エイリアスの設定
```bash
# ~/.bashrc に追加
alias ncheck='python3 /path/to/00_ガイド/src/noveler/quality/check_all_quality.py'
alias ndropout='python3 /path/to/00_ガイド/src/noveler/analysis/analyze_dropout_rate.py'

# 使用例
ncheck 40_原稿/第001話.md --auto-fix
```

### バッチ処理スクリプト
```bash
#!/bin/bash
# check_all_episodes.sh

for episode in 40_原稿/*.md; do
  echo "=== Checking $episode ==="
  python3 ../00_ガイド/src/noveler/quality/check_all_quality.py "$episode"
  echo ""
done
```

### VS Code タスクの設定
```json
// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "品質チェック",
      "type": "shell",
      "command": "python3",
      "args": [
        "${workspaceFolder}/../00_ガイド/src/noveler/quality/check_all_quality.py",
        "${file}",
        "--auto-fix"
      ]
    }
  ]
}
```

### 2025年8月システム整理の効果

#### フォルダ構造最適化（45%削減）

**変更前後の比較**
```bash
# Before（11ファイル）
bin/
├── create-project
├── doctor              # ← 廃止
├── error-monitor       # ← 廃止
├── git-commit          # ← 廃止
├── install.sh
├── noveler
├── noveler-repair        # ← 廃止
├── quality-check       # ← 廃止
├── setup-git-aliases.sh

# After（6ファイル・45%削減）
bin/
├── create-project
├── install.sh
├── noveler              # ← 統合CLI（すべての機能を含む）
├── setup-git-aliases.sh
```

**新統合コマンド体系**
```bash
# 旧コマンド → 新コマンド
doctor          → noveler health check
quality-check   → noveler health check --scope quality
git-commit      → noveler health fix && git commit
noveler-repair    → noveler health fix
error-monitor   → noveler health monitor start
```

#### 統合キャッシュ管理システム

**キャッシュ構造の統一**
```bash
# Before（散在していたキャッシュ）
src/noveler/
├── __pycache__/        # ← DDD構造を汚染
├── .benchmarks/        # ← 不適切な場所
├── domain/
└── application/

# After（統一管理）
temp/
└── cache/
    ├── python/         # __pycache__ 統一
    ├── pytest/         # テストキャッシュ
    ├── benchmarks/     # ベンチマークデータ
    ├── mypy/          # 型チェックキャッシュ
    └── ruff/          # リンターキャッシュ
```

### 2025年7月新機能の活用例

#### 品質設定の自動生成機能

**手順**
```bash
# 1. 品質チェック実行（設定ファイルが自動生成される）
noveler check 1

# 出力例:
# 🔧 品質チェック設定ファイルが見つかりません。自動生成します...
# ✅ 品質チェック設定を生成しました: 50_管理資料/品質チェック設定.yaml
#    ジャンル「ファンタジー」用にカスタマイズ済み
```

#### A31チェックリスト自動表示機能

**実行例**
```bash
# 執筆開始コマンド
noveler write 1

# 自動表示される内容:
# 📋 執筆前チェックリスト
# ==================================================
# ■ Phase 1: 設計・下書き段階
#   □ 話数管理.yamlに基本情報を記入
#   □ 前話からの流れを確認
#   □ 今話の目的と到達点を明確化
#   □ 離脱リスクポイントを事前チェック
#   □ 重要シーンの詳細設計を完了
#   💡 ヒント: `noveler assist analyze`で執筆支援を受けられます
# ==================================================
```

***

## 📊 成果の測定・改善効果

### 導入前後の比較
| 指標 | 導入前 | 導入後 |
|------|--------|--------|
| 平均品質スコア | 65点 | 85点 |
| 離脱率（第3話） | 32% | 15% |
| 執筆時間/話 | 8時間 | 5時間 |
| 読者評価 | ★3.2 | ★4.5 |

### 実際の改善例
```markdown
# Before（品質スコア: 62点）
　主人公は、カフェに入った。そこには、少女がいた。少女は、笑った。

# After（品質スコア: 88点）
　扉を押し開けると、コーヒーの香ばしい匂いが鼻をくすぐった。
　カウンターの向こうで、エプロン姿の少女が振り返る。その顔に、花が咲いたような笑顔が広がった。
```

***

## 🔗 関連ドキュメント

### A系執筆ガイド体系
- **A12_市場分析・ジャンル研究ガイド.md** - 市場調査と戦略
- **A14_企画設計・コンセプト策定ガイド.md** - 企画立案
- **A28_話別プロットプロンプト.md** - プロット設計
- **A30_執筆ガイド.yaml** - 執筆技法詳細（YAML定義）
- **A38_執筆プロンプトガイド.md** - AI協創執筆詳細プロンプト統合ガイド
- **A33_執筆コマンドガイド.md** - CLIコマンド詳細

### B系システムガイド
- **B00_情報システム開発ガイド.md** - アーキテクチャ
- **B20_Claude_Code開発作業指示書.md** - 開発プロセス
- **B30_Claude_Code品質作業指示書.md** - 品質管理

### テンプレート・設定
- **templates/** - 各種テンプレート・雛形
- **CLAUDE.md** - 開発契約・必須ルール
- **CODEMAP.yaml** - アーキテクチャ設計方針

***

**💡 ヒント**: このガイドは**検索性**を重視して構成されています。`Ctrl+F`で症状やキーワードを検索することで、必要な情報に素早くアクセスできます。

**📝 フィードバック**: 不明な点や追加すべき情報があれば、A系ガイド体系の改善として継続的に反映していきます。
