# Dev Workflow

> 새 기능 개발을 시작하거나 기획/설계, 상세개발계획, 구현/테스트, 최종리뷰 단계를 진행할 때 사용한다. 브랜치 생성 규칙, 설계·계획 문서의 저장 경로와 명명 규칙, 단계별 스킬·모델 규칙을 정의한다.

- Skill: `youngju-heo/dev-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add youngju-heo/dev-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/youngju-heo/dev-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Youngju-Heo (https://skillmd.com/u/youngju-heo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/youngju-heo/dev-workflow

---


# 기능 개발 워크플로

모든 개발은 **기획/설계 → 상세계획 → 구현/테스트 → 최종리뷰** 순서로 진행한다.

## 단계별 스킬·모델 규칙

| 단계         | 스킬                                                                         | 모델   |
| ------------ | ---------------------------------------------------------------------------- | ------ |
| 기획/설계    | superpowers/brainstorming                                                    | Opus   |
| 상세개발계획 | superpowers/writing-plans                                                    | Opus   |
| 구현/테스트  | superpowers/subagent-driven-development, superpowers/test-driven-development | Sonnet |
| 최종리뷰     | superpowers/requesting-code-review                                           | Opus   |

- SDD 진행 중 태스크별 리뷰는 구현 단계에 속하므로 Sonnet 5로 진행한다.
- 최종리뷰는 전체 브랜치를 **1회만** 리뷰한다. 추가 리뷰 라운드나 재검증 패스를 스스로 만들지 마라.
- 리뷰에서는 발견한 이슈를 심각도와 무관하게 모두 보고하라.
- 최종리뷰에는 산출물이 「원 요청」 인용문에 답하는지를 계획 준수
  여부와 독립된 별도 항목으로 포함하라. 예/아니오 체크가 아니라
  **어떻게 답하는지를 서술**한 뒤 판정하라.
- 실행 시 현재 기본 모델과 다를 시: 상세개발계획·최종리뷰는 해당 모델의 서브에이전트로 위임하고, 기획/설계(대화형)는 사용자에게 `/model` 전환을 요청한다.
- 위 단계에 정의된 것 외의 서브에이전트는 만들지 마라.

## 단계 전환 규칙

- 기획/설계와 상세계획 단계가 끝나면 산출물(설계 문서, 계획 문서)을
  요약해 보고하고 사용자 컨펌을 받은 뒤에만 다음 단계로 진행하라.
  컨펌 없이 다음 단계를 시작하지 마라. 수정 요청이 있으면 반영 후
  다시 컨펌을 받아라.
- 컨펌 보고에는 「원 요청」 인용과, 산출물이 그 요청에 어떻게 답하는지를
  함께 제시하라. 사용자가 승인하는 대상은 산출물 자체가 아니라 "원
  요청에 대한 이 답"이다.
- 구현/테스트가 끝나면 컨펌 없이 바로 최종리뷰로 진행하라.
- 최종리뷰가 끝나면 구현 결과와 리뷰에서 발견된 이슈를 함께 보고하고
  사용자 컨펌을 받아라. 이 컨펌이 머지·이슈 수정 여부의 결정이다.

## 경량 경로

아래 두 조건을 **모두** 만족하면 4단계 대신 경량 경로를 쓴다.

- 설계 결정이 없다 — 어떻게 고칠지가 자명하고 선택지가 하나뿐이다.
- 변경이 한 관심사에 국한된다 — 새 모듈·새 의존성·인터페이스 변경이 없다.

경량 경로:

1. 무엇을 왜 어떻게 고칠지 2~3줄로 보고하고 컨펌을 받아라.
2. 구현하라. 버그면 재현 테스트를 먼저 쓴다(TDD는 그대로 유지한다).
3. 변경 요약을 보고하라. 설계·계획 문서와 최종리뷰는 생략한다.

- 판단이 애매하면 전체 경로를 써라. 경량 경로는 예외이지 기본값이 아니다.
- 구현 중에 설계 결정이 필요해지면 즉시 멈추고 전체 경로로 전환하라.
- 브랜치·커밋 규칙은 경량 경로에도 그대로 적용된다.

## 브랜치·커밋 규칙

- 새 기획 시작 시 `{feature-name}` 기반으로 브랜치를 만들고 시작하라.
- 작업 단계별로 git에 커밋하여 이력을 저장하라.
- **커밋 메시지 형식**: `<type>: #<일감번호> <제목 (한글 가능)>` + 본문(선택)
  - type 예시: `feat`, `fix`, `refactor`, `chore`, `docs`
  - #<일감번호>: DevOps, Zira 등 형상관리 도구에 사용하는 번호가 있을 경우, 없으면 생략
- **`Co-Authored-By` 문구 사용 금지** — 커밋 메시지에 포함하지 않음

## 문서 규칙

- 기획/계획 작성 시 반드시 markdown 파일로 저장하라.
  - 설계: `docs/feature/yyyy-mm/yyyy-mm-dd-{day-sequence}-{feature-name}-design.md`
  - 계획: `docs/feature/yyyy-mm/yyyy-mm-dd-{day-sequence}-{feature-name}-plan.md`
  - `{day-sequence}`는 그날 순번 2자리, `01`부터. 계획은 해당 설계와 동일한 순번을 쓴다.
- 설계·계획 문서 맨 위에 「원 요청」 섹션을 두고 사용자의 요청을
  원문 그대로 인용하라(요약·의역 금지). 계획 문서는 설계 문서의
  인용을 그대로 옮긴다.
- 설계 문서에는 해당 기능의 주요 엔티티·모듈 네이밍 항목을 포함하라.
  구현은 이 네이밍을 따른다. (코드 네이밍 상세 규칙은 `.claude/rules/`의
  언어별 규칙을 따르라.)
- 문서는 결정 사항과 그 근거 중심으로 필요한 내용만 담아라. 상투적 요약,
  채우기 섹션, 중복 설명으로 분량을 늘리지 마라.
- 모든 문서는 한국어로 작성하라.