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.
Prevents over-engineering by enforcing AHA, YAGNI, and Rule of Three principles. Triggers when you design features, plan architecture, or request "architect this" to block premature abstractions and enforce colocation.
/plugin marketplace add pproenca/dot-claude/plugin install dev-workflow@pproencaThis skill cannot use any tools. It operates in read-only mode without the ability to modify files or execute commands.
references/abstraction-examples.mdreferences/file-organization.mdDesign for today's requirements. Let complexity grow incrementally as needed.
"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 |
"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:
Recovery: Inline the abstraction, re-duplicate, let the right pattern emerge.
"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 |
"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 |
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
Prefer:
foo.test.ts next to foo.ts)Avoid:
types/, utils/, constants/, helpers/ folders that scatter related code"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.
"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.
Creating BaseHandler, AbstractService, GenericRepository before concrete needs exist.
Block: Any abstract class without 2+ concrete implementations in the plan.
When designing architecture:
For detailed patterns and examples:
references/file-organization.md — Colocated vs scattered patternsreferences/abstraction-examples.md — Good vs bad abstraction decisionsThis skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.