カスタマイズ
オプションの個人設定: ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md。
そのファイルが存在する場合は読み込んで適用し、それ以外の場合はスキルのデフォルト設定を使用します。個人設定のみ(リポジトリやプロダクトに関する事実は、リポジトリ自身(.claude/workflow-profile.sh やツール設定)に属するものであり、ここには決して記述しないでください)。
CodeQuality は何をしますか?
1つのループ、2つのレンズ。ループは常に「検出 → 1つの項目を選択 → テスト後に修正 → 検証 → 繰り返し」です。ツールレンズは、スキャナーがフラグを立てた項目を優先順位に従って、既存のテストをガードとして修正します。原則レンズは、コードを変更しにくくする要因(神クラス、重複、テスト不可能なコア部分)を、SOLID / Clean Codeの原則を1つずつ適用して修正し、設計変更を事前に提示せずに適用することはありません。どちらのレンズも同じツールマニフェストを読み、同じレポートディレクトリに書き込み、同じ「品質改善レポート」で終了します。
2つのレンズ
| ツールレンズ | 原則レンズ | |
|---|---|---|
| ドライバー | スキャナー出力(summary.md) | Principles.md にマッピングされた設計スメル(smell-inventory.md、roadmap.md) |
| 作業単位 | 1つの発見項目(1つのルール、1ファイル、行指定) | 1つの境界付けられたホットスポットに対する1つの原則(1つの抽出、1つのクラス分割、1つの依存性逆転) |
| 順序 | P0 セキュリティ → P1 正確性 → P2 保守性 | レバレッジラダー(下記参照)、リポジトリごとに調整 |
| 自律性 | 修正し、差分を表示 | 提案 → 確認 → 適用。承認なしに編集は行われません |
| セーフティネット | 既存のテストがグリーンのまま維持される | 対象が未テストの場合、特性テストを最初に作成 |
| メトリクス | 発見項目の減少、ツール再実行でクリーン | 重複率、循環的複雑度、関数長、fan-in/out、「ユニットテスト可能になった」 |
| いつ選択するか | lint/型/セキュリティの負債、CIが赤、「スキャナーを満足させる」 | 変更に抵抗するコード、リメディエーションスプリントの構造ティア |
ループ
SCAN → SELECT → SAFETY NET → [PROPOSE → CONFIRM] → FIX → VERIFY → REPORT → REPEAT
└─ 原則モードでは必須、ツールモードではスキップ ─┘
ワークフロールーティング
| トリガー | ワークフロー | 生成物 |
|---|---|---|
| 「品質ツールをインストール」「コード品質をセットアップ」 | Workflows/Install.md | マニフェストツールのインストールと検証 |
| 「スキャン」「ベースライン」「コード品質を分析」「スメルレポート」「最初に何を修正すべきか」「リファクタリングロードマップ」 | Workflows/Scan.md | summary.md (A)、smell-inventory.md (B)、roadmap.md (C) |
| 「コード品質を改善」「lintを修正」「品質ループ」「[発見項目]を修正」 | Workflows/Loop.md ツールモード | 修正、session-log.md、レポート |
| 「リファクタリング」「SOLIDを適用」「これをクリーンアップ」「ループを開始」 | Workflows/Loop.md 原則モード | 修正、session-log.md、レポート |
| 「このリポジトリをクリーンアップ」(修飾語なし) | Scan A + B + C、その後原則モードでLoop | 上記すべて |
| 「リメディエーションスプリント」「リメディエーションサイクル」 | IssueFlow Remediation がブランチ、PR、マージを管理。Scan がサイクルの範囲を決め、Loop が実行 | サイクルごとに1つのPR |
Loopは指定がない場合、自らモードを選択します。リポジトリに roadmap.md が存在しない場合はツールモード、存在する場合は原則モードになります。ユーザーはどちらかを強制できます。
マニフェスト
Tools/tools.tsv は、このスキルにおけるツールの唯一のリストです。タブ区切りで、言語とツールごとに1行:language category priority tool install run notes。language は js | python | yaml、category は lint | format | types | security | deadcode | duplication | complexity | deps | coverage、priority は P0 | P1 | P2。両方のスクリプトがこれを読みます。ワークフローはインラインでツールをリストしません。ツールを追加または削除するには、1行を編集します。
| スクリプト | マニフェストから読み取るもの | 動作 |
|---|---|---|
Tools/install-quality-tools.sh [--dry-run] [lang ...] | 選択した言語の install セル | 言語を検出(package.json → js; pyproject.toml, requirements.txt または *.py → python; *.yaml/*.yml → yaml); jsツールはリポジトリのパッケージマネージャーでdevDependenciesとしてインストール(lockfile → npm/pnpm/bun)、pythonおよびyamlツールは uv pip install または pip でインストール; npm:/pip: プレフィックスでチャネルを上書き、- は何もインストールしない |
Tools/run-quality-baseline.sh [--dry-run] [lang ...] | run セル | すべてのツールを reports/codequality/<YYYY-MM-DD>-<HHMMSS>/ に実行。$OUT(レポートディレクトリ)、$SRC(QUALITY_SRC_DIRS、デフォルトは src(存在する場合)または .)、$PM、$NPX を置換。インストールされていないツールは MISSING、クラッシュしたツールは FAILED とマークされるが、実行は停止しない。ツールごとのステータス、解析された問題数、P0/P1/P2の合計を含む summary.md を書き込み、レポートパスを出力 |
run が - の行(カバレッジツール)はインストールされるが、ベースラインでは実行されない。カバレッジはLoop内で、対象範囲に限定して測定される。すべてのツールは無料でローカル実行される。npm audit、pip-audit、checkov は脆弱性データベースのためだけにネットワークにアクセスする。
レバレッジラダー(原則レンズのデフォルト順序)
- 名前 — 読めないコードは安全に変更できない。安価であり、すべての基盤となる。
- DRY / 重複 — 最も低リスクで最も多くのコードを削除する。隠れた抽象化を露呈させる。
- 小さな関数 — 長いメソッド → 抽出。関数ごとに1つの抽象レベル。
- SRP — 複数の理由で変更されるクラスやモジュールを分割する。
- OCP / DIP — 依存関係を逆転し、シームを追加する。影響は大きくリスクも高いため、セーフティネットを先に。
- ISP / LSP — 肥大化したインターフェースと壊れた代替可能性。ステップ5のシームが必要。
ScanパートCは、この順序を実際のインベントリに基づいて調整します(レバレッジ = 影響 ÷ リスク。Principles.md パート3を参照)。
譲れないルール
- 1イテレーションにつき1項目。 1つの発見項目、または1つの境界付けられた対象に対する1つの原則。小規模でレビュー可能な差分。
- 振る舞いを保持する。 構造は変わっても、振る舞いは変わらない。振る舞いを変更する必要がある場合は停止し、それをフラグする。それは修正ではなく機能追加である。
- グリーンからグリーンへ。 変更の前後でテストがパスしていること。変更後にレッドになった場合は元に戻し、前進して修正しない。
- 触れる行が未テストの場合、特性テストを最初に作成する。 セーフティネットなしにリファクタリングはしない。
- 設計の変更を適用する前に提案すること(原則モード)。 ツールモードでは直接修正し、その後に差分を表示する。
- P0 → P1 → P2 の順序でツールの発見項目に対処する。複数言語にまたがっても、言語ごとにはしない。
- テストやlintルールを弱めることでグリーンを得てはならない。 古いテストは新しい正しい振る舞いに合わせて移動する。ルールはコード内で満たす。
- ボーイスカウトルール、ただし範囲は限定。 触ったファイルはきれいにするが、現在の項目を超えてスコープが拡大しないようにする。
- 証拠、意見ではない。 ルールまたは原則の名前、可能な場合はメトリクスを明示する。
出力アーティファクト
すべて reports/codequality/ 配下に生成(git管理外):
| ファイル | 作成元 |
|---|---|
<YYYY-MM-DD>-<HHMMSS>/summary.md + 生のツール出力 | run-quality-baseline.sh(Scan A) |
<YYYY-MM-DD>/smell-inventory.md | Scan B |
<YYYY-MM-DD>/roadmap.md | Scan C |
<YYYY-MM-DD>/session-log.md | Loop、イテレーションごとに1エントリ |
<YYYY-MM-DD>/quality-report.md | Loop、セッション終了時(下記) |
品質改善レポート(必須)
すべてのLoopセッションは、このレポートで終了します。どちらのモードでも同様です。これはコード変更とともに提供される成果物であり、作業がIssueFlowを通じて出荷される際には、PRまたはトラッカーコメントの本文となります。
| セクション | 内容 |
|---|---|
| サマリーテーブル | 追加行 / 削除行 / ネット; 優先度ごとの発見項目数(前 → 後); 削除されたデッドコードホットスポット; テスト数(前 → 後、すべてグリーン) |
| 削除されたコード | ファイル、内容、行数、リスク |
| 追加または変更されたコード | ファイル、内容、行数、目的 |
| 修正されたバグ | 重大度、説明、根本原因(発見された場合のみ) |
| 複雑性の変化 | 最大および平均循環的複雑度(前 → 後)、ホットスポットごとのASCIIバー |
| 先送り | 確認されたが対象外の項目とその理由 |