React Refactoring Skill

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

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

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

워크플로우

Phase 1: 현황 파악

• 대상 컴포넌트/파일 읽기

• 관련 의존성 파일들 파악 (imports, hooks, types)

• 현재 코드의 구조를 간략히 정리

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

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

모드 선택 기준

조건 모드 설명

1-2개 단순 문제점 Standard Mode 기존 sequential-thinking 3회 방식

3개 이상 또는 복잡한 문제점 Multi-Perspective Mode 병렬 sub-agent 3관점 분석

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

각 문제점마다 mcp__sequential-thinking__sequentialthinking 도구를 사용하여 사고 과정을 기록한다.

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

Step 2.1: 문제 정의 검증

sequential-thinking으로 다음을 분석:

이 문제가 정말 문제인가?

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

Step 2.2: 제안된 방향 평가

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

이 방향이 정말 개선인가?

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

Step 2.3: 대안 탐색

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

더 나은 대안은?

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

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

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

에이전트 구성

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개 에이전트의 결과를 수집한 후 오케스트레이터가 종합:

합의 상황 행동

3개 일치 (수용/수정/기각) 높은 확신으로 해당 판단 채택

2:1 (다수:소수) 소수 의견의 근거를 검토 후 오케스트레이터가 최종 결정

3개 상이 AskUserQuestion 으로 사용자에게 선택지와 근거를 제시하여 판단 요청

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

분석 중 다음 상황이면 반드시 AskUserQuestion 도구로 질문:

• 비즈니스 컨텍스트가 필요한 경우 (예: "이 컴포넌트가 여러 곳에서 재사용되나요?")

• 기존 코드의 의도가 불명확한 경우 (예: "이 훅이 이렇게 설계된 이유가 있나요?")

• 사용자의 제안과 분석 결과가 충돌하는 경우 (예: "이 방향은 오히려 복잡해질 수 있는데, 그래도 진행할까요?")

• 팀 컨벤션 확인이 필요한 경우 (예: "팀에서 네임스페이스 패턴을 사용하는 곳이 있나요?")

Phase 3: 리팩토링 계획 수립

모든 문제점 분석 완료 후:

• 분석 결과 요약: 각 문제점에 대한 판단 (수용/수정/기각)

• Multi-Perspective Mode인 경우: 각 관점의 Verdict와 최종 결정 근거 포함

• 리팩토링 계획서 작성:

• 변경 대상 파일 목록

• 각 변경의 목적과 기대 효과

• 변경 순서 (의존성 고려)

• 예상 위험 요소

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

Phase 4: 사용자 승인

계획서를 제시하고 AskUserQuestion 으로 승인 요청:

리팩토링 계획을 검토해주세요.

• [수용] 문제 1: ... → 이렇게 변경
• [수정] 문제 2: ... → 제안과 다르게 이 방향으로
• [기각] 문제 3: ... → 현재 구조가 더 적절함 진행해도 될까요?

Phase 5: 리팩토링 실행

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

• 변경 전 상태 확인

• 변경 수행

• 변경이 의도대로 되었는지 검증

• 필요시 관련 테스트 확인/수정

주의사항

하지 말아야 할 것

• 사용자 제안을 무비판적으로 수용

• 분석 없이 바로 코드 수정 시작

• "일반적으로 좋은 패턴"이라는 이유만으로 변경 제안

• 한 번에 너무 많은 것을 변경

항상 해야 할 것

• 모든 판단에 구체적 근거 제시

• 불확실하면 질문

• 변경의 트레이드오프 명시

• 기존 코드베이스 스타일 존중

React/TypeScript 특화 체크리스트

훅 분리 시:

• 분리 후에도 co-location이 유지되는가?

• 커스텀 훅의 반환 타입이 명확한가?

• 훅 간 의존성이 단방향인가?

컴포넌트 분리 시:

• Props drilling이 과도해지지 않는가?

• 상태 끌어올리기가 필요해지지 않는가?

• 컴포넌트 경계가 자연스러운가?

폴더 구조 변경 시:

• import 경로가 과도하게 길어지지 않는가?

• 순환 의존성이 생기지 않는가?

• 기존 구조와의 일관성은?