# 要求整理書

**プロジェクト名:** 小説執筆支援システム (noveler)
**バージョン:** 3.0.0
**作成日:** 2025-09-30
**参照:** B20_Claude_Code開発作業指示書_最終運用形.md

---

## 1. 目的・目標

### 1.1 目的
なろう系Web小説執筆の全工程（企画→執筆→品質管理→公開）を統合的にサポートするシステムを提供する。

### 1.2 目標
1. **執筆効率50%向上**: システム化によるタスク削減
2. **品質スコア85%以上**: 視点連動評価による精度向上
3. **離脱率30%削減**: 内面描写評価とエラー具体化
4. **学習コスト75%削減**: TDD+DDD統合ガイド

### 1.3 前提条件
- Python 3.10以上がインストール済み
- Git環境が利用可能
- Claude Code / MCP統合環境（推奨）
- テキストエディタ（VS Code推奨）

---

## 2. 入出力仕様

### 2.1 入力
**ユーザー要求:**
- 執筆タスク: エピソード番号、プロット情報
- 品質チェック: 原稿ファイル、チェック観点 (rhythm/readability/grammar/style)
- 推敲タスク: ステージ指定 (stage2: 内容推敲 / stage3: 読者体験)

**設定ファイル:**
- `.novelerrc.yaml`: 品質基準、出力形式
- `config/novel_config.yaml`: プロジェクト設定、パス管理
- `プロジェクト設定.yaml`: 作品名、ncode、ジャンル

### 2.2 出力
**成果物:**
- 原稿ファイル (`.md`形式)
- 品質レポート (JSON/YAML/NDJSON/Markdown)
- 推敲レポート (A41形式)
- アーティファクト (`.noveler/artifacts/`)

**メトリクス:**
- 品質スコア (0-100点)
- アスペクト別評価 (rhythm/readability/grammar/style)
- 離脱率予測
- カバレッジ率 (テスト)

---

## 3. ユーザーペルソナ・利用シナリオ

### 3.1 ペルソナ1: なろう新人作家
**ニーズ:**
- 基本的な執筆技法の習得
- システム化されたワークフローの理解
- 品質基準の明確化

**利用シナリオ:**
```bash
noveler write 1           # 第1話執筆開始
noveler check 1           # 品質チェック（Smart Auto-Enhancement）
noveler complete-episode 1  # 完成処理
```

### 3.2 ペルソナ2: 経験者
**ニーズ:**
- 執筆効率化
- 品質向上の定量化
- 複数話の一括管理

**利用シナリオ:**
```bash
noveler check --bulk      # 全話品質チェック
noveler analyze           # 離脱率分析
noveler polish 5          # 第5話推敲
```

### 3.3 ペルソナ3: AI協創執筆者
**ニーズ:**
- 構造化されたAI協働プロセス
- MCPツール直接呼び出し
- カスタマイズ可能な品質基準

**利用シナリオ:**
```bash
noveler mcp call run_quality_checks '{
  "episode_number": 1,
  "additional_params": {
    "format": "summary",
    "weights": {"rhythm":0.35,"readability":0.35,"grammar":0.2,"style":0.1}
  }
}'
```

### 3.4 ペルソナ4: データ分析重視
**ニーズ:**
- 読者反応の数値把握
- NDJSON形式での一括出力
- CI/CD統合

**利用シナリオ:**
```bash
python scripts/ci/run_quality_checks_ndjson.py \
  --episode 1 \
  --severity-threshold medium \
  --fail-on-score-below 80 \
  --out reports/quality.ndjson
```

---

## 4. 依存関係

### 4.1 主要パッケージ (requirements)
| パッケージ | バージョン | 用途 |
|----------|----------|------|
| PyYAML | >=6.0 | 設定ファイル管理 |
| rich | >=13.0.0 | MCP美しい出力表示 |
| requests | >=2.28.0 | なろうAPI連携 |
| janome | >=0.4.2 | 形態素解析 |
| deal | >=4.24.0 | Design by Contract |
| mcp | >=1.13.0 | Claude Code統合 |
| jinja2 | >=3.1.0 | テンプレート処理 |
| psutil | >=5.9.0 | ビルドプロセス管理 |
| ruamel.yaml | >=0.18.0 | YAML整形 |
| yamllint | >=1.33.0 | YAML検証 |
| numpy | >=1.26.0 | ログ分析 |

### 4.2 開発依存関係 (dev)
| パッケージ | バージョン | 用途 |
|----------|----------|------|
| pytest | >=8.0.0 | テスト実行 |
| pytest-cov | >=4.0.0 | カバレッジ測定 |
| pytest-xdist | >=3.5.0 | 並列実行 |
| mypy | >=1.8.0 | 型チェック |
| ruff | >=0.1.0 | リンター |
| import-linter | >=2.0 | アーキテクチャ検証 |
| pytest-archon | >=0.0.5 | DDD層検証 |

### 4.3 外部ツール (オプション)
- **GNU parallel**: 並列処理による品質チェック高速化（推奨）
  - Ubuntu/Debian: `sudo apt install parallel`
  - macOS: `brew install parallel`

---

## 5. 非機能要件

### 5.1 パフォーマンス要件
| 指標 | 目標値 | 測定方法 |
|-----|-------|---------|
| 単一話品質チェック | 3秒以内 | `time noveler check 1` |
| MCPツール応答 (P95) | <1ms | MessageBus計測 |
| Smart Auto-Enhancement | 1,250ms以内 | 統合品質チェック |
| 並列品質チェック (10話) | 10秒以内 | GNU parallel使用時 |

### 5.2 信頼性要件
| 指標 | 目標値 | 検証方法 |
|-----|-------|---------|
| TDDカバレッジ | 80%以上 | `make coverage` |
| 型安全性 | mypy strict合格 | `make lint` |
| 構文エラー | 0件 | ruff検証 |
| 契約違反 | 0件 | 契約テスト |

### 5.3 保守性要件
| 指標 | 基準値 | 検証方法 |
|-----|-------|---------|
| ファイル行数 | 300行以下 | B20閾値 |
| クラスメソッド数 | 10個以下 | B20閾値 |
| 関数行数 | 50行以下 | B20閾値 |
| 複雑度 | 10以下 | B20閾値 |
| ネスト深さ | 4以下 | B20閾値 |
| DDD層分離 | importlinter合格 | レイヤリング検証 |

### 5.4 セキュリティ要件
1. **固有名詞保護**: 設定集からの自動抽出・除外
2. **安全な自動修正**: 限定された理由コードのみ適用
3. **パス検証**: strictモードでフォールバック遮断
4. **秘密管理**: vault方式 (`.novelerrc.yaml`)

---

## 6. 制約事項

### 6.1 技術的制約
- Python 3.10以上必須 (型ヒント、構造的パターンマッチング使用)
- Linux/macOS/Windows WSL環境推奨 (並列処理最適化)
- メモリ使用量: 最大2GB (大規模プロジェクト時)

### 6.2 運用制約
- `.novelerrc.yaml` による設定統一（SSOT管理）
- MCPツール経由での機能呼び出し推奨
- CI/CD統合時はstrict モード推奨

### 6.3 互換性制約
- レガシーCLI (`novel` コマンド) は廃止済み
- `noveler` 統合CLI および MCP ツールのみサポート
- 旧配置/命名はフォールバック対応（strict モード除く）

---

## 7. 成功基準

### 7.1 機能面
- ✅ 18ステップ執筆ワークフローの完全動作
- ✅ 統合品質チェック (4観点) の正確な評価
- ✅ A40推敲システム (Stage2/3) の適用
- ✅ MCPツール17個の正常動作

### 7.2 品質面
- ✅ Must要件100%準拠
- ✅ Should要件達成 or 正当化
- ✅ テストカバレッジ80%以上
- ✅ SOLID原則検証済み

### 7.3 ユーザー体験面
- ✅ クイックスタート5分以内
- ✅ エラーメッセージの具体性（改善前後の例示）
- ✅ 日本語ドキュメント完備
- ✅ 段階的学習パス提供

---

## 8. リスクと対策

### 8.1 技術リスク
| リスク | 影響度 | 対策 |
|-------|-------|------|
| MCP統合の互換性問題 | 高 | バージョン固定、後方互換性維持 |
| 並列処理の競合 | 中 | ロック機構、トランザクション管理 |
| 大規模プロジェクトのメモリ枯渇 | 中 | ページング、ストリーミング処理 |

### 8.2 運用リスク
| リスク | 影響度 | 対策 |
|-------|-------|------|
| 設定ファイルの不整合 | 高 | SSOT管理、自動検証 |
| パスフォールバックの依存 | 中 | strict モード、移行ツール提供 |
| テストカバレッジの低下 | 中 | CI失敗条件、定期監視 |

---

## 9. 今後の拡張方針

### 9.1 短期 (v3.1)
- B20ワークフローの完全自動化
- 品質チェックの機械学習強化
- 離脱率予測の精度向上

### 9.2 中期 (v3.5)
- リアルタイムコラボレーション機能
- Web UI提供
- プラグインシステム

### 9.3 長期 (v4.0)
- クラウドベース執筆環境
- AIペアプログラミング統合
- マルチプラットフォーム展開

---

**承認:** B20ワークフロー Phase 1 完了
**次フェーズ:** Phase 2 - CODEMAP作成