전체적인 리팩토링

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

@@ -96,12 +96,75 @@ description: 구현 완료 직후 가독성·데이터 흐름·성능을 다듬
 
 1. 주석 보강 작업은 코드 로직(타입/런타임/동작/변수명/import)을 바꾸지 않는다.
 2. 함수/API/쿼리 주석은 `[목적]`, `[사용처]`, `[데이터 흐름]` 중심으로 쉽게 쓴다.
-3. 상태(`useState`, `useRef`, store)는 "화면에 어떤 영향을 주는지" 한 줄 주석을 단다.
-4. 복잡한 로직/핸들러는 `1.`, `2.`, `3.` 단계 주석으로 흐름을 나눈다.
+3. 상태(`useState`, `useRef`, `useMemo`, store 파생 상태)는 반드시 `[State]`, `[Ref]` 형식으로 역할 주석을 단다.
+   - 예: `// [State] 자동매매 실행 중 여부 (배너/버튼 상태에 사용)`
+   - 예: `// [Ref] 마지막 신호 요청 시각 (요청 과다 방지용)`
+4. 복잡한 로직/핸들러는 반드시 `[Step 1]`, `[Step 2]`, `[Step 3]` 형식으로 흐름을 나눈다.
+   - 예: `// [Step 1] 입력값 유효성 검증`
 5. 긴 JSX는 화면 구역 주석으로 나눠서 읽기 쉽게 만든다.
-   - 예: `{/* ===== 1. 상단: 페이지 제목 및 액션 버튼 ===== */}`
-6. `@param`, `@see`, `@remarks` 같은 딱딱한 TSDoc 태그는 강제하지 않는다.
-7. 결과 기준은 "주니어가 5분 내 파악 가능한지"로 잡는다.
+   - 예: `{/* ========== 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/브랜드/문구 규칙
 
@@ -134,6 +197,10 @@ description: 구현 완료 직후 가독성·데이터 흐름·성능을 다듬
 [데이터 흐름 정리]
 - 어느 UI -> A 함수 호출 -> B 함수 호출 -> 리턴값 반영
 
+[핵심 입력 흐름 추적표]
+- 입력값: (예: 전략 프롬프트)
+- [파일:라인] -> 함수 -> 다음 호출
+
 [회귀 위험 점검]
 - ...
 ```