Claude Code × Vitest：カバレッジポリシーとvitest-mcpでテスト不足を自律的に補う

はじめに

TDD（開発サイクルの方法論）でも、Playwright（ブラウザE2E）でもない。コードベース全体のユニットテストカバレッジが放置されていく問題——vitest-mcpとCLAUDE.mdのカバレッジポリシーでClaude Codeがテスト不足を自律的に検出・補完する話だ。

「実装が終わったらテストを書く」という約束は、多くのプロジェクトで守られないまま技術的負債として積み上がる。フィーチャー実装が優先され、カバレッジは30〜40%のまま1年が経つ。さらにAIコーディングツールの普及でこの問題は悪化しやすい。Claude Codeで関数やコンポーネントを生成しても、テストまで自動で書かれることは少ないからだ。

「AIが書いたコードはAIがテストまで書く」という規約をCLAUDE.mdで定義し、vitest-mcpでカバレッジの現状を可視化し、GitHub ActionsのCIゲートでカバレッジの低下を自動ブロックする——この3つを組み合わせることで、テストが後回しになる構造的な問題に対処できる。

CLAUDE.mdでテストポリシーを定義する——「実装したらテストも作る」をデフォルトに

なぜCLAUDE.mdが必要か

CLAUDE.mdにテスト規約がなければ、Claude Codeは「テストが必要か」を毎回文脈から推測しようとする。プロジェクトのコード構造によっては実装のみを生成することが多い。「新しい関数を追加するときは必ずテストも作れ」という期待が暗黙のままだと、実現しない。

# CLAUDE.md（テスト規約）
## Testing Policy

### Vitestルール
- テストファイルはソースファイルと同一ディレクトリに配置（例: Button.tsx → Button.test.tsx）
- 新しい関数・コンポーネントを追加する際は必ずテストファイルも作成すること
- describe/it形式で記述。test()単体は禁止
- モックは最小限に留める。外部APIのみmock化（内部ロジックはmockしない）

### カバレッジ閾値（下限）
- lines: 80%
- functions: 80%
- branches: 75%
- statements: 80%

### PRルール
- カバレッジが閾値を下回るPRはマージ不可（GitHub ActionsでVitest Coverage Reportアクション必須）
- 新規追加ファイルのカバレッジ: 90%以上を目標とする

### カバレッジ確認コマンド
- npx vitest run --coverage を実行してからPRを出すこと

このCLAUDE.mdがある状態でClaude Codeに「ユーザー認証のutility関数を書いて」と依頼すると、関数本体と同じディレクトリに.test.tsファイルが一緒に生成される。「後でテストを書く」という先送りが構造的になくなる。

カバレッジ閾値の設定ロジック

閾値を80%に設定するのは多くのプロジェクトで現実的な基準だが、既存プロジェクトへの導入では「現状値+10%」から始めて段階的に引き上げるアプローチが現実的だ。CLAUDE.mdに「現在の目標閾値」を明記して、スプリントごとに更新するのがよい。最初から90%を要求すると、カバレッジ不足で全てのPRがブロックされて開発が止まる。

vitest-mcpでClaude Codeにカバレッジの「見る目」を持たせる

コミュニティ製MCPサーバーの概要

github.com/djankies/vitest-mcpはClaude Code向けにLLM最適化されたVitestのMCPサーバーだ。コミュニティ製のため、導入前にリポジトリのメンテナンス状態・npmパッケージの公開状況を確認してほしい。

インストールはclaude mcp addコマンドで行う。

claude mcp add vitest -- npx -y @djankies/vitest-mcp

または.mcp.jsonに直接設定する。

{
  "mcpServers": {
    "vitest": {
      "command": "npx",
      "args": ["-y", "@djankies/vitest-mcp"]
    }
  }
}

4つのMCPツールの使い方

vitest-mcpが提供するMCPツールはそれぞれ役割が分かれている。set_project_rootはプロジェクトルートを設定するもので、他のツールを使う前に必ず最初に実行する。list_testsはテストファイルを一覧して、Claude Codeが対象ファイルに絞り込むのに使う。run_testsはテストを実行し、構造化されたJSONアウトプットとログキャプチャ付きで結果を返す。analyze_coverageはカバレッジ分析で、summaryモードとdetailedモードがあり、行単位のカバレッジギャップを検出できる。

重要な機能として安全ガードが組み込まれている。全テストスイートの一括実行の防止・watchモードの起動禁止（セッションを占有するため）・無効なvitestコマンドのブロックが入っている。LLMが誤って意図しない大規模テスト実行を起こすリスクを減らす設計だ。

自然言語指示パターン

vitest-mcpが導入された状態でのClaude Codeへの指示はこうなる。

「プロジェクトルートを設定してカバレッジが低いファイルを特定し、
カバレッジギャップを埋めるテストを追加して」

「src/utils/以下のテストを実行して、失敗しているテストを修正して」

「カバレッジ分析でdetailedモードを実行して、80%を下回るファイルのテストを追加して」

人間がカバレッジレポートを読んで「このファイルのテストが足りない」と判断して指示する作業が、analyze_coverageの結果をClaude Code自身が読むことで不要になる。

GitHub ActionsでカバレッジをPRゲートにする——CIが下限を自動強制する

vitest.config.tsのカバレッジ設定

Vitestのカバレッジ設定はvitest.config.tsで行う。

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',          // v3.2.0以降: ASTリマッピングでIstanbul同等の精度
      reporter: ['text', 'json-summary', 'html'],
      include: ['src/**/*.{ts,tsx}'],
      exclude: ['src/**/*.stories.tsx', 'src/**/*.d.ts', 'node_modules'],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 75,
        statements: 80,
      },
    },
  },
})

プロバイダーの選択について補足しておく。Vitestのv3.2.0以降、V8カバレッジにAST基盤のリマッピングが導入されてIstanbulと同等の精度になった。ViteプロジェクトではV8がデフォルトで高速性も高いため推奨できる。Istanbul側の13年の実績とCI環境での安定性を重視する場合は引き続きInstanbulを選んでよい。どちらを選ぶかより、閾値を設定してCIゲートに組み込むことの方が重要だ。

GitHub Actionsワークフローの設定

PR時にカバレッジレポートを自動投稿するGitHub Actionsワークフローの構成はこうなる。Vitestカバレッジレポートを投稿するアクションはGitHub Marketplaceで提供されているが、正確なアクションIDはリサーチ時点で未確定のため、導入前にGitHub Marketplaceで「Vitest Coverage Report」を検索して公式のowner/repo@version形式を確認してほしい。

# .github/workflows/test-coverage.yml
name: Test Coverage

on:
  pull_request:
    branches: [main]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx vitest run --coverage --reporter=json-summary
      - name: Coverage Report
        uses: <GitHub Marketplace で確認したアクションID>
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          summary-file: coverage/coverage-summary.json
          threshold: 80

このワークフローが動いている状態では、Claude Codeが実装を追加してテストが追いついていない場合、GitHub ActionsのCIがPRをブロックする。マージ前にClaude Code自身がカバレッジを修正するループが自然に回る設計になる。

CLAUDE.mdの「PRルール：カバレッジを下回るとマージ不可」という定義と合わせることで、「ポリシーはあるが守られていない」という状況をCIで技術的に強制できる。

まとめ

テストカバレッジが放置される問題は、意識の問題ではなく仕組みの問題だ。CLAUDE.mdで「実装したらテストも作る」をデフォルトにし、vitest-mcpでClaude Code自身がカバレッジギャップを検出できるようにし、GitHub ActionsのCIゲートで低カバレッジのPRを自動ブロックする——この3つが揃うことで、テストを後回しにする文化的な問題が構造的に解消される。

まず着手するなら、vitest.config.tsのcoverageセクションにthresholdsを追加してCLAUDE.mdにテスト規約を書くことだ。「現状のカバレッジを計測して、そこから閾値を決める」というアプローチで始めれば、既存プロジェクトでも段階的に整備できる。

コメント

タイトルとURLをコピーしました