213 lines
8.2 KiB
Markdown
213 lines
8.2 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`, `useMemo`, store 파생 상태)는 반드시 `[State]`, `[Ref]` 형식으로 역할 주석을 단다.
|
|
- 예: `// [State] 자동매매 실행 중 여부 (배너/버튼 상태에 사용)`
|
|
- 예: `// [Ref] 마지막 신호 요청 시각 (요청 과다 방지용)`
|
|
4. 복잡한 로직/핸들러는 반드시 `[Step 1]`, `[Step 2]`, `[Step 3]` 형식으로 흐름을 나눈다.
|
|
- 예: `// [Step 1] 입력값 유효성 검증`
|
|
5. 긴 JSX는 화면 구역 주석으로 나눠서 읽기 쉽게 만든다.
|
|
- 예: `{/* ========== 1. 상단: 상태/액션 영역 ========== */}`
|
|
6. 데이터 흐름이 중요한 입력(UI prompt, 검색어, 주문 설정값)은 입력 지점에 "어디 API로 가는지"를 한 줄로 명시한다.
|
|
- 예: `// [데이터 흐름] textarea -> patchSetupForm -> compile API -> AI provider(OpenAI/CLI)`
|
|
7. `@param`, `@see`, `@remarks` 같은 딱딱한 TSDoc 태그는 강제하지 않는다.
|
|
8. 결과 기준은 "주니어가 5분 내 파악 가능한지"로 잡는다.
|
|
|
|
### 파일 상단 역할 주석 (필수)
|
|
|
|
1. 핵심 파일(`components`, `hooks`, `apis`, `lib`, `route.ts`)은 import 위(또는 `"use client"` 바로 아래)에 파일 역할 주석을 단다.
|
|
2. 형식은 아래 템플릿을 따른다.
|
|
|
|
```ts
|
|
/**
|
|
* [파일 역할]
|
|
* 이 파일이 시스템에서 맡는 역할
|
|
*
|
|
* [주요 책임]
|
|
* - 책임 1
|
|
* - 책임 2
|
|
* - 책임 3
|
|
*/
|
|
```
|
|
|
|
### 흐름 추적 문서화 규칙 (필수)
|
|
|
|
1. 사용자가 "이 값이 어디로 가는지"를 물으면 반드시 함수 체인을 파일/라인으로 답한다.
|
|
2. 형식은 `UI 입력 -> 핸들러 -> 훅/서비스 -> API 클라이언트 -> route -> provider -> 결과 반영` 순서를 유지한다.
|
|
3. 최종 답변에 최소 1개 이상의 "핵심 입력 흐름 추적표"를 포함한다.
|
|
4. 라인 표기는 `절대경로:라인` 링크 형식으로 제공한다.
|
|
|
|
### 필수 주석 패턴 (컴포넌트/훅)
|
|
|
|
1. State/Ref 선언부
|
|
|
|
```ts
|
|
// [State] 자동매매 설정 모달 열림 여부
|
|
const [panelOpen, setPanelOpen] = useState(false);
|
|
|
|
// [Ref] 최근 가격 캐시 (신호 생성용)
|
|
const recentPricesRef = useRef<number[]>([]);
|
|
```
|
|
|
|
2. 핸들러/비즈니스 함수
|
|
|
|
```ts
|
|
const handleStart = async () => {
|
|
// [Step 1] 필수 입력값 검증
|
|
// [Step 2] 전략 컴파일/검증 API 호출
|
|
// [Step 3] 세션 시작 및 UI 상태 갱신
|
|
};
|
|
```
|
|
|
|
3. JSX 섹션 구분
|
|
|
|
```tsx
|
|
return (
|
|
<>
|
|
{/* ========== 1. 상단: 상태 및 액션 ========== */}
|
|
{/* ========== 2. 본문: 설정 입력 영역 ========== */}
|
|
{/* ========== 3. 하단: 검증/시작 버튼 영역 ========== */}
|
|
</>
|
|
);
|
|
```
|
|
|
|
## UI/브랜드/문구 규칙
|
|
|
|
1. UI 수정 시 `brand-*` 토큰과 `primary` 사용 기준을 지킨다.
|
|
2. 사용자 문구는 불안을 줄이고 확신을 주는 톤으로 개선한다.
|
|
|
|
## 품질 체크리스트
|
|
|
|
- 핵심 비즈니스 로직 변경이 없는가?
|
|
- 작은 UX 개선이라도 API 계약(입출력 규칙), 권한, 저장 데이터 구조를 건드리지 않았는가?
|
|
- 주니어가 5분 안에 흐름을 파악할 수 있는가?
|
|
- 상태 변경이 화면 어디에 반영되는지 보이는가?
|
|
- 무거운 계산/렌더가 메모이제이션(재계산 줄이기) 대상인지 검토했는가?
|
|
|
|
## 출력 템플릿
|
|
|
|
```md
|
|
[리팩토링 요약]
|
|
- ...
|
|
|
|
[가독성 개선 포인트]
|
|
- ...
|
|
|
|
[작은 UX 개선 포인트]
|
|
- ...
|
|
|
|
[성능 개선 포인트]
|
|
- ...
|
|
|
|
[데이터 흐름 정리]
|
|
- 어느 UI -> A 함수 호출 -> B 함수 호출 -> 리턴값 반영
|
|
|
|
[핵심 입력 흐름 추적표]
|
|
- 입력값: (예: 전략 프롬프트)
|
|
- [파일:라인] -> 함수 -> 다음 호출
|
|
|
|
[회귀 위험 점검]
|
|
- ...
|
|
```
|
|
|
|
## 규칙
|
|
|
|
- 파일 이동/삭제가 있으면 영향 범위를 먼저 검증한다.
|
|
- 구조 개선은 하되 과도한 분리(쪼개기)는 피한다.
|
|
- 작은 UX 개선을 했으면 왜 개선했는지 한 줄 근거를 남긴다.
|