AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection

Value-First Engineering

Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value while keeping the system correct and maintainable.

• Resolve verified problems within confirmed scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change.
• Introduce capabilities, infrastructure, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them.
• Treat behavior-preserving maintenance inside the confirmed responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope.

Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same confirmed value and proof at lower total complexity.

Technical Anti-patterns (Red Flag Patterns)

Pause the affected decision and review the design when detecting the following patterns: