Engineering principles

Design

1. Subtract, then add little. Remove dead code and stale checks first, then make the shortest diff that works. No abstraction with one user. Apply when sizing a diff or tempted to add a layer.
2. Data shape first. Choose the core types and structures before logic. Apply before writing new logic.
3. Model the domain. Put states in one structure, such as a typed union, state machine, or lookup table, not scattered conditionals. Apply when code branches a lot or repeats a shape across files.
4. Redesign for the new need. Fit a new requirement as if it existed from day one. Apply when an addition strains the design.
5. Low reader load. Inline one-caller wrappers and shrink mutable scope. Apply when code is hard to trace.
6. Guards at boundaries. Validate where input enters: CLI, config, network, files, external APIs. Trust types inside and keep core logic pure. Apply when adding validation or error handling.
7. Idempotent steps. Rerunning a step, even after a crash, reaches the same state. Apply to commands, setup, and retries.
8. No shared writers. Give each concurrent actor its own file, branch, or key before using locks. Apply when parallel work touches shared state.
9. Migrate, then delete. Move every caller and delete the old API in one change. No shims. Apply when replacing an API or rewriting in phases.
10. Compare options. For an unprecedented design, sketch two or three. Prefer fewer, polished features. Apply to novel architecture, UX, or scope choices.

Debugging and verification

1. Fix root causes. Fix where state first went wrong. A guard fixes only legitimate states. Apply when debugging.
2. Attack the premise. After two failed fixes that share an assumption, write it down and test it directly. Apply before a third attempt.
3. Prove it works. Run the real thing and read the actual output, not a proxy. Apply before claiming done.
4. Verifiable units. Split work into steps that each end in a passing check. Apply to sweeps, migrations, and stacked commits.
5. Test behavior. Assert what callers can observe, so tests survive refactors. Apply when writing or keeping a test.
6. Explain the number. Find what limits a measurement and confirm it measured the right work. Apply to benchmarks and eval scores.
7. Build the tool. Script bulk or repeated work so it can be rerun. Apply to large edit sets or checks.

Process

1. Guard the context. Keep summaries, not dumps. Send bulk reading to subagents. Apply when outputs or files are large.
2. Do not block on the human. On reversible work, proceed and show the result. Apply when tempted to ask "should I?".
3. Encode repeated lessons. A correction given twice becomes a lint, test, or script. Apply when a mistake recurs.
4. Comments explain why. Keep a comment only for a reason the code cannot show, such as an external constraint or a public API contract. Delete narration and dead code. Fix code whose surprise needs a comment. Apply when writing or reviewing code.

Types

• Make illegal states unrepresentable. Use discriminated unions, not optional-field bags.
• Parse external data once at the boundary into a named type. Trust it inside.
• Use

  unknown

  for untrusted input. Never

  any

  . No

  as

  casts before validation.
• Derive types from a schema, not hand-written guards.
• Add a

  never

  check in default branches so new variants fail the build.
• Brand primitives that must not mix, such as user IDs and order IDs.