Agent Skills: Pragmatic Architecture

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:

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