---
spec_id: SPEC-A31-001
status: canonical
owner: bamboocity
last_reviewed: 2025-09-13
category: QUALITY
sources: [E2E]
tags: [a31, auto-evaluation, checklist, quality]
---
# SPEC-A31-001: A31自動評価エンジン仕様書

## 概要

A31原稿執筆チェックリスト（全68項目）の自動評価システムの技術仕様。
各チェックリスト項目を6つの評価カテゴリに分類し、それぞれに特化した評価アルゴリズムを適用する。

## 1. システムアーキテクチャ

### 1.1 コアコンポーネント

```
A31EvaluationEngine
├── FormatEvaluator (フォーマット系)
├── QualityEvaluator (品質閾値系)
├── ContentEvaluator (内容バランス系)
├── ConsistencyEvaluator (整合性系)
├── ClaudeCodeEvaluator (Claude Code連携自動評価系)
└── SystemEvaluator (システム自動系)
```

### 1.2 評価フロー

1. **項目分類**: 68項目を6つのカテゴリに自動分類
2. **評価実行**: カテゴリ別の専用アルゴリズムで評価
3. **閾値判定**: 項目ごとの設定閾値と比較
4. **結果集約**: 全項目の評価結果を統合
5. **修正提案**: 自動修正可能項目の特定と修正案生成

## 2. 評価カテゴリ別仕様

### 2.1 フォーマット系評価 (FORMAT_CHECK)

**対象項目**: A31-045（段落字下げ）, A31-035（記号統一）等

**評価アルゴリズム**:

**A31-045 段落字下げ評価**:
- **検出方法**: 各段落行の開始文字チェック（全角スペース「　」の有無）
- **スコア計算**: `(字下げ済み段落数 / 総段落数) × 100`
- **閾値**: 95%以上
- **自動修正**: 可能（safe level）- 段落頭に全角スペース自動追加

**A31-035 記号統一性評価**:
- **検出対象**: 三点リーダー（`...` vs `…`）、ダッシュ（`--` vs `—`）
- **統一性判定**: 同じ記号が複数の表記法で混在している場合は減点
- **スコア計算**: `100 - (混在パターン数 × 20)`
- **閾値**: 100%（混在なし）
- **自動修正**: 可能（safe level）- 標準表記に統一

### 2.2 品質閾値系評価 (QUALITY_THRESHOLD)

**対象項目**: A31-042（品質スコア70点以上）等

**評価アルゴリズム**:

**A31-042 品質スコア閾値評価**:
- **データ源**: 既存品質チェックシステムの評価結果
- **取得場所**: `50_管理資料/品質記録/第XXX話_品質記録.yaml`
- **スコア取得**: メタデータから`quality_score`フィールドを参照
- **閾値**: 70.0点以上
- **合格判定**: `current_score >= 70.0`
- **自動修正**: 不可（根本的な品質改善が必要）

### 2.3 内容バランス系評価 (CONTENT_BALANCE)

**対象項目**: A31-022（会話と地の文バランス3:7～4:6）, A31-023（五感描写）等

**評価アルゴリズム**:

**A31-022 会話・地の文バランス評価**:
- **検出方法**: 「」で囲まれた部分を会話文として識別
- **比率計算**: `会話行数 / (会話行数 + 地の文行数) × 100`
- **適正範囲**: 30-40%
- **スコア計算**: 適正範囲内=100点、範囲外は距離に応じて減点
- **閾値**: 30-40%の範囲内
- **自動修正**: 不可（内容調整が必要）

**A31-023 五感描写評価**:
- **検出対象**: 視覚・聴覚・触覚・嗅覚・味覚の表現キーワード
- **判定方法**: 各感覚カテゴリの表現の存在確認
- **バランス評価**: 5感覚のうち3感覚以上が含まれているか
- **閾値**: 3感覚以上の配置
- **自動修正**: 不可（創作的判断が必要）

### 2.4 整合性系評価 (CONSISTENCY_CHECK)

**対象項目**: A31-033（キャラクター口調）, A31-044（固有名詞表記）等

**評価アルゴリズム**:

**A31-033 キャラクター口調整合性評価**:
- **データ源**: `30_設定集/キャラクター.yaml`のキャラクター設定
- **検証内容**: 設定された口調パターンと実際の台詞の一致度
- **マッチング方法**: 語尾パターン、一人称、敬語レベルの照合
- **スコア計算**: `(一致した台詞数 / 総台詞数) × 100`
- **閾値**: 95%以上の一貫性
- **自動修正**: 部分的に可能（standard level）

**A31-044 用語統一性評価**:
- **データ源**: `30_設定集/用語集.yaml`の標準表記リスト
- **検証内容**: 固有名詞・専門用語の表記ゆれ検出
- **チェック方法**: 登録済み用語の異表記パターン検索
- **スコア計算**: `100 - (表記ゆれ件数 × ペナルティ)`
- **閾値**: 表記ゆれ0件
- **自動修正**: 可能（safe level）- 標準表記への置換

### 2.5 Claude Code連携自動評価 (CLAUDE_CODE_EVALUATION)

**対象項目**: A31-001（ガイド確認）, A31-012（前話からの流れ）, A31-013（目的と到達点明確化）等

**評価アルゴリズム**:
- **評価方式**: Claude Code実行中セッションでの自動問い合わせ評価
- **データ源**: 関連ファイル（前話、プロット、設定ファイル等）の読み込み
- **コスト**: 追加料金なし（Maxプランの実行中セッション活用）
- **閾値**: Claude Codeの評価結果（PASS/FAIL）による判定
- **スコア計算**: PASS=100点、FAIL=0点
- **自動修正**: 不可（内容改善が必要）

**Claude Code問い合わせ仕様（行数付きYAMLプロトコル）**:

**統一レスポンス形式**:
```yaml
- id: "A31-001"
  item: "A30_原稿執筆ガイド.mdの内容を確認"
  status: true                    # Claude Codeの評価結果
  required: true
  type: "document_review"
  auto_fix_supported: false
  auto_fix_applied: false
  fix_details: []
  claude_evaluation:
    evaluated_at: "2025-08-03T10:35:00"
    result: "PASS"
    score: 85.0
    confidence: 0.9
    primary_reason: "ガイド内容が適切に理解・適用されている"
    evidence_points:
      - content: "冒頭3行で読者を引き込む工夫が確認できる"
        line_range: [1, 3]
        file: "第001話_始まりの物語.md"
    improvement_suggestions:
      - content: "五感描写をもう少し増やすとより効果的"
        line_range: [8, 12]
        file: "第001話_始まりの物語.md"
        suggestion_type: "enhancement"
    issues_found:
      - content: "段落の字下げが不足"
        line_number: 7
        file: "第001話_始まりの物語.md"
        severity: "minor"
        auto_fixable: true
    references_validated:
      - guide: "A30_原稿執筆ガイド.md"
        section: "冒頭の技法"
        applied_at_lines: [1, 3]
        compliance_score: 90
```

**構造化プロンプト例**:
```
エピソードファイルを分析し、A31チェックリスト形式で行数を含めて評価してください：

重要：必ず行数情報を含めてください
- evidence_points: 良い箇所の行数範囲
- improvement_suggestions: 改善提案の具体的行数
- issues_found: 問題箇所の正確な行番号

[A31チェックリスト項目の詳細]
評価対象ファイル: {エピソードファイルパス}
参照ガイド: {関連ガイドファイル}
```

#### 2.5.1 Claude Code評価エンジン

**実装アーキテクチャ**:
```python
class ClaudeCodeEvaluator:
    def evaluate_manual_item(self, item_id: str, context_data: dict) -> EvaluationResult:
        """Claude Code実行中セッションでの評価実行"""
        prompt = self._build_evaluation_prompt(item_id, context_data)
        response = self._query_claude_code(prompt)
        return self._parse_evaluation_response(response)
```

**評価実行フロー**:
1. **コンテキスト収集**: 評価に必要な関連ファイルの読み込み
2. **プロンプト構築**: 項目別の構造化プロンプト生成
3. **Claude Code問い合わせ**: セッション内での評価実行
4. **結果解析**: PASS/FAILと理由の抽出
5. **チェックリスト更新**: 評価結果のYAML自動記録

**技術的利点**:
- **コスト効率**: 追加API料金なし
- **高速処理**: セッション内処理による低レイテンシ
- **柔軟性**: プロンプト調整の容易さ
- **統合性**: 既存ワークフローとの親和性

#### 2.5.2 チェック状態管理システム

**ファイル作成フロー**:
1. **テンプレート元**: `$GUIDE_ROOT/templates/A31_原稿執筆チェックリストテンプレート.yaml`
2. **コピー先**: `{プロジェクトフォルダ}/50_管理資料/チェックリスト/第XXX話_A31チェックリスト.yaml`
3. **初期化タイミング**: `novel write [話数]`実行時またはチェック初回実行時
4. **自動評価実行**: Claude Code評価エンジンによる自動チェック

**データ構造例**:
```yaml
metadata:
  checklist_name: "A31_原稿執筆チェックリスト"
  target_episode: 1
  target_title: "始まりの物語"
  created_date: "2025-08-03T10:30:00"

checklist_items:
  Phase0_自動執筆開始（推奨）:
    - id: "A31-001"
      status: true
      checked_at: "2025-08-03T10:35:00"
      evaluation_method: "claude_code_auto"
      claude_evaluation:
        result: "PASS"
        score: 85.0
        primary_reason: "ガイド内容が適切に理解・適用されている"
        evidence_points:
          - content: "冒頭3行で読者を引き込む工夫"
            line_range: [1, 3]
        improvement_suggestions:
          - content: "五感描写追加推奨"
            line_range: [8, 12]
```

#### 2.5.3 既存コマンド統合仕様

**`novel a31-auto-fix` コマンド拡張**:
```bash
# レビュー表示機能付き自動修正
novel a31-auto-fix プロジェクト名 1 --level safe --show-review
novel a31-auto-fix プロジェクト名 1 --level standard --show-review --verbose
```

**出力例**:
```
A31自動修正実行結果:

修正完了項目:
  A31-045 [FIXED] 段落字下げ → 7箇所修正完了
  A31-035 [FIXED] 記号統一 → 3箇所修正完了

Claude Code評価結果:
  A31-001 [PASS] ガイド確認
    ✓ 良い点: 冒頭の引き込み (行1-3)
    ⚠ 改善案: 五感描写追加 (行8-12)

  A31-012 [PASS] 前話からの流れ
    ✓ 良い点: 自然な継続性 (行5-8)

要手動確認:
  A31-013 [PENDING] 目的・到達点明確化
    → プロットファイルとの照合が必要
```

**`novel check` コマンド統合**:
```bash
# 品質チェックにA31評価を統合
novel check 1 --include-a31
novel check 1 --a31-only
```

**`novel complete` コマンド統合**:
```bash
# 完成処理時にA31チェックリスト実行
novel complete 1 --status 執筆済 --run-a31
novel complete 1 --status 推敲済 --a31-summary
```

**プロジェクト設定統合**:
```yaml
# プロジェクト設定.yaml
a31_checklist:
  auto_run_on_write: true      # novel write時の自動実行
  auto_run_on_check: true      # novel check時の自動実行
  auto_run_on_complete: true   # novel complete時の自動実行
  claude_evaluation: true      # Claude Code評価の有効化
  show_line_numbers: true      # 行数表示の有効化
  review_verbosity: "standard" # none/basic/standard/verbose
```

### 2.6 システム自動系評価 (SYSTEM_FUNCTION)

**対象項目**: A31-048（品質記録自動保存）, A31-050（改善率計算）等

**評価アルゴリズム**:

**A31-048 品質チェック結果自動保存**:
- **検証内容**: 品質記録ファイルの存在と内容の妥当性
- **チェック対象**: `50_管理資料/品質記録/第XXX話_品質記録.yaml`
- **判定基準**: ファイル存在 + 必要フィールド完備 + タイムスタンプ妥当性
- **閾値**: 処理成功率100%
- **自動修正**: システムレベルで自動実行（再実行）

**A31-049 カテゴリ別スコア記録**:
- **検証内容**: 各評価カテゴリのスコアが正しく記録されているか
- **チェック項目**: 基本文体、構成、キャラクター描写等のスコア存在
- **データ形式**: YAML内の構造化されたスコアデータ
- **閾値**: 全カテゴリのスコア記録完了
- **自動修正**: システムレベルで自動実行

**A31-050 改善率計算**:
- **計算対象**: 前回エピソードとの品質スコア比較
- **データ源**: 過去の品質記録ファイル履歴
- **計算式**: `(今回スコア - 前回スコア) / 前回スコア × 100`
- **閾値**: 計算処理の正常完了
- **自動修正**: システムレベルで自動実行

## 3. 閾値設定システム

### 3.1 閾値タイプ定義

```python
class ThresholdType(Enum):
    PERCENTAGE = "percentage"    # パーセンテージ（0-100）
    SCORE = "score"             # スコア値（0.0-100.0）
    BOOLEAN = "boolean"         # 真偽値
    RANGE = "range"             # 範囲値（min-max）
    COUNT = "count"             # カウント数
```

### 3.2 項目別閾値設定

| 項目ID | 閾値タイプ | 値 | 説明 |
|--------|-----------|----|----|
| A31-042 | SCORE | 70.0 | 品質スコア70点以上 |
| A31-022 | RANGE | 30-40 | 会話比率30-40% |
| A31-045 | PERCENTAGE | 95 | 字下げ率95%以上 |
| A31-035 | PERCENTAGE | 100 | 記号統一率100% |
| A31-044 | COUNT | 0 | 表記ゆれ0件 |

### 3.3 動的閾値調整

```python
class AdaptiveThreshold:
    def adjust_threshold(self, item_id: str, historical_data: list[float]) -> float:
        """過去の実績に基づく閾値の動的調整

        調整ロジック:
        1. 過去10回の平均スコア計算
        2. 標準偏差による変動幅考慮
        3. プロジェクト特性に応じた補正
        """
```

## 4. 自動修正システム

### 4.1 修正レベル定義

```python
class FixLevel(Enum):
    SAFE = "safe"           # 安全な修正（形式的な調整）
    STANDARD = "standard"   # 標準的な修正（内容に軽微な影響）
    INTERACTIVE = "interactive"  # 対話的修正（ユーザー確認必要）
```

### 4.2 自動修正可能項目マップ

| 項目ID | 修正レベル | 修正内容 |
|--------|-----------|---------|
| A31-045 | SAFE | 段落頭への全角スペース追加 |
| A31-035 | SAFE | 記号表記の統一（...→…） |
| A31-044 | SAFE | 用語集に基づく表記統一 |
| A31-033 | STANDARD | キャラクター口調の部分修正 |

### 4.3 修正エンジン

```python
class AutoFixEngine:
    def apply_fixes(self, content: str, failed_items: list[A31ChecklistItem], fix_level: FixLevel) -> AutoFixResult:
        """自動修正の適用

        処理フロー:
        1. 修正レベルによるフィルタリング
        2. 修正優先度の決定
        3. 競合チェック
        4. 修正適用とログ記録
        """
```

## 5. 評価結果データ構造

### 5.1 個別評価結果

```python
@dataclass
class EvaluationResult:
    item_id: str                    # 項目ID
    current_score: float            # 現在のスコア
    threshold_value: float          # 閾値
    passed: bool                    # 合格判定
    details: dict[str, Any]         # 詳細情報
    auto_fixable: bool              # 自動修正可能性
    fix_suggestions: list[str]      # 修正提案
    confidence: float               # 評価信頼度
```

### 5.2 総合評価結果

```python
@dataclass
class ComprehensiveEvaluationResult:
    total_items: int                # 総項目数
    evaluated_items: int            # 評価済み項目数
    passed_items: int               # 合格項目数
    auto_fixable_items: int         # 自動修正可能項目数
    overall_score: float            # 総合スコア
    category_scores: dict[str, float]  # カテゴリ別スコア
    recommendations: list[str]      # 改善推奨事項
```

## 6. パフォーマンス要件

### 6.1 処理時間目標

- **単一項目評価**: 50ms以下
- **全68項目評価**: 3秒以下
- **自動修正適用**: 1秒以下

### 6.2 メモリ使用量

- **最大メモリ使用量**: 100MB
- **同時評価セッション**: 最大5セッション

### 6.3 信頼性要件

- **評価精度**: 95%以上（手動評価との一致率）
- **エラー率**: 1%未満
- **可用性**: 99.9%

## 7. 拡張性設計

### 7.1 新規項目追加

```python
class EvaluatorRegistry:
    def register_evaluator(self, item_type: ChecklistItemType, evaluator: BaseEvaluator) -> None:
        """新しい評価器の登録"""

    def register_auto_fixer(self, item_id: str, fixer: BaseAutoFixer) -> None:
        """新しい自動修正器の登録"""
```

### 7.2 プラグインシステム

- **カスタム評価器**: プロジェクト固有の評価ロジック追加
- **外部連携**: AI評価サービスとの統合
- **設定カスタマイズ**: プロジェクト別の閾値・重み調整

## 8. 運用監視

### 8.1 評価品質監視

```python
class EvaluationQualityMonitor:
    def track_evaluation_accuracy(self, item_id: str, auto_result: bool, manual_result: bool) -> None:
        """評価精度の追跡"""

    def generate_quality_report(self) -> QualityReport:
        """品質レポート生成"""
```

### 8.2 パフォーマンス監視

- **実行時間トラッキング**
- **メモリ使用量監視**
- **エラー率監視**
- **ユーザビリティ指標**

## 9. 実装優先度

### フェーズ1: 基本評価エンジン

1. ✅ A31EvaluationService基盤実装
2. ✅ フォーマット系評価器（A31-045, A31-035）
3. ✅ 品質閾値系評価器（A31-042）
4. ✅ 内容バランス系評価器（A31-022）

### フェーズ2: 拡張評価機能

1. 整合性系評価器（A31-033, A31-044）
2. システム自動系評価器（A31-048～A31-055）
3. 手動確認系インターフェース

### フェーズ3: 自動修正システム

1. AutoFixEngine実装
2. 修正レベル別処理
3. 修正結果検証

### フェーズ4: 運用最適化

1. パフォーマンス最適化
2. 監視システム統合
3. プラグインシステム

---

**仕様策定日**: 2025年8月3日
**バージョン**: 1.0
**実装担当**: Claude Code + MCP Serena
**レビュー担当**: プロジェクト管理者
