스킬 정리 및 리팩토링

.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-..-..: ...
+```
+
+## 규칙
+
+- 계획 승인 전에 실제 구현 코드를 대량 작성하지 않는다.
+- 파일 삭제는 반드시 필요성/대체 경로를 확인한 뒤 진행한다.
+- 동작 변경과 리팩토링을 섞지 않는다.