# Engineering Philosophy

> Apply KISS, YAGNI, DRY, SOLID, fail-fast, be-brief on every code decision.

- Skill: `swell-agents/engineering-philosophy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add swell-agents/engineering-philosophy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swell-agents/engineering-philosophy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: swell-agents (https://skillmd.com/u/swell-agents)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/swell-agents/engineering-philosophy

---


## Principles

- **Architecture** — Class responsibilities defined in the project's architecture map (often `docs/architecture.md`).
- **KISS** — Simple solutions over complex ones.
- **YAGNI** — Build only what's needed now. Less code is better.
- **Minimal Scope** - Narrowest visibility that works: keep methods and attributes private (`_name` in Python) unless something outside the class needs them; don't export what only one module uses. Widen only when a real consumer appears.
- **Write Less** - If you can avoid writing the code or the comment, don't. A comment earns its place only when it says what the code cannot: a why, an invariant, a magic-number derivation, never a restatement. **Default every comment to one line.** Multi-line is allowed ONLY for a byte-layout, a derivation, or a non-obvious why that needs the room. This covers every comment, source, config, and CI YAML alike; before committing, re-read each comment you added and cut it to one line or delete it.
- **One-Line Diagnostics** - Error messages and comments fit on one line within the line-length limit; keep exception texts short enough that the whole `raise` statement is a single line.
- **DRY** — Single source of truth. Never copy-paste. Reuse spans the repo: prefer an existing sibling idiom over a second variant.
- **OOP** — Follow OOP approach and best practices.
- **SOLID** — Enforce Single Responsibility; keep the others in mind when possible.
- **No Magic** — Make everything explicit. No hidden behaviour or implicit transformations.
- **No Number Without Measurement** — Performance figures in docs (gas, latency, throughput, proof sizes) MUST come from a real measurement: a test run, a profile, a fixture, or an upstream spec citation. Author-quoted "approximately X" without a source is a future-self trap; either remove the number or measure it first. Same for scaling claims ("supports 10k concurrent users"): unmeasured is hope, not fact.
- **Small Steps** — Minimal changes, commit often.
- **Stay In Scope** - Change only what the task requires. Don't fix, reformat, or rename unrelated code you happen to read, even when it looks wrong: note it and leave it. Off-task diffs are harder to review and revert; genuine cleanups earn their own PR.
- **Specs Lead, Code Follows** - The spec, plan, and interface contracts are the source of truth; code conforms to them, not the reverse. When your code contradicts the spec (shape doesn't fit, an Open/TBD item blocks you, a requirement looks wrong), stop and surface it for a human instead of rewriting the spec to match. Retro-fitting the spec destroys the audit trail and closes coordination points left open on purpose.
- **Use Libraries** — Prefer established libraries (ORMs, validators, parsers) over reimplementing features. Check the ecosystem before writing custom code.
- **Backwards Compatibility** — Don't keep code for backwards-compatibility purposes.
- **CI** — Automate all possible quality checks.
- **Investigate, Don't Mask** — When a check fails or unexpected behaviour occurs, investigate the root cause instead of adding defensive code to mask the symptom.
- **Fail Fast** — Detect and surface errors immediately at the point of failure. Use assertions, strict validation, and early returns.
- **Be Brief** — Imperative output. No preamble, no recap, no restating the task back. Compress *response prose*, never *operational checklists*: keep every named rule, severity word, sub-check, and category from the active skill verbatim — cut the explanation around them, not the rule itself. Applies to chat replies, commit messages, PR bodies, review findings, and any other text the agent emits.

## Application

These principles are *judgement weights*, not rules. When two principles conflict, this skill defers to the workflow skill driving the task:

- During `designing-architecture`: KISS, YAGNI, Use Libraries, and No Magic dominate. Reject premature abstractions and speculative configurability.
- During `reviewing-changes`: SOLID, DRY, Investigate-Don't-Mask, Fail Fast, and Stay In Scope dominate. Flag defensive try/except that hides root causes; flag duplication; flag oversized classes; flag edits to files outside the change's stated scope.
- During `running-tdd-cycles`: Small Steps, Stay In Scope, and Fail Fast dominate. One requirement per red-green-refactor; one logical change per commit; touch only the files that requirement needs.

When a user proposes a change that violates one of these principles, name the principle and explain the consequence — don't just refuse.