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