task-quality-kpi

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

概要

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

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

┌─────────────────────────────────────────────────────────────┐
│  HOOK (auto-executes)                                       │
│  Trigger: PostToolUse on TASK-*.md                          │
│  Script: task-kpi-analyzer.py                               │
│  Output: TASK-XXX--kpi.json                                 │
├─────────────────────────────────────────────────────────────┤
│  SKILL / AGENT (reads output)                               │
│  Input: TASK-XXX--kpi.json                                  │
│  Action: Make evaluation decisions                          │
└─────────────────────────────────────────────────────────────┘

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

問題	解決策
スキルからスクリプトを実行できない	ファイルの保存時にフックが自動実行されます
主観的な review_status	定量的な 0～10 のスコア
「問題なさそうです」	エビデンスに基づく評価
合否の二択	段階的な品質レベル

KPI ファイルの場所

タスクファイルを変更した後、KPI データを次の場所で確認します。

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

KPI カテゴリ

┌─────────────────────────────────────────────────────────────┐
│                    OVERALL SCORE (0-10)                     │
├─────────────────────────────────────────────────────────────┤
│  Spec Compliance (30%)                                      │
│  ├── Acceptance Criteria Met (0-10)                         │
│  ├── Requirements Coverage (0-10)                           │
│  └── No Scope Creep (0-10)                                  │
├─────────────────────────────────────────────────────────────┤
│  Code Quality (25%)                                         │
│  ├── Static Analysis (0-10)                                 │
│  ├── Complexity (0-10)                                      │
│  └── Patterns Alignment (0-10)                              │
├─────────────────────────────────────────────────────────────┤
│  Test Coverage (25%)                                        │
│  ├── Unit Tests Present (0-10)                              │
│  ├── Test/Code Ratio (0-10)                                 │
│  └── Coverage Percentage (0-10)                             │
├─────────────────────────────────────────────────────────────┤
│  Contract Fulfillment (20%)                                 │
│  ├── Provides Verified (0-10)                               │
│  └── Expects Satisfied (0-10)                               │
└─────────────────────────────────────────────────────────────┘

カテゴリの重み

カテゴリ	重み	理由
仕様への準拠	30%	最も重要です。依頼されたものを構築できたかを示します
コード品質	25%	技術的な優秀さ
テストカバレッジ	25%	検証と信頼性
契約の充足	20%	他のタスクとの統合

使用する場面

• タスク品質評価のために KPI データを読み取る
• 品質指標とスコアの内訳を理解する
• 定量データに基づいて、改善を続けるか承認するかを判断する
• KPI チェックを自動ループ（agents_loop.py）に統合する
• エビデンスに基づく評価レポートを生成する

手順

1. KPI データを読み取る（主な用途）

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

Read the KPI file:
  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:
  → Task meets quality standards
  → Approve and proceed

IF passed_threshold == false:
  → Task needs improvement
  → Check recommendations for specific targets
  → Create fix specification

ワークフローとの統合

タスクレビュー内（evaluator-agent）

## Review Process

1. Read KPI file: TASK-XXX--kpi.json
2. Extract overall_score and kpi_scores
3. Read task file to validate
4. Generate evaluation report
5. Decision based on passed_threshold

agents_loop 内

# Check KPI file exists
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"]:
        # Quality threshold met
        advance_state("update_done")
    else:
        # Need more work
        fix_targets = kpi_data["recommendations"]
        create_fix_task(fix_targets)
        advance_state("fix")
else:
    # KPI not generated yet - task may not be implemented
    log_warning("No KPI data found")

複数回の反復ループ

最大 3 回の再試行ではなく、品質のしきい値を満たすまで反復します。

Iteration 1: Score 6.2 → FAILED → Fix: Improve test coverage
Iteration 2: Score 7.1 → FAILED → Fix: Refactor complex functions  
Iteration 3: Score 7.8 → PASSED → Proceed

タスクを保存するたびに、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	妥協は許されません

指標の詳細

仕様準拠の指標

受け入れ基準の達成数

• 計算式：(checked_criteria / total_criteria) * 10
• 参照元：タスクファイルのチェックボックス数
• 例：10 項目中 9 項目にチェック済み = 9.0

要件カバレッジ

• 計算方法：このタスクが対象とする REQ-ID の数
• 参照元：traceability-matrix.md
• 例：4 件の要件をカバー = 8.0

スコープクリープなし

• 計算式：(implemented_files / expected_files) * 10
• 参照元：タスクの「作成するファイル」と実際のファイル
• 減点対象：不足ファイルや想定外の追加

コード品質の指標

静的解析

• Java：Maven Checkstyle
• TypeScript：ESLint
• Python：ruff
• スコア：問題がなければ 10、問題が見つかった場合は 5

複雑度

• 計算方法：50 行を超える関数の数
• スコア：10 - (long_functions_ratio * 5)
• 減点対象：規模が大きく複雑な関数

パターンとの整合性

• チェック対象：ナレッジグラフのパターン
• 参照元：knowledge-graph.json
• 検証内容：実装がプロジェクトのパターンに従っているか

テストカバレッジの指標

ユニットテストの有無

• 計算式：min(10, test_files * 5)
• テストファイルが 2 つあれば最高スコア
• 減点対象：テストの不足

テストとコードの比率

• 計算式：(test_count / code_count) * 10
• 比率が 1:1 の場合は 10/10
• 理想：コードファイル 1 つにつき、テストファイルが少なくとも 1 つ

カバレッジ率

• 参照元：カバレッジレポート（JaCoCo、lcov など）
• 計算式：coverage_percent / 10
• カバレッジ 80% = 8.0

コントラクト充足メトリクス

提供内容を検証

• 確認内容：ファイルが存在し、想定されるシンボルをエクスポートしている
• ソース：タスクの provides フロントマター
• 検証内容：コントラクトが満たされている

期待条件の充足を検証

• 確認内容：依存関係が必要なファイル／シンボルを提供している
• ソース：タスクの expects フロントマター
• 検証内容：前提条件が満たされている

KPI ファイルがない場合

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

1. タスクが一度も変更されていない - フックはファイルの保存時に実行されます
2. フックが失敗した - Claude Code のログを確認してください
3. タスクが新しい - まずファイルを保存して、フックを実行してください

KPI を手動で計算しないでください。 次の場合にフックが自動的に実行されます：

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

ベストプラクティス

1. KPI ファイルが存在することを必ず確認する

評価する前に：

Check if KPI file exists:
  docs/specs/[ID]/tasks/TASK-XXX--kpi.json

If missing:
  - Task may not be implemented yet
  - Ask user to save the task file first

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

KPI は客観的な指標です。文書化された根拠がある場合にのみ、評価を上書きしてください：

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

3. KPI が低い場合は改善を繰り返す

対象のカテゴリを絞ります：

❌ "Fix code quality issues"
✅ "Improve Code Quality KPI from 5.2 to 7.0:
    - Complexity: Refactor processData() (5→8)
    - Patterns: Add error handling (6→8)"

4. KPI の推移を追跡する

品質の経時的な変化を監視します：

Sprint 1: Average KPI 6.8
Sprint 2: Average KPI 7.3 (+0.5)
Sprint 3: Average KPI 7.9 (+0.6)

トラブルシューティング

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

確認事項：

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

KPI スコアが正しくないように見える

検証事項：

1. evidence フィールドでデータソースを確認する
2. 想定されるパスにファイルが存在することを確認する
3. メトリクスによってはビルドツール（Maven、npm）が必要です

コードの品質が高いのにスコアが低い

考えられる原因：

• テストファイルがない
• カバレッジレポートが生成されていない
• 受け入れ基準が確認されていない
• Lint ルールが厳しすぎる

スコアだけでなく、根本原因を解決してください。

例

例 1：KPI データを読み取る

Read the KPI file to evaluate task quality:
  docs/specs/001-feature/tasks/TASK-042--kpi.json

Based on the data:
- Overall score: 6.8/10 (below threshold)
- Lowest KPI: Test Coverage (5.0/10)
- Recommendation: Add unit tests

Decision: REQUEST FIXES - target Test Coverage improvement

例 2：反復に基づく判断

Iteration 1 KPI: Score 6.2 → FAILED
- Spec Compliance: 7.0 ✓
- Code Quality: 5.5 ✗
- Test Coverage: 6.0 ✗

Fix targets:
1. Refactor complex functions (Code Quality)
2. Add test coverage (Test Coverage)

Iteration 2 KPI: Score 7.8 → PASSED ✓

例 3：agents_loop との統合

# In agents_loop, after implementation step
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"✅ Task passed quality check: {kpi['overall_score']}/10")
        advance_state("update_done")
    else:
        print(f"❌ Task failed quality check: {kpi['overall_score']}/10")
        print("Recommendations:")
        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 を読み取るオーケストレーター