Code Clone Assistant

Code Clone Assistant

Detect code clones and guide refactoring using PMD CPD (exact duplicates) + Semgrep (patterns).

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Tools

• PMD CPD v7.17.0+: Exact duplicate detection
• Semgrep v1.140.0+: Pattern-based detection

Tested: October 2025 - 30 violations detected across 3 sample files Coverage: ~3x more violations than using either tool alone

---

When to Use This Skill

Use this skill when:

• Finding duplicate code in a codebase
• Detecting DRY violations
• Refactoring similar code patterns
• Identifying copy-paste code

---

Why Two Tools?

PMD CPD and Semgrep detect different clone types:

Result: Using both finds ~3x more DRY violations.

Clone Types

---

Quick Start Workflow

# 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

---

---

Accepted Exceptions (Known Intentional Duplication)

Not all code duplication is a problem. Some codebases deliberately use copy-and-adapt patterns where refactoring would be harmful. When running clone detection, always check for accepted exceptions before recommending refactoring.

When Duplication Is Acceptable

How to Report Accepted Exceptions

When clone detection finds duplication that matches an accepted exception pattern:

1. Report it — always show the user what was found (lines, tokens, files) 2. Flag as accepted — explicitly state it matches a known exception pattern 3. Explain why — cite the specific reason refactoring is not recommended 4. Do NOT recommend refactoring — this is the key difference from actionable findings

Example output format:

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

Project-Level Exception Configuration

Projects can declare accepted exception patterns in their 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

When this section exists in a project's CLAUDE.md, the code-clone-assistant should check it before classifying findings.

---

Reference Documentation

For detailed information, see:

• Detection Commands - PMD CPD and Semgrep command details
• Complete Workflow - Detection, analysis, and presentation phases
• Refactoring Strategies - Approaches for addressing violations

---

Troubleshooting

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Skill: Code Clone Assistant

Complete Detection Workflow

Phase 1: Detection

/usr/bin/env bash << 'CONFIG_EOF'
# Create working directory
mkdir -p /tmp/dry-audit-$(date +%Y%m%d)
cd /tmp/dry-audit-$(date +%Y%m%d)

# Run both tools
pmd cpd -d /path/to/project -l python --minimum-tokens 20 -f markdown > pmd-cpd.md
semgrep --config=/path/to/clone-rules.yaml --sarif --quiet /path/to/project > semgrep.sarif
CONFIG_EOF

Phase 2: Analysis

# Parse PMD CPD (direct read - LLM-native format)
cat pmd-cpd.md

# Parse Semgrep SARIF
jq -r '.runs[0].results[] | "\(.ruleId): \(.message.text) at \(.locations[0].physicalLocation.artifactLocation.uri):\(.locations[0].physicalLocation.region.startLine)"' semgrep.sarif

Combine findings:

1. List PMD CPD duplications by severity (tokens/lines) 1. List Semgrep violations by file 1. Check for accepted exceptions — read the project's CLAUDE.md for a "Code Clone Exceptions" section. Also check if the duplication matches any known acceptable pattern (see Accepted Exceptions) 1. Classify each finding as actionable or accepted exception 1. Prioritize actionable findings: Exact duplicates across files > Large within-file > Patterns

Phase 3: Presentation

Present to user:

• Total findings (PMD + Semgrep)
• Breakdown: actionable vs accepted exceptions
• For actionable: files affected, estimated effort, suggested approach
• For accepted: which exception pattern applies and why refactoring is not recommended

Example (with accepted exceptions):

Code Clone Analysis Results
===========================
PMD CPD: 5 duplications found
  Actionable: 2
  Accepted exceptions: 3

Accepted Exceptions:
1. 115 lines — base_bars → signals CTEs (gen610 ↔ gen710)
   Exception: generation-per-directory experiment (immutable provenance)
2. 36 lines — metrics aggregation SELECT (gen610 ↔ gen710)
   Exception: SQL template without include mechanism
3. 20 lines — trade_outcomes exit logic (gen610 ↔ gen710)
   Exception: generation-per-directory experiment (immutable provenance)

Actionable Findings:
1. process_user_data() duplicated in file1.py:5 and file2.py:5 (21 lines)
2. Duplicate validation logic across 6 locations (Semgrep)

Recommended Refactoring:
- Extract process_user_data() to shared utils module
- Create validate_input() function for validation logic

Proceed with refactoring? (y/n)

Phase 4: Refactoring (With User Approval)

1. Read affected files using Read tool 1. Create shared functions/classes 1. Replace duplicates using Edit tool 1. Run tests using Bash tool 1. Commit changes if tests pass

---

Best Practices

DO:

• ✅ Run both PMD CPD and Semgrep (complementary coverage)
• ✅ Check for accepted exceptions before recommending refactoring
• ✅ Read the project's CLAUDE.md for exception declarations
• ✅ Start with conservative thresholds (PMD: 50 tokens)
• ✅ Review results before refactoring
• ✅ Run full test suite after refactoring
• ✅ Commit incrementally

DON'T:

• ❌ Only use one tool (miss ~70% of violations)
• ❌ Set thresholds too low (noise overwhelms signal)
• ❌ Refactor without understanding context
• ❌ Recommend refactoring for accepted exceptions (intentional duplication)
• ❌ Skip test verification

Skill: Code Clone Assistant

Detection Commands

PMD CPD (Exact Duplicates)

# Markdown format (optimal for AI processing)
pmd cpd -d . -l python --minimum-tokens 20 -f markdown

# Multi-language projects (run separately per language)
pmd cpd -d . -l python --minimum-tokens 20 -f markdown > pmd-python.md
pmd cpd -d . -l ecmascript --minimum-tokens 20 -f markdown > pmd-js.md

Tuning thresholds:

• New codebases: 30-50 tokens
• Legacy codebases: 75-100 tokens (start high, lower gradually)

Exclusions:

pmd cpd -d . -l python --minimum-tokens 20 \
    --exclude="**/tests/**,**/node_modules/**,**/__pycache__/**" \
    -f markdown

Semgrep (Pattern Violations)

# SARIF format (CI/CD standard)
semgrep --config=clone-rules.yaml --sarif --quiet

# Text format (human-readable)
semgrep --config=clone-rules.yaml --quiet

# Parse SARIF with jq
semgrep --config=clone-rules.yaml --sarif --quiet | \
    jq -r '.runs[0].results[] | "\(.ruleId): \(.message.text)"'

Full rules file: ./clone-rules.yaml

______________________________________________________________________

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Skill: Code Clone Assistant

______________________________________________________________________

Security

Allowed Tools: Read, Grep, Bash, Edit, Write

Safe Refactoring:

• Only refactor after user approval
• Run tests before marking complete
• Never use destructive commands
• Preserve git history
• Validate file paths before editing

______________________________________________________________________

Detailed Documentation

For comprehensive details, see:

• PMD CPD Reference: reference-pmd.md - Commands, options, exclusions, error handling
• Semgrep Reference: reference-semgrep.md - Rules, patterns, advanced features
• Examples: examples.md - Real-world examples, complementary detection scenarios
• Sample Rules: clone-rules.yaml - Ready-to-use Semgrep patterns

______________________________________________________________________

Installation

# Check installation
which pmd      # Should be /opt/homebrew/bin/pmd
which semgrep  # Should be /opt/homebrew/bin/semgrep

# Install if missing
brew install pmd      # PMD v7.17.0+
brew install semgrep  # Semgrep v1.140.0+

______________________________________________________________________

Testing Results

Test Date: October 26, 2025 Files Tested: 3 files (sample1.py, sample2.py, sample.js)

Results:

• PMD CPD: 9 exact duplications
• Semgrep: 21 pattern violations
• Total Unique: ~27 DRY violations
• Coverage: 3x more than either tool alone

______________________________________________________________________

This skill uses only tested commands validated in October 2025 with PMD CPD and Semgrep