Frontend-specific technical decision criteria, anti-patterns, debugging techniques, and quality check workflow. Use when making frontend technical decisions or performing quality assurance.
Excessive use of type assertions (as) - Abandoning type safety
Prop drilling through 3+ levels - Should use Context API or state management
Massive components (300+ lines) - Split into smaller components
Design Anti-patterns
"Make it work for now" thinking - Accumulation of technical debt
Patchwork implementation - Unplanned additions to existing components
Optimistic implementation of uncertain technology - Designing unknown elements assuming "it'll probably work"
Symptomatic fixes - Surface-level fixes that don't solve root causes
Unplanned large-scale changes - Lack of incremental approach
Fallback Design Principles
Core Principle: Fail-Fast
Design philosophy that prioritizes improving primary code reliability over fallback implementations.
Criteria for Fallback Implementation
Fallback rule: Implement fallbacks only when explicitly defined in Design Doc
Layer Responsibilities:
Component Layer: Use Error Boundary for error handling
Hook Layer: Implement decisions based on business requirements
Detection of Excessive Fallbacks
Require design review when writing the 3rd catch statement in the same feature
Verify Design Doc definition before implementing fallbacks
Properly log errors and make failures explicit
Rule of Three - Criteria for Code Duplication
How to handle duplicate code based on Martin Fowler's "Refactoring":
Duplication Count
Action
Reason
1st time
Inline implementation
Cannot predict future changes
2nd time
Consider future consolidation
Pattern beginning to emerge
3rd time
Implement commonalization
Pattern established
Criteria for Commonalization
Cases for Commonalization
Business logic duplication
Complex processing algorithms
Component patterns (form fields, cards, etc.)
Custom hooks
Validation rules
Cases to Avoid Commonalization
Accidental matches (coincidentally same code)
Possibility of evolving in different directions
Significant readability decrease from commonalization
Simple helpers in test code
Implementation Example
// 1st-2nd occurrence: keep separate, no commonalization yet
function UserEmailInput() { /* ... */ }
function ContactEmailInput() { /* ... */ }
// Commonalize on 3rd occurrence
function EmailInput({ context }: { context: 'user' | 'contact' | 'admin' }) { /* ... */ }
Common Failure Patterns and Avoidance Methods
Pattern 1: Error Fix Chain
Symptom: Fixing one error causes new errors
Cause: Surface-level fixes without understanding root cause
Avoidance: Identify root cause with 5 Whys before fixing
Pattern 2: Abandoning Type Safety
Symptom: Excessive use of any type or as
Cause: Impulse to avoid type errors
Avoidance: Handle safely with unknown type and type guards
Pattern 3: Implementation Without Sufficient Testing
Symptom: Many bugs after implementation
Cause: Ignoring Red-Green-Refactor process
Avoidance: Always start with failing tests
Pattern 4: Ignoring Technical Uncertainty
Symptom: Frequent unexpected errors when introducing new technology
Cause: Assuming "it should work according to official documentation" without prior investigation
Avoidance:
Record certainty evaluation at the beginning of task files
Certainty: low (Reason: new experimental feature with limited production examples)
Exploratory implementation: true
Fallback: use established patterns
For low certainty cases, create minimal verification code first
Symptom: Duplicate implementations, architecture inconsistency, integration failures
Cause: Insufficient understanding of existing code before implementation
Avoidance Methods:
Before implementation, always search for similar functionality (using domain, responsibility, component patterns as keywords)
Similar functionality found → Use that implementation (do not create new implementation)
Similar functionality is technical debt → Create ADR improvement proposal before implementation
No similar functionality exists → Implement new functionality following existing design philosophy
Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc
Debugging Techniques
1. Error Analysis Procedure
Read error message (first line) accurately
Focus on first and last of stack trace
Identify first line where your code appears
Check React DevTools for component hierarchy
2. 5 Whys - Root Cause Analysis
Symptom: Component not rendering
Why1: Props are undefined → Why2: Parent component didn't pass props
Why3: Parent using old prop names → Why4: Component interface was updated
Why5: No update to parent after refactoring
Root cause: Incomplete refactoring, missing call-site updates
3. Minimal Reproduction Code
To isolate problems, attempt reproduction with minimal code:
Remove unrelated components
Replace API calls with mocks
Create minimal configuration that reproduces problem
Use React DevTools to inspect component tree
4. Debug Log Output (temporary)
Add structured debug logs to isolate the issue, then remove them before commit (per "Delete debug console.log()" in typescript-rules):
console.log('DEBUG:', {
context: 'user-form-submission',
props: { email, name },
state: currentState,
timestamp: new Date().toISOString()
})
Quality Check Workflow
Read package.json scripts and run them with the project's package manager (packageManager field). Map the project's actual script names to the phases below — do not assume fixed names.
Phases (run in order)
Lint/format — the project's formatter + linter (e.g., Biome, or ESLint + Prettier)
Type check — type check without emit
Build — production build
Test — unit/integration tests
Coverage — coverage run when the task added or changed behavior
Troubleshooting
Port already in use — stop the stale dev/preview/test process holding the port
Stale cache — re-run with the project's fresh/clean-cache option
Dependency errors — clean reinstall dependencies
Situations Requiring Technical Decisions
Timing of Abstraction
Extract patterns after writing concrete implementation 3 times
Be conscious of YAGNI, implement only currently needed features
Prioritize current simplicity over future extensibility
Performance vs Readability
Prioritize readability unless React DevTools Profiler identifies a measurable bottleneck (e.g., render time exceeding 16ms, unnecessary re-renders)
Measure before optimizing with React DevTools Profiler
