tomevault-io 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 경로가 과도하게 길어지지 않는가?
- 순환 의존성이 생기지 않는가?
- 기존 구조와의 일관성은?
Converted and distributed by TomeVault — claim your Tome and manage your conversions.