Detecting Code Smells with an AI ‘Smell’ Skill: My Scan of a Fresh Open‑Source Project

Origin of the term “code smell”

The phrase was coined in the late 1990s on the WardsWiki (c2.com) by Kent Beck while helping Martin Fowler write Refactoring . Fowler’s 1999 book listed 22 smells and associated refactoring techniques, providing a concrete, classifiable framework.

Evolution of the catalog

Refactoring.guru later grouped the original smells into five classic categories (Bloaters, OO‑Abusers, Change‑Preventers, Dispensables, Couplers). The author extends this to eight categories and more than 50 specific smells, adding “Testing” and “Complexity” groups to address AI‑generated code’s testing deficits and performance‑related issues.

The /smell AI skill

The skill can be invoked from a command‑line AI agent (e.g., Claude Code, Ducc) and works in four steps:

Scope selection : scan the whole project, a specific module, or recent git diff changes.

Parallel evidence gathering : launch multiple Explore sub‑agents that run find / grep scans for project structure, dependencies, cohesion, pattern recognition, test coverage, naming clarity, and complexity hotspots. Built‑in heuristics include “file > 500 lines & > 20 public methods ⇒ God Object”.

Structured reporting : produce a prioritized Markdown report with severity levels (🔴 severe, 🟡 warning, 🔵 suggestion), architectural style comparison, and a health scorecard.

Persist & present : save the report to tasks/smell-report-[timestamp].md and optionally provide an oral summary.

Installation command:

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

Case study: scanning Gitlawb/zero

Project statistics:

Project: Gitlawb/zero
Language: Go 1.25 (toolchain 1.26)
Go files: 974
Total lines: ~250 000
Test files: 500 | Non‑test files: 474

Positive findings :

Test‑to‑code ratio > 1:1 (500 tests vs 474 source files), rare in open‑source projects.

Only one TODO/FIXME comment, indicating minimal hidden technical debt.

Clear package layout (e.g., cmd/, internal/ with 60+ sub‑packages) avoids a “big mud ball”.

Detected problems :

God Object (🔴 severe) : internal/tui/model.go is 4 657 lines, defines a Model struct with 173 fields and 111 methods – nine times the heuristic threshold.

Long files (🟡 warning) : 23 files exceed 800 lines, concentrated in internal/tui/ and internal/agent/. Notably, internal/agent/loop.go has 2 736 lines and 84 functions, showing “divergent change” risk.

Complexity hotspots (🔵 suggestion, needs human validation) :

307 occurrences of linear searches inside loops (e.g., strings.Contains, slices.Contains, .Index()).

63 occurrences of sorting inside loops.

The skill notes that such patterns are harmless on cold paths but become performance bugs on hot paths (e.g., per‑render loops).

Refactoring roadmap

Immediate : split tui/model.go using Extract Class to separate concerns.

Short‑term (1‑3 months) : review the 23 oversized files in tui/, applying Extract Class to improve cohesion.

Long‑term : perform hot‑path analysis on the 307 linear‑search and 63 sort‑inside‑loop instances, then replace with appropriate data structures (e.g., map, set) where needed.

Overall health assessment: 🟡 good‑to‑high . The architecture is solid, tests are abundant, and dead code is minimal; the main issues reside in the TUI layer’s God Object and long files, a common pattern for terminal UI projects.

References

Martin Fowler, “Code Smell” – https://martinfowler.com/bliki/CodeSmell.html

Wikipedia, “Code smell” – https://en.wikipedia.org/wiki/Code_smell

c2 WardsWiki, “CodeSmell” – http://c2.com/ppr/wiki/WikiPagesAboutRefactoring/CodeSmell.html

Fowler & Beck, Refactoring: Improving the Design of Existing Code , 1999

refactoring.guru – code smell & refactoring catalog

Chapter 23 of “AI Era Software Engineering” – “Refactoring in the AI Age” smell skill repository – https://github.com/smallnest/goal-workflow

Analyzed project – https://github.com/Gitlawb/zero