test-updates

テストの更新と保守

概要

コードベース全体のテストを保守、生成、強化するために、TDD／BDD の原則を適用する詳細なテスト管理システムです。このスキルは、自らが推奨する手法を実践します。開発に TDD の原則を用い、ベストプラクティスを示す生きた見本として機能します。

基本理念

• RED-GREEN-REFACTOR：TDD サイクルを厳格に遵守します
• 振る舞い優先：コードが何をすべきかを表す BDD パターン
• 不変条件のエンコード：テストで振る舞いだけでなく、設計上の決定も保護します
• メタ・ドッグフーディング：このスキル自体のテストが、教える原則を実践します
• 品質ゲート：テストの完了とみなす前に詳細な検証を行います

概要

以下を行うモジュール式のテスト管理システムです。

• テストや更新が必要な箇所を検出します
• TDD の原則に沿ってテストを生成します
• BDD パターンを用いて既存のテストを強化します
• 複数の観点からテストの品質を検証します

クイックスタート

初回利用時の簡単なチェックリスト

• pytest がインストールされていることを確認します（pip install pytest）
• ソースコードを src/ または同様のディレクトリに配置します
• tests/ ディレクトリが存在しない場合は作成します
• 変更内容を把握するため、最初に Skill(sanctum:git-workspace-review) を実行します
• 対象を絞って更新するには、Skill(test-updates) --target <specific-module> から始めます

詳細なテスト更新

# Run full test update workflow
Skill(test-updates)

検証： pytest -v を実行してテストが成功することを確認します。

対象を絞ったテスト更新

# Update tests for specific paths
Skill(test-updates) --target src/sanctum/agents
Skill(test-updates) --target tests/test_commit_messages.py

検証： pytest -v を実行してテストが成功することを確認します。

新機能の TDD

# Apply TDD to new code
Skill(test-updates) --tdd-only --target new_feature.py

検証： pytest -v を実行してテストが成功することを確認します。

スクリプトを直接使用する

人が読みやすい出力：

# Analyze test coverage gaps
python plugins/sanctum/scripts/test_analyzer.py --scan src/

# Generate test scaffolding
python plugins/sanctum/scripts/test_generator.py \
    --source src/my_module.py --style pytest_bdd

# Check test quality
python plugins/sanctum/scripts/quality_checker.py \
    --validate tests/test_my_module.py

検証： pytest -v を実行してテストが成功することを確認します。

プログラムから扱う出力（Claude Code 用）：

# Get JSON output for programmatic parsing - test_analyzer
python plugins/sanctum/scripts/test_analyzer.py \
    --scan src/ --output-json

# Returns:
# {
#   "success": true,
#   "data": {
#     "source_files": ["src/module.py", ...],
#     "test_files": ["tests/test_module.py", ...],
#     "uncovered_files": ["module_without_tests", ...],
#     "coverage_gaps": [{"file": "...", "reason": "..."}]
#   }
# }

# Get JSON output - test_generator
python plugins/sanctum/scripts/test_generator.py \
    --source src/my_module.py --output-json

# Returns:
# {
#   "success": true,
#   "data": {
#     "test_file": "path/to/test_my_module.py",
#     "source_file": "src/my_module.py",
#     "style": "pytest_bdd",
#     "fixtures_included": true,
#     "edge_cases_included": true,
#     "error_cases_included": true
#   }
# }

# Get JSON output - quality_checker
python plugins/sanctum/scripts/quality_checker.py \
    --validate tests/test_my_module.py --output-json

# Returns:
# {
#   "success": true,
#   "data": {
#     "static_analysis": {...},
#     "dynamic_validation": {...},
#     "metrics": {...},
#     "quality_score": 85,
#     "quality_level": "QualityLevel.GOOD",
#     "recommendations": [...]
#   }
# }

検証： pytest -v を実行してテストが成功することを確認します。

使用する場面

次のような場合にこのスキルを使用してください。

• コード変更後にテストを更新する
• 新機能のテストを生成する
• 既存のテスト品質を向上させる
• 詳細なテストカバレッジを検証する

特に次の用途に適しています。

• コミット前のテスト検証
• CI/CD パイプラインとの統合
• テストで安全性を確保したリファクタリング
• 新しい開発者のオンボーディング

使用しない場面

• テストスイートの監査
  • pensive:test-review を使用します
• プロダクションコードの作成
  • まず実装に集中します
• テストスイートの監査
  • pensive:test-review を使用します
• プロダクションコードの作成
  • まず実装に集中します

ワークフローとの統合

フェーズ 1：検出

1. コードベースをスキャンしてテストの不足箇所を探します
2. 最近の変更を分析します
3. 失敗しているテストや古くなったテストを特定します

検出パターンについては modules/test-discovery.md を参照してください。

フェーズ 2：戦略

1. 適切な BDD スタイルを選びます（modules/bdd-patterns.md を参照）
2. テスト構成を計画します
3. 品質基準を定義します
4. テストとしてエンコードする設計上の不変条件を特定します

フェーズ 2.5：不変条件をエンコードするテスト

動作テストを書く前に、コードが依存している設計上の不変条件を特定し、それらの不変条件が破られたときに失敗するテストを書きます。

エンコードする内容：

• モジュール境界の制約（A が B からインポートしない）
• データフローの方向（イベントはパブリッシャーからサブスクライバーへ流れ、逆方向には流れない）
• API コントラクトの形式（公開インターフェースは、バージョン管理なしに変更されない）
• データ構造の選択（リストではなくマップを選択した場合、その選択を正当化する特性をテストする）
• エラー処理の戦略（フェイルファストの境界、復旧領域）

例：

def test_plugins_never_import_from_other_plugins():
    """Encode the invariant: plugins are independent modules.

    If this test breaks, someone is coupling plugins
    directly. Present the 3 options to a human:
    1. Preserve: revert the import, keep plugins independent
    2. Layer: add a shared interface in leyline instead
    3. Revise: merge the plugins (requires ADR)
    """
    for plugin_dir in plugin_dirs:
        imports = extract_imports(plugin_dir)
        for imp in imports:
            assert not imp.startswith("plugins."), (
                f"{plugin_dir} imports {imp} — violates plugin independence invariant"
            )

重要な理由： 不変条件をエンコードするテストは、基盤となるものです。エージェントが後になって不変条件と衝突する機能に遭遇したとき、テストの失敗によって、知らないうちに設計がずれていくのではなく、意識的な判断を迫られます。こうしたテストがなければ、誤った不変条件の判断が積み重なり、コードベースの修復が不可能になるまで進んでしまいます。

既存のテストを更新する場合：

不変条件をエンコードするテストを変更する必要がある場合、アサーションを黙って更新してはいけません。次の 3 つの選択肢とともに、人間によるレビューを求めてください。不変条件を維持する、既存の不変条件の上に重ねる、不変条件を改訂する。これは人間の知恵を必要とする判断です。モデルは学習データの「平均」に偏りがちで、こうした判断を誤ることがあまりにも多いためです。

フェーズ 3：実装

1. 失敗するテスト（RED）を書く - サイクルには Skill(superpowers:test-driven-development) を、ローカルでの内容には modules/tdd-workflow.md を使用します
2. 最小限の合格するコード（GREEN）を実装します
3. 明確さを重視してリファクタリングします（REFACTOR）

生成テンプレートについては modules/test-generation.md を参照してください。

フェーズ 4：検証

1. 静的解析とリンティング
2. 動的テストの実行
3. カバレッジと品質のメトリクス

検証基準については modules/quality-validation.md を参照してください。

品質保証

このスキルでは、複数の品質チェックを適用します：

• 静的：リンティング、型チェック、パターン検証
• 動的：サンドボックス環境でのテスト実行
• メトリクス：カバレッジ、ミューテーションスコア、複雑度分析
• 不変条件：設計判断に関するテストが弱められていないことの検証
• レビュー：ピアレビューのための構造化チェックリスト

例

BDD スタイルのテスト生成

追加のパターンについては modules/bdd-patterns.md を参照してください。

class TestGitWorkflow:
    """BDD-style tests for Git workflow operations."""

    def test_commit_workflow_with_staged_changes(self):
        """Committing with staged changes produces a formatted commit.

        GIVEN a Git repository with staged changes
        WHEN the user runs the commit workflow
        THEN it should create a commit with proper message format
        AND all tests should pass
        """
        # Test implementation following TDD principles
        pass

検証： pytest -v を実行して、テストが合格することを確認します。

テストの強化

• エッジケースとエラーシナリオを追加します
• パフォーマンスベンチマークを含めます
• 堅牢性を高めるため、ミューテーションテストを追加します

強化戦略については modules/test-enhancement.md を参照してください。

既存のスキルとの統合

1. git-workspace-review：変更のコンテキストを把握します
2. structure mapping：modules/structure-mapping.md を使って、レイアウト、言語、大きなファイルをマッピングします
3. test-driven-development：厳格な TDD の規律を適用します
4. skills-eval：品質と準拠状況を検証します

成功指標

• テストカバレッジ > 85%
• すべてのテストが BDD パターンに従っている
• CI で失敗するテストがゼロ
• ミューテーションスコア > 80%

トラブルシューティング FAQ

よくある問題

Q: 生成後にテストが失敗します A: これは想定どおりです！このスキルは TDD の原則に従っており、生成されたテストは最初に失敗するように設計されています。RED-GREEN-REFACTOR サイクルに従ってください。

1. テストを実行し、適切な理由で失敗することを確認します
2. テストを通すための最小限のコードを実装します
3. 読みやすさを高めるためにリファクタリングします

Q: テストがあるのに品質スコアが低いです A: 次のよくある問題がないか確認してください。

• BDD パターン（Given/When/Then）が不足している
• assert result is not None のような曖昧なアサーション
• ドキュメントがないテスト
• 長く複雑なテスト（50 行超）

Q: 生成されたテストが自分のコード構造と一致しません A: スクリプトは AST パターンを分析するため、指示が必要になる場合があります。

• --style フラグを使って、希望する BDD スタイルに合わせます
• ソースファイルに適切な関数やクラスの定義があることを確認します
• 生成された足場コードを確認し、必要に応じてカスタマイズします

Q: ミューテーションテストに時間がかかりすぎます A: ミューテーションテストはリソースを大量に消費します。

• サブセットをテストするには --quick-mutation フラグを使います
• まず重要なモジュールに集中します
• 詳細な分析を行うには、一晩実行します

Q: ファイルのテストが見つかりません A: アナライザーは命名規則を使用します。

• ソース：my_module.py → テスト：test_my_module.py
• テストファイルが pytest の命名パターンに従っていることを確認します
• テストディレクトリの構造が標準的であることを確認します

パフォーマンスのヒント

• 大規模なコードベース：特定のディレクトリに絞るには --target を使います
• CI との統合：ほかのチェックと並行して検証を実行します
• メモリ使用量：非常に大規模なプロジェクトでは、ファイルをバッチ処理します

サポートを受ける

1. 詳細なエラーメッセージを確認するには、スクリプトの出力を確認します
2. 詳しい情報を得るには --verbose フラグを使います
3. 具体的な推奨事項を確認するには、検証レポートを確認します
4. 規模を拡大する前に、小さなモジュールから始めてパターンを理解します

完了条件

• 対象ファイルにすべてのテスト更新を適用した後、pytest -v が失敗ゼロで成功する
• 対象範囲内のファイルのテストカバレッジが、pytest --cov の報告で 85% を超える
• すべての新しいテストに、modules/bdd-patterns.md の BDD パターンに沿った GIVEN/WHEN/THEN の docstring が含まれている
• quality_checker.py --validate <test_file> --output-json を実行すると、更新した各テストファイルの quality_score が 80 以上になる
• 不変条件をエンコードするテストを変更する場合、アサーションを変更する前に、3 つの選択肢（保持／階層化／修正）を提示して人間のレビュー対象としてフラグを立てる