A Code Smell Detection Prompt That Ranks by Severity, Not Style

Every codebase has the file everyone avoids. Six-hundred-line methods, a class that reaches into three others, a boolean flag that quietly forks the logic two ways. Nobody touches it because nobody's sure what breaks. That's not a bug. It's a smell, and smells compound until the file becomes a no-go zone.

A code smell detection prompt surfaces those problems before they calcify. Not as a wall of style nags, but as a ranked report: smell type, severity, exact location, and a fix worth making. The trick is the severity ranking. A long method in a hot path matters; a long method in a one-off migration script doesn't, and a prompt that treats them equally just generates noise.

This is the prompt, the output contract, and why it beats both the tool listicles and the concept explainers ranking for this query.

Why tool lists and concept pages don't help you ship a fix

Search "code smell detection" and you get two kinds of page. One is the concept explainer, like CodeAnt's what is code smell detection, which names the seven classic smells (long method, duplicate code, large class, feature envy, primitive obsession, dead code, long parameter list) and then pitches a product. The other is the tools roundup, like 12 best code smell detection tools in 2026, which compares SonarQube, Codacy, DeepSource, and friends.

Neither gives you a prompt. Neither gives you a structured output you can paste into a review. And the scanners they recommend catch mechanical smells well but miss the semantic ones, the method that does three unrelated things, the abstraction that leaks, because those need reasoning about intent, not pattern matching against rules.

That's the opening. An LLM reasons about intent. A prompt with a severity contract turns that reasoning into a report you can act on today.

What you can do with this prompt

• Scan a module and get every smell tagged by type and severity.
• Rank smells so you fix the painful ones first and ignore the cosmetic ones.
• Get a one-line refactor suggestion per smell, not a vague "consider improving."
• Catch semantic smells linters can't: hidden control flow, leaky abstractions, feature envy.
• Run it on a pull request diff to flag smells before they merge.
• Feed the output into your review process so smell-checking isn't a personality trait.

Anatomy of the prompt

Severity is the load-bearing part. The contract forces a rating per smell so the output sorts itself by what's worth your afternoon.

Role:    You are a senior engineer reviewing {{module}} for maintainability.
Context: {{source_code}}. {{hot_paths}} — code that runs often or is
         changed often (weight smells here higher).
Task:    Identify code smells. For each, classify the type, rate severity
         (high/medium/low) by blast radius and change frequency, and propose
         one concrete refactor. Skip cosmetic nits a formatter would fix.
Output:  A table — Smell | Type | Location | Severity | Why it hurts | Fix.
         Sort by severity. End with the single highest-leverage refactor.

Step-by-step usage

1. Gather inputs

Pick the module, ideally the one people avoid. Note which functions are hot paths or change often; paste that as {{hot_paths}} so severity weights correctly.

2. Fill variables

Set {{module}}, {{source_code}}, and {{hot_paths}}. The hot-paths hint is what stops the prompt from flagging a stable utility as urgently as a churning controller.

3. Run the prompt

Read the high-severity rows first. If the model rated everything "medium," push back: ask it to justify severity by naming the blast radius for each.

4. Post-process

Pick one high-severity smell. Don't batch-fix. The legacy code comprehension workflow pairs well when the smell sits in code nobody fully understands.

5. Iterate

After the fix, re-run on the changed file to confirm the smell's gone and you didn't introduce a new one.

Prompt-craft patterns

Define severity explicitly, or it's meaningless. Tell the model what high, medium, and low mean in your terms (blast radius, change frequency, test coverage). Leave it undefined and every smell drifts to "medium."

Severity rubric:
  high   = in a hot path OR changed in the last 30 days, and hard to test
  medium = real smell, but isolated and stable
  low    = cosmetic; a formatter or rename fixes it

Ask for the fix, not the lecture. "This violates single responsibility" is a grade. "Extract the validation block into validate_order() and call it from both branches" is a fix. The contract should demand the second.

Name the smell taxonomy you care about. If feature envy and primitive obsession matter to your team, list them. Otherwise the model defaults to the famous handful and skips the ones specific to your stack.

Behavior to expect across models: Claude is more conservative about flagging smells, it tends to report fewer, higher-confidence findings, while GPT-4o casts a wider net and surfaces more low-severity nits you'll end up ignoring. Neither is wrong; they're tuned differently. If you want the short, actionable list, Claude's default is closer. If you're doing a one-time deep audit and want everything on the table, GPT-4o's breadth helps. Set the severity rubric tightly either way, or the wide-net runs drown you.

The opinionated take: most "code smell" findings aren't worth fixing, and acting on all of them is its own anti-pattern. A clean smell report with twelve mediums is a way to feel productive while changing nothing that matters. Fix the one or two high-severity smells in the code you actually touch, and leave the stable, ugly-but-working modules alone. Refactoring code nobody edits is rearranging furniture in a room nobody enters.

Variables you'll set

Getting started

1. Pick the module the team avoids.
2. Note the hot paths and recent churn.
3. Fill {{source_code}} and {{hot_paths}}.
4. Define the severity rubric so the ranking means something.
5. Fix only the high-severity smells in code you touch.
6. Re-run on the changed file to confirm.
7. To make smell-checking a standing review dimension, the Code Review Policy System Prompt bakes maintainability into every review.

Detection is the easy half; deciding what to fix is the hard one. Two reads that close the loop: triaging technical debt so the fixes get sequenced, and reviewing the diffs where smells creep in. When a smell lives in code nobody understands, the Legacy Code Comprehension Harness infers what the module actually does before you touch it.