Detect Code Smells with AI: The Open‑Source /smell Skill for Architectural Decay

What the /smell Skill Does

/smell is an AI‑enabled skill that can be embedded in Claude Code, Codex, Cursor and other AI coding agents. When invoked with /smell or a natural‑language request, it scans the entire repository, analyzes architecture and code, and produces a Markdown report.

The report lists file and line numbers for issues such as God Objects, circular dependencies, N+1 queries, and violations of SOLID principles, each accompanied by code evidence and refactoring advice.

Knowledge Base Behind the Skill

Martin Fowler’s Refactoring and Analysis Patterns

Robert C. Martin’s SOLID principles

Eric Evans’s Domain‑Driven Design

Foote & Yoder’s “Big Ball of Mud” paper (1997)

Clean Architecture, Onion Architecture, Hexagonal Architecture

A set of algorithm‑complexity anti‑pattern rules

These sources encode decades of architectural expertise into the skill’s detection engine.

Eight Detection Dimensions

1. Architecture‑Level Anti‑Patterns

Big Ball of Mud, Distributed Monolith, Anemic Domain Model, Violated Layer Boundaries.

2. Coupling Issues

Circular dependencies, content coupling, common coupling, stamp coupling.

3. Cohesion Problems

God Object, Shotgun Surgery, Feature Envy, Data Clumps.

4. Design‑Principle Violations

Broken SOLID rules, DRY violations, over‑engineered KISS, premature YAGNI abstractions.

5. Code‑Level Smells

Long Method, Long Parameter List, Primitive Obsession (e.g., using string for Email), Magic Numbers (e.g., if (status == 3)), dead code.

6. Test Health

Modules with zero test coverage, tests that mock implementation details, slow I/O‑bound tests.

7. Naming Quality

Overuse of generic names like Manager, Handler, Util, mixed snake_case and camelCase, inconsistent terminology.

8. Algorithm‑Complexity Hotspots

N+1 queries: 100 rows → 101 SQL statements.

Nested loops O(n²) causing exponential blow‑up.

Linear scans inside loops ( includes()) instead of O(1) set lookups.

Sorting inside a loop ( sort()) leading to K × O(n log n).

Redundant rendering paths in React/Vue ( .filter().map().sort()) without memoization.

Wrong data structures: using Array where Map would give O(1) lookups.

How to Use

In Claude Code, open the project and type: /smell The skill then asks for the analysis scope (full project, specific module, recent changes, or architecture‑only). After selection it launches parallel tasks to scan structure, dependencies, cohesion, anti‑patterns, and test coverage.

Results are written to tasks/ as a markdown file, e.g., tasks/smell-report-2026-05-28-1430.md, and a concise summary is printed in the terminal.

Sample Analysis of a Go Project

Running /smell 分析这个 Go 项目的架构质量 produced the following findings:

All structs under internal/model/ are anemic; behavior resides in internal/service/. This is an Anemic Domain Model. internal/service/order.go:233 contains an N+1 query; replace with a bulk WHERE id IN (...) query. pkg/auth and pkg/user import each other, creating a circular dependency; extract a shared interface to break the cycle.

Six files under internal/handler/ repeat parameter‑validation logic, violating DRY; introduce a common validation middleware.

Twenty‑three magic numbers such as if order.Status == 3; define a constant or enum like const StatusCompleted = 3.

The report also includes a phased refactoring roadmap, letting teams tackle the most critical issues first.

Quick Mode

For a fast “fatal‑wound” scan, run: /smell 快速检查一下架构 This skips code‑level and naming checks, focusing on critical architecture anti‑patterns, circular dependencies, God Objects, and N+1 queries, delivering results in minutes.

Specific dimensions can be targeted, e.g.: /smell 只分析算法复杂度热点 which limits the scan to nested loops, N+1 queries, and data‑structure misuse.

Why It’s Needed

While seasoned architects can spot these smells manually, most teams lack that depth of experience. Junior developers often accept anemic models or duplicated validation as normal, and large codebases become impossible to audit manually. Code reviews usually focus on functional correctness, not architectural health.

/smell fills this gap by providing concrete evidence and severity rankings, allowing teams to prioritize remediation based on resources.

Installation

The skill is bundled in the goal‑workflow skill set. If you already have goal‑workflow installed, simply invoke /smell. Otherwise install with:

npx skills add smallnest/goal-workflow --skill smell

For Claude Code, place SKILL.md into .claude/skills/smell/ to activate instantly.

Conclusion

Code smells accumulate through shortcuts and deadline‑driven compromises. The hardest part of remediation is not “whether” but “where to start.” /smell generates a clear problem map, highlights severity, and suggests a remediation order, leaving the actual refactoring work to the team.