code-clone-assistant

代码克隆助手

使用 PMD CPD（精确重复）和 Semgrep（模式匹配）检测代码克隆并指导重构。

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采取变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

工具

• PMD CPD v7.17.0+：检测精确重复
• Semgrep v1.140.0+：基于模式检测

测试时间：2025 年 10 月——在 3 个示例文件中检测到 30 处违规 覆盖范围：检测到的违规数量约为单独使用任一工具的 3 倍

---

何时使用此技能

在以下情况下使用此技能：

• 查找代码库中的重复代码
• 检测违反 DRY 原则的情况
• 重构相似的代码模式
• 识别复制粘贴的代码

---

为什么使用两种工具？

PMD CPD 和 Semgrep 检测不同类型的克隆：

方面	PMD CPD	Semgrep
检测内容	精确的复制粘贴重复代码	存在差异的相似模式
范围	跨文件 ✅	文件内/跨文件（仅 Pro 版）
匹配方式	基于 Token（忽略格式）	基于模式（AST 匹配）
规则	❌ 不支持自定义规则	✅ 支持自定义规则

结果：同时使用两者可发现约 3 倍的 DRY 违规。

克隆类型

类型	描述	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 releases 下载
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，以便下次调用时无需重复采用相同的变通方案。

仅在问题真实且可复现时进行更新，不要针对推测性问题更新。