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