dependency-resolver

依存関係リゾルバーのスキル

目的

このスキルは、プッシュ前にローカル環境と CI 環境の不一致を検出して解決し、DISCOVERIES.md の「CI Failure Resolution Process Analysis」に記録されている20〜45分のデバッグサイクルを防ぎます。

このスキルは、重要なギャップに対処します。既存のツール（ci-diagnostic-workflow、pre-commit-diagnostic）は、問題が発生した後に修正します。このスキルは、プッシュ前に不一致を検出します。

問題の説明

DISCOVERIES.md の分析より：

• 環境の不一致（ローカルの Python 3.12 と CI の Python 3.11）が、調査に20〜25分の余分な時間を要する原因になります
• バージョンのずれ（ローカルの ruff 0.12.7 と CI の ruff 0.13.0）が、気づきにくい失敗の原因になります
• 依存関係の競合が原因と判明した、45分に及ぶ複雑なデバッグセッション
• プッシュ前に環境を自動比較する手段がありません

実行手順

有効化されたら、次の手順を自律的に実行します。

ステップ 1：ローカル環境を収集する

# Python version
python --version

# Installed tool versions
pip show ruff black pyright mypy 2>/dev/null | grep -E "^(Name|Version):"

# Pre-commit hook versions (if available)
cat .pre-commit-config.yaml 2>/dev/null | grep -E "rev:|repo:"

ステップ 2：CI 設定を読み取る

Read(file_path=".github/workflows/ci.yml")
Read(file_path="pyproject.toml")
Read(file_path=".pre-commit-config.yaml")

以下を抽出します。

• CI の Python バージョン（python-version: を確認）
• pyproject.toml に指定されたツールのバージョン
• .pre-commit-config.yaml に指定された pre-commit フックのバージョン

ステップ 3：環境を比較する

比較表を作成します。

コンポーネント	ローカル	CI	ステータス
Python	3.12.10	3.11	不一致
ruff	0.12.7	0.13.0	不一致
black	24.3.0	24.3.0	OK

ステップ 4：推奨事項を提示する

不一致ごとに、実行可能な修正方法を提示します。

Python バージョンの不一致：

# Option A: Use pyenv to match CI version
pyenv install 3.11
pyenv local 3.11

# Option B: Update CI to match local (if local is intentional)
# Edit .github/workflows/ci.yml line 33

ツールのバージョンの不一致：

# Pin versions in pyproject.toml
pip install ruff==0.13.0

# Or update pre-commit hooks
pre-commit autoupdate

ステップ 5：自動修正する（要求された場合）

ユーザーが自動修正を要求した場合：

1. .pre-commit-config.yaml を最新のバージョンに更新する
2. pre-commit autoupdate を実行する
3. 該当する場合は requirements.txt を再生成する
4. 変更をコミット用にステージする

統合ポイント

fix-agent との連携

以下の fix-agent テンプレートと連携します。

• インポート／依存関係の修正（テンプレート 1）
• 設定の修正（テンプレート 2）
• CI/CD の修正（テンプレート 4）

pre-commit-diagnostic との連携

バージョン同期後に pre-commit の失敗が検出された場合、処理を引き継ぎます。

ci-diagnostic-workflow との連携

プッシュ前の検証で検出できなかった、プッシュ後の CI 失敗を引き継ぎます。

よくある不一致パターン

パターン 1：Python のマイナーバージョンのずれ

症状：

• CI でのみ型エラーが発生する
• 新しい構文を使うとインポートエラーが発生する
• f-string の問題が発生する

修正：

# Check CI Python version
grep -r "python-version" .github/workflows/

# Match locally or update CI

パターン 2：リンターのバージョンのずれ

症状：

• 「ローカルでは動作するが、CI では lint に失敗する」
• CI の新しいルールがローカルでは適用されない
• フォーマットの違い

修正：

# Sync pre-commit hooks to latest
pre-commit autoupdate

# Or pin specific version
pip install ruff==<ci-version>

パターン 3：依存関係の不足

症状：

• CI で ModuleNotFoundError が発生する
• オプションの依存関係がインストールされていない

修正：

# Install all optional dependencies
pip install -e ".[dev]"

# Ensure requirements.txt is up to date
pip freeze > requirements.txt

出力形式

## Dependency Resolver Report

### Environment Comparison

| Component | Local   | CI      | Status   |
| --------- | ------- | ------- | -------- |
| Python    | 3.12.10 | 3.11    | MISMATCH |
| ruff      | 0.12.7  | 0.13.0  | MISMATCH |
| pyright   | 1.1.350 | 1.1.350 | OK       |

### Mismatches Found: 2

### Recommendations

1. **Python Version** (CRITICAL)
   - Local: 3.12.10, CI: 3.11
   - Action: Consider using pyenv to test with CI version before push
   - Risk: Type syntax differences may cause failures

2. **ruff Version** (WARNING)
   - Local: 0.12.7, CI: 0.13.0
   - Action: Run `pip install ruff==0.13.0` or `pre-commit autoupdate`
   - Risk: New rules may flag previously passing code

### Quick Fix Commands

```bash
# Sync ruff version
pip install ruff==0.13.0

# Update all pre-commit hooks
pre-commit autoupdate

# Re-run pre-commit to validate
pre-commit run --all-files
```

### Status: ACTION REQUIRED

Push may fail due to environment mismatches.
Run recommended fixes before pushing.

このスキルを使う場面

使用する兆候：

• 「CI は失敗するが、ローカルでは動作する」
• 「ここでは lint に通るが、CI では通らない」
• 長時間の開発セッション後にプッシュする前
• ローカルの Python やツールを更新した後
• 新しいプロジェクトへの参加時

不要な場合：

• CI がすでに安定して通っている
• 環境を同期したばかりである
• ドキュメントのみを編集している

関連リソース

• DISCOVERIES.md：CI Failure Resolution Process Analysis（836〜914行目）
• fix-agent.md：インポート／設定／CI の修正用テンプレート
• ci-diagnostic-workflow.md：プッシュ後の CI 失敗の解決
• pre-commit-diagnostic.md：pre-commit フックの失敗
• .github/workflows/ci.yml：CI 設定の信頼できる情報源

哲学との整合性

徹底したシンプルさ

• 手順に沿ったアプローチ：明確な5つのステップで、不要な抽象化はありません
• 直接的なシェルコマンド：ユーザーは推奨事項をコピーして貼り付けられます
• 対象を限定：環境の不一致のみを検出し、修正は既存のエージェントに委ねます

BS ゼロの実装

• 実行可能な出力：すべての推奨事項に正確なコマンドが含まれます
• 理論的な助言なし：具体的なバージョン番号とファイルパスを示します
• プッシュ前に予防：CI のサイクルを無駄にする前に問題を検出します

モジュール設計

• スムーズな引き継ぎ：fix-agent、pre-commit-diagnostic、ci-diagnostic-workflow と連携します
• 単一責任：検出と比較のみを行い、修正は専門のエージェントに委任します
• 再生成可能：この仕様から再構築できます