스킬 정리 및 리팩토링

.agents/skills/dev-auto-pipeline/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: dev-auto-pipeline
+description: 기능 개발/버그 수정/리팩토링 같은 구현 요청에서 계획→구현→리팩토링→테스트→완료체크를 순서대로 실행하는 상위 오케스트레이션 스킬. 단순 설명/문서 요약/잡담에는 사용하지 않는다.
+---
+
+# Dev Auto Pipeline
+
+## 목표
+
+- 개발 요청을 표준 5단계로 자동 처리한다.
+- 각 단계 결과를 다음 단계 입력으로 넘겨 누락을 줄인다.
+
+## 실행 단계 (고정)
+
+1. `dev-plan-writer`
+2. `dev-mcp-implementation`
+3. `dev-refactor-polish`
+4. `dev-test-gate`
+5. `dev-plan-completion-checker`
+
+## 단계 연결 규칙
+
+1. 계획 단계에서 생성한 계획 문서(`common-docs/improvement/plans/*.md`)를 이후 단계의 기준 문서로 사용한다.
+2. 구현/리팩토링에서 변경된 파일 목록을 테스트 단계 입력으로 전달한다.
+3. 테스트 결과를 완료체크 단계 입력으로 전달한다.
+4. 완료체크는 계획 대비 `완료/부분 완료/미완료`와 최종 판정을 반드시 남긴다.
+
+## common-docs 기준
+
+- 사용 문서:
+  - `common-docs/api-reference/openapi_all.xlsx`
+  - `common-docs/api-reference/kis_api_reference.md`
+  - `common-docs/api-reference/kis-error-code-reference.md`
+  - `common-docs/features/trade-stock-sync.md`
+  - `common-docs/ui/GLOBAL_ALERT_SYSTEM.md`
+- 제외 문서:
+  - `common-docs/features-autotrade-design.md`
+
+## 최종 보고 형식
+
+```md
+[1. 계획]
+- ...
+
+[2. 구현]
+- ...
+
+[3. 리팩토링/성능/가독성]
+- ...
+
+[4. 테스트]
+- ...
+
+[5. 계획 대비 완료체크]
+- 완료/부분 완료/미완료
+- 최종 판정: 배포 가능/보완 필요
+```

.agents/skills/dev-auto-pipeline/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Dev Auto Pipeline"
+  short_description: "Run end-to-end development pipeline"
+  default_prompt: "Use $dev-auto-pipeline to execute plan, implement, refactor, test, and completion checks."
+policy:
+  allow_implicit_invocation: true

.agents/skills/dev-mcp-implementation/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: dev-mcp-implementation
+description: 구현 단계에서 MCP와 기존 스킬을 활용해 근거 기반으로 코드를 작성하는 스킬. 계획 문서가 확정된 뒤 실제 코드 변경이 필요할 때 사용하며, 단순 계획 작성/완료 판정 단계에는 사용하지 않는다.
+---
+
+# Dev MCP Implementation
+
+## 목표
+
+- 추측 구현을 줄이고 공식 문서/런타임 진단 기반으로 구현한다.
+- 구현 결과를 나중에 리팩토링/테스트 단계로 넘기기 쉬운 형태로 만든다.
+
+## 기본 구현 원칙 (AGENTS 반영)
+
+1. 모든 코드/주석/설명은 한국어 기준으로 작성한다.
+2. 기술 스택 기준을 지킨다.
+   - Next.js 16 App Router, React 19, TypeScript
+   - Zustand(클라이언트 UI 상태), Supabase, react-hook-form + zod
+   - Tailwind CSS v4, Radix UI
+3. 사이드이펙트가 예상되면 영향 범위를 먼저 확인하고 구현한다.
+4. 불필요한 삭제는 하지 않는다. 삭제가 필요하면 영향 검증 후 진행한다.
+
+## 구현 순서
+
+1. `dev-plan-writer` 결과를 읽고 구현 범위를 고정한다.
+2. Next.js 프로젝트면 `next-devtools`로 현재 라우트/에러 상태를 먼저 확인한다.
+3. 외부 라이브러리 API가 모호하면 `context7`로 공식 문서를 확인한다.
+4. 복잡한 로직은 `sequential-thinking`으로 엣지 케이스(경계 상황)를 먼저 정리한다.
+5. DB/권한/SQL 변경은 `supabase-mcp-server`로 안전하게 반영한다.
+6. 코드 수정 후 최소 동작 확인(`lint`/핵심 UI 실행)을 진행한다.
+
+## 리팩토링 구현 규칙 (refactoring-rule 반영)
+
+1. 리팩토링 요청이면 `FEATURE_ROOT` 기준으로 작업한다.
+2. 아래 기본 구조를 우선 사용한다.
+   - `apis`, `components`, `hooks`, `stores`, `types`
+3. 필요 시 선택 구조를 사용한다.
+   - `utils`, `lib`, `constants`
+4. 대형 파일은 책임 단위로 분해하고, 로직은 보존한다.
+5. `index.ts` 배럴 export 의존을 줄이고 직접 경로 import로 전환한다.
+6. 파일 이동 후 외부 진입점(`page.tsx` 등) import까지 함께 갱신한다.
+
+## 필수 적용 스킬
+
+- `nextjs-app-router-patterns`: Server/Client 경계 검증
+- `vercel-react-best-practices`: 렌더링/번들/데이터 요청 최적화
+
+## MCP 활용 맵 (AGENTS 반영)
+
+- `next-devtools`: Next.js 라우트/컴파일/런타임 오류 점검
+- `playwright`: 브라우저 상호작용/스모크 검증
+- `playwriter`: Chrome 확장 기반 상세 디버깅
+- `context7`: 라이브러리/프레임워크 공식 문서 조회
+- `supabase-mcp-server`: DB/SQL/함수 작업
+- `tavily-remote`: 최신 자료/기술 검색
+- `sequential-thinking`: 복잡 로직 단계화
+- `figma`: 디자인 파일 레이아웃/스타일/에셋 확인
+- `mcp:kis-code-assistant-mcp`: 한국투자증권 API 검색/소스 확인
+
+## 코드/주석 규칙 (문서화 전문가 기준)
+
+1. 주석 보강 작업은 코드 로직(타입/런타임/동작/변수명/import)을 바꾸지 않는다.
+2. 주석은 쉬운 한글로 작성하고 "사용처"와 "데이터 흐름"을 먼저 보이게 쓴다.
+3. 함수/API/Query 주석은 아래 3가지를 중심으로 작성한다.
+   - `[목적]`
+   - `[사용처]`
+   - `[데이터 흐름]`
+4. 상태(`useState`, `useRef`, store)에는 "값이 바뀌면 화면이 어떻게 변하는지" 한 줄 주석을 단다.
+5. 복잡한 로직/이벤트 핸들러는 `1, 2, 3...` 단계 주석으로 흐름을 나눈다.
+6. 긴 JSX는 화면 구역별 주석으로 시각적으로 분리한다.
+   - 예: `{/* ===== 1. 상단: 제목/액션 ===== */}`
+7. `@param`, `@see`, `@remarks` 같은 딱딱한 TSDoc 태그는 강제하지 않는다.
+
+## UI/브랜드/문구 규칙
+
+1. 새 UI는 `indigo/purple/pink` 하드코딩 대신 `brand-*` 토큰을 사용한다.
+2. 기본 액션 색은 `primary`를 우선한다.
+3. 색상 톤 변경은 컴포넌트 개별 수정보다 `app/globals.css` 토큰 조정을 우선 검토한다.
+4. 사용자 문구는 불안을 줄이고 확신을 주는 친근한 톤을 사용한다.
+
+## common-docs 구현 규칙
+
+1. KIS API 구현 기준:
+   - `openapi_all.xlsx`를 1순위 스펙으로 본다.
+   - 문서 확인 순서: `openapi_all.xlsx` -> `mcp:kis-code-assistant-mcp` -> `.tmp/open-trading-api` -> `kis_api_reference.md`
+   - 차이가 크면 사용자에게 최신 파일 재확인을 요청한다.
+2. 에러코드 처리 기준:
+   - `kis-error-code-reference.md`를 따라 `msg_cd + 문구` 형태를 유지한다.
+   - `lib/kis/error-codes.ts`의 `buildKisErrorDetail`/`getKisErrorGuide` 사용 패턴을 유지한다.
+3. 종목 마스터 데이터 기준:
+   - `features/trade/data/korean-stocks.json`은 수동 편집하지 않는다.
+   - `trade-stock-sync.md` 기준으로 `npm run sync:stocks` / `npm run sync:stocks:check`를 사용한다.
+4. 전역 알림 UI 기준:
+   - `GLOBAL_ALERT_SYSTEM.md` 기준으로 `useGlobalAlert` 패턴을 우선 사용한다.
+   - 로컬 임시 Alert/Confirm 구현보다 전역 시스템(`GlobalAlertModal`) 연동을 우선한다.
+5. 제외 문서:
+   - `features-autotrade-design.md`는 현 구현 기준에서 제외한다.
+
+## 출력 템플릿
+
+```md
+[구현 결과]
+- ...
+
+[사용한 MCP/Skills]
+- MCP: ...
+- Skills: ...
+
+[변경 파일]
+- ...
+
+[핵심 데이터 흐름]
+- 어느 UI -> A 함수 호출 -> B 함수 호출 -> 리턴값 반영
+
+[남은 이슈]
+- ...
+```
+
+## 규칙
+
+- 필요 없는 파일/코드는 남기지 않는다.
+- 불확실한 라이브러리 API는 문서 근거 없이 단정하지 않는다.
+- 구현 단계에서 성능에 큰 악영향이 보이면 즉시 메모(기록)하고 다음 단계에서 정리한다.

.agents/skills/dev-mcp-implementation/agents/openai.yaml

@@ -0,0 +1,23 @@
+interface:
+  display_name: "Dev MCP Implementation"
+  short_description: "Implement features with MCP workflows"
+  default_prompt: "Use $dev-mcp-implementation to build code using MCP-first verification."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "next-devtools"
+      description: "Next.js route and runtime diagnostics"
+    - type: "mcp"
+      value: "context7"
+      description: "Official framework and library docs"
+    - type: "mcp"
+      value: "supabase-mcp-server"
+      description: "Supabase SQL and function operations"
+    - type: "mcp"
+      value: "playwright"
+      description: "Browser smoke verification"
+    - type: "mcp"
+      value: "kis-code-assistant-mcp"
+      description: "KIS API lookup and source references"
+policy:
+  allow_implicit_invocation: false

.agents/skills/dev-plan-completion-checker/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: dev-plan-completion-checker
+description: 구현 완료 후 계획 문서와 실제 변경·테스트 근거를 대조해 완료 상태를 판정하는 스킬. 최종 점검 단계에서 사용하며, 계획 작성/구현/테스트 실행 단계를 대신하지 않는다.
+---
+
+# Dev Plan Completion Checker
+
+## 목표
+
+- 계획대로 구현이 수행됐는지 객관적으로 확인한다.
+- 누락/부분 완료 항목을 마지막에 명확히 남긴다.
+
+## 입력
+
+1. 계획 문서 경로 (`common-docs/improvement/plans/*.md`)
+2. 변경 파일 목록
+3. 테스트 결과 (`lint`, `build`, `playwright smoke`, 추가 검증)
+
+## 작업 순서
+
+1. 계획 문서의 체크 항목을 읽는다.
+   - 구현 단계 체크박스
+   - 검증 계획 체크박스
+2. 변경 파일/테스트 결과를 근거로 각 항목 상태를 판정한다.
+   - 완료: 근거가 충분함
+   - 부분 완료: 일부 근거만 있음
+   - 미완료: 근거가 없음
+3. 누락 항목에 대해 바로 실행 가능한 후속 작업을 작성한다.
+4. 최종 완료 판정(`배포 가능` / `보완 필요`)을 내린다.
+
+## 판정 규칙
+
+1. 구현 단계에 미완료가 1개 이상이면 `보완 필요`
+2. 검증 계획에 미완료가 있으면 `보완 필요`
+3. 테스트 생략 항목은 사유와 대체 검증이 있으면 `부분 완료`로 인정 가능
+
+## 출력 템플릿
+
+```md
+[계획 문서]
+- 경로: ...
+
+[완료 체크 결과]
+- 완료: ...
+- 부분 완료: ...
+- 미완료: ...
+
+[근거]
+- 변경 파일: ...
+- 테스트 결과: ...
+
+[보완 필요 항목]
+1. ...
+2. ...
+
+[최종 판정]
+- 배포 가능/보완 필요
+```

.agents/skills/dev-plan-completion-checker/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Dev Completion Checker"
+  short_description: "Check plan completion against evidence"
+  default_prompt: "Use $dev-plan-completion-checker to compare plan checklists with changed files and test results."
+policy:
+  allow_implicit_invocation: false

.agents/skills/dev-plan-writer/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: dev-plan-writer
+description: 구현 전에 실행 가능한 계획 문서를 만드는 스킬. 기능 추가/버그 수정/구조 변경 요청에서 범위·영향·작업 순서·검증 기준을 먼저 고정할 때 사용하며, 실제 코드 대량 구현 단계에서는 단독 사용하지 않는다.
+---
+
+# Dev Plan Writer
+
+## 목표
+
+- 구현 전에 계획부터 확정하여 누락(빠뜨림)을 줄인다.
+- 주니어 개발자도 바로 따라갈 수 있게 단계를 단순하게 작성한다.
+
+## 언어/소통 규칙
+
+1. 모든 계획과 설명을 한국어로 작성한다.
+2. 어려운 용어는 짧은 괄호 설명을 붙인다.
+3. 요청이 모호하면 질문 1~3개로 범위를 먼저 고정한다.
+
+## 프로젝트 기본 컨텍스트
+
+- 기술 스택: Next.js 16 App Router, React 19, TypeScript, Zustand, Supabase, react-hook-form, zod, Tailwind CSS v4, Radix UI
+- 기본 명령어: `npm run dev`(포트 3001), `npm run lint`, `npm run build`, `npm run start`
+
+## 안전 계획 규칙
+
+1. 수정/추가/삭제 파일을 분리해서 영향 범위를 먼저 적는다.
+2. 삭제/이동/계약 변경(입출력 규칙 변경)은 사전 확인 질문을 남긴다.
+3. "진짜 필요 없는 코드만 제거" 원칙으로 계획을 세운다.
+4. 사이드이펙트(옆 영향) 가능성이 있으면 검증 단계를 계획에 반드시 넣는다.
+
+## 작업 순서
+
+1. 요구사항을 3줄 이내로 요약한다.
+2. 모호한 부분이 있으면 질문 1~3개로 범위를 먼저 고정한다.
+3. 영향 파일(수정/추가/삭제)을 먼저 찾고, 사이드이펙트(옆 영향)를 표시한다.
+4. 사용할 MCP/Skills를 단계별로 고른다.
+5. 구현 단계를 순서대로 작성한다.
+6. 검증 단계를 구현 단계와 1:1로 매핑한다.
+
+## 계획 문서 저장 규칙 (필수)
+
+1. 저장 위치: `common-docs/improvement/plans/`
+2. 파일명 규칙: `dev-plan-YYYY-MM-DD-<작업슬러그>.md`
+   - 예: `dev-plan-2026-02-25-order-validation.md`
+3. 하나의 개발 요청은 하나의 계획 파일을 기준으로 끝까지 추적한다.
+4. 구현이 시작되면 같은 파일에 진행/완료 상태를 계속 갱신한다.
+
+## 계획 상태 관리 규칙
+
+1. 구현 단계/검증 계획을 체크박스 형식으로 작성한다.
+2. 각 체크 항목 옆에 근거(변경 파일, 테스트 결과)를 짧게 남긴다.
+3. 완료 판단은 마지막에 `dev-plan-completion-checker`가 수행한다.
+
+## 리팩토링 요청 전용 계획 규칙 (refactoring-rule 반영)
+
+1. 입력값으로 `FEATURE_ROOT`를 명시한다.
+2. 목표에 아래 4가지를 반드시 넣는다.
+   - 표준 폴더 구조(`apis/components/hooks/stores/types`)
+   - 선택 폴더 허용(`utils/lib/constants`)
+   - 대형 파일 분해
+   - 배럴 파일 제거 및 직접 import
+3. 작업 지시는 6단계로 고정해 계획한다.
+   - 분석 -> 구조 설계 -> 이동/생성 -> 경로 수정 -> 청소 -> 진입점 갱신
+4. 계획 문서에 "권장 파일 구조 트리"를 포함한다.
+
+## 도구 선택 기준
+
+- Next.js 런타임/라우트 점검: `next-devtools`
+- 라이브러리 공식 문서 확인: `context7`
+- 복잡 로직 분해: `sequential-thinking`
+- Supabase SQL/함수 작업: `supabase-mcp-server`
+- 브라우저 동작 검증: `playwright`
+- Chrome 확장 기반 디버깅: `playwriter`
+- 최신 기술/레퍼런스 검색: `tavily-remote`
+- Figma 레이아웃/스타일 확인: `figma`
+
+## common-docs 계획 반영 규칙
+
+1. `common-docs` 기준 문서를 계획 단계에서 먼저 지정한다.
+   - `common-docs/api-reference/openapi_all.xlsx`
+   - `common-docs/api-reference/kis_api_reference.md`
+   - `common-docs/api-reference/kis-error-code-reference.md`
+   - `common-docs/features/trade-stock-sync.md`
+   - `common-docs/ui/GLOBAL_ALERT_SYSTEM.md`
+2. 아래 문서는 계획에서 제외한다.
+   - `common-docs/features-autotrade-design.md` (향후 기획 문서)
+3. KIS 연동 작업이면 스펙 확인 순서를 계획에 명시한다.
+   - `openapi_all.xlsx` -> `mcp:kis-code-assistant-mcp` -> `.tmp/open-trading-api` -> `kis_api_reference.md`
+4. 종목 코드/마스터 데이터 변경이면 `trade-stock-sync.md` 기준으로 자동 동기화 명령을 계획에 넣는다.
+5. 사용자 알림/확인 모달 변경이면 `GLOBAL_ALERT_SYSTEM.md` 기준으로 전역 알림 시스템 유지 계획을 넣는다.
+
+## 출력 템플릿
+
+```md
+[계획 문서 경로]
+- common-docs/improvement/plans/dev-plan-YYYY-MM-DD-<작업슬러그>.md
+
+[요구사항 요약]
+- ...
+
+[확인 질문(필요 시 1~3개)]
+- ...
+
+[가정]
+- ...
+
+[영향 범위]
+- 수정: ...
+- 추가: ...
+- 삭제: ...
+
+[구현 단계]
+- [ ] 1. ...
+- [ ] 2. ...
+- [ ] 3. ...
+
+[사용할 MCP/Skills]
+- MCP: ...
+- Skills: ...
+
+[참조 문서(common-docs)]
+- ...
+
+[주석/문서 반영 계획]
+- 함수 주석: [목적]/[사용처]/[데이터 흐름]
+- 상태 주석: 값 변경 시 화면 영향 한 줄 설명
+- 복잡 로직/핸들러: 1, 2, 3 단계 주석
+- JSX 구역 주석: 화면 구조가 보이게 분리
+- TSDoc 딱딱한 태그(`@param`, `@see`, `@remarks`) 강제 없음
+
+[리팩토링 구조 계획(리팩토링 요청 시)]
+- FEATURE_ROOT: ...
+- 목표(표준 구조/선택 구조/대형파일 분해/배럴 제거): ...
+- Workflow 6단계: ...
+- 권장 구조 트리: ...
+
+[리스크/회귀 포인트]
+- ...
+
+[검증 계획]
+- [ ] 1. ...
+- [ ] 2. ...
+- [ ] 3. ...
+
+[진행 로그]
+- 2026-..-..: ...
+```
+
+## 규칙
+
+- 계획 승인 전에 실제 구현 코드를 대량 작성하지 않는다.
+- 파일 삭제는 반드시 필요성/대체 경로를 확인한 뒤 진행한다.
+- 동작 변경과 리팩토링을 섞지 않는다.

.agents/skills/dev-plan-writer/agents/openai.yaml

@@ -0,0 +1,17 @@
+interface:
+  display_name: "Dev Plan Writer"
+  short_description: "Write implementation plans with checks"
+  default_prompt: "Use $dev-plan-writer to create a tracked implementation plan file."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "next-devtools"
+      description: "Next.js runtime and route diagnostics"
+    - type: "mcp"
+      value: "context7"
+      description: "Official library documentation lookup"
+    - type: "mcp"
+      value: "sequential-thinking"
+      description: "Step-by-step reasoning for complex planning"
+policy:
+  allow_implicit_invocation: false

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

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

.agents/skills/dev-refactor-polish/agents/openai.yaml

@@ -0,0 +1,14 @@
+interface:
+  display_name: "Dev Refactor Polish"
+  short_description: "Refactor code for readability and performance"
+  default_prompt: "Use $dev-refactor-polish to improve readability, data flow, and small UX polish."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "context7"
+      description: "Official docs for framework-safe refactors"
+    - type: "mcp"
+      value: "sequential-thinking"
+      description: "Dependency impact reasoning before file moves"
+policy:
+  allow_implicit_invocation: false

.agents/skills/dev-test-gate/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: dev-test-gate
+description: 개발/리팩토링 후 lint·build·Playwright 스모크 테스트를 실행하고 실패 원인을 정리하는 검증 스킬. 최종 품질 게이트 단계에서 사용하며, 구현 자체를 대체하지 않는다.
+---
+
+# Dev Test Gate
+
+## 목표
+
+- 변경 사항의 안정성을 빠르게 확인한다.
+- 실패 원인과 영향 범위를 짧고 명확하게 남긴다.
+
+## 공통 기준
+
+1. 결과 보고는 한국어로 작성한다.
+2. 테스트 결과는 주니어도 이해 가능하게 쉬운 말로 정리한다.
+3. 테스트 생략은 원칙적으로 금지하고, 불가한 경우 사유와 대체 검증을 남긴다.
+
+## 테스트 순서
+
+1. 정적 검사: `npm run lint`
+2. 빌드 검사: `npm run build`
+3. 개발 서버 실행: `npm run dev` (기본 포트 3001)
+4. 런타임 확인: 핵심 화면 로드와 기본 동작 확인
+5. Playwright 스모크 테스트(기본): 핵심 화면 간단 확인을 반드시 수행
+6. 사용자 요청 테스트가 있으면 해당 테스트를 추가 실행한다.
+
+## Playwright 스모크 기본 규칙
+
+1. 핵심 화면 3종을 기본 대상으로 잡는다.
+2. 화면 타입은 아래 기준으로 고른다.
+   - 서비스 진입 화면 1개
+   - 핵심 기능 화면 1개
+   - 설정/인증 관련 화면 1개
+3. 각 화면에서 최소 항목을 확인한다.
+   - 페이지 로드 성공
+   - 치명 오류 문구/콘솔 에러 없음
+   - 핵심 버튼 또는 입력 요소 1개 이상 상호작용 가능
+
+## 검증 보강 규칙
+
+1. UI 변경이 있으면 브랜드 토큰(`brand-*`, `primary`) 적용 여부를 함께 점검한다.
+2. KIS API 연동 변경이 있으면 계좌/인증/오류 처리 기본 시나리오를 스모크 범위에 포함한다.
+3. 리팩토링 요청이면 구조 점검을 추가한다.
+   - `FEATURE_ROOT`가 목표 구조(`apis/components/hooks/stores/types`)를 따르는지 확인
+   - 파일 이동 후 진입점 import 경로가 깨지지 않았는지 확인
+   - 불필요한 `index.ts` 배럴 파일 잔존 여부를 확인
+
+## common-docs 연계 검증 규칙
+
+1. KIS 연동 파일 변경 시 아래를 점검한다.
+   - `kis_api_reference.md` 기준 엔드포인트/흐름이 크게 어긋나지 않는지 확인
+   - `kis-error-code-reference.md` 기준 `msg_cd + 문구` 표시 흐름 유지 확인
+2. `features/trade/data/korean-stocks.json` 또는 동기화 스크립트 변경 시
+   - `npm run sync:stocks:check`를 추가 실행한다.
+3. 전역 알림 관련 파일(`features/layout/hooks/use-global-alert.ts`, `GlobalAlertModal`) 변경 시
+   - 핵심 시나리오(성공 알림 1건, 확인 모달 1건)를 스모크 검증에 포함한다.
+4. `features-autotrade-design.md`는 테스트 기준 문서에서 제외한다.
+
+## 실패 처리 규칙
+
+1. 실패 로그에서 직접 원인 라인을 먼저 찾는다.
+2. 원인 수정 후 같은 테스트를 재실행한다.
+3. 연쇄 실패(한 수정으로 여러 실패)가 있으면 우선순위를 나눠 정리한다.
+4. 시간/환경 제한으로 테스트를 못 돌리면 이유와 대체 검증을 반드시 기록한다.
+
+## 출력 템플릿
+
+```md
+[테스트 결과]
+- lint: 통과/실패
+- build: 통과/실패
+- playwright smoke: 통과/실패
+- common-docs 연계 검증: 통과/실패
+- 추가 테스트: ...
+
+[실패 및 조치]
+- ...
+
+[최종 상태]
+- 배포 가능/보류
+```
+
+## 완료체크 인계 규칙
+
+1. 테스트 결과는 `dev-plan-completion-checker`에 그대로 전달한다.
+2. 전달 형식은 아래 4줄을 포함한다.
+   - lint 결과
+   - build 결과
+   - playwright smoke 결과
+   - 생략/실패 사유 및 대체 검증

.agents/skills/dev-test-gate/agents/openai.yaml

@@ -0,0 +1,14 @@
+interface:
+  display_name: "Dev Test Gate"
+  short_description: "Run lint, build, and Playwright smoke tests"
+  default_prompt: "Use $dev-test-gate to run lint, build, and smoke verification before completion."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "playwright"
+      description: "Browser smoke test automation"
+    - type: "mcp"
+      value: "next-devtools"
+      description: "Next.js runtime error and route checks"
+policy:
+  allow_implicit_invocation: false

.agents/skills/nextjs-app-router-patterns/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: nextjs-app-router-patterns
+description: Best practices and patterns for building applications with Next.js App Router (v13+).
+---
+
+# Next.js App Router Patterns
+
+## Core Principles
+
+### Server-First by Default
+
+- **Use Server Components** for everything possible (data fetching, layout, static content).
+- **Use Client Components** (`"use client"`) only when interactivity (hooks, event listeners) is needed.
+- **Pass Data Down**: Fetch data in Server Components and pass it as props to Client Components.
+- **Composition**: Wrap Client Components around Server Components to avoid "rendering undefined" issues or waterfall de-opts.
+
+### Routing & Layouts
+
+- **File Structure**:
+  - `page.tsx`: Route UI.
+  - `layout.tsx`: Shared UI (wraps pages).
+  - `loading.tsx`: Loading state (Suspense).
+  - `error.tsx`: Error boundary.
+  - `not-found.tsx`: 404 UI.
+  - `template.tsx`: Layout that re-mounts on navigation.
+- **Parallel Routes**: Use `@folder` for parallel UI (e.g. dashboards).
+- **Intercepting Routes**: Use `(..)` to intercept navigation (e.g. modals).
+- **Route Groups**: Use `(group)` to organize routes without affecting the URL path.
+
+## Data Fetching Patterns
+
+### Server Side
+
+- **Direct Async/Await**: `const data = await fetch(...)` inside the component.
+- **Request Memoization**: `fetch` is automatically memoized. For DB calls, use `React.cache`.
+- **Data Caching**:
+  - `fetch(url, { next: { revalidate: 3600 } })` for ISR.
+  - `fetch(url, { cache: 'no-store' })` for SSR.
+  - Use `unstable_cache` for caching DB results.
+
+### Client Side
+
+- Use **SWR** or **TanStack Query** for client-side fetching.
+- Avoid `useEffect` for data fetching to prevent waterfalls.
+- Prefetch data using `queryClient.prefetchQuery` in Server Components and hydrate on client.
+
+## Server Actions
+
+- Use **Server Actions** (`"use server"`) for mutations (form submissions, button clicks).
+- Define actions in separate files (e.g. `actions.ts`) for better organization and security.
+- Use `useFormState` (or `useActionState` in React 19) to handle loading/error states.
+
+## Optimization
+
+- **Images**: Use `next/image` for automatic resizing and format conversion.
+- **Fonts**: Use `next/font` to eliminate layout shift (CLS).
+- **Scripts**: Use `next/script` with `strategy="afterInteractive"`.
+- **Streaming**: Use `<Suspense>` to stream parts of the UI (e.g. slow data fetches).
+
+## Common Anti-Patterns to Avoid
+
+1. **Fetching in Client Components without cache lib**: Leads to waterfalls.
+2. **"use client" at top level layout**: Forces the entire tree to be client-side.
+3. **Prop Drilling**: specialized `Context` should be used sparingly; prefer Composition.
+4. **Large Barrel Files**: Avoid `index.ts` exporting everything; import directly to aid tree-shaking.

.agents/skills/nextjs-app-router-patterns/agents/openai.yaml

@@ -0,0 +1,14 @@
+interface:
+  display_name: "Next.js App Router Patterns"
+  short_description: "Next.js App Router patterns and checks"
+  default_prompt: "Use $nextjs-app-router-patterns to review App Router structure, server/client boundaries, and data fetching patterns."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "next-devtools"
+      description: "Next.js runtime route and error diagnostics"
+    - type: "mcp"
+      value: "context7"
+      description: "Official Next.js documentation lookup"
+policy:
+  allow_implicit_invocation: false