engineering-principles
/engineering-principles
Use when writing, designing, refactoring or extending code: where logic belongs, how much abstraction is enough, module and interface structure, error handling, validation at boundaries, naming, what a test should prove. Triggers on "how should I structure this", "is this too complex", "should I abstract this". Not for checking a finished diff before a PR (use reviewing-code). Not for deep SOLID, TDD or DDD (use solid-principles, testing-principles, domain-driven-design). Not for choosing or implementing a named pattern (use design-patterns). Not for system-level layering, CQRS, sagas, event-d
- Author
- joeblackwaslike ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 8
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when writing, designing, refactoring or extending code: where logic belongs, how much abstraction is enough, module and interface structure, error handling, validation at boundaries, naming, what a test should prove. Triggers on "how should I structure this", "is this too complex", "should I abstract this". Not for checking a finished diff before a PR (use reviewing-code). Not for deep SOLID, TDD or DDD (use solid-principles, testing-principles, domain-driven-design). Not for choosing or implementing a named pattern (use design-patterns). Not for system-level layering, CQRS, sagas, event-d
Triggers from the description
Original author description
Use when writing, designing, refactoring or extending code: where logic belongs, how much abstraction is enough, module and interface structure, error handling, validation at boundaries, naming, what a test should prove. Triggers on "how should I structure this", "is this too complex", "should I abstract this". Not for checking a finished diff before a PR (use reviewing-code). Not for deep SOLID, TDD or DDD (use solid-principles, testing-principles, domain-driven-design). Not for choosing or implementing a named pattern (use design-patterns). Not for system-level layering, CQRS, sagas, event-d
How it works
- What to load
- Related skills
SKILL.md preview
---
name: engineering-principles
description: >-
Use when writing, designing, refactoring or extending code: where logic
belongs, how much abstraction is enough, module and interface structure,
error handling, validation at boundaries, naming, what a test should prove.
Triggers on "how should I structure this", "is this too complex", "should I
abstract this". Not for checking a finished diff before a PR (use
reviewing-code). Not for deep SOLID, TDD or DDD (use solid-principles,
testing-principles, domain-driven-design). Not for choosing or
implementing a named pattern (use design-patterns). Not for system-level
layering, CQRS, sagas, event-driven design or service splits (use code-architectures).
metadata:
last_updated: "2026-11-11"
---
# Engineering Principles
A small set of principles covers most of what makes code good. Apply them while you write, in this order, because an early mistake is expensive to fix later:
1. **Scope.** Do what was asked and nothing more. KISS, YAGNI, DRY with the Rule of Three, Gall's Law (grow a working simple system, don't design a complex one). Delete before you add.
2. **Design.** Separate concerns, give each unit one reason to change, depend on abstractions at real seams, prefer composition, tell objects what to do instead of pulling their state apart (Law of Demeter, Tell Don't Ask), keep queries and commands separate.
3. **Correctness.** Parse at the boundary and trust the types inside, fail fast on every path, make illegal states unrepresentable, grant the least privilege, remember that any observable behavior becomes a contract (Hyrum's Law).
4. **Readability and tests.** Least astonishment, explicit over implicit, the idiom the language expects, and a test that fails when the behavior breaks.
Get scope and design right before polishing lines. Hand anything a rule can state (formatting, imports, types) to a tool, not to judgment.
## What to load
Open only what the task needs.
| You are... | Read |
|---|---|
| Deciding what to build, or how much | [principles.md](references/principles.md), "1. Simplicity and scope" |
| Structuring modules, classes, interfaces, dependencies | [principles.md](references/principles.md), "2. Design and structure" |
| Handling input, errors, concurrency, data models, permissions, performance | [principles.md](references/principles.md), "3. Correctness and safety" |
| Naming, clarity, idioms, writing tests | [principles.md](references/principles.md), "4. Readability and tests" |
| Writing Python, TypeScript or JavaScript, Rust, shell or SQL | [language-notes/index.md](references/language-notes/index.md), then the one file for that language |
The one-paragraph summaries at the top of `principles.md` ("Principles") are enough for a quick decision. Read the detailed section when the summary doesn't settle it.
## Related skills
- `solid-principles`: the full SRP/OCP/LSP/ISP/DIP treatment with bad-to-good examples.
- `testing-principles`: what a good test is, plus the red-green-refactor discipline (its `test-driven-development` reference) and test doubles.
- `domain-driven-design`: aggregates, value objects and bounded contexts.
- `code-architectures`: layering, CQRS, event sourcing, event-driven design and service boundaries.
- `senior-engineering-best-practices`: verifying docs before a workaround, root-cause discipline, blast radius, dependency judgment.
- `reviewing-code`: the process for checking a finished diff against these principles, with per-change-type playbooks (endpoints, migrations, auth, Dockerfiles and so on).
- `design-patterns`: the catalog of named patterns, with a reference per pattern. Use it once you have decided an abstraction is warranted.
Files in this package (8)
- SKILL.md 4 KB
- references/principles.md 45 KB
- references/language-notes/index.md 3 KB
- references/language-notes/python.md 7 KB
- references/language-notes/rust.md 8 KB
- references/language-notes/shell.md 4 KB
- references/language-notes/sql.md 3 KB
- references/language-notes/typescript.md 8 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · joeblackwaslike/agent-skills | 100 | MIT |
| wolfinApp/wolfin-senior | 100 | MIT |
| Cynnamoroll/factory-stack | 90 | MIT |
| johantor/brain | 86 | Apache-2.0 |
| voyager67/Agent-Workbench | 86 | MIT |
| ericwang200608-beep/LANYANT-Skills | 85 | MIT |
| jstarfilms/vibecode-protocol-suite | 85 | ISC |
Database snapshot: 13.11.2026 · package version 8fd9805760cc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100design-patterns
Use when picking or implementing a named pattern: Strategy, Observer, Adapter, Decorator, Factory, Repository, Unit of Work, Dependency injection, Retry with backoff, Circuit Breaker, Idempotency key, Outbox, Result type. Not for whether to abstract at all (use… - 100clean-code-principles
SOLID principles, design patterns, DRY, KISS, and clean code fundamentals. Use when reviewing architecture, checking code quality, refactoring, or discussing design decisions. Triggers on "review architecture", "check code quality", "SOLID principles", "design patterns", or "clean code". - 100code-architectures
Use when choosing or structuring how a system is built: hexagonal layering, CQRS, event sourcing, event-driven design, sagas, microservices vs monolith, strangler-fig migration, service timeouts and contracts, CAP and eventual consistency. Not for aggregates or bounded contexts… - 100solid-principles-code-review-compliance
Use this skill when review object-oriented architectures for compliance with SOLID software design principles. - 100solid-principles
Audits code for adherence to the five SOLID principles and reports violations with concrete fixes. Use when reviewing class design, dependency structure, or object-oriented quality. - 100solid-review
SOLID design-principles review (SRP / OCP / LSP / ISP / DIP) on a file/directory/glob. Review-only. Triggers on `/solid-review`, \"SOLID review\", \"design review\", \"design principles\", \"SOLID 검증\", \"디자인 리뷰\", \"원칙 검증\", or `/deep-test` running it as the Advisory Gate.