auto-trade/.agents/skills/dev-refactor-polish/SKILL.md

---
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 개선을 했으면 왜 개선했는지 한 줄 근거를 남긴다.