A battle-tested catalog of 24 foundational engineering principles for autonomous agents and engineers.
Why This Skill Is Needed & Target State
Why this skill is needed: Engineers and AI agents only question decisions using perspectives active in their immediate attention. Unconsidered failure modes never surface as questions, leading to silent repetitions of known mistakes: scattered validation, symptom patching, loose test assertions, premature frameworks, and leaky abstractions.
Target state: Every architectural decision, refactoring step, implementation slice, and code review is systematically evaluated through these proven principles, producing robust, minimal, type-safe, and self-verifying systems.
The 24 Principles
Read all linked references in references/ relevant to your active task:
attack-the-premise: When two or more fixes sharing one premise fail the same gate, suspect the premise rather than the fixes.boundary-discipline: Consolidate validation, type narrowing, and error handling at system boundaries; trust internal types unconditionally; keep business logic in pure functions.build-the-lever: Avoid tedious repetitive manual edits; build the deterministic script, generator, or codemod that does the job rerunnably.encode-lessons-in-structure: When an instruction is repeated twice, convert it from natural language into a linter, schema, metadata, or verification check.exhaust-the-design-space: For unprecedented or critical designs, construct 2-3 competing prototypes to contrast tradeoffs before deciding.experience-first: When implementation convenience conflicts with user delight, choose user delight; polish fewer features to perfection.explain-the-number: Before trusting a benchmark or metric, name what physical resource or code path bounds it ("why not double?").fix-root-causes: Never patch symptoms. Reproduce first, ask "why" recursively, and eliminate the underlying mechanism.foundational-thinking: Settle data structures and core domain types before writing algorithmic logic.guard-the-context-window: Delegate verbose token dumps and research to subagents; retain only concise summaries in the primary context thread.laziness-protocol: Default to subtraction; make the smallest coherent change that solves the problem.make-operations-idempotent: Design commands and mutators so that repeated execution or mid-flight crash recovery converges to the same target state.migrate-callers-then-delete-legacy-apis: When introducing a replacement API, migrate all call sites and eliminate the legacy interface in the same release wave.minimize-reader-load: Reduce both the number of layers a reader must traverse and the working state they must hold in mind.model-the-domain: Make invalid states unrepresentable in the data structure instead of scattering defensive branch checks.never-block-on-the-human: For reversible and reviewable actions, proceed with reasonable decisions and present verifiable results rather than stalling.outcome-oriented-execution: In planned refactors and migrations, prioritize convergence on the verified final state over preserving fragile intermediate states.prove-it-works: Verify work against the real runtime environment or live binary, never via self-reports, mocks, or passive assumptions.redesign-from-first-principles: When integrating new requirements, design as if the requirement was present from the beginning rather than bolting on shims.separate-before-serializing-shared-state: Eliminate mutable shared state where possible; where unavoidable, enforce structural serialization via lockfiles or explicit phases.sequence-verifiable-units: Break work into small, verifiable slices where each slice transitions from red to green before proceeding.subtract-before-you-add: Remove obsolete code, unused parameters, dead branches, and speculative scaffolding before introducing additions.test-behavior-not-implementation: Invoke the code as callers do and assert literal outcomes; delete tests that pass if the subject returns dummy stubs.type-system-discipline: Model variants as tagged unions; brand semantic primitives; validate external payloads at boundaries; never lie to the compiler with casts.
Invariant Rules
- Cite the Principle with Evidence: When applying a principle, cite its file name and state the concrete before/after change.
- Structural Levers Over Narrative Rules: Convert repeated warnings into mechanical linters or schema validations per
encode-lessons-in-structure. - Subtract First: Delete dead code, unused flags, and abandoned abstractions before adding new features per
subtract-before-you-add.