react-refactor
Audited by Runlayer on Feb 21, 2026
Malicious tool definition detected
Tool: AGENTS.md Description: # React **Version 0.1.0** React Refactor Best Practices February 2026 > **Note:** React architectural refactoring guide for agents and LLMs.
Malicious tool definition detected
Tool: README.md Description: # React Refactor Best Practices Architectural refactoring guide for React applications, designed for AI agents and LLMs.
Malicious tool definition detected
Tool: SKILL.md [1/2] Description: --- name: react-refactor description: Architectural refactoring guide for React applications covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data flow, and refactoring safety.
Tool: SKILL.md [2/2]
Malicious tool definition detected
Tool: assets/templates/_template.md Description: --- title: Rule Title Here impact: MEDIUM impactDescription: Optional description of impact (e.g., "20-50% improvement") tags: tag1, tag2 --- ## Rule Title Here **Impact: MEDIUM (optional impact description)** Brief explanation of the rule and why it matters.
Malicious tool definition detected
Tool: metadata.json Description: { "version": "1.0.1", "organization": "React Refactor Best Practices", "technology": "React", "date": "February 2026", "abstract": "Architectural refactoring guide for React applications.
Malicious tool definition detected
Tool: references/_sections.md Description: # Sections This file defines all sections, their ordering, impact levels, and descriptions.
Malicious tool definition detected
Tool: references/arch-composition-over-props.md Description: --- title: Prefer Composition Over Props Explosion impact: CRITICAL impactDescription: reduces prop count by 50-70%, enables independent extension tags: arch, composition, children, slots, extensibility --- ## Prefer Composition Over Props Explosion Components with 15+ configuration props become rigid — every new use case requires a new prop.
Malicious tool definition detected
Tool: references/arch-compound-components.md Description: --- title: Use Compound Components for Implicit State Sharing impact: CRITICAL impactDescription: reduces component API surface by 60%, eliminates prop drilling tags: arch, compound-components, composition, state-sharing --- ## Use Compound Components for Implicit State Sharing When a parent passes the same state and callbacks to N children through props, the API surface grows linearly with each new child.
Malicious tool definition detected
Tool: references/arch-container-presentational.md Description: --- title: Separate Container Logic from Presentational Components impact: CRITICAL impactDescription: enables independent testing and Storybook preview tags: arch, container, presentational, testability, separation-of-concerns --- ## Separate Container Logic from Presentational Components Components that mix data fetching, state management, and rendering are hard to test because tests must mock network calls just to verify visual ou
Malicious tool definition detected
Tool: references/arch-feature-colocation.md Description: --- title: Colocate Files by Feature Instead of Type impact: CRITICAL impactDescription: reduces cross-directory navigation by 70%, makes features self-contained tags: arch, colocation, project-structure, feature-modules --- ## Colocate Files by Feature Instead of Type Organizing by type (components/, hooks/, styles/, tests/) scatters the files for a single feature across the entire tree.
Malicious tool definition detected
Tool: references/arch-headless-pattern.md Description: --- title: Extract Headless Components for Logic Reuse impact: CRITICAL impactDescription: enables 5x more reuse scenarios for the same behavior tags: arch, headless, hooks, separation-of-concerns, reuse --- ## Extract Headless Components for Logic Reuse When behavior is welded to a specific UI, reusing the same logic with a different visual design requires duplicating the entire component.
Malicious tool definition detected
Tool: references/arch-interface-segregation.md Description: --- title: Apply Interface Segregation to Component Props impact: CRITICAL impactDescription: prevents 30-50% of unnecessary re-renders from unrelated prop changes tags: arch, interface-segregation, props, type-safety, re-renders --- ## Apply Interface Segregation to Component Props Components accepting a wide union of optional props for different contexts create false dependencies.
Malicious tool definition detected
Tool: references/arch-push-client-low.md Description: --- title: Push Client Boundaries to Leaf Components impact: HIGH impactDescription: keeps 60-80% of component tree server-rendered tags: arch, client-boundary, server-components, bundle-size --- ## Push Client Boundaries to Leaf Components A `'use client'` directive makes the component and every component it imports client-side.
Malicious tool definition detected
Tool: references/arch-render-props-to-hooks.md Description: --- title: Convert Render Props to Custom Hooks impact: CRITICAL impactDescription: eliminates 2-4 levels of nesting, improves readability tags: arch, render-props, hooks, migration, nesting --- ## Convert Render Props to Custom Hooks Legacy render prop components create deep nesting when composed together.
Malicious tool definition detected
Tool: references/couple-barrel-free-features.md Description: --- title: Use Barrel-Free Feature Modules for Clean Dependencies impact: MEDIUM impactDescription: 200-800ms build time reduction, effective tree shaking tags: couple, barrel-files, tree-shaking, build-performance --- ## Use Barrel-Free Feature Modules for Clean Dependencies Large barrel `index.ts` files that re-export everything from a feature force bundlers to parse every module in the directory, even when the consumer uses one expo
Malicious tool definition detected
Tool: references/couple-break-circular-deps.md Description: --- title: Break Circular Dependencies with Intermediate Modules impact: MEDIUM impactDescription: eliminates undefined-at-import-time bugs, enables proper tree shaking tags: couple, circular-dependencies, module-graph, refactoring --- ## Break Circular Dependencies with Intermediate Modules When module A imports from B and B imports from A, one of them receives `undefined` at load time because the other has not finished executing.
Malicious tool definition detected
Tool: references/couple-dependency-injection.md Description: --- title: Use Dependency Injection for External Services impact: MEDIUM impactDescription: enables testing without mocking modules, 3x faster test setup tags: couple, dependency-injection, testability, decoupling --- ## Use Dependency Injection for External Services Direct imports of API clients and external services weld a component to a specific implementation.
Malicious tool definition detected
Tool: references/couple-stable-imports.md Description: --- title: Import from Stable Public API Surfaces Only impact: MEDIUM impactDescription: enables internal refactoring without breaking consumers tags: couple, public-api, encapsulation, imports --- ## Import from Stable Public API Surfaces Only Reaching into a feature's internal file paths (e.g., `../../components/Button/utils`) couples consumers to private implementation details.
Malicious tool definition detected
Tool: references/data-context-module-pattern.md Description: --- title: Use Context Module Pattern for Action Colocation impact: MEDIUM impactDescription: reduces mutation surface to single file per context tags: data, context-module, actions, colocation --- ## Use Context Module Pattern for Action Colocation When actions that mutate shared state are scattered across consuming components, tracing data flow requires searching the entire codebase.
Malicious tool definition detected
Tool: references/data-granular-error-boundaries.md Description: --- title: Place Error Boundaries at Data Fetch Granularity impact: MEDIUM impactDescription: prevents full-page crash from single component failure tags: data, error-boundaries, resilience, fault-isolation --- ## Place Error Boundaries at Data Fetch Granularity A single error boundary at the application root kills the entire page when any component throws.
Malicious tool definition detected
Tool: references/data-server-first-fetch.md Description: --- title: Fetch Data on the Server by Default impact: MEDIUM impactDescription: eliminates client loading spinners, reduces client JS bundle by 30-60% tags: data, server-components, data-fetching, performance --- ## Fetch Data on the Server by Default Client-side fetching with useEffect creates a waterfall: download JS, parse, render shell, fetch data, render content.
Malicious tool definition detected
Tool: references/data-tanstack-query-client.md Description: --- title: Use TanStack Query for Client-Side Server State impact: MEDIUM impactDescription: eliminates 80% of data fetching boilerplate, built-in cache/retry/deduplication tags: data, tanstack-query, caching, client-state --- ## Use TanStack Query for Client-Side Server State Manual useEffect + useState fetch patterns require hand-rolled loading states, error handling, caching, request deduplication, and retry logic.
Malicious tool definition detected
Tool: references/decomp-complete-extraction.md Description: --- title: Complete Component Extraction Without Half-Measures impact: HIGH impactDescription: enables independent testing and reuse of extracted component tags: decomp, extraction, encapsulation, props --- ## Complete Component Extraction Without Half-Measures Extracted components that still reach into their parent's state or internals provide no isolation benefit.
Malicious tool definition detected
Tool: references/decomp-extract-by-change-reason.md Description: --- title: Extract Components by Independent Change Reasons impact: HIGH impactDescription: 70% fewer files touched per feature change tags: decomp, single-responsibility, change-isolation, extraction --- ## Extract Components by Independent Change Reasons Code that changes for different business reasons should live in different components.
Malicious tool definition detected
Tool: references/decomp-extract-pure-functions.md Description: --- title: Extract Pure Functions from Component Bodies impact: HIGH impactDescription: pure functions testable without React, 10× faster unit tests tags: decomp, pure-functions, testability, performance --- ## Extract Pure Functions from Component Bodies Utility logic defined inside a component body is untestable without rendering the component and re-executes its definition on every render.
Malicious tool definition detected
Tool: references/decomp-inline-premature.md Description: --- title: Inline Premature Abstractions Before Re-Extracting impact: HIGH impactDescription: 40-60% simpler code after inlining wrong abstractions tags: decomp, abstraction, inlining, duplication --- ## Inline Premature Abstractions Before Re-Extracting A wrong abstraction resists change more than duplicated code.
Malicious tool definition detected
Tool: references/decomp-scroll-test.md Description: --- title: Apply the Scroll Test to Identify Oversized Components impact: HIGH impactDescription: reduces component size to under 100 lines, 3× faster code review tags: decomp, component-size, readability, extraction --- ## Apply the Scroll Test to Identify Oversized Components If you must scroll to read a component from top to bottom, it contains multiple responsibilities that should be separate components.
Malicious tool definition detected
Tool: references/decomp-separate-view-logic.md Description: --- title: Separate View Layer from Business Logic impact: HIGH impactDescription: business logic testable without rendering, 5× faster test suite tags: decomp, custom-hooks, view-logic-separation, testability --- ## Separate View Layer from Business Logic Business logic embedded in JSX forces every test to render the component, making tests slow and brittle.
Malicious tool definition detected
Tool: references/hook-avoid-object-deps.md Description: --- title: Avoid Object and Array Dependencies in Custom Hooks impact: HIGH impactDescription: prevents effect re-execution on every render tags: hook, dependencies, referential-equality, primitives --- ## Avoid Object and Array Dependencies in Custom Hooks Object and array literals in dependency arrays fail referential equality on every render, even when their contents are identical.
Malicious tool definition detected
Tool: references/hook-composition-over-nesting.md Description: --- title: Compose Hooks Instead of Nesting Them impact: HIGH impactDescription: flattens dependency graph, eliminates hidden coupling tags: hook, composition, nesting, dependency-graph, coupling --- ## Compose Hooks Instead of Nesting Them When hooks call other hooks internally, the dependency chain becomes invisible to the consuming component.
Malicious tool definition detected
Tool: references/hook-dependency-stability.md Description: --- title: Stabilize Hook Dependencies with Refs and Callbacks impact: HIGH impactDescription: prevents infinite loops, eliminates unnecessary re-executions tags: hook, dependencies, useRef, stability, infinite-loops --- ## Stabilize Hook Dependencies with Refs and Callbacks Unstable dependencies — callback props that are recreated every render — cause useEffect to re-execute infinitely.
Malicious tool definition detected
Tool: references/hook-extract-when-nameable.md Description: --- title: Extract Logic into Custom Hooks When Behavior Is Nameable impact: HIGH impactDescription: makes component 40-60% shorter, behavior self-documenting tags: hook, extraction, readability, abstraction --- ## Extract Logic into Custom Hooks When Behavior Is Nameable Inline timer setup, event subscriptions, and cleanup logic obscure the component's intent behind implementation mechanics.
Malicious tool definition detected
Tool: references/hook-naming-conventions.md Description: --- title: Follow Hook Naming Conventions for Discoverability impact: HIGH impactDescription: reduces codebase navigation time by 40% tags: hook, naming, conventions, discoverability --- ## Follow Hook Naming Conventions for Discoverability Inconsistent hook names force developers to open each file to understand what a hook does.
Malicious tool definition detected
Tool: references/hook-single-responsibility.md Description: --- title: Keep Custom Hooks to a Single Responsibility impact: HIGH impactDescription: 3× faster to test, 2× wider reuse tags: hook, single-responsibility, testability, reuse --- ## Keep Custom Hooks to a Single Responsibility Hooks that fetch, transform, subscribe, and cache in one function become untestable monoliths — mocking one concern requires stubbing all of them.
Malicious tool definition detected
Tool: references/safety-characterization-tests.md Description: --- title: Write Characterization Tests Before Refactoring impact: MEDIUM impactDescription: catches 90% of unintended behavior changes during refactoring tags: safety, characterization-tests, refactoring, regression --- ## Write Characterization Tests Before Refactoring Refactoring without tests means changing behavior without a safety net.
Malicious tool definition detected
Tool: references/safety-extract-pure-testability.md Description: --- title: Extract Pure Functions to Increase Testability impact: MEDIUM impactDescription: 10x faster test execution, no React test renderer needed tags: safety, pure-functions, testability, extraction --- ## Extract Pure Functions to Increase Testability Business logic embedded inside components requires rendering, interacting, and querying the DOM to verify correctness.
Malicious tool definition detected
Tool: references/safety-integration-over-unit.md Description: --- title: Prefer Integration Tests for Component Verification impact: MEDIUM impactDescription: catches 40% more bugs than isolated unit tests tags: safety, integration-tests, testing-strategy, confidence --- ## Prefer Integration Tests for Component Verification Unit testing each component in isolation with mocked children and dependencies proves that individual pieces work, but misses the bugs that occur when pieces connect.
Malicious tool definition detected
Tool: references/safety-snapshot-free.md Description: --- title: Avoid Snapshot Tests for Refactored Components impact: MEDIUM impactDescription: eliminates false test failures during refactoring, tests validate behavior tags: safety, snapshot-tests, false-negatives, refactoring --- ## Avoid Snapshot Tests for Refactored Components Snapshot tests serialize the entire rendered output, so any change to class names, wrapper elements, whitespace, or attribute order causes a failure.
Malicious tool definition detected
Tool: references/safety-test-behavior.md Description: --- title: Test Component Behavior Not Implementation Details impact: MEDIUM impactDescription: reduces test maintenance by 5× per refactoring cycle tags: safety, testing, behavior, implementation-details --- ## Test Component Behavior Not Implementation Details Tests that assert on internal state values, hook return values, or component instance methods break every time the implementation changes, even when the user-visible behavior stays id
Malicious tool definition detected
Tool: references/state-colocate-with-consumers.md Description: --- title: Colocate State with Components That Use It impact: CRITICAL impactDescription: reduces prop passing by 60%, improves component isolation tags: state, colocation, prop-drilling, isolation --- ## Colocate State with Components That Use It State lifted too high forces intermediate components to forward props they do not use.
Malicious tool definition detected
Tool: references/state-context-for-static.md Description: --- title: Use Context for Rarely-Changing Values Only impact: CRITICAL impactDescription: 5-50x fewer re-renders for context consumers tags: state, context, performance, re-renders, static-values --- ## Use Context for Rarely-Changing Values Only Every context value change re-renders the entire consumer subtree, regardless of which part of the value changed.
Malicious tool definition detected
Tool: references/state-derive-dont-sync.md Description: --- title: Derive Values Instead of Syncing State impact: CRITICAL impactDescription: eliminates double-render cycle, prevents sync drift tags: state, derived-state, useEffect, sync-bugs --- ## Derive Values Instead of Syncing State Using useEffect to compute a derived value from other state causes a double-render: first the source state updates and renders, then the effect fires, updates the derived state, and renders again.
Malicious tool definition detected
Tool: references/state-lift-only-when-shared.md Description: --- title: Lift State Only When Multiple Components Read It impact: CRITICAL impactDescription: eliminates unnecessary parent re-renders, clearer ownership tags: state, lifting, shared-state, ownership --- ## Lift State Only When Multiple Components Read It Premature lifting places state in a component that does not use it directly, making ownership unclear and forcing unnecessary re-renders on every state change.
Malicious tool definition detected
Tool: references/state-machines-for-workflows.md Description: --- title: Use State Machines for Complex UI Workflows impact: CRITICAL impactDescription: reduces valid states from 2^n to exactly N defined states tags: state, state-machine, workflows, finite-states --- ## Use State Machines for Complex UI Workflows Boolean flags scale combinatorially: 4 booleans create 16 possible states, most of which are invalid (e.g., loading AND error AND success simultaneously).
Malicious tool definition detected
Tool: references/state-reducer-for-complex.md Description: --- title: Use useReducer for Multi-Field State Transitions impact: CRITICAL impactDescription: eliminates impossible states, centralizes transition logic tags: state, useReducer, state-transitions, type-safety --- ## Use useReducer for Multi-Field State Transitions Multiple related useState calls allow independent updates that produce impossible combinations — like `isSubmitting: true` and `isSuccess: true` simultaneously.
Malicious tool definition detected
Tool: references/state-url-as-state.md Description: --- title: Use URL Parameters as State for Shareable Views impact: CRITICAL impactDescription: enables deep linking, back/forward navigation, state sharing tags: state, url-state, search-params, deep-linking --- ## Use URL Parameters as State for Shareable Views Local state for filters, pagination, and search queries breaks browser back/forward navigation and makes views unshareable.