react-component-hook-guidelines-cn

React Component Hook Guidelines

Overview

Provide judgment for splitting, refactoring, and reviewing React components, page components, and custom Hooks. Focus on handling mixed responsibilities, overly broad props, passing down large state, too many branches, overly heavy page orchestration, and coupling of presentation and logic.

When to use

Use this skill when the user raises the following needs:

• Split components
• Split Hooks
• Component is too large, Hook is too heavy
• Help sort out the page or React layering
• Refactor React components, page logic, or component design
• Reduce props, converge responsibilities, split God Component or God Hook
• Handle issues such as chaotic page state, coupling of logic and UI, and too many branches

Do not use

This skill should not be used in the following scenarios:

• Tasks unrelated to React components, Hooks, or page orchestration
• Pure backend logic or non-frontend tasks
• Simple style changes unrelated to responsibility boundaries, state flow, or props design

Usage instructions

1. First identify the task type: code review, refactoring, implementing a new feature, or sorting out directories/layering.
2. Locate the core units: page components, business components, presentational components, custom Hooks, utility functions.
3. Determine whether the reason for change is single, then check whether props, state, side effects, routing, caching, modals, or analytics are incorrectly coupled.
4. Prioritize solving complexity by splitting boundaries; do not mechanically compress line counts as a substitute for design judgment.

Quick decisions

• When you need to determine whether a component or Hook should be split, read references/react-component-hook-rules.md。
• When you need to review existing React code, check in the order of "responsibility boundaries → props design → complexity → branch expansion".
• When you need to implement refactoring, prioritize extracting business Hooks, presentational components, and pure functions; do not first do ineffective style-level moving around.
• When you need to implement a new component, first decide whether it belongs to page orchestration, a business container, a presentational component, or a general UI component.

Execution rules

Review

At least check the following issues:

• Whether only one main component or main Hook is exported.
• Whether page-level large state or the entire actions package is passed directly down to child components.
• Whether UI, requests, routing, side effects, caching, modals, or analytics are coupled at the same time.
• Whether there are more than 3 mode branches and it is more suitable to change them to a mapping/strategy.
• Whether there is logic that should be extracted as a Hook or lib/utils logic.

Refactoring

Prioritize using this splitting path:

1. Remove business state and side effects from page components.
2. Extract reusable or testable state flow into business Hooks.
3. Split heavy JSX blocks into minimal presentational components.
4. Move pure data transformation, validation, and mapping to lib/ or utils/。
5. Shrink props, keeping only the fields and callbacks that child components truly need.

New implementation

Before implementation, make three judgments:

1. Is this the orchestration layer or the presentation layer?
2. Should the state logic go into a Hook?
3. Does this logic still hold after being detached from the React lifecycle? If it holds, put it in lib/utils。

Additional hard constraints:

• Code comments must be in Chinese.
• Functions need a functional comment before their definition, explaining their responsibilities and the scenarios they handle.
• Hooks need a functional comment before their definition, explaining the business responsibilities they encapsulate, their state scope, or their side effect boundaries.
• Comments only explain responsibilities, boundaries, and intent; do not write low-information line-by-line translation-style comments.

Output requirements

• If it is a review, first provide the "problems found," then give revision suggestions.
• If it is a refactor, clearly list the new boundaries: which stay in the page, which go into a Hook, which go into presentational components, and which go into utility functions.
• If it is an implementation, follow the reference conventions when producing code, do not reintroduce "big object props" or "universal Hooks," and add functional comments for newly added or modified functions and Hooks.

Exception handling

Reasonable exceptions are allowed, but the reason must be explained. Common acceptable exceptions:

• A purely presentational component is slightly long, but the visual structure is centralized and its responsibilities are stable.
• A small number of auxiliary subcomponents in the same file only serve the current main component.
• The page entry file is a bit long, but the business logic has already been extracted.

If a clear reason cannot be given, tighten the boundaries according to the conventions by default.