qe-quality-assessment

QE 品質評価

目的

自動品質ゲート、メトリクスの集約、傾向分析、デプロイ準備状況の評価など、v3 の品質評価機能の利用方法を説明します。

有効化するタイミング

• コード品質を評価するとき
• 品質ゲートを設定するとき
• デプロイ準備状況を評価するとき
• 品質メトリクスを追跡するとき
• 品質レポートを生成するとき

クイックスタート

# Run quality assessment
aqe quality assess --scope src/ --gates all

# Check deployment readiness
aqe quality deploy-ready --environment production

# Generate quality report
aqe quality report --format dashboard --period 30d

# Compare quality between releases
aqe quality compare --from v1.0 --to v2.0

エージェントのワークフロー

// Comprehensive quality assessment
Task("Assess code quality", `
  Evaluate quality for src/:
  - Code complexity (cyclomatic, cognitive)
  - Test coverage and mutation score
  - Security vulnerabilities
  - Code smells and technical debt
  - Documentation coverage
  Generate quality score and recommendations.
`, "qe-quality-analyzer")

// Deployment readiness check
Task("Check deployment readiness", `
  Evaluate if release v2.1.0 is ready for production:
  - All tests passing
  - Coverage thresholds met
  - No critical vulnerabilities
  - Performance benchmarks passed
  - Documentation updated
  Provide go/no-go recommendation.
`, "qe-deployment-advisor")

品質の評価軸

1. コード品質メトリクス

await qualityAnalyzer.assessCode({
  scope: 'src/**/*.ts',
  metrics: {
    complexity: {
      cyclomatic: { max: 15, warn: 10 },
      cognitive: { max: 20, warn: 15 }
    },
    maintainability: {
      index: { min: 65 },
      duplication: { max: 3 }  // percent
    },
    documentation: {
      publicAPIs: { min: 80 },
      complexity: { min: 70 }
    }
  }
});

2. 品質ゲート

await qualityGate.evaluate({
  gates: {
    coverage: { min: 80, blocking: true },
    // Fault detection — coverage is necessary but NOT sufficient (ADR-113).
    // A suite can hit 90% coverage and catch no bugs; mutation score does not lie.
    mutationScore: { min: 0.6, blocking: false },   // warn-by-default; opt-in blocking
    regenerability: { min: 0.5, blocking: false },  // Deletion Test: durable oracle backing per module
    complexity: { max: 15, blocking: false },
    vulnerabilities: { critical: 0, high: 0, blocking: true },
    duplications: { max: 3, blocking: false },
    techDebt: { maxRatio: 5, blocking: false }
  },
  action: {
    onPass: 'proceed',
    onFail: 'block-merge',
    onWarn: 'notify'
  }
});

2a. 再生成可能性ゲート（ADR-113）

カバレッジは実行された行を測定し、ミューテーションスコアはテストが バグに気づくかどうかを測定します。また、再生成可能性は削除テスト、つまり「このモジュールを 削除して再生成した場合、誤った再構築を検出できるか？」に答えるものです。再生成可能性 = モジュールを支える 耐久性ティア（durable > live > ephemeral > none）に応じて割引したミューテーションスコアです。再実装後も残らないため、 ephemeral のテストのみではスコアが低くなります。

import { evaluateRegenerabilityGate } from '../../../src/feedback/regenerability-gate.js';

const verdict = evaluateRegenerabilityGate(moduleProfiles, {
  mutationScoreMin: 0.6,
  regenerabilityMin: 0.5,
  mode: 'warn',   // 'block' to fail CI; warn-by-default so adoption never breaks pipelines
});
// verdict.passed (thresholds met) · verdict.blocking (should fail CI) · verdict.failures[]

レポートでは、カバレッジの隣に表示します：Coverage 88% ✅ / Mutation 41% ⚠️ / Regenerability: ephemeral-only ⚠️。

3. デプロイ準備状況

await deploymentAdvisor.assess({
  release: 'v2.1.0',
  criteria: {
    testing: {
      unitTests: 'all-pass',
      integrationTests: 'all-pass',
      e2eTests: 'critical-pass',
      performanceTests: 'baseline-met'
    },
    quality: {
      coverage: 80,
      noNewVulnerabilities: true,
      noRegressions: true
    },
    documentation: {
      changelog: true,
      apiDocs: true,
      releaseNotes: true
    }
  }
});

品質スコアの計算

quality_score:
  components:
    test_coverage:
      weight: 0.25
      metrics: [statement, branch, function]

    code_quality:
      weight: 0.20
      metrics: [complexity, maintainability, duplication]

    security:
      weight: 0.25
      metrics: [vulnerabilities, dependencies]

    reliability:
      weight: 0.20
      metrics: [bug_density, flaky_tests, error_rate]

    documentation:
      weight: 0.10
      metrics: [api_coverage, readme, changelog]

  scoring:
    A: 90-100
    B: 80-89
    C: 70-79
    D: 60-69
    F: 0-59

品質ダッシュボード

interface QualityDashboard {
  overallScore: number;  // 0-100
  grade: 'A' | 'B' | 'C' | 'D' | 'F';
  dimensions: {
    name: string;
    score: number;
    trend: 'improving' | 'stable' | 'declining';
    issues: Issue[];
  }[];
  gates: {
    name: string;
    status: 'pass' | 'fail' | 'warn';
    value: number;
    threshold: number;
  }[];
  trends: {
    period: string;
    scores: number[];
    alerts: Alert[];
  };
  recommendations: Recommendation[];
}

CI/CD との統合

# Quality gate in pipeline
quality_check:
  stage: verify
  script:
    - aqe quality assess --gates all --output report.json
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  artifacts:
    reports:
      quality: report.json
  allow_failure:
    exit_codes:
      - 1  # Warnings only

実行履歴

品質評価の実行後は毎回、このスキルディレクトリの run-history.json に結果を追記します：

node -e "
const fs = require('fs');
const h = JSON.parse(fs.readFileSync('.claude/skills/qe-quality-assessment/run-history.json'));
h.runs.push({date: new Date().toISOString().split('T')[0], gate_result: 'PASS_OR_FAIL', failed_checks: []});
fs.writeFileSync('.claude/skills/qe-quality-assessment/run-history.json', JSON.stringify(h, null, 2));
"

各実行の前に run-history.json を読み込み、直近 5 回の実行中 3 回で品質ゲートに失敗している場合は警告します。

スキルの組み合わせ

• 評価の前 → まず /qe-coverage-analysis と /mutation-testing を実行します
• 問題が見つかった場合 → /test-failure-investigator を使用して失敗の原因を調査します
• PR レビューの場合 → /code-review-quality と組み合わせて包括的にレビューします

注意点

• エージェントが報告する合格／不合格のステータスを決して信用しないでください。エージェントが合格と主張したテストの失敗が 12 件検出されています（Nagual パターン、報酬 0.92）。
• 完了を装うケースに注意してください。エージェントが package.json から値を読み取らず、バージョン「3.0.0」をハードコードしたことがありました。出力に含まれる実際の値を確認してください。
• 問題は優先度の高い順（P0 → P1 → P2）に対応し、各段階の間で検証してください。すべてを並行して修正しないでください。
• quality-assessment ドメインの成功率は 53.7% です。失敗を想定し、フォールバックを用意してください。
• HybridMemoryBackend の初期化に失敗した場合は、aqe health を実行して診断するか、aqe init を実行して再初期化してください。

連携

主要エージェント：qe-quality-analyzer、qe-deployment-advisor、qe-metrics-collector コーディネーター：qe-quality-coordinator 関連スキル：qe-coverage-analysis、security-testing