Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install seb155-atlas-plugin-skills-sota-code-patternsgit clone https://github.com/seb155/atlas-plugin.gitcp atlas-plugin/SKILL.MD ~/.claude/skills/seb155-atlas-plugin-skills-sota-code-patterns/SKILL.md---
name: sota-code-patterns
description: "Architecture pattern selection guide. Use when starting a new service/module, planning a refactor, or when the user asks to 'choose architecture', 'pattern selection', 'clean vs hexagonal', 'CQRS', 'DDD', 'event-driven vs layered'."
mode: [engineering]
effort: medium
refs:
- sota-architecture-patterns
- code-smells-catalog
---
# SOTA Code Patterns — Architecture Selection Skill
Use this skill when:
- Starting a new service, module, or bounded context
- Planning a major refactor (> 20 files affected)
- Reviewing an architecture proposal
- Debating "how should we structure this" in design review
**DO NOT** use this skill for:
- Small bug fixes, single-file changes, style tweaks
- Adding a feature within an existing architecture (just follow it)
- Writing tests (see `test-driven-development` skill)
## Process
### Step 1 — Assess the problem
Ask 4 questions (AskUserQuestion encouraged):
1. **Domain complexity**: Is this a CRUD app, or is there rich business logic?
2. **Lifespan**: Quick MVP or long-lived (>3 years)?
3. **Team**: Single developer, small team (2-5), or larger?
4. **Infra volatility**: Will we swap DB/framework/queue in foreseeable future?
### Step 2 — Apply the decision framework
```
Q: Domain complexity high?
├── No (simple CRUD, few rules) → Layered OR Hexagonal
└── Yes (rich rules, many edge cases) → Hexagonal + consider DDD
Q: Will infrastructure change?
├── No (locked to framework/DB) → Layered OK
└── Yes → Hexagonal (ports & adapters enable swap)
Q: Read/write patterns very different?
├── No → Single model
└── Yes → CQRS (with care — complexity cost is real)
Q: Distributed (multiple services)?
├── No → Monolith (modular, boring, fast to ship)
└── Yes → Event-Driven (expect eventual consistency)
```
### Step 3 — Present 2-3 options to the user
Always use AskUserQuestion with comparison:
```
Q: "Which architecture for this new billing service?"
Options:
1. Hexagonal (Recommended — default)
- Domain testable standalone, DB-swappable
- ~2 weeks boilerplate investment
- Medium learning curve
2. DDD + Hexagonal
- Bounded contexts, ubiquitous language
- +1 week modeling, +domain expert involvement
- Steep learning curve
3. Layered
- Fastest to ship, lowest complexity
- Tightly coupled — hard to evolve
- Shallow learning curve
```
**Default recommendation: Hexagonal.** It's the sweet spot.
### Step 4 — Document the decision
After user picks:
- Write the decision to `.claude/decisions.jsonl` via decision-log skill
- Create a `docs/architecture.md` (or update existing) with the chosen pattern
- Reference `skills/refs/sota-architecture-patterns/` for the pattern details
### Step 5 — Link to refactor if applicable
If this is a refactor (not greenfield):
- Identify code smells via `skills/refs/code-smells-catalog/`
- Sequence refactors: smallest first (Extract Method), biggest last (Extract Class / Context Split)
- Keep tests green after each step (run them, don't assume)
## Architecture patterns (cheat sheet)
| Pattern | Complexity | Best for |
|---------|-----------|----------|
| Layered | Low | CRUD MVPs, framework-driven |
| **Hexagonal** | Medium | **Default backend** — most services |
| Clean | High | Long-lived rich domain, many I/O |
| Onion | High | Same as Clean, concentric mental model |
| DDD | High | Complex domains, bounded contexts |
| CQRS | High | Read-heavy + different read/write models |
| Event-Driven | High | Microservices, async workflows |
Details + file structures in `skills/refs/sota-architecture-patterns/`.
## Code-level patterns (what to emit within the architecture)
| Situation | Pattern |
|-----------|---------|
| 3+ duplicated blocks | Extract Method / Function |
| Many primitives for a domain concept | Value Object / Replace Primitive with Object |
| Function > 50 lines | Extract Method, Replace Conditional with Polymorphism |
| Class > 300 lines | Extract Class (split by responsibility) |
| > 4 parameters | Introduce Parameter Object / DTO |
| Deep nesting | Guard Clauses (early return), Extract Method |
| Magic numbers | Replace Magic Number with Named Constant |
| Feature envy (method reads foreign data) | Move Method |
Full catalog in `skills/refs/code-smells-catalog/`.
## SOLID quick reference
- **S**ingle Responsibility — class changes for one reason
- **O**pen/Closed — open for extension, closed for modification
- **L**iskov Substitution — subclasses usable where parent is expected
- **I**nterface Segregation — many small interfaces > one big
- **D**ependency Inversion — depend on abstractions, not concretions
Hexagonal/Clean both enforce DIP naturally (domain depends on ports, not adapters).
## Anti-patterns to avoid
1. **Architecture Astronaut**: adopting Clean+DDD+CQRS for a CRUD app. Start Hexagonal, evolve.
2. **Distributed Monolith**: microservices calling each other sync over HTTP. Go event-driven or merge.
3. **Premature abstraction**: designing for hypothetical needs. YAGNI applies.
4. **Framework coupling**: business logic in controllers/ORM. Extract to domain/use cases.
## Output format
```
🏛️ Architecture Recommendation
Problem: {1-line summary of what user is building}
Analysis:
- Domain complexity: {low/medium/high}
- Lifespan: {short/long}
- Team: {size}
- Infra volatility: {yes/no}
Recommended: {Pattern}
Why: {1-2 sentence justification}
File structure: {point to refs/sota-architecture-patterns/ section}
Tradeoffs to accept:
+ {pro 1}
+ {pro 2}
- {con to be aware of}
Next steps:
1. {concrete action}
2. Log decision via decision-log skill
```
## References
- Detail: `skills/refs/sota-architecture-patterns/SKILL.md`
- Smells: `skills/refs/code-smells-catalog/SKILL.md`
- Complement: `senior-review-checklist` skill (review process)
- Complement: `code-review` skill (local/PR review with LSP + pattern awareness)