146 lines
6.0 KiB
Markdown
146 lines
6.0 KiB
Markdown
---
|
|
name: dev-refactor-polish
|
|
description: 구현 완료 직후 가독성·데이터 흐름·성능을 다듬는 후처리 리팩토링 스킬. 핵심 동작을 바꾸지 않는 정리 단계에서 사용하며, 신규 기능의 본 구현 단계 대체 용도로는 사용하지 않는다.
|
|
---
|
|
|
|
# Dev Refactor Polish
|
|
|
|
## 목표
|
|
|
|
- 핵심 비즈니스 동작은 유지하고 코드 품질을 높인다.
|
|
- 읽기 쉬운 구조와 명확한 데이터 흐름 설명을 만든다.
|
|
- 사용자 혼란을 줄이는 작은 UX 개선(문구, 버튼 라벨, 피드백 표시)은 허용한다.
|
|
|
|
## 리팩토링 목표 (refactoring-rule 반영)
|
|
|
|
1. 표준 폴더 구조를 지향한다.
|
|
- 기본: `apis`, `components`, `hooks`, `stores`, `types`
|
|
2. 필요 시 보조 폴더를 유연하게 허용한다.
|
|
- 선택: `utils`, `lib`, `constants`
|
|
3. 거대한 단일 파일은 기능 단위로 분해한다.
|
|
4. 배럴 파일(`index.ts` re-export) 의존을 줄이고 직접 import 경로를 사용한다.
|
|
|
|
## 리팩토링 기본 원칙
|
|
|
|
1. 설명과 주석은 한국어로 쉽게 쓴다. 어려운 용어는 괄호로 짧게 풀어쓴다.
|
|
2. 사이드이펙트 위험이 있으면 영향 범위를 먼저 확인하고 수정한다.
|
|
3. 불필요한 코드만 제거하고, 영향 가능성이 있으면 검증 후 반영한다.
|
|
|
|
## 리팩토링 순서
|
|
|
|
1. 핵심 동작 변경 없이 중복 코드를 줄인다.
|
|
2. 함수/변수 이름을 역할이 드러나는 이름으로 정리한다.
|
|
3. 복잡한 JSX는 섹션 주석으로 나눈다.
|
|
4. 상태/이벤트/복잡 로직에 인라인 주석을 보강한다.
|
|
5. 함수/API/Query에 쉬운 설명 주석을 보강한다.
|
|
6. 데이터 흐름을 `어느 UI -> A 함수 호출 -> B 함수 호출 -> 리턴값 반영`으로 명시한다.
|
|
7. `vercel-react-best-practices` 기준으로 불필요한 리렌더/요청을 줄인다.
|
|
|
|
## 작업 지시 (Workflow, refactoring-rule 반영)
|
|
|
|
1. 분석: `FEATURE_ROOT` 내부 파일 구조와 외부 import 의존성을 파악한다.
|
|
2. 구조 설계: 기본/선택 폴더 기준으로 파일 분류 계획을 세운다.
|
|
3. 이동/생성: 파일을 이동하거나 책임 단위로 분리 생성한다.
|
|
4. 경로 수정: 이동된 파일에 맞춰 import 경로를 일괄 수정한다.
|
|
5. 청소: 옛 폴더와 불필요한 `index.ts`를 정리한다.
|
|
6. 진입점 갱신: `page.tsx` 등 외부 진입 파일 import를 최종 갱신한다.
|
|
|
|
## 권장 파일 구조 (Standard Structure)
|
|
|
|
```text
|
|
<FEATURE_ROOT>/
|
|
├── apis/
|
|
│ ├── apiError.ts
|
|
│ ├── <feature>.api.ts
|
|
│ ├── <feature>Form.adapter.ts
|
|
│ └── <feature>List.adapter.ts
|
|
├── hooks/
|
|
│ ├── queryKeys.ts
|
|
│ ├── use<Feature>List.ts
|
|
│ ├── use<Feature>Mutations.ts
|
|
│ └── use<Feature>Form.ts
|
|
├── types/
|
|
│ ├── api.types.ts
|
|
│ ├── <feature>.types.ts
|
|
│ └── selectOption.types.ts
|
|
├── stores/
|
|
│ └── <feature>Store.ts
|
|
├── components/
|
|
│ ├── <Feature>Container.tsx
|
|
│ └── <Feature>Modal.tsx
|
|
├── utils/ # Optional
|
|
│ └── <feature>Utils.ts
|
|
├── lib/ # Optional
|
|
│ └── <feature>Lib.ts
|
|
└── constants/ # Optional
|
|
└── <feature>.constants.ts
|
|
```
|
|
|
|
## 의존성/리스크 분석 규칙
|
|
|
|
1. 파일 이동 전 `sequential-thinking`으로 의존성 지도를 먼저 만든다.
|
|
2. 최신 구조 기준이 모호하면 `context7`로 공식 문서를 확인한다.
|
|
|
|
## common-docs 리팩토링 반영 규칙
|
|
|
|
1. KIS 연동 리팩토링 시 아래 기준을 유지한다.
|
|
- 스펙 기준: `common-docs/api-reference/openapi_all.xlsx`
|
|
- 보조 확인: `kis_api_reference.md`, `kis-error-code-reference.md`
|
|
2. 에러 처리 리팩토링 시 `lib/kis/error-codes.ts` 중심 구조(`msg_cd + 문구`)를 깨지 않게 유지한다.
|
|
3. 종목 데이터 리팩토링 시 `korean-stocks.json`을 수동 편집 대상으로 옮기지 않는다.
|
|
- 동기화 흐름은 `trade-stock-sync.md` 기준으로 유지한다.
|
|
4. 알림 UI 리팩토링 시 전역 알림 구조(`useGlobalAlert`, `GlobalAlertModal`)를 우선 유지한다.
|
|
5. `features-autotrade-design.md`는 리팩토링 기준 문서로 사용하지 않는다.
|
|
|
|
## 주석 규칙 (문서화 전문가 기준)
|
|
|
|
1. 주석 보강 작업은 코드 로직(타입/런타임/동작/변수명/import)을 바꾸지 않는다.
|
|
2. 함수/API/쿼리 주석은 `[목적]`, `[사용처]`, `[데이터 흐름]` 중심으로 쉽게 쓴다.
|
|
3. 상태(`useState`, `useRef`, store)는 "화면에 어떤 영향을 주는지" 한 줄 주석을 단다.
|
|
4. 복잡한 로직/핸들러는 `1.`, `2.`, `3.` 단계 주석으로 흐름을 나눈다.
|
|
5. 긴 JSX는 화면 구역 주석으로 나눠서 읽기 쉽게 만든다.
|
|
- 예: `{/* ===== 1. 상단: 페이지 제목 및 액션 버튼 ===== */}`
|
|
6. `@param`, `@see`, `@remarks` 같은 딱딱한 TSDoc 태그는 강제하지 않는다.
|
|
7. 결과 기준은 "주니어가 5분 내 파악 가능한지"로 잡는다.
|
|
|
|
## UI/브랜드/문구 규칙
|
|
|
|
1. UI 수정 시 `brand-*` 토큰과 `primary` 사용 기준을 지킨다.
|
|
2. 사용자 문구는 불안을 줄이고 확신을 주는 톤으로 개선한다.
|
|
|
|
## 품질 체크리스트
|
|
|
|
- 핵심 비즈니스 로직 변경이 없는가?
|
|
- 작은 UX 개선이라도 API 계약(입출력 규칙), 권한, 저장 데이터 구조를 건드리지 않았는가?
|
|
- 주니어가 5분 안에 흐름을 파악할 수 있는가?
|
|
- 상태 변경이 화면 어디에 반영되는지 보이는가?
|
|
- 무거운 계산/렌더가 메모이제이션(재계산 줄이기) 대상인지 검토했는가?
|
|
|
|
## 출력 템플릿
|
|
|
|
```md
|
|
[리팩토링 요약]
|
|
- ...
|
|
|
|
[가독성 개선 포인트]
|
|
- ...
|
|
|
|
[작은 UX 개선 포인트]
|
|
- ...
|
|
|
|
[성능 개선 포인트]
|
|
- ...
|
|
|
|
[데이터 흐름 정리]
|
|
- 어느 UI -> A 함수 호출 -> B 함수 호출 -> 리턴값 반영
|
|
|
|
[회귀 위험 점검]
|
|
- ...
|
|
```
|
|
|
|
## 규칙
|
|
|
|
- 파일 이동/삭제가 있으면 영향 범위를 먼저 검증한다.
|
|
- 구조 개선은 하되 과도한 분리(쪼개기)는 피한다.
|
|
- 작은 UX 개선을 했으면 왜 개선했는지 한 줄 근거를 남긴다.
|