# B50_システム運用基礎

## ✅ 最新システム状況（2025年8月4日更新）

**運用ステータス: 本格運用レベル達成**

小説執筆支援システムは統合サービス分離移行の完了により、企業級品質と安定性を達成しています。本ガイドでは最新アーキテクチャでの日常的な運用、トラブルシューティング、バックアップ管理を統合的に解説します。

### 🎯 システム品質指標
- ✅ **テスト成功率**: 289+テストパス（97%改善）
- ✅ **エラー削減**: RUF001-003エラー97.8%削減
- ✅ **アーキテクチャ**: DDD原則準拠、Enterprise-Grade品質
- ✅ **依存関係**: Import競合100%解決

---

## 🚀 クイックスタート（2025-09-21 更新）

### 基本的な使い方
```bash
# ヘルプ表示
./bin/noveler --help

# 執筆関連
./bin/noveler write 1                          # 第1話の執筆バッファを生成
./bin/noveler check 1 --auto-fix               # A31統合品質チェック（自動修正）
./bin/noveler mcp call noveler_complete '{"episode_number":1}'

# プロジェクトサマリ / 健全性
./bin/noveler mcp call status '{}'

# プロット生成
./bin/noveler mcp call noveler_plot '{"episode_number":1,"regenerate":false}'
```

### 主な運用タスクのマッピング

| 目的 | 現行コマンド | 補足 |
|------|--------------|------|
| 執筆開始 | `./bin/noveler write <episode>` | `40_原稿/第◯◯◯話_*.md` に原稿が自動生成されます |
| 品質チェック | `./bin/noveler check <episode|path> [--auto-fix]` | `--prompt` や `--standard` など従来オプションも利用可 |
| エピソード完成処理 | `./bin/noveler mcp call noveler_complete '{"episode_number":N,"auto_publish":false}'` | 自動投稿が必要な場合は `auto_publish` を `true` に |
| プロット管理 | `./bin/noveler mcp call noveler_plot '{"episode_number":N,"regenerate":true}'` | regenerate=false で参照のみ |
| 健全性診断 | `./bin/noveler mcp call status '{}'` | JSON レスポンスは構造化されたサマリを返却 |
| バックアップ操作 | `./bin/noveler mcp call backup_management '{"action":"list"}'` | 復元: `{ "action":"restore", "backup_id":"..." }` |

> ℹ️ 旧 `bin/novel` コマンドの完全な移行手順は [docs/migration/novel_to_noveler.md](migration/novel_to_noveler.md) を参照してください。歴史的な手順は文末の「レガシーCLI資料（参照のみ）」セクションに移動しました。

---

## 🆘 緊急時対応

### システムが動かない
```bash
# 1. 健全性サマリを取得
./bin/noveler mcp call status '{}'

# 2. 代表的な品質チェックを実行（エピソード番号は状況に応じて調整）
./bin/noveler check 1 --verbose

# 3. バックアップ状態を確認
./bin/noveler mcp call backup_management '{"action":"list"}'

# 4. ログ確認
tail -f logs/noveler_$(date +%Y%m%d).log
```

### 執筆が進まない
```bash
# 1. 直近のプロットを再生成
./bin/noveler mcp call noveler_plot '{"episode_number":1,"regenerate":true}'

# 2. 執筆ワークスペースを再構築
./bin/noveler write 1

# 3. 品質チェック状況を確認
./bin/noveler check 1 --prompt
```

### 品質スコアが低い
```bash
# 1. 詳細レビューを出力
./bin/noveler check 1 --show-review --verbose

# 2. 自動修正を実行
./bin/noveler check 1 --auto-fix

# 3. 完成処理で再検証
./bin/noveler mcp call noveler_complete '{"episode_number":1,"auto_publish":false}'
```

---

## 🔧 環境設定

### 初回セットアップ

**方法1: インストールスクリプト使用（推奨）**
```bash
# ワンコマンドでセットアップ完了
cd 00_ガイド
./bin/install.sh
```

**方法2: 手動セットアップ**
```bash
# 1. 依存関係インストール（pyproject.toml統合版）
pip install .[dev]  # 開発環境一式をインストール
# LogAnalyzer（ログ分析）の機能を使う場合は NumPy も追加インストール
pip install numpy

# 2. パス設定（.bashrcに追加）
echo 'export PATH="/path/to/00_ガイド/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 3. 動作確認
novel health check
```

### novelコマンドエラーの対処

## 📚 レガシーCLI資料（参照のみ）

> ⚠️ 以下は旧 `bin/novel` コマンドに基づく歴史的な手順です。現行運用では使用しません。最新手順は本ドキュメント冒頭と [migration guide](migration/novel_to_noveler.md) を参照してください。

#### エラー: `novel: command not found`
```bash
# 解決方法1: インストールスクリプト実行
cd 00_ガイド
./bin/install.sh

# 解決方法2: 手動PATH設定
export PATH="/path/to/00_ガイド/bin:$PATH"
echo 'export PATH="/path/to/00_ガイド/bin:$PATH"' >> ~/.bashrc

# 解決方法3: フルパスで実行
/path/to/00_ガイド/bin/novel --help

# 確認方法
which noveler
noveler --help
```

### システム設定
```bash
# 現在のシステム状態確認
noveler health status

# Claude Code統合の管理
noveler health claude-code enable   # Claude Code統合を有効化
noveler health claude-code disable  # Claude Code統合を無効化
noveler health claude-code status   # 統合状態確認
```

---

## 💾 バックアップ管理

### 自動バックアップ
- エピソード完成時に自動実行
- ZIP圧縮とGitタグ作成
- メタデータ記録

### 手動バックアップ
```bash
# 全体バックアップ作成
noveler backup create

# バックアップ一覧表示
noveler backup list

# 特定バックアップの詳細表示
noveler backup show [バックアップID]

# バックアップの復旧
noveler backup restore [バックアップID]
```

### 復旧手順
```bash
# 利用可能なバックアップ確認
noveler backup list

# 特定バックアップから復旧
noveler backup restore backup_YYYYMMDD_HHMMSS

# 手動でのバックアップ確認
ls -la backup/
```

---

## 📝 YAML管理

### 主要YAMLファイル
```
プロジェクト設定.yaml        # プロジェクト基本設定
10_企画/企画書.yaml         # 企画・コンセプト
20_プロット/全体構成.yaml    # マスタープロット
30_設定集/キャラクター.yaml  # キャラクター設定
50_管理資料/話数管理.yaml    # 話数管理
```

### YAML操作支援
```bash
# YAML構文チェック（システム診断の一部）
noveler health check --scope yaml

# 整合性チェック（総合診断）
noveler health check --format json

# 品質管理での YAML チェック
noveler quality check --scope yaml
```

---

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

### よくある問題と解決法

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

# パス追加
export PATH="$PATH:/path/to/00_ガイド/bin"
```

#### YAMLファイルエラー
```bash
# 構文チェック（統合診断）
noveler health check --scope yaml

# 自動修復試行
noveler health fix --type yaml

# バックアップから復旧
noveler backup restore [バックアップID]
```

#### Git関連問題
```bash
# 状態確認
git status

# 変更の取り消し
git checkout -- ファイル名

# 履歴確認
git log --oneline -5
```

## 🔧 Git運用管理

### 🔄 統合コミットフロー（2025年7月更新）

#### コミット実行時の自動処理流れ
```bash
git add .
git commit
```

実行すると以下の順序で自動処理されます：

1. **品質チェック** （pre-commitフック）
   - 末尾空白の削除
   - ファイル末尾の改行修正
   - YAML/JSON構文チェック
   - 大きなファイルのチェック
   - マージコンフリクトチェック
   - Ruffリンター・フォーマッター
   - 型チェック
   - ユニットテスト
   - 複雑度チェック
   - 品質ゲート

2. **チェック結果の表示**
   - ✅ 成功：コミットメッセージ入力画面へ
   - ❌ 失敗：詳細なエラー情報と修正方法を表示して停止

3. **コミットメッセージ入力**（品質チェック通過後のみ）
   - エディタが開き、メッセージを入力

4. **コミットメッセージ検証**（commit-msgフック）
   - Conventional Commit形式のチェック
   - 形式エラーがあれば修正を促す

#### エラー時の対処法

**自動修正（推奨）**
```bash
# すべての自動修正可能な問題を修正
pre-commit run --all-files

# または個別に実行
ruff check scripts/ --fix --config=pyproject.toml
ruff format scripts/
```

**手動修正**
表示されたエラーメッセージを確認して、該当ファイルを直接編集

**緊急時のスキップ（非推奨）**
```bash
git commit --no-verify
```

#### Conventional Commitメッセージ形式

**基本形式**
```
<type>: <subject>

[optional body]

[optional footer]
```

**タイプ一覧**
- `feat`: 新機能
- `fix`: バグ修正
- `docs`: ドキュメント更新
- `style`: コードスタイル変更
- `refactor`: リファクタリング
- `test`: テスト追加・修正
- `chore`: 雑務・設定変更
- `perf`: パフォーマンス改善
- `ci`: CI/CD関連
- `build`: ビルド関連

**例**
```
feat: pre-commitフックの実行順序を改善

- リンティングエラー時にコミットメッセージ入力を防ぐ
- エラー詳細と修正方法を分かりやすく表示
- すべてのpre-commitチェックの結果を統合表示
```

#### 便利なコマンド

```bash
# 特定のフックだけを実行
pre-commit run ruff
pre-commit run mypy

# すべてのファイルに対してチェック実行
pre-commit run --all-files

# フックの更新
pre-commit autoupdate

# フックの無効化（一時的）
SKIP=ruff git commit
```

### ブランチ戦略

小説執筆プロジェクトでは以下のフェーズ別ブランチ構成を推奨：

```
main（完成原稿・安定版）
├── develop-plot（プロット作業ブランチ）
├── develop-episode-001（第1話執筆・推敲）
├── develop-episode-002（第2話執筆・推敲）
├── develop-episode-003（第3話執筆・推敲）
└── ...（各話数別ブランチ）
```

**ブランチの役割：**
- **develop-plot**: プロット作成・修正専用（A20対応）
- **develop-episode-XXX**: 話数別エピソード執筆・推敲・品質向上（A30/A40対応）
- **main**: 各フェーズ完了後の安定版

**話数別ブランチのメリット：**
- 複数話の並行作業が可能
- 各話の作業履歴が独立して管理される
- 完成した話だけを選択的にmainにマージ可能
- 特定話の大幅修正を安全に実行可能

#### フェーズ別基本運用フロー

**プロット作業時（A20）:**
```bash
# develop-plotブランチで作業
git checkout develop-plot 2>/dev/null || git checkout -b develop-plot
git pull origin develop-plot 2>/dev/null || true

# プロット作成
noveler plot master
noveler plot chapter 1

# コミット・マージ
git add .
git commit -m "plot: 全体構成プロット作成完了"
git checkout main
git merge develop-plot
```

**執筆作業時（A30）:**
```bash
# 話数別エピソードブランチで作業（例：第3話）
git checkout -b develop-episode-003

# 執筆・品質チェック
noveler write 3
noveler check 第003話.md --auto-fix

# コミット・マージ
git add .
git commit -m "feat: 第003話執筆完了"
git checkout main
git merge develop-episode-003

# 作業ブランチの削除（オプション）
git branch -d develop-episode-003
```

**推敲作業時（A40）:**
```bash
# 既存の話数別ブランチで推敲作業（例：第3話）
git checkout develop-episode-003

# 推敲・品質向上
noveler check 第003話.md --auto-fix

# コミット・マージ
git add .
git commit -m "quality: 第003話推敲完了（品質スコア：XX点達成）"
git checkout main
git merge develop-episode-003

# 作業ブランチの削除（オプション）
git branch -d develop-episode-003
```

#### 実践的なブランチ管理パターン

**新規プロジェクト（初回）:**
```bash
# 新規リポジトリ初期化
git init
git add .
git commit -m "initial: プロジェクト初期設定"

# developブランチ作成
git checkout -b develop
git commit --allow-empty -m "feat: developブランチ作成"

# リモート設定（必要に応じて）
git remote add origin <リポジトリURL>
git push -u origin main
git push -u origin develop
```

**既存プロジェクト（継続作業）:**
```bash
# ブランチ存在確認と自動対応
git checkout develop 2>/dev/null || git checkout -b develop

# リモートと同期（存在する場合のみ）
git pull origin develop 2>/dev/null || true

# 作業開始
# ... 作業内容 ...

# 完成時のマージ
git checkout main
git merge develop
git push origin main --tags
```

**チーム作業時:**
```bash
# 最新状態の取得
git fetch origin
git checkout develop
git pull origin develop

# 作業完了後
git push origin develop
# プルリクエスト作成（GitHub/GitLab等）
```

#### 特別なケースでのブランチ作成
```bash
# 実験的な展開
git checkout -b experiment/different-ending develop

# 大規模な修正要求
git checkout -b fix/publisher-revision develop

# 複数パターンの検討
git checkout -b alternative/route-a develop
```

### タグ管理体系

#### タグ命名規則
**フォーマット**: `[カテゴリ]/[番号]-[説明]`

```bash
# 執筆完了時
ep/001-complete    # 第1話執筆完了
ep/002-complete    # 第2話執筆完了

# 章の区切り
ch/01-complete     # 第1章完了

# 巻の区切り
vol/01-draft       # 第1巻初稿
vol/01-final       # 第1巻最終稿

# リリース・公開
pub/001-narou      # 第1話なろう投稿版

# 特別なマイルストーン
ms/plot-locked     # プロット確定
ms/halfway         # 全体の半分完了
```

#### タグの使用例
```bash
# 第3話完成時
git tag ep/003-complete -m "第3話「DEBUGログの副作用」執筆完了"

# プロット確定時
git tag ms/plot-locked -m "第1-3章プロット確定版"

# タグ一覧の確認
git tag -l "ep/*"     # 全話数タグ
git tag -l "ch/*"     # 全章タグ
git tag -l "pub/*"    # 全公開タグ
```

### コミットメッセージ規則

#### コミットタイプ
```
feat:       新話執筆・新機能追加
fix:        既存話の修正・バグ修正
docs:       設定資料・ドキュメント更新
refactor:   文章のリファクタリング
style:      文体・表現の調整
plot:       プロット関連の変更
quality:    品質チェック・改善
wip:        作業進行中（Work In Progress）
check:      セルフチェック・確認作業
experiment: 実験的な表現・手法の試行
idea:       アイデア・方向転換の記録
refine:     細かな調整・改善
```

#### コミットメッセージ例
```bash
# 新話執筆
git commit -m "feat: 第5話「エラーを進化させる者」執筆完了"

# 既存話修正
git commit -m "fix: 第3話 - あすかの反応を自然に修正"

# 品質改善
git commit -m "quality: 第1-3話の三点リーダー形式統一"

# 設定資料更新
git commit -m "docs: キャラクター設定にThe Architect関連を追加"
```

### Git トラブル対応

#### よくある問題と対処法

**1. 間違ったコミット**
```bash
# 直前のコミットを修正
git commit --amend -m "修正されたメッセージ"

# 複数コミットを修正（注意：pushする前のみ）
git rebase -i HEAD~3
```

**2. ブランチの切り忘れ**
```bash
# 現在の変更を一時保存
git stash

# 新ブランチを作成して移動
git checkout -b fix/urgent-revision

# 変更を復元
git stash pop
```

**3. 誤ったマージ**
```bash
# マージを取り消し
git reset --hard HEAD~1

# または特定のコミットに戻る
git reset --hard <commit-hash>
```

### セキュリティ・バックアップ

#### セキュリティ考慮事項
- 秘匿性の高い設定情報は`.gitignore`に追加
- 個人情報や契約内容は含めない
- 執筆メモやプライベートな情報の分離

#### バックアップ戦略
```bash
# 重要な変更前のバックアップ
git tag backup/plot-$(date +%Y%m%d) -m "プロット変更前バックアップ"

# 定期的なリモートリポジトリへのプッシュ
git push origin main --tags

# 週次・月次の整理
git branch -d experiment/old-idea  # 不要ブランチの削除
git push origin develop --tags     # リモートとの同期
```

### チーム作業（共同執筆時）

#### プルリクエストの活用
```bash
# フィーチャーブランチ作成
git checkout -b feature/character-development

# 作業完了後
git push origin feature/character-development

# GitHub/GitLab等でプルリクエスト作成
```

#### コミットメッセージの統一
- チーム内でコミットメッセージ規則を統一
- レビュアーが理解できる明確な説明
- 変更の意図と背景を記載

---

## 📊 プロジェクト管理

### プロジェクト作成
```bash
# 基本作成
noveler create "魔法学園の日常"

# ジャンル指定
noveler create "時空の図書館" --genre "SF"
```

### プロット管理
```bash
# 全体構成作成
noveler plot master

# 章別プロット
noveler plot chapter 1

# 話プロット
noveler plot episode 1
```

### 執筆記録管理
```bash
# プロジェクト状態確認
noveler status

# エピソード完成処理（記録も自動更新）
noveler complete-episode プロジェクト名 1

# 品質チェック履歴の確認
noveler check プロジェクト名 1 --verbose
```

---

## ⚙️ 高度な運用

### システム最適化
```bash
# 統合システム最適化
noveler health fix --type cache              # キャッシュ関連問題修復
noveler health check                         # 全体の健全性確認

# ログ整理
find logs/ -name "*.log" -mtime +30 -delete

# バックアップ管理
noveler backup list                          # バックアップ一覧確認
noveler backup cleanup --older-than 30d     # 古いバックアップの整理
```

### 定期メンテナンス
```bash
# 週次チェック
noveler health check                         # 統合システム診断
noveler health status                        # システム状態確認
noveler test run --unit                      # 高速テスト実行

# 月次バックアップ
noveler backup create                        # フルバックアップ作成
git tag -a "backup_$(date +%Y%m)" -m "Monthly backup"
```

### パフォーマンス向上
1. 不要なログファイルの削除
2. キャッシュの定期クリア
3. Gitリポジトリの最適化（`git gc`）

---

## 📚 ベストプラクティス

### 日常運用フロー
1. **朝**: `noveler health check`でシステムチェック
2. **執筆前**: `noveler write [番号]`で自動準備
3. **執筆後**: `noveler check プロジェクト名 [番号]`で品質チェック
4. **エピソード完成時**: `noveler complete-episode プロジェクト名 [番号] --a31-check`で最終確認

### データ保護
- 毎日の自動バックアップ
- 週次でGitプッシュ
- 月次で外部ストレージへ保存

### 効率的な執筆
- プロット生成での Claude Code 連携活用（`--claude-generate`）
- A31チェックリストでの品質向上（`noveler a31-auto-fix`）
- 高速テスト実行での開発効率化（`noveler test run`）

---

## ❓ FAQ

### Q: バックアップはどこに保存される？
A: プロジェクトルートの`backup/`フォルダに日時付きで保存されます。`noveler backup list`で確認できます。

### Q: YAMLファイルが壊れた場合は？
A: `novel health fix --type yaml`で自動修復を試みるか、`novel backup restore [バックアップID]`でバックアップから復旧してください。

### Q: 古いログファイルは削除して良い？
A: 30日以上前のログは削除しても問題ありません。

### Q: A31チェックリストとは何ですか？
A: 原稿執筆品質チェックリストです。`novel a31-auto-fix`コマンドで自動評価・修正が可能です。

### Q: Claude Code連携が動作しない場合は？
A: `novel health claude-code status`で統合状態を確認し、必要に応じて`novel health claude-code enable`で有効化してください。

### Q: テストが遅い場合はどうすれば？
A: `novel test run --unit`で高速並列テストを実行してください。従来のpytestよりも大幅に高速化されています。
