Code Health MCP (CodeScene)
AI支援コーディングのための構造的メンテナンス性フィードバック。スタイル/リンター系スキル (coding-standards、plankton-code-quality) を設計レベルの健全性スコアと回帰ゲートで補完します。
上流リポジトリ: codescene-oss/codescene-mcp-server
パッケージ: @codescene/codehealth-mcp (npx経由のstdio)
セキュリティと境界
オプトイン (ECC): mcp-configs/mcp-servers.json 内の codescene ブロックはテンプレートにすぎません。ECCプラグインのインストールでは、バンドルされたMCPサーバーは自動的に有効になりません。必要な場合のみ、このエントリを設定にコピーしてください。ECCのインストール/同期時に ECC_DISABLED_MCPS=codescene,... を使用して除外することもできます。
認証情報: トークンはバンドルされていません。CS_ACCESS_TOKEN は自身で設定してください（上流リポジトリの getting-a-personal-access-token.md を参照）。トークンをリポジトリにコミットしないでください。
ツールの読み取り対象: ツールを呼び出すと、指定されたローカルリポジトリ内のファイルとgit状態を分析します（渡したパスと、analyze_change_set のブランチコンテキスト）。ツールは自動的には実行されません。スタンドアロンモードの場合は、上流のプライバシードキュメント（codescene-mcp-server README および CodeSceneポリシー）に従ってください。このスキルを、分析されたくないシークレット、認証情報、パスに使用しないでください。
MCPが利用できない場合（オフライン、不正なトークン、サーバークラッシュ）: Code Healthスコアをでっち上げないでください。チェックがスキップされたことをユーザーに伝えてください。明示的なユーザーの承認がある場合のみ続行してください。MCPがダウンしている場合は、ゲートにはリンター/テスト/検証ループを優先してください。サーバーが接続されたらチェックを再有効にしてください。
使用時
- ユーザーが コード品質のレビュー、ファイルの リファクタリング、または AI変更によるメンテナンス性の低下 の確認を依頼した場合
- ホットスポット、レガシーモジュール、または不慣れなファイルを編集する前
- メンテナンス性の安全策が必要な コミット または プルリクエスト の前
- 大規模なエージェント作成差分の後 — Code Healthが低下していないことを確認
- 構造チェックとして
verification-loop、tdd-workflow、または/quality-gateと組み合わせる（テスト/リンターの代わりにはなりません）
アクティブ化時
上記の使用時と同じトリガーです — この見出しはECCがスキルの自動アクティブ化に使用するものです。
仕組み
1. MCPサーバーに接続
mcp-configs/mcp-servers.json から codescene エントリをハーネスのMCP設定にコピーします。
Claude Code (~/.claude.json → mcpServers):
"codescene": {
"command": "npx",
"args": ["-y", "@codescene/codehealth-mcp"],
"env": {
"CS_ACCESS_TOKEN": "YOUR_CS_ACCESS_TOKEN_HERE"
}
}
プロジェクトスコープ: 同じブロックをリポジトリルートの .mcp.json にマージします。
トークン設定は上流リポジトリ（上記リンク）に文書化されています。スタンドアロンモードでは、以下の4つのツールに対して有料のCodeSceneプラットフォームアカウントは不要です。セッションを再起動し、codescene サーバーが接続されていることを確認してからスコアに依存してください。
2. スタンドアロンツールのみを呼び出す
| ツール | 使用時 |
|---|---|
code_health_review | ファイルを変更する前の完全な構造分析 |
code_health_score | 各変更後の素早い数値スコア（差分チェック） |
pre_commit_code_health_safeguard | Code Healthの回帰をもたらすコミットをブロック |
analyze_change_set | PRを開く前のブランチレベルチェック |
プラットフォーム専用ツール（例: リポジトリ全体の技術的負債ホットスポットリスト）は呼び出さないでください。delta_analysis も参照しないでください — スタンドアロンでは利用できません。
3. スコアの解釈（1〜10）
| 範囲 | 意味 | エージェントの動作 |
|---|---|---|
| 9.0～10.0 | 緑 — 健全 | 拡張しても安全ですが、垂直スライスを推奨 |
| 4.0～8.9 | 黄色 — 負債あり | 注意して作業；通りがかりのリファクタリングは避ける |
| 1.0～3.9 | 赤 — 深刻な負債 | スコープは最小限のみ |
4. フィードバックループの実行
ファイルに触れる前
- 対象パスに対して
code_health_reviewを実行します。 - ベースラインスコアとリストアップされたコードスメルを記録します。
- タスクに対応する最小の変更を計画します。
スコアによるスコープ: 5未満 — 最小限の差分のみ；5～7 — 広範なリファクタリングはしない；7超 — リファクタリングしても安全ですが、編集後に毎回確認します。
各変更後
- 同じファイルに対して
code_health_scoreを実行します。 code_health_reviewのベースラインと比較します。- スコアが低下した場合、続行する前に修正します。開始時よりスコアが低いままタスクを完了としないでください。
コミット前 — リポジトリパスに対して pre_commit_code_health_safeguard を実行します。
PR前 — ベースブランチ（例: main）に対して analyze_change_set を実行します。
例
例: Flaskのメンテナンス性改善
pallets/flask において、スタンドアロンツールのみを使用したエージェントループ:
- 対象モジュールに対して
code_health_review（ベースライン 4.82） - リストアップされたスメルに対処する対象を絞ったリファクタリング
- 編集後に毎回
code_health_score - コミット前に
pre_commit_code_health_safeguard - PR前に
analyze_change_set
結果: Code Health 4.82 → 9.1（無料スタンドアロントークンのみ）。
例: AGENTS.md の強制ブロック
プロジェクトの AGENTS.md または CLAUDE.md に貼り付け:
## Code Health (CodeScene MCP)
ファイルを変更する前: `code_health_review` を実行し、スコアと問題点を記録します。
- スコア5未満: 問題のある範囲 — 変更は狭いスコープに限定。
- スコア5～7: 警告範囲 — 広範なリファクタリングはしない。
各変更後: `code_health_score` を実行して差分を検証します。
- スコアが低下した場合: 続行する前に修正。スコアが低下したまま完了としない。
コミット前: `pre_commit_code_health_safeguard` を実行。
PR前: `analyze_change_set` を実行。
例: アンチパターン vs 正しいループ
# 悪い例: 先に編集、後で確認
[code_health_review なしで大規模リファクタリング]
# 悪い例: スコア低下を無視
「テストが通った」→ Code Healthが低下したままタスク完了
# 悪い例: 赤点スコア（5未満）のファイルで広範なリファクタリング
モジュール全体の通りがかりのクリーンアップ
# 良い例: レビュー → 小さな変更 → スコア確認 → コミットガード → analyze_change_set
ECCとの連携
| ECCスキル/フロー | Code Health MCPの役割 |
|---|---|
coding-standards | スタイル/命名；Code Health = 構造/複雑性 |
plankton-code-quality | 記述時リンター/フォーマット；Code Health = 編集前後の構造ゲート |
verification-loop / /quality-gate | 「完了」前に構造回帰チェックを追加 |
security-review | セキュリティ vs メンテナンス性 — 両方該当する場合は両方使用 |
tdd-workflow | テスト合格 ≠ 健全な設計 — リファクタリング後にスコアを確認 |
コンテキストのヒント: ECCはMCPの数を少なく保つことを推奨しています。実質的な編集を行う場合に codescene を有効にし、不要な場合は無効にしてください。
関連スキル
coding-standards— 基本規約plankton-code-quality— 記述時リンター/フォーマットフックverification-loop— ビルド/テスト/リンターゲートtdd-workflow— テスト駆動開発security-review— セキュリティチェックリストdocumentation-lookup— Context7によるライブラリドキュメント（直交）