Skip to content

charlieviettq/awesome-agent-skill / .claude/skills/design-smell-review

design-smell-review

Verified

Lightweight design smell review for modules and APIs—coupling, cohesion, naming, boundaries, and unnecessary complexity. Use before large refactors or when code feels hard to change. Complements gstack/review (diff-focused).

Design smell review

Scope

Review structure and boundaries, not line-by-line style. Pair with PR diff review for changes; use this for module-level health.

Smell checklist

SmellSignalDirection
God moduleMany unrelated responsibilitiesSplit by domain
Shotgun surgeryOne change touches many filesConsolidate logic
Feature envyModule A mostly uses B's dataMove behavior
Leaky abstractionImpl details escape APINarrow public surface
Config soupMagic strings everywhereNamed constants / schema
Boolean flagsif is_x branches everywherePolymorphism or strategy

Workflow

  1. Map entry points and dependencies (imports, public API).
  2. List responsibilities per module; flag >1 unrelated core job.
  3. Check testability — can core logic run without I/O?
  4. Propose smallest structural improvement (not full rewrite).
  5. Record decision in ADR if trade-off is significant.

Output format

## Summary
[1-2 sentences]

## Smells (priority order)
1. [Smell] — evidence — suggested fix (effort: S/M/L)

## Recommended next step
[One concrete change to try first]

Simplification (Chesterton's Fence)

Before deleting or collapsing code, ask why it exists:

  • Comment, test, or git history explaining constraint?
  • If unknown, prefer small experiment or question over bulk delete.
  • Remove duplication only when behavior is proven identical.
  • "Fewer lines" is not success if edge cases or observability regress.

Boundaries

  • Do not block small fixes on perfect architecture.
  • Prefer incremental extraction over big-bang rewrites.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall