charlieviettq/awesome-agent-skill / .claude/skills/design-smell-review
design-smell-review
VerifiedLightweight 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
| Smell | Signal | Direction |
|---|---|---|
| God module | Many unrelated responsibilities | Split by domain |
| Shotgun surgery | One change touches many files | Consolidate logic |
| Feature envy | Module A mostly uses B's data | Move behavior |
| Leaky abstraction | Impl details escape API | Narrow public surface |
| Config soup | Magic strings everywhere | Named constants / schema |
| Boolean flags | if is_x branches everywhere | Polymorphism or strategy |
Workflow
- Map entry points and dependencies (imports, public API).
- List responsibilities per module; flag >1 unrelated core job.
- Check testability — can core logic run without I/O?
- Propose smallest structural improvement (not full rewrite).
- 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |