react-refactoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Refactoring Skill

사용자가 제시하는 문제점을 무조건 수용하지 않는다. 각 문제점에 대해 비판적으로 검토하고, 정말 문제인지, 제시된 방향이 최선인지 분석한 후 리팩토링을 수행한다.

不会无条件接受用户提出的问题点。会对每个问题点进行批判性审查，分析其是否真的是问题、提出的方向是否最优后再执行重构。

핵심 원칙: 수정하기 좋은 코드

核心原则：易于修改的代码

모든 판단의 기준은 **"수정하기 좋은 코드인가?"**이다. 평가 기준 상세는 references/evaluation-criteria.md 참조.

所有判断的标准都是**「是否是易于修改的代码？」**。详细评估标准请参考references/evaluation-criteria.md。

워크플로우

工作流程

Phase 1: 현황 파악

阶段1：现状把握

대상 컴포넌트/파일 읽기
관련 의존성 파일들 파악 (imports, hooks, types)
현재 코드의 구조를 간략히 정리

读取目标组件/文件
识别相关依赖文件（imports、hooks、types）
简要整理当前代码的结构

Phase 2: 문제점별 비판적 분석

阶段2：按问题点进行批判性分析

사용자가 제시한 문제점의 수와 복잡도에 따라 모드를 선택한다.

根据用户提出的问题点数量和复杂程度选择模式。

모드 선택 기준

模式选择标准

조건	모드	설명
1-2개 단순 문제점	Standard Mode	기존 sequential-thinking 3회 방식
3개 이상 또는 복잡한 문제점	Multi-Perspective Mode	병렬 sub-agent 3관점 분석

条件	模式	说明
1-2个简单问题点	Standard Mode	原有sequential-thinking三轮方式
3个以上或复杂问题点	Multi-Perspective Mode	并行sub-agent三维度分析

Standard Mode (1-2개 단순 문제점)

Standard Mode（1-2个简单问题点）

각 문제점마다

mcp__sequential-thinking__sequentialthinking

도구를 사용하여 사고 과정을 기록한다.

각 문제점당 최소 3번의 thinking 루프를 수행한다.

针对每个问题点，使用

mcp__sequential-thinking__sequentialthinking

工具记录思考过程。

每个问题点至少执行3次思考循环。

Step 2.1: 문제 정의 검증

步骤2.1：问题定义验证

sequential-thinking으로 다음을 분석:

이 문제가 정말 문제인가?
- 현재 코드가 실제로 어떤 불편/위험을 초래하는가?
- "수정하기 좋은 코드" 9가지 기준 중 어떤 것을 위반하는가?
- 위반이 없다면, 이건 취향의 문제인가 실질적 문제인가?

通过sequential-thinking分析以下内容：

这个问题真的是问题吗？
- 当前代码实际会带来哪些不便/风险？
- 违反了「易于修改的代码」9项标准中的哪一项？
- 如果没有违反，这是偏好问题还是实质性问题？

Step 2.2: 제안된 방향 평가

步骤2.2：评估提议方向

사용자가 방향을 제시했다면:

이 방향이 정말 개선인가?
- 제안된 변경이 "수정하기 좋은 코드" 기준을 충족하는가?
- 오히려 복잡성을 증가시키지는 않는가?
- 기존 코드베이스의 일관성을 해치지 않는가?
- 과한 추상화(Over-engineering)는 아닌가?

如果用户提出了改进方向：

这个方向真的是改进吗？
- 提议的变更是否符合「易于修改的代码」标准？
- 会不会反而增加复杂度？
- 会不会破坏现有代码库的一致性？
- 是否属于过度设计(Over-engineering)？

Step 2.3: 대안 탐색

步骤2.3：探索替代方案

제안된 방향이 최선이 아니라면:

더 나은 대안은?
- 더 단순한 해결책이 있는가?
- 점진적으로 개선할 수 있는 방법은?
- 이 문제를 해결하지 않는 것도 선택지인가?

如果提议的方向不是最优解：

更好的替代方案是什么？
- 有没有更简单的解决方案？
- 有没有可以逐步改进的方法？
- 不解决这个问题是否也是可选方案？

Multi-Perspective Mode (3개 이상 또는 복잡한 문제점)

Multi-Perspective Mode（3个以上或复杂问题点）

각 문제점에 대해 3개 관점의 Task sub-agent를 병렬 실행한다.

针对每个问题点，并行执行3个视角的Task sub-agent。

에이전트 구성

Agent构成

Agent	subagent_type	model	관점
Readability Advocate	general-purpose	sonnet	가독성, 의도의 명확성
Architecture Purist	typescript-pro	sonnet	타입 안전성, 패턴 일관성, 구조적 정합성
Pragmatic Developer	frontend-developer	sonnet	유지보수성, 실용성, 개발 경험

Agent	subagent_type	model	视角
Readability Advocate	general-purpose	sonnet	可读性、意图明确性
Architecture Purist	typescript-pro	sonnet	类型安全性、模式一致性、结构合理性
Pragmatic Developer	frontend-developer	sonnet	可维护性、实用性、开发体验

실행 방법

执行方法

3개의 Task sub-agent를 단일 메시지에서 동시 실행 (

run_in_background: true

Agent: Readability Advocate

You are a Readability Advocate analyzing a React refactoring proposal.
Your lens: code readability, intent clarity, self-documenting code.

Read the target component at: [파일 경로]
The user's proposed issues and changes:
[문제점 목록]

For EACH issue, provide your verdict:
- Verdict: [수용/수정/기각]
- Reasoning: [Why, focused on readability impact]
- Alternative: [Better approach from readability perspective, if any]

Write your analysis. Focus on whether each change makes the code easier to READ and UNDERSTAND.

Agent: Architecture Purist

You are an Architecture Purist analyzing a React refactoring proposal.
Your lens: type safety, pattern consistency, structural integrity, SOLID principles.

Read the target component at: [파일 경로]
The user's proposed issues and changes:
[문제점 목록]

For EACH issue, provide your verdict:
- Verdict: [수용/수정/기각]
- Reasoning: [Why, focused on type safety and architectural patterns]
- Alternative: [Better approach from architecture perspective, if any]

Write your analysis. Focus on whether each change improves TYPE SAFETY and STRUCTURAL CONSISTENCY.

Agent: Pragmatic Developer

You are a Pragmatic Developer analyzing a React refactoring proposal.
Your lens: maintainability, practicality, developer experience, cost-benefit.

Read the target component at: [파일 경로]
The user's proposed issues and changes:
[문제점 목록]

For EACH issue, provide your verdict:
- Verdict: [수용/수정/기각]
- Reasoning: [Why, focused on practical maintenance impact]
- Alternative: [Better approach from practical perspective, if any]

Write your analysis. Focus on whether each change is WORTH THE EFFORT and improves MAINTAINABILITY.

在单条消息中同时执行3个Task sub-agent（

run_in_background: true

）：

Agent: Readability Advocate

You are a Readability Advocate analyzing a React refactoring proposal.
Your lens: code readability, intent clarity, self-documenting code.

Read the target component at: [文件路径]
The user's proposed issues and changes:
[问题点列表]

For EACH issue, provide your verdict:
- Verdict: [接受/修改/驳回]
- Reasoning: [Why, focused on readability impact]
- Alternative: [Better approach from readability perspective, if any]

Write your analysis. Focus on whether each change makes the code easier to READ and UNDERSTAND.

Agent: Architecture Purist

You are an Architecture Purist analyzing a React refactoring proposal.
Your lens: type safety, pattern consistency, structural integrity, SOLID principles.

Read the target component at: [文件路径]
The user's proposed issues and changes:
[问题点列表]

For EACH issue, provide your verdict:
- Verdict: [接受/修改/驳回]
- Reasoning: [Why, focused on type safety and architectural patterns]
- Alternative: [Better approach from architecture perspective, if any]

Write your analysis. Focus on whether each change improves TYPE SAFETY and STRUCTURAL CONSISTENCY.

Agent: Pragmatic Developer

You are a Pragmatic Developer analyzing a React refactoring proposal.
Your lens: maintainability, practicality, developer experience, cost-benefit.

Read the target component at: [文件路径]
The user's proposed issues and changes:
[问题点列表]

For EACH issue, provide your verdict:
- Verdict: [接受/修改/驳回]
- Reasoning: [Why, focused on practical maintenance impact]
- Alternative: [Better approach from practical perspective, if any]

Write your analysis. Focus on whether each change is WORTH THE EFFORT and improves MAINTAINABILITY.

종합 규칙

综合规则

3개 에이전트의 결과를 수집한 후 오케스트레이터가 종합:

합의 상황	행동
3개 일치 (수용/수정/기각)	높은 확신으로 해당 판단 채택
2:1 (다수:소수)	소수 의견의 근거를 검토 후 오케스트레이터가 최종 결정
3개 상이	`AskUserQuestion` 으로 사용자에게 선택지와 근거를 제시하여 판단 요청

收集3个Agent的结果后，由协调器进行综合：

共识情况	行动
3个一致（接受/修改/驳回）	以高置信度采纳该判断
2:1（多数:少数）	审查少数意见的依据后，由协调器做出最终决定
3个意见不同	通过 `AskUserQuestion` 工具向用户提供选项和依据，请求其判断

Step 2.4: 불명확한 점 질문 (공통)

步骤2.4：询问不明确点（通用）

분석 중 다음 상황이면 반드시

AskUserQuestion

도구로 질문:

비즈니스 컨텍스트가 필요한 경우 (예: "이 컴포넌트가 여러 곳에서 재사용되나요?")
기존 코드의 의도가 불명확한 경우 (예: "이 훅이 이렇게 설계된 이유가 있나요?")
사용자의 제안과 분석 결과가 충돌하는 경우 (예: "이 방향은 오히려 복잡해질 수 있는데, 그래도 진행할까요?")
팀 컨벤션 확인이 필요한 경우 (예: "팀에서 네임스페이스 패턴을 사용하는 곳이 있나요?")

分析过程中如果出现以下情况，必须使用

AskUserQuestion

工具询问：

需要业务上下文时（例如：「这个组件是否在多个地方复用？」）
现有代码的意图不明确时（例如：「这个Hook这样设计的原因是什么？」）
用户的提议与分析结果冲突时（例如：「这个方向反而可能会增加复杂度，仍要继续吗？」）
需要确认团队规范时（例如：「团队中有使用命名空间模式的地方吗？」）

Phase 3: 리팩토링 계획 수립

阶段3：制定重构计划

모든 문제점 분석 완료 후:

분석 결과 요약: 각 문제점에 대한 판단 (수용/수정/기각)
- Multi-Perspective Mode인 경우: 각 관점의 Verdict와 최종 결정 근거 포함
리팩토링 계획서 작성:

변경 대상 파일 목록
각 변경의 목적과 기대 효과
변경 순서 (의존성 고려)
예상 위험 요소

점진적 실행 계획: 한 번에 큰 변경 대신 작은 단위로 분리

完成所有问题点分析后：

分析结果总结：每个问题点的判断（接受/修改/驳回）
- 若为Multi-Perspective Mode：需包含各视角的Verdict及最终决定的依据
编写重构计划书：

变更目标文件列表
每项变更的目的和预期效果
变更顺序（考虑依赖关系）
预期风险因素

渐进式执行计划：不一次性进行大幅变更，而是拆分为小单元执行

Phase 4: 사용자 승인

阶段4：用户确认

계획서를 제시하고

AskUserQuestion

으로 승인 요청:

리팩토링 계획을 검토해주세요.
- [수용] 문제 1: ... → 이렇게 변경
- [수정] 문제 2: ... → 제안과 다르게 이 방향으로
- [기각] 문제 3: ... → 현재 구조가 더 적절함
진행해도 될까요?

提交计划书后，通过

AskUserQuestion

工具请求确认：

请审查重构计划。
- [接受] 问题1：... → 如此变更
- [修改] 问题2：... → 与提议不同，将按此方向进行
- [驳回] 问题3：... → 当前结构更合适
可以继续执行吗？

Phase 5: 리팩토링 실행

阶段5：执行重构

승인 후 계획에 따라 코드 수정. 각 단계마다:

변경 전 상태 확인
변경 수행
변경이 의도대로 되었는지 검증
필요시 관련 테스트 확인/수정

获得确认后，按照计划修改代码。每个步骤需：

确认变更前的状态
执行变更
验证变更是否符合预期
必要时检查/修改相关测试

주의사항

注意事项

하지 말아야 할 것

禁止事项

사용자 제안을 무비판적으로 수용
분석 없이 바로 코드 수정 시작
"일반적으로 좋은 패턴"이라는 이유만으로 변경 제안
한 번에 너무 많은 것을 변경

无批判地接受用户提议
未分析就直接开始修改代码
仅以「通常是好的模式」为由提议变更
一次性进行过多变更

항상 해야 할 것

必须事项

모든 판단에 구체적 근거 제시
불확실하면 질문
변경의 트레이드오프 명시
기존 코드베이스 스타일 존중

所有判断都提供具体依据
不确定时及时询问
明确说明变更的权衡
尊重现有代码库的风格

React/TypeScript 특화 체크리스트

React/TypeScript专项检查清单

훅 분리 시:

분리 후에도 co-location이 유지되는가?
커스텀 훅의 반환 타입이 명확한가?
훅 간 의존성이 단방향인가?

컴포넌트 분리 시:

Props drilling이 과도해지지 않는가?
상태 끌어올리기가 필요해지지 않는가?
컴포넌트 경계가 자연스러운가?

폴더 구조 변경 시:

import 경로가 과도하게 길어지지 않는가?
순환 의존성이 생기지 않는가?
기존 구조와의 일관성은?

分离Hook时：

分离后是否仍保持co-location？
自定义Hook的返回类型是否明确？
Hook之间的依赖是否为单向？

分离组件时：

是否不会过度出现Props drilling？
是否不需要进行状态提升？
组件边界是否自然合理？

修改文件夹结构时：

import路径是否不会过长？
是否不会产生循环依赖？
与现有结构是否一致？