124 lines
5.6 KiB
Markdown
124 lines
5.6 KiB
Markdown
---
|
|
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는 문서 근거 없이 단정하지 않는다.
|
|
- 구현 단계에서 성능에 큰 악영향이 보이면 즉시 메모(기록)하고 다음 단계에서 정리한다.
|