コード品質の自動改善
役割の明確化: このスキルは make check-all 相当の自動修正とコード整理を実行します。
- •検証・スコアリングのみ行いたい場合 →
/scan --validate - •分析レポートが欲しい場合 →
/analyze - •エビデンスベースの改善実装 →
/improve
目的
このスキルは以下を提供します：
- •品質修正:
make check-allが成功するまで自動的にコードを修正 - •コード整理: git diff で変更されたファイルを対象に、コードの整理とリファクタリングを実行
- •段階的な修正: 2つのフェーズで安全にコード品質を向上
いつ使用するか
プロアクティブ使用（自動で使用を検討）
以下の状況では、ユーザーが明示的に要求しなくても使用を検討してください：
- •
コード品質の問題
- •
make check-allが失敗している - •リント・型チェック・テストのエラーが複数ある
- •コードレビューで品質指摘がある
- •
- •
リファクタリング後
- •大規模なリファクタリング後の品質チェック
- •コーディング規約への準拠確認
- •
PR作成前
- •PR作成前の品質確保
- •自動修正可能な問題の解消
明示的な使用（ユーザー要求）
- •
/ensure-qualityコマンド - •「コード品質を改善して」「make check-all を通して」などの直接的な要求
実行内容
このスキルは2つのフェーズで品質を向上させます：
フェーズ1: 品質修正（quality-checker）
make check-allが成功するまで、自動的にコードを修正してコード品質を保証します。
フェーズ2: コード整理（code-simplifier）
git diffで変更されたファイルを対象に、コードの整理とリファクタリングを実行します。
プロセス
フェーズ1: 品質修正（quality-checker）
yaml
subagent_type: "quality-checker" description: "Auto-fix code quality issues" prompt: | コード品質の自動修正を実行してください。 ## モード --auto-fix ## 対象 [指定されたパス、またはプロジェクト全体] ## 目標 make check-all が成功するまで以下を繰り返し修正: 1. make format - コードフォーマット 2. make lint - リントチェック 3. make typecheck - 型チェック 4. make test - テスト実行 ## 参照 - CLAUDE.md のコーディング規約 - template/ ディレクトリの実装例
修正の順序:
- •コードフォーマット (
make format) - Ruff による自動フォーマット - •リントチェック (
make lint) - Ruff によるリントチェックと自動修正 - •型チェック (
make typecheck) - pyright による厳格な型チェック - •テスト実行 (
make test) - 全テストの実行
フェーズ2: コード整理（code-simplifier）
※品質修正（quality-checker）が成功した後に実行
yaml
subagent_type: "code-simplifier" description: "Simplify and refactor code" prompt: | git diffで変更されたファイルのコード整理を実行してください。 ## 対象 git diff --name-only --diff-filter=ACMR '*.py' で検出されたPythonファイル ## 整理項目（優先度順） 1. 型ヒント完全化（90%カバレッジ目標） 2. ロギング実装（全関数に必須） 3. エラーメッセージの具体性 4. 命名統一（snake_case/PascalCase/UPPER_SNAKE_CASE） 5. 関数分割（100行超過コードの分割） 6. Docstring追加（NumPy形式） 7. 重複削除（DRY原則） 8. 複雑度低減（サイクロマティック複雑度21以上をリファクタ） ## 安全性 - 1ファイルずつ段階的に修正 - 各修正後に make test 実行 - テスト失敗時は即座にロールバック - 動作を変える変更は一切行わない（リファクタリングのみ） ## 参照 - CLAUDE.md のコーディング規約 - docs/coding-standards.md の詳細規約 - template/ ディレクトリの実装例 - improvement-implementer の改善パターン
整理の順序:
- •変更ファイル特定 - git diff で変更されたPythonファイルを検出
- •分析とスコアリング - 型ヒント、ロギング、関数長、複雑度、命名、Docstring、重複を評価
- •優先度順に修正 - 高優先度（型ヒント、ロギング、関数分割）から順次実行
- •テスト確認 - 各修正後に make test 実行、失敗したらロールバック
使用例
例1: プロジェクト全体の品質修正
状況: make check-all が失敗している
実行:
code
このスキルを使用し、プロジェクト全体の品質修正を実行
期待される結果:
- •フェーズ1で make check-all が成功
- •フェーズ2で変更されたファイルのコード整理が完了
例2: 特定ディレクトリの品質修正
状況: 特定のディレクトリのみ修正したい
実行:
code
このスキルを使用し、src/mylib/core/ の品質修正を実行
期待される結果:
- •指定ディレクトリのみが対象
- •段階的な修正とテスト確認
例3: PR作成前の品質確保
状況: PR作成前に自動修正可能な問題を解消
実行:
code
このスキルを使用し、PR作成前の品質チェックを実行
期待される結果:
- •すべての品質チェックがパス
- •コード整理も完了
例4: リファクタリング後の品質チェック
状況: 大規模なリファクタリング後の品質確認
実行:
code
このスキルを使用し、リファクタリング後の品質チェックを実行
期待される結果:
- •型ヒント、ロギング、Docstring が適切に追加
- •テストがすべてパス
実行フロー図
code
┌─────────────────────────────────────────────────────────────┐ │ │ │ フェーズ1: 品質修正（quality-checker） │ │ │ │ make check-all 実行 │ │ │ │ │ ├─→ 成功 → フェーズ2へ │ │ │ │ │ └─→ 失敗 → エラー種別を判定 │ │ │ │ │ ├─→ フォーマット → make format → 再検証 │ │ ├─→ リント → make lint + 手動修正 → 再検証 │ │ ├─→ 型エラー → 型ヒント修正 → 再検証 │ │ └─→ テスト失敗 → 実装/テスト修正 → 再検証 │ │ │ │ 最大5回ループ後、未解決問題をレポート │ │ │ ├─────────────────────────────────────────────────────────────┤ │ │ │ フェーズ2: コード整理（code-simplifier） │ │ │ │ git diff で変更ファイルを特定 │ │ │ │ │ ├─→ 変更なし → スキップ │ │ │ │ │ └─→ 変更あり → 各ファイルを分析 │ │ │ │ │ ├─→ 優先度順にソート │ │ │ │ │ └─→ 1ファイルずつ修正 │ │ │ │ │ ├─→ 修正実行 │ │ ├─→ make test 実行 │ │ │ │ │ │ │ ├─→ PASS → 次へ │ │ │ └─→ FAIL → ロールバック │ │ │ │ │ └─→ 全ファイル完了 │ │ │ │ 最終レポート出力 │ │ │ └─────────────────────────────────────────────────────────────┘
品質基準
このスキルの成果物は以下の品質基準を満たす必要があります：
必須（MUST）
- • フェーズ1（品質修正）が成功し、make check-all がパス
- • フェーズ2（コード整理）で変更されたファイルが整理されている
- • 各修正後にテストを実行し、失敗時はロールバック
- • CLAUDE.md のコーディング規約に準拠
- • 最終レポートが出力されている
推奨（SHOULD）
- •型ヒントカバレッジが90%以上
- •全関数にロギングが実装されている
- •関数長が100行以下
- •サイクロマティック複雑度が20以下
- •Docstringカバレッジが80%以上
禁止（NEVER）
- • テストが失敗したまま次の修正に進む
- • 動作を変える変更を行う
- • 一度にすべてのファイルを修正する
- • ロールバック機能を省略する
重要な注意事項
- •CLAUDE.md の規約に従う: 型ヒント、エラーメッセージ、コーディングスタイルは CLAUDE.md の規約に準拠
- •既存の動作を保持: テストが失敗した場合、まず実装が仕様通りかを確認し、必要に応じてテストも修正
- •段階的な修正: 一度にすべてを修正せず、エラーの種類ごとに段階的に対処
- •進捗の報告: 各ステップでの修正内容と結果を明確に報告
エラー対処の具体例
型エラーの例
python
# エラー: Incompatible return value type (got "None", expected "str")
def get_name() -> str:
return None # 修正前
# 修正後
def get_name() -> str | None:
return None
リントエラーの例
python
# エラー: F401 'os' imported but unused import os # 修正: 未使用のインポートを削除 # エラー: E501 line too long (120 > 100 characters) # 修正: 長い行を適切に改行
出力フォーマット
yaml
品質改善レポート:
実行時間: [秒]
フェーズ1: 品質修正（quality-checker）
修正サイクル数: [回]
初期状態:
フォーマット: [PASS/FAIL]
リント: [PASS/FAIL] ([エラー数]件)
型チェック: [PASS/FAIL] ([エラー数]件)
テスト: [PASS/FAIL] ([失敗数]/[総数])
実施した修正:
- ファイル: [パス]
問題: [問題の説明]
修正: [修正内容]
最終状態:
make check-all: PASS
フェーズ2: コード整理（code-simplifier）
対象ファイル数: [件]
分析結果:
高優先度: [件]
中優先度: [件]
低優先度: [件]
実施した整理:
成功:
- ファイル: [パス]
整理項目: [項目]
改善内容: [内容]
テスト結果: PASS
失敗:
- ファイル: [パス]
整理項目: [項目]
エラー: [エラー内容]
対応: ロールバック完了
スキップ:
- ファイル: [パス]
理由: [理由]
統計:
型ヒントカバレッジ: [前]% → [後]%
平均関数長: [前]行 → [後]行
平均複雑度: [前] → [後]
Docstringカバレッジ: [前]% → [後]%
最終状態:
make test: PASS
統合結果:
品質修正: ✅ 成功
コード整理: ✅ 成功
全体状況: ✅ プロジェクト品質向上完了
エラーハンドリング
品質修正が5回以内に成功しない
原因:
- •構造的な問題（アーキテクチャレベルの問題）
- •テストの仕様が不明確
対処法:
- •未解決の問題をレポート
- •手動修正が必要な箇所を明示
- •
/analyzeで詳細な分析を提案
テストが失敗してロールバック
原因:
- •リファクタリングが動作を変えた
- •テスト自体に問題がある
対処法:
- •即座にロールバック
- •失敗内容をレポート
- •手動確認を促す
型チェックエラーが解消しない
原因:
- •型ヒントが不完全
- •サードパーティライブラリの型定義がない
対処法:
- •型ヒントを追加
- •
# type: ignoreを最小限に使用 - •未解決の問題をレポート
完了条件
このスキルは以下の条件を満たした場合に完了とする：
- • フェーズ1（品質修正）が成功し、make check-all がパス
- • フェーズ2（コード整理）が完了（または変更ファイルがなくスキップ）
- • 最終レポートが出力されている
- • すべてのテストがパス
- • CLAUDE.md のコーディング規約に準拠
関連スキル
- •coding-standards: Python コーディング規約（型ヒント、命名規則等）
- •tdd-development: TDD 開発プロセス
- •error-handling: エラーハンドリングパターン
参考資料
- •
CLAUDE.md: プロジェクト全体のガイドライン - •
docs/coding-standards.md: 詳細なコーディング規約 - •
template/: 実装例 - •
.claude/agents/quality-checker/: 品質修正エージェント - •
.claude/agents/code-simplifier/: コード整理エージェント