frontend-ai-guide

AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection (Frontend)

Value-First Engineering

Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user or maintainer value while keeping the UI 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 state, props, variants, 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 user decision, prop, state, variant, concept, output, persistent state, and component or hook path, together with its 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:

Code Quality Anti-patterns

1. Duplicating one UI responsibility across independently maintained components - Review whether the duplicated behavior or contract should have one owner
2. Multiple responsibilities mixed in a single component - Violates Single Responsibility Principle (SRP)
3. Defining same content in multiple components - Violates DRY principle
4. Making changes without checking dependencies - Potential for unexpected impacts
5. Disabling code with comments - Should use version control
6. Error suppression - Hiding problems creates technical debt
7. Type assertions standing in for a guarantee - Declaring a type established by neither a check nor an existing contract
8. Pass-through prop chains that obscure state ownership - Use composition, Context, or the project's state layer when intermediate components only forward values and a broader owner is clearer; retain explicit props when they preserve local ownership and broader state ownership would add coordination while responsibility remains local
9. Components mixing independently changing responsibilities - Split when rendering, state/data ownership, or reusable/testable behavior forms an independent responsibility; retain cohesive components when splitting would add avoidable prop/state synchronization