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

name, description

name	description
dev-plan-writer	구현 전에 실행 가능한 계획 문서를 만드는 스킬. 기능 추가/버그 수정/구조 변경 요청에서 범위·영향·작업 순서·검증 기준을 먼저 고정할 때 사용하며, 실제 코드 대량 구현 단계에서는 단독 사용하지 않는다.

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 기준으로 전역 알림 시스템 유지 계획을 넣는다.

출력 템플릿

[계획 문서 경로]
- 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-..-..: ...

규칙

• 계획 승인 전에 실제 구현 코드를 대량 작성하지 않는다.
• 파일 삭제는 반드시 필요성/대체 경로를 확인한 뒤 진행한다.
• 동작 변경과 리팩토링을 섞지 않는다.