pragmatic-architecture

Included with Lifetime

$97 forever

Prevents over-engineering by enforcing industry-proven principles: AHA (Avoid Hasty Abstractions), YAGNI, Colocation, and Rule of Three. Use when designing features, planning architecture, "architect this", "design the structure", or when the code-architect agent is dispatched. Triggers: file structure, module organization, abstraction decisions, component splitting.

Design

What this skill does


# Pragmatic Architecture

Design for today's requirements. Let complexity grow incrementally as needed.

## The Four Principles

### 1. Rule of Three (Don Roberts)

> "The first time, just do it. The second time, wince at duplication but do it anyway. The third time, refactor."

**Abstract on the 3rd occurrence, not before.**

| Occurrences | Action |
|-------------|--------|
| 1 | Implement directly |
| 2 | Duplicate, note similarity |
| 3+ | Now extract abstraction |

### 2. AHA - Avoid Hasty Abstractions (Kent C. Dodds)

> "Prefer duplication over the wrong abstraction." — Sandi Metz

**Duplication is cheaper than the wrong abstraction.** Wrong abstractions accumulate parameters and conditionals until unmaintainable.

Signs of wrong abstraction:
- Adding parameters to handle "just one more case"
- Conditional paths through shared code
- Comments explaining which caller uses which path

**Recovery:** Inline the abstraction, re-duplicate, let the right pattern emerge.

### 3. YAGNI - You Ain't Gonna Need It (Ron Jeffries)

> "Always implement things when you actually need them, never when you just foresee that you need them."

**No hooks for future features.** No "we might need this someday."

| ❌ Speculative | ✅ Pragmatic |
|----------------|--------------|
| `options?: ExtensionConfig` unused | Add when extension exists |
| Abstract factory for one impl | Direct instantiation |
| Event system for single listener | Direct call |
| Plugin architecture for no plugins | Hardcoded behavior |

### 4. Colocation (Kent C. Dodds)

> "Place code as close to where it's relevant as possible."

**Minimize file splitting. Keep related code together.**

| ❌ Over-split | ✅ Colocated |
|---------------|--------------|
| `types/user.ts`, `utils/user.ts`, `constants/user.ts` | Single `user.ts` with all |
| Separate `styles/`, `hooks/`, `utils/` folders | Component folder with all related |
| 10 files for one feature | 1-3 files max per feature |

## Decision Framework

Before creating abstraction, ask:

```text
1. Does this exist 3+ times? → No? Don't abstract
2. Are the use cases truly identical? → No? Don't abstract
3. Would someone unfamiliar understand this? → No? Simpler design
4. Am I solving today's problem? → No? YAGNI
```

## File Organization Rules

**Prefer:**
- Feature-based folders over type-based folders
- Fewer, larger files over many tiny files
- Colocated tests (`foo.test.ts` next to `foo.ts`)
- Single source of truth per concept

**Avoid:**
- `types/`, `utils/`, `constants/`, `helpers/` folders that scatter related code
- Files under 50 lines (usually should be merged)
- More than 3 files per feature (unless genuinely complex)

## Anti-Patterns to Block

### Speculative Generality (Fowler)

> "Oh, I think we'll need the ability to do this someday"

Symptoms: Abstract classes doing nothing, unused parameters, delegation that could be direct.

**Block:** Any "for future use" justification.

### Shotgun Surgery (Fowler)

> "One change requires modifications across many files"

Caused by over-splitting. Fix by consolidating related code.

**Block:** Designs requiring 5+ file changes for simple features.

### Premature Abstraction

Creating `BaseHandler`, `AbstractService`, `GenericRepository` before concrete needs exist.

**Block:** Any abstract class without 2+ concrete implementations in the plan.

## Output Requirements

When designing architecture:

1. **Justify every new file** — Why can't this live in an existing file?
2. **Justify every abstraction** — Where are the 3 concrete uses?
3. **Prefer boring** — Standard patterns over clever solutions
4. **Count the files** — If feature needs 5+ files, reconsider

## References

For detailed patterns and examples:
- `references/file-organization.md` — Colocated vs scattered patterns
- `references/abstraction-examples.md` — Good vs bad abstraction decisions

Files: 3

Size: 14.4 KB

Complexity: 36/100

Category: Design

Source: https://github.com/pproenca/dot-claude/tree/main/plugins/dev-workflow/skills/pragmatic-architecture

Related in Design

contribute

Included

Local-only OSS contribution command center. Auto-refreshes the user's in-flight PR and issue state on invoke so conversations start with full context — no need to brief Claude on what's in flight. Helps the user find issues to contribute to on GitHub, builds per-repo dossiers of what each upstream expects (CLA, DCO, branch convention, AI policy, draft-first, review bots, issue templates), runs deterministic gates before any external action so AI-assisted contributions don't reach maintainers as slop. State is markdown-only: candidate files at ~/.contribute-system/candidates/, repo dossiers at ~/.contribute-system/research/, append-only event log at ~/.contribute-system/log.jsonl. No database, no cloud calls. Use when the user asks about their PRs / issues / contributions, wants to find new work to take on, claim an issue, build/refresh a repo's dossier, or draft a Design Issue or PR. Trigger with "/contribute", "what's my PR status", "find a contribution", "claim issue X", "draft a Design Issue for Y", "refresh dossier for Z".

Designscripts

architectural-analysis

Included

User-triggered deep architectural analysis of a codebase or scoped subtree across eight modes — information architecture, data flow, integration points, UI surfaces, interaction patterns, data model, control flow, and failure modes. This skill should be used when the user asks to "diagram this codebase," "map the architecture," "show the data flow," "give me an ERD," "trace control flow," "find the integration points," "verify the layout pattern," "audit the UX architecture," or any similar request whose primary deliverable is mermaid diagrams plus cited reports under docs/architecture/. Dispatches haiku/sonnet sub-agents in parallel for per-mode exploration, then verifies every citation mechanically before any node lands in a diagram. Not for one-off prose explanations of code (use code-explanation) or for high-level system design from scratch (use system-design).

Designscripts

mcp

Included

Model Context Protocol (MCP) server development and tool management. Languages: Python, TypeScript. Capabilities: build MCP servers, integrate external APIs, discover/execute MCP tools, manage multi-server configs, design agent-centric tools. Actions: create, build, integrate, discover, execute, configure MCP servers/tools. Keywords: MCP, Model Context Protocol, MCP server, MCP tool, stdio transport, SSE transport, tool discovery, resource provider, prompt template, external API integration, Gemini CLI MCP, Claude MCP, agent tools, tool execution, server config. Use when: building MCP servers, integrating external APIs as MCP tools, discovering available MCP tools, executing MCP capabilities, configuring multi-server setups, designing tools for AI agents.

Designscripts

react-native-skia

Included

Design, build, debug, and optimise high-polish animated graphics in React Native or Expo using @shopify/react-native-skia, Reanimated, and Gesture Handler. Use when the user wants canvas-driven UI, shaders, paths, rich text, image filters, sprite fields, Skottie, video frames, snapshots, web CanvasKit setup, or performance tuning for custom motion-heavy elements such as loaders, hero art, cards, charts, progress indicators, particle systems, or gesture-driven surfaces. Also use when the user asks for fluid, glow, glass, blob, parallax, 60fps/120fps, or GPU-friendly animated effects in React Native, even if they do not explicitly say "Skia". Do not use for ordinary form/layout work with standard views.

Designscripts

plaid

Included

Product Led AI Development — guides founders from idea to launched product. Six capabilities: Idea (discover a product idea), Validate (pressure-test the idea against fatal flaws, problem reality, competition, and 2-week MVP feasibility), Plan (vision intake + document generation), Design (translate image references into a design.md spec), Launch (go-to-market strategy), and Build (roadmap execution). Use when someone says "PLAID", "plaid idea", "help me find an idea", "product idea", "idea from my business", "idea from my expertise", "plaid validate", "validate my idea", "pressure-test", "is this idea good", "find fatal flaws", "validate the problem", "plan a product", "define my vision", "generate a PRD", "product strategy", "plaid design", "design from image", "translate image to design", "create design.md", "extract design tokens", "plaid launch", "go-to-market", "launch plan", "GTM strategy", "launch playbook", "plaid build", "build the app", "start building", or "execute the roadmap".

Designscripts

nextjs-framer-motion-animations

Included

Adds production-safe Motion for React or Framer Motion animations to Next.js apps, including reveal, hover and tap micro-interactions, whileInView, stagger, AnimatePresence, layout and layoutId transitions, reorder, scroll-linked UI, and lightweight route-content transitions. Use when the user asks to add, refactor, or debug Motion or Framer Motion in App Router or Pages Router codebases, especially around server/client boundaries, reduced motion, LazyMotion, bundle size, hydration, or route transitions. Avoid for GSAP-style timelines, WebGL or 3D scenes, heavy scroll storytelling, or CSS-only effects unless Motion is explicitly requested.

Designscripts