engineering-standards
engineering-standards
The goal is always the same: solve the problem with the least code and the least complexity that actually solves it. Not the cleverest solution, not the most extensible one — the one a senior engineer would defend in review. Every rule below is phrased as a checkable test, not a slogan: if you can't run the test, the rule doesn't apply; if the test fails, change the code.
The repo overrides. A documented repo standard (CLAUDE.md, AGENTS.md, runbooks/, contributing docs, lint config) always wins over this baseline. This skill fills the gaps; it never argues with the repo.
The tests
- The deletion test — imagine deleting the module/abstraction/layer. If the complexity vanishes, it was a pass-through: delete it for real. If the complexity reappears spread across N callers, it was earning its keep.
- The two-adapters rule — one implementation behind an interface is a hypothetical seam; two is a real one. Don't introduce an interface, strategy, plugin point, or config flag unless something actually varies across it today. "We might need it later" fails this test by definition (YAGNI).
- The inline test — could this helper/wrapper/abstraction be inlined at its call sites with less total code? Then inline it. Indirection must pay for itself in removed duplication or hidden complexity.
- The diff test — is every hunk in the diff required by the stated goal? Drive-by refactors, "while I'm here" cleanups, renamed variables, and reformatted neighbors belong in separate commits or not at all. The smallest diff that solves the problem is the best diff. One deliberate exception: docs that document the changed thing (runbooks, design-guide showcases, design docs) update in the same diff — keeping the source of truth in sync is part of the change, not scope creep.
- The explanation test — can you explain the design in two sentences to someone who knows the codebase? If the explanation needs a diagram, the design is probably too clever for the problem size (KISS).
- The new-dependency test — a new package must clear a higher bar than new code: is it maintained, is it doing something genuinely hard (crypto, parsing, dates), and would the hand-rolled version be >100 lines? Otherwise write the 20 lines.
Deleting code is the best outcome. A change that solves the problem by removing code beats one that adds it. Always check whether the problem is an existing abstraction that should die, before building a new one on top (see Sediment, below).