タスク品質KPIフレームワーク

概要

タスク品質KPIフレームワークは、タスク実装の品質を評価するための客観的で定量的なメトリクスを提供します。

主要アーキテクチャ: KPIはフックによって自動生成されます - スクリプトを実行するのではなく、結果を読み取ります。

┌─────────────────────────────────────────────────────────────┐
│  HOOK (自動実行)                                             │
│  トリガー: TASK-*.md への PostToolUse                         │
│  スクリプト: task-kpi-analyzer.py                            │
│  出力: TASK-XXX--kpi.json                                    │
├─────────────────────────────────────────────────────────────┤
│  SKILL / AGENT (出力を読み取り)                               │
│  入力: TASK-XXX--kpi.json                                    │
│  アクション: 評価判定を実施                                   │
└─────────────────────────────────────────────────────────────┘

このアーキテクチャを採用する理由

問題	解決方法
Skill はスクリプトを実行できない	フックがファイル保存時に自動実行
主観的な review_status	定量的な 0-10 スコア
「良さそうに見える」	エビデンスベースの評価
二項選択の合格/不合格	段階的な品質レベル

KPIファイルの場所

タスクファイルが修正されると、KPIデータは以下の場所にあります:

docs/specs/[ID]/tasks/TASK-XXX--kpi.json

KPI カテゴリ

┌─────────────────────────────────────────────────────────────┐
│                   総合スコア (0-10)                          │
├─────────────────────────────────────────────────────────────┤
│  仕様準拠性 (30%)                                            │
│  ├── 受け入れ基準の充足 (0-10)                               │
│  ├── 要件カバレッジ (0-10)                                   │
│  └── スコープ逸脱なし (0-10)                                 │
├─────────────────────────────────────────────────────────────┤
│  コード品質 (25%)                                            │
│  ├── 静的解析 (0-10)                                        │
│  ├── 複雑性 (0-10)                                          │
│  └── パターン準拠性 (0-10)                                   │
├─────────────────────────────────────────────────────────────┤
│  テストカバレッジ (25%)                                      │
│  ├── ユニットテスト実装 (0-10)                               │
│  ├── テスト/コード比率 (0-10)                                │
│  └── カバレッジパーセンテージ (0-10)                         │
├─────────────────────────────────────────────────────────────┤
│  契約充足度 (20%)                                            │
│  ├── 提供物検証 (0-10)                                      │
│  └── 期待値充足 (0-10)                                      │
└─────────────────────────────────────────────────────────────┘

カテゴリウェイト

カテゴリ	ウェイト	理由
仕様準拠性	30%	最重要 - 要求通りに構築したか？
コード品質	25%	技術的卓越性
テストカバレッジ	25%	検証と信頼度
契約充足度	20%	他のタスクとの統合

使用する場面

• タスク品質評価のためのKPIデータ読み取り
• 品質メトリクスとスコア内訳の理解
• 定量データに基づいた反復または承認の判定
• 自動ループへのKPI チェック統合 (agents_loop.py)
• エビデンスベースの評価レポート生成

使用方法

1. KPIデータの読み取り (主な用途)

スクリプトを実行しないでください - 自動生成されたファイルを読み取ります:

KPIファイルを読み取ります:
  docs/specs/001-feature/tasks/TASK-001--kpi.json

2. データを理解する

KPI ファイルには以下の内容が含まれます:

{
  "task_id": "TASK-001",
  "evaluated_at": "2026-01-15T10:30:00Z",
  "overall_score": 8.2,
  "passed_threshold": true,
  "threshold": 7.5,
  "kpi_scores": [
    {
      "category": "Spec Compliance",
      "weight": 30,
      "score": 8.5,
      "weighted_score": 2.55,
      "metrics": {
        "acceptance_criteria_met": 9.0,
        "requirements_coverage": 8.0,
        "no_scope_creep": 8.5
      },
      "evidence": [
        "Acceptance criteria: 9/10 checked",
        "Requirements coverage: 8/10"
      ]
    }
  ],
  "recommendations": [
    "Code Quality: Moderate improvements possible"
  ],
  "summary": "Score: 8.2/10 - PASSED"
}

3. 判定を行う

overall_score と passed_threshold を使用します:

IF passed_threshold == true:
  → タスクが品質基準を満たしている
  → 承認して進める

IF passed_threshold == false:
  → タスクに改善が必要
  → 推奨事項から改善の具体的な対象を確認
  → 修正仕様を作成

ワークフローとの統合

タスクレビューにおいて (evaluator-agent)

## レビュープロセス

1. KPIファイルを読み取る: TASK-XXX--kpi.json
2. overall_score と kpi_scores を抽出
3. タスクファイルを読み取って検証
4. 評価レポートを生成
5. passed_threshold に基づいて判定

agents_loop 内

# KPIファイルの存在を確認
kpi_path = spec_path / "tasks" / f"{task_id}--kpi.json"

if kpi_path.exists():
    kpi_data = json.loads(kpi_path.read_text())
    
    if kpi_data["passed_threshold"]:
        # 品質基準を満たしている
        advance_state("update_done")
    else:
        # さらなる改善が必要
        fix_targets = kpi_data["recommendations"]
        create_fix_task(fix_targets)
        advance_state("fix")
else:
    # KPIがまだ生成されていない - タスクが実装されていない可能性
    log_warning("No KPI data found")

マルチイテレーションループ

最大3回の再試行ではなく、品質基準を満たすまでイテレーションします:

イテレーション1: スコア 6.2 → 失敗 → 修正: テストカバレッジの向上
イテレーション2: スコア 7.1 → 失敗 → 修正: 複雑な関数のリファクタリング  
イテレーション3: スコア 7.8 → 成功 → 進める

各イテレーションでタスク保存時に KPI ファイルが自動更新されます。

基準値ガイドライン

スコア	品質レベル	アクション
9.0-10.0	優秀	承認し、ベストプラクティスを記録
8.0-8.9	良好	軽微な注釈付きで承認
7.0-7.9	許容範囲	承認 (基準値が 7.5 の場合)
6.0-6.9	基準以下	具体的な改善を要求
< 6.0	不良	大規模な修正が必要

推奨される基準値

プロジェクトタイプ	基準値	根拠
本番 MVP	8.0	高い品質が必要
内部ツール	7.0	充分な品質
プロトタイプ	6.0	完璧さより機能
重要システム	8.5	妥協なし

メトリクスの詳細

仕様準拠性のメトリクス

受け入れ基準の充足

• 計算式: (チェック済み基準数 / 総基準数) * 10
• 出典: タスクファイルのチェックボックス数
• 例: 9/10 チェック済み = 9.0

要件カバレッジ

• 計算式: このタスクでカバーされる REQ-ID の数
• 出典: traceability-matrix.md
• 例: 4 つの要件をカバー = 8.0

スコープ逸脱なし

• 計算式: (実装ファイル数 / 予定ファイル数) * 10
• 出典: タスク「作成するファイル」 vs 実際のファイル
• ペナルティ: 不足しているファイルまたは予期しない追加

コード品質のメトリクス

静的解析

• Java: Maven Checkstyle
• TypeScript: ESLint
• Python: ruff
• スコア: 合格で 10、問題ありで 5

複雑性

• 計算式: 50 行を超える関数の数
• スコア: 10 - (長い関数の割合 * 5)
• ペナルティ: 大規模で複雑な関数

パターン準拠性

• チェック: ナレッジグラフパターン
• 出典: knowledge-graph.json
• 検証: 実装がプロジェクトパターンに従っているか

テストカバレッジのメトリクス

ユニットテスト実装

• 計算式: min(10, テストファイル数 * 5)
• 2 つのテストファイル = 最高スコア
• ペナルティ: テストが不足

テスト/コード比率

• 計算式: (テスト数 / コード数) * 10
• 1:1 比率 = 10/10
• 理想: コードファイルごとに最低 1 つのテストファイル

カバレッジパーセンテージ

• 出典: カバレッジレポート (JaCoCo, lcov など)
• 計算式: カバレッジパーセンテージ / 10
• 80% カバレッジ = 8.0

契約充足度のメトリクス

提供物検証

• チェック: ファイルが存在し、期待されるシンボルをエクスポート
• 出典: タスク provides フロントマッター
• 検証: 契約が満たされているか

期待値充足

• チェック: 依存関係が必要なファイル/シンボルを提供
• 出典: タスク expects フロントマッター
• 検証: 前提条件が満たされているか

KPI ファイルが見つからない場合

TASK-XXX--kpi.json が存在しない場合:

1. タスクが修正されたことがない - フックはファイル保存時に実行
2. フックが失敗した - Claude Code ログを確認
3. 新しいタスク - フックをトリガーするためにまずファイルを保存

KPI を手動で計算しようとしないでください。 フックは以下の場合に自動実行されます:

• タスクファイルが保存されたとき (Write ツール)
• タスクファイルが編集されたとき (Edit ツール)

ベストプラクティス

1. 常に KPI ファイルの存在を確認

評価前に:

KPIファイルが存在するか確認します:
  docs/specs/[ID]/tasks/TASK-XXX--kpi.json

見つからない場合:
  - タスクがまだ実装されていない可能性がある
  - ユーザーにタスクファイルを最初に保存するよう依頼

2. メトリクスを信頼する

KPI は客観的です。ドキュメント化されたエビデンスがある場合のみオーバーライド:

• メトリクスに記載されていない重大なセキュリティ問題
• 静的解析で検出されないロジックエラー
• メトリクスで測定されない例外的な品質

3. 低い KPI をイテレーションで改善

特定のカテゴリをターゲット:

❌ 「コード品質の問題を修正」
✅ 「コード品質 KPI を 5.2 から 7.0 に改善:
    - 複雑性: processData() をリファクタリング (5→8)
    - パターン: エラーハンドリングを追加 (6→8)」

4. KPI のトレンドを追跡

時間とともに品質を監視:

スプリント1: 平均 KPI 6.8
スプリント2: 平均 KPI 7.3 (+0.5)
スプリント3: 平均 KPI 7.9 (+0.6)

トラブルシューティング

KPI ファイルが生成されない

確認事項:

1. hooks.json でフックが有効
2. タスクファイル名が TASK-*.md パターンに一致
3. ファイルが実際に保存された (表示されただけではない)

KPI スコアが間違って見える

検証:

1. エビデンスフィールドでデータソースを確認
2. ファイルが予定されたパスに存在することを確認
3. いくつかのメトリクスはビルドツールが必要 (Maven, npm)

良いコードなのにスコアが低い

考えられる原因:

• テストファイルが不足
• カバレッジレポートが生成されていない
• 受け入れ基準がチェックされていない
• 린トルールが厳しすぎる

スコアだけでなく、根本原因を修正します。

例

例1: KPI データの読み取り

タスク品質を評価するために KPI ファイルを読み取ります:
  docs/specs/001-feature/tasks/TASK-042--kpi.json

データに基づいて:
- 総合スコア: 6.8/10 (基準値以下)
- 最も低い KPI: テストカバレッジ (5.0/10)
- 推奨: ユニットテストを追加

判定: 修正を要求 - テストカバレッジの改善をターゲット

例2: イテレーション判定

イテレーション1 KPI: スコア 6.2 → 失敗
- 仕様準拠性: 7.0 ✓
- コード品質: 5.5 ✗
- テストカバレッジ: 6.0 ✗

修正ターゲット:
1. 複雑な関数をリファクタリング (コード品質)
2. テストカバレッジを追加 (テストカバレッジ)

イテレーション2 KPI: スコア 7.8 → 成功 ✓

例3: agents_loop の統合

# agents_loop で、実装ステップの後
kpi_file = spec_dir / "tasks" / f"{task_id}--kpi.json"

if kpi_file.exists():
    kpi = json.loads(kpi_file.read_text())
    
    if kpi["passed_threshold"]:
        print(f"✅ タスクが品質チェックに合格: {kpi['overall_score']}/10")
        advance_state("update_done")
    else:
        print(f"❌ タスクが品質チェックに不合格: {kpi['overall_score']}/10")
        print("推奨事項:")
        for rec in kpi["recommendations"]:
            print(f"  - {rec}")
        advance_state("fix")

参考資料

• evaluator-agent.md - KPI データを使用して評価するエージェント
• hooks.json - 自動生成用フック設定
• task-kpi-analyzer.py - フックスクリプト (直接実行しないこと)
• agents_loop.py - KPI による判定を読み取るオーケストレータ