code-clone-assistant

コードクローンアシスタント

PMD CPD（完全一致の重複）と Semgrep（パターン）を使用してコードクローンを検出し、リファクタリングを支援します。

自己進化型スキル：このスキルは使用を通じて改善されます。指示に誤りがある場合、パラメーターにずれが生じた場合、または回避策が必要になった場合は、先送りせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合にのみ更新してください。

ツール

• PMD CPD v7.17.0+：完全一致の重複を検出
• Semgrep v1.140.0+：パターンベースの検出

テスト済み：2025年10月 - サンプルファイル3件で30件の違反を検出 カバレッジ：どちらか一方のツールだけを使用した場合と比べて、違反を約3倍検出

---

このスキルを使用する場面

次のような場合に、このスキルを使用します。

• コードベース内の重複コードを見つける
• DRY 違反を検出する
• 類似したコードパターンをリファクタリングする
• コピー＆ペーストされたコードを特定する

---

2つのツールを使用する理由

PMD CPD と Semgrep は、異なる種類のクローンを検出します。

項目	PMD CPD	Semgrep
検出対象	完全に同じコピー＆ペーストの重複	変化を伴う類似パターン
範囲	ファイル間 ✅	ファイル内／ファイル間（Pro のみ）
照合方法	トークンベース（書式を無視）	パターンベース（AST 照合）
ルール	❌ カスタムルールなし	✅ カスタムルール

結果：両方を使用すると、DRY 違反を約3倍多く検出できます。

クローンの種類

種類	説明	PMD CPD	Semgrep
Type-1	完全なコピー	✅ デフォルト	✅
Type-2	識別子の名前変更	✅ --ignore-*	✅
Type-3	変化を伴う、わずかに異なるコード	⚠️ 部分的	✅ パターン
Type-4	意味的クローン（同じ振る舞い）	❌	❌

---

クイックスタートのワークフロー

# Step 1: Detect exact duplicates (PMD CPD)
pmd cpd -d . -l python --minimum-tokens 20 -f markdown > pmd-results.md

# Step 2: Detect pattern violations (Semgrep)
semgrep --config=clone-rules.yaml --sarif --quiet > semgrep-results.sarif

# Step 3: Analyze combined results (Claude Code)
# Parse both outputs, prioritize by severity

# Step 4: Refactor (Claude Code with user approval)
# Extract shared functions, consolidate patterns, verify tests

---

---

受け入れ済みの例外（意図的な重複として認識されているもの）

すべてのコードの重複が問題になるわけではありません。リファクタリングすると悪影響があるため、コードをコピーして調整するパターンを意図的に採用しているコードベースもあります。クローン検出を実行する際は、リファクタリングを推奨する前に、必ず受け入れ済みの例外を確認してください。

重複が許容されるケース

パターン	許容される理由	例
ディレクトリごとの生成実験	それぞれの世代は変更されない、自己完結型の実験です。世代間でコードを共有すると、来歴が損なわれ、過去の実験を再現できなくなります。	SQL テンプレート、各 gen{NNN}/ が独立しているスイープスクリプト
プレースホルダー置換を使う SQL テンプレート	SQL にはインポート／インクルードの仕組みがありません。テンプレートでは関数呼び出しではなく、sed によるプレースホルダー置換（__PLACEHOLDER__）を使用します。共有 CTE を別ファイルに抽出すると、単一ファイルで実行するモデルが損なわれます。	シグナル検出とメトリクスの CTE を共有する ClickHouse のスイープテンプレート
プロトコル／スキーマの定型コード	シリアライズ形式、API コントラクト、ワイヤープロトコルでは、各箇所で正確に同じ構造が必要です。抽象化すると、コントラクトが見えにくくなります。	ラッパースクリプトでの NDJSON テレメトリー行の構築
テストフィクスチャと期待値ファイル	テストデータでは、動作を検証するために意図的に本番環境のパターンを重複させます。フィクスチャを共有すると、テスト間の依存関係が壊れやすくなります。	テストセットアップコード、期待される出力のスナップショット

許容される例外の報告方法

クローン検出で、許容される例外パターンに該当する重複が見つかった場合：

1. 報告する — 見つかった内容（行、トークン、ファイル）を必ずユーザーに示します
2. 許容される例外として明示する — 既知の例外パターンに該当することを明確に伝えます
3. 理由を説明する — リファクタリングを推奨しない具体的な理由を挙げます
4. リファクタリングを推奨しない — 実行可能な指摘との主な違いはここです

出力形式の例：

Code Clone Analysis Results

PMD CPD Findings:
  Clone 1: 115 lines (575 tokens) — base_bars → signals CTEs
    gen610_template.sql:33 ↔ gen710_template.sql:38
    Status: ACCEPTED EXCEPTION (generation-per-directory experiment)
    Reason: Each generation is immutable. Shared CTEs would break
            experiment provenance and reproducibility.

  Clone 2: 36 lines (478 tokens) — metrics aggregation
    gen610_template.sql:207 ↔ gen710_template.sql:244
    Status: ACCEPTED EXCEPTION (SQL template without include mechanism)

Actionable Findings: 0
Accepted Exceptions: 2

プロジェクトレベルの例外設定

プロジェクトでは、許容される例外パターンを CLAUDE.md に宣言できます。

## Code Clone Exceptions

- `sql/gen*_template.sql` — generation-per-directory experiments (immutable)
- `scripts/gen*/` — copy-and-adapt sweep scripts (no shared infrastructure)
- `tests/fixtures/` — intentional duplication for test isolation

プロジェクトの CLAUDE.md にこのセクションがある場合、code-clone-assistant は指摘を分類する前に内容を確認します。

---

参考ドキュメント

詳細については、以下を参照してください。

• 検出コマンド - PMD CPD と Semgrep のコマンドの詳細
• ワークフロー全体 - 検出、分析、提示の各フェーズ
• リファクタリング戦略 - 違反に対処する方法

---

トラブルシューティング

問題	原因	解決策
PMD CPD が見つからない	インストールされていないか、PATH にない	brew install pmd または PMD のリリースからダウンロード
Semgrep がタイムアウトする	大規模なコードベースのスキャン	--exclude を使って対象範囲を絞る
重複が検出されない	minimum-tokens の値が高すぎる	--minimum-tokens の値を下げる（15 を試す）
誤検出が多すぎる	minimum-tokens の値が低すぎる	--minimum-tokens を増やす（30 以上を試す）
言語が認識されない	-l フラグが誤っている	PMD CPD がサポートする言語の一覧を確認する
SARIF の解析エラー	Semgrep の出力が不正	Semgrep を最新バージョンにアップグレードする
大規模なリポジトリでメモリエラー	Java ヒープが小さすぎる	PMD_JAVA_OPTS=-Xmx4g を設定する
クローンルールファイルがない	カスタムルールが作成されていない	clone-rules.yaml を作成するか、デフォルト設定を使う

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラーテーブルを修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェイスに変更があった場合は、使用例とパラメーターテーブルを更新してください。
3. 回避策が必要でしたか？ — 工夫が必要だった場合（別のフラグや追加の手順など）は、次回の実行で同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測に基づく問題は対象外です。