react-architecture-enforcer

Use when fixing bugs, something broken, not working, or doesn't work in React - also when adding features, request says "quick fix", "keep it simple", or "follow existing pattern"

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The React Architecture Enforcer is a specialized Claude skill designed to maintain high code quality and structural integrity in React applications. It strictly enforces architectural best practices—such as separating logic from UI and limiting file size—to prevent technical debt during rapid development, bug fixing, or feature additions. By implementing the 'Five Laws' of React architecture, it ensures that codebases remain scalable, testable, and maintainable.

Use Cases

  • Refactoring bloated React components (over 300 lines) by enforcing mandatory extraction of logic into dedicated domain services, config files, or custom hooks.
  • Preventing technical debt during 'quick fixes' or emergency patches by ensuring new code adheres to established architectural patterns rather than taking shortcuts.
  • Decoupling complex business logic, such as validation, calculations, and data fetching, from the UI layer to improve code reusability and clarity.
  • Auditing and justifying the use of side effects (useEffect) and state management to ensure predictable component lifecycles and prevent unexamined performance issues.
  • Enforcing a canonical source for duplicated logic in large-scale projects to maintain consistency across different modules.
namereact-architecture-enforcer
descriptionUse when fixing bugs, something broken, not working, or doesn't work in React - also when adding features, request says "quick fix", "keep it simple", or "follow existing pattern"

React Architecture Enforcer

Triggers

Phrases: "broken", "not working", "fix", "quick", "simple", "just add", "follow pattern", "match current"

Context: Modifying React components, adding features/fixes, file >200 lines, adding hooks

The Five Laws

Law Rule On Violation
A. No Logic in UI Components contain NO: prerequisites, credits, progression, scheduling, eligibility Extract to /domain, /services, /config
B. No Mutating Singletons Engines = pure functions or stateless services Refactor to pure functions
C. No File >300 Lines Check wc -l before ANY edit Extract before implementing
D. No Duplicated Logic Credits, prerequisites, eligibility = ONE canonical source Find existing first
E. No Unexamined Effects New useEffect requires: justification, dependency audit, store alternative check Document or reject

Pre-Flight (MANDATORY)

  1. Check size: wc -l <file> — >300 lines = HALT
  2. Check pressure words: quick, simple, temporary, minimal, follow existing → require extraction plan FIRST
  3. Check logic type: credits | pathways | prerequisites | GPA | eligibility | scheduling → search existing first

Rationalization Overrides

Pattern Response
"Pattern exists / follow existing" Existing violations don't justify new ones. Extract.
"It's small / quick / simple" Size doesn't exempt from laws. Extract.
"We'll refactor later" Requires ticket + sprint + owner. Vague = rejected.
"Emergency / production down" Still output extraction plan (30 sec). Then proceed.
"File is already large" Size IS the problem. No additions without extraction.

Extraction Reference

Logic Type Extract To
Validation domain/validators/<name>.js
Calculations domain/<name>Calculator.js
Config/Requirements config/<name>.config.js
Multiple useState (>3) hooks/use<Name>.js or useReducer
Data fetching services/<name>Service.js
Scheduling/eligibility domain/<Name>Engine.js

Escalation

  1. "This violates Law [X]. Extraction required."
  2. If user insists → offer minimal extraction path
  3. If user overrides → tag code: // TECH-DEBT: Law X violation [date]

Exempt

Comments, formatting, temporary debug logs (removed before commit)