@sduck/sduck-cli 0.1.2 → 0.1.3

package/.sduck/sduck-assets/types/feature.md

@@ -0,0 +1,187 @@
+# [feature] {기능명}
+
+> **작업 타입:** `feature` (Standard Feature)
+> **작성자:**
+> **작성일:** YYYY-MM-DD
+> **연관 티켓:**
+
+---
+
+## 1. 배경 및 목적
+
+### 문제 / 요구사항
+
+<!-- 이 기능이 왜 필요한지, 어떤 사용자 문제 혹은 비즈니스 요구를 해결하는지 기술 -->
+
+### 기대 효과
+
+<!-- 이 기능이 완성되었을 때 사용자 또는 시스템 관점에서 달라지는 점 -->
+
+---
+
+## 2. 기능 명세
+
+### 사용자 스토리
+
+```
+As a [사용자 유형],
+I want to [원하는 행동],
+So that [기대하는 결과].
+```
+
+### 수용 기준 (Acceptance Criteria)
+
+> 모든 항목이 충족되어야 이 작업이 완료(Done)로 간주된다.
+
+- [ ] AC1:
+- [ ] AC2:
+- [ ] AC3:
+
+### 기능 상세 설명
+
+<!-- 핵심 비즈니스 로직, 상태 전이, 엣지 케이스 등을 상세하게 기술 -->
+
+---
+
+## 3. 기술 설계
+
+### 변경 대상 컴포넌트
+
+| 레이어 | 파일 / 모듈 | 변경 내용 요약 |
+| ------ | ----------- | -------------- |
+|        |             |                |
+|        |             |                |
+
+### API 명세 (해당 시)
+
+```
+Method: POST / GET / PUT / PATCH / DELETE
+Endpoint: /api/v1/...
+
+Request:
+{
+  "field": "type"
+}
+
+Response (200 OK):
+{
+  "field": "type"
+}
+
+Error Responses:
+- 400: 잘못된 요청
+- 401: 인증 실패
+- 404: 리소스 없음
+```
+
+### 데이터 모델 변경 (해당 시)
+
+```sql
+-- 추가 / 변경되는 컬럼, 테이블, 인덱스 등
+```
+
+### 시퀀스 다이어그램 (해당 시)
+
+```
+Client → [Service A] → [Service B] → DB
+              ↓
+           Response
+```
+
+---
+
+## 4. UI/UX 명세 (해당 시)
+
+### 화면 목록
+
+| 화면명 | 라우트 | 설명 |
+| ------ | ------ | ---- |
+|        |        |      |
+
+### 디자인 레퍼런스
+
+<!-- Figma 링크, 스크린샷, 기타 시각 자료 -->
+
+### 인터랙션 정의
+
+<!-- 버튼 클릭, 폼 유효성 검사, 로딩 상태, 에러 메시지 표시 방식 등 -->
+
+---
+
+## 5. 테스트 계획
+
+### 단위 테스트 (Unit Test)
+
+| 대상 함수 / 모듈 | 테스트 케이스 | 예상 결과 |
+| ---------------- | ------------- | --------- |
+|                  | 정상 입력     |           |
+|                  | 경계값        |           |
+|                  | 비정상 입력   |           |
+
+### 통합 / E2E 테스트
+
+| 시나리오 | 단계 | 예상 결과 |
+| -------- | ---- | --------- |
+|          |      |           |
+
+---
+
+## 6. 영향 범위 분석
+
+### 변경 파일 목록 (예상)
+
+```
+target_paths:
+  - src/...
+  - tests/...
+```
+
+### 사이드 이펙트 검토
+
+<!-- 이 기능 변경으로 인해 영향받을 수 있는 다른 기능이나 모듈 -->
+
+- 영향 가능성 있는 모듈:
+- 회귀 테스트 필요 영역:
+
+### 롤백 계획
+
+<!-- 문제 발생 시 어떻게 되돌릴 것인지 -->
+
+---
+
+## 7. 보안 / 성능 고려사항
+
+- **인증·인가:** (예: 이 API는 `ADMIN` 권한 필요)
+- **입력값 검증:**
+- **성능:** (예: N+1 쿼리 방지, 캐싱 적용 여부)
+- **민감 데이터 처리:**
+
+---
+
+## 8. 비기능 요구사항
+
+| 항목             | 요구사항 |
+| ---------------- | -------- |
+| 응답 시간        |          |
+| 동시 사용자      |          |
+| 데이터 보존 기간 |          |
+
+---
+
+## 9. 의존성 및 선행 조건
+
+- 이 작업 시작 전 완료되어야 하는 작업:
+- 외부 서비스 / API 연동 필요 여부:
+- 피처 플래그(Feature Flag) 사용 여부:
+
+---
+
+## 10. 미결 사항 (Open Questions)
+
+- [ ]
+
+---
+
+## 11. 참고 자료
+
+-

package/.sduck/sduck-assets/types/fix.md

@@ -0,0 +1,174 @@
+# [fix] {버그 요약 한 줄}
+
+> **작업 타입:** `fix` (Quick Fix)
+> **심각도:** `critical` / `high` / `medium` / `low`
+> **작성자:**
+> **작성일:** YYYY-MM-DD
+> **연관 티켓:**
+
+---
+
+## 1. 버그 개요
+
+### 문제 요약
+
+<!-- 한두 문장으로 버그의 핵심을 요약 -->
+
+### 발견 경위
+
+- [ ] 사용자 제보
+- [ ] 모니터링 알림
+- [ ] 코드 리뷰 중 발견
+- [ ] QA 테스트
+- [ ] 기타:
+
+### 발생 빈도
+
+- [ ] 항상 재현됨 (100%)
+- [ ] 간헐적 재현 (약 %)
+- [ ] 특정 조건에서만 재현
+
+---
+
+## 2. 재현 방법 (Steps to Reproduce)
+
+**환경 정보**
+| 항목 | 내용 |
+|------|------|
+| 환경 (local / dev / staging / production) | |
+| OS / 브라우저 / 앱 버전 | |
+| 계정 유형 / 권한 | |
+| 관련 데이터 ID / 조건 | |
+
+**재현 단계**
+
+1.
+2.
+3.
+
+**실제 결과 (Actual)**
+
+<!-- 무슨 일이 일어났는지 -->
+
+**기대 결과 (Expected)**
+
+<!-- 원래 어떻게 동작해야 하는지 -->
+
+---
+
+## 3. 원인 분석 (Root Cause)
+
+### 원인 파악 현황
+
+- [ ] 원인 특정 완료
+- [ ] 원인 조사 중
+- [ ] 원인 불명
+
+### 원인 요약
+
+<!-- 코드 레벨에서 왜 이 버그가 발생하는지 기술 -->
+
+### 원인 코드 위치
+
+```
+파일: src/...
+함수 / 라인:
+```
+
+### 발생 조건
+
+<!-- 특정 값, 상태, 순서 등 버그를 트리거하는 조건 -->
+
+---
+
+## 4. 수정 방안
+
+### 방안 검토
+
+| 방안   | 설명 | 장점 | 단점 |
+| ------ | ---- | ---- | ---- |
+| 방안 A |      |      |      |
+| 방안 B |      |      |      |
+
+### 선택한 방안 및 이유
+
+> **선택:** 방안 \_
+>
+> **이유:**
+
+### 변경 파일 목록 (예상)
+
+```
+target_paths:
+  - src/...
+  - tests/...
+```
+
+---
+
+## 5. 테스트 계획
+
+### 버그 재현 테스트 (수정 전 실패 확인)
+
+- [ ] 기존 버그 재현 테스트 케이스 작성 완료
+
+### 수정 검증 테스트 (수정 후 통과 확인)
+
+| 테스트 케이스 | 조건           | 예상 결과      |
+| ------------- | -------------- | -------------- |
+|               | 버그 유발 조건 | 정상 동작      |
+|               | 정상 입력      | 기존 동작 유지 |
+|               | 경계값         |                |
+
+### 회귀 테스트
+
+<!-- 이 수정으로 인해 영향받을 수 있는 관련 기능의 테스트 목록 -->
+
+- [ ]
+- [ ]
+
+---
+
+## 6. 영향 범위
+
+### 사이드 이펙트 검토
+
+<!-- 이 수정이 다른 기능에 미칠 수 있는 영향 -->
+
+### 데이터 정합성
+
+- [ ] DB 데이터 정정 작업 필요 없음
+- [ ] DB 데이터 정정 작업 필요: _(내용 작성)_
+
+---
+
+## 7. 롤백 계획
+
+<!-- 수정 후에도 문제가 지속되거나 새로운 문제 발생 시 대응 방안 -->
+
+- 롤백 방법:
+- 롤백 판단 기준 (임계값 또는 조건):
+
+---
+
+## 8. 임시 조치 (Workaround, 해당 시)
+
+<!-- 수정 배포 전까지 사용자 또는 운영팀이 취할 수 있는 임시 방편 -->
+
+---
+
+## 9. 재발 방지 대책
+
+<!-- 동일한 유형의 버그가 다시 발생하지 않도록 개선할 점 -->
+
+- [ ] 테스트 케이스 추가
+- [ ] 코드 리뷰 체크리스트 항목 추가
+- [ ] 모니터링 알림 추가
+- [ ] 기타:
+
+---
+
+## 10. 참고 자료
+
+- 에러 로그:
+- 관련 이슈 / PR:

package/.sduck/sduck-assets/types/refactor.md

@@ -0,0 +1,174 @@
+# [refactor] {리팩토링 대상 및 목적}
+
+> **작업 타입:** `refactor` (Refactor)
+> **작성자:**
+> **작성일:** YYYY-MM-DD
+> **연관 티켓:**
+
+---
+
+## ⚠️ 리팩토링 불변 조건
+
+> **이 작업은 외부 동작(기능, API 응답, UI)을 변경하지 않는다.**
+> 코드 구조만 개선하며, 비즈니스 로직의 변경은 별도의 `feature` 또는 `fix` 작업으로 분리한다.
+
+---
+
+## 1. 배경 및 목적
+
+### 리팩토링이 필요한 이유
+
+<!-- 현재 코드의 어떤 문제(기술 부채, 가독성, 유지보수성, 성능 등)가 있는지 구체적으로 기술 -->
+
+### 기대 효과
+
+- [ ] 가독성 / 이해하기 쉬운 코드
+- [ ] 유지보수성 향상
+- [ ] 중복 코드 제거
+- [ ] 테스트 용이성 향상
+- [ ] 성능 개선 (측정 지표 명시 필요)
+- [ ] 기타:
+
+---
+
+## 2. 현재 상태 (As-Is)
+
+### 문제 코드 / 구조
+
+```
+파일: src/...
+```
+
+<!-- 문제가 되는 코드 패턴, 구조, 의존 관계 등을 스케치 또는 설명 -->
+
+### 측정 지표 (개선 전)
+
+| 지표                                | 현재 값 | 목표 값 |
+| ----------------------------------- | ------- | ------- |
+| 순환 복잡도 (Cyclomatic Complexity) |         |         |
+| 중복 코드 라인 수                   |         |         |
+| 함수/클래스 크기                    |         |         |
+| 응답 시간 (해당 시)                 |         |         |
+| 테스트 커버리지                     |         |         |
+
+---
+
+## 3. 목표 상태 (To-Be)
+
+### 개선된 구조
+
+```
+파일: src/...
+```
+
+<!-- 리팩토링 후 디렉토리 구조, 클래스 구조, 함수 분리 방향 등을 기술 -->
+
+### 적용할 패턴 / 원칙
+
+- [ ] SOLID 원칙 적용:
+- [ ] 디자인 패턴 적용:
+- [ ] 기타 컨벤션:
+
+---
+
+## 4. 리팩토링 범위
+
+### 변경 대상 파일
+
+```
+target_paths:
+  - src/...
+  - tests/...
+```
+
+### 변경하지 않는 범위 (명시적 경계)
+
+```
+blocked_paths:
+  - src/api/routes/    # 외부 API 계약 불변
+  - migrations/        # DB 스키마 불변
+```
+
+### 인터페이스 불변 확인
+
+<!-- 다음 항목들이 변경 전후 동일하게 유지되어야 함을 확인 -->
+
+- [ ] Public API 엔드포인트 및 응답 스펙
+- [ ] 공개 함수 / 메서드 시그니처
+- [ ] DB 스키마 및 마이그레이션
+- [ ] 이벤트 / 메시지 포맷
+
+---
+
+## 5. 테스트 전략
+
+> 리팩토링의 안전성은 테스트가 보장한다. 기존 테스트가 통과하는 것이 완료 기준이다.
+
+### 기존 테스트 현황
+
+- 현재 테스트 커버리지:
+- 테스트 통과 여부 (작업 시작 전 확인):
+  - [ ] 모든 기존 테스트 통과 확인됨
+
+### 리팩토링 중 테스트 전략
+
+- [ ] 기존 테스트를 변경하지 않고 통과시키며 리팩토링 진행
+- [ ] 구조 변경에 따라 테스트도 함께 재구성 (이유 명시):
+
+### 보완 테스트
+
+<!-- 기존 테스트 커버리지가 낮아 리팩토링 전 보강이 필요한 경우 -->
+
+- [ ] 추가 테스트 케이스 작성 대상:
+
+---
+
+## 6. 단계별 분리 계획
+
+> 리팩토링은 한 번에 모든 것을 바꾸지 않고 작은 단위로 나눠서 진행한다.
+
+| 단계 | 작업 내용 | 검증 방법        |
+| ---- | --------- | ---------------- |
+| 1    |           | 테스트 전부 통과 |
+| 2    |           | 테스트 전부 통과 |
+| 3    |           | 테스트 전부 통과 |
+
+---
+
+## 7. 영향 범위 분석
+
+### 의존 모듈 목록
+
+<!-- 리팩토링 대상을 import / 사용하는 다른 모듈 -->
+
+| 모듈 | 영향 내용 | 대응 방안 |
+| ---- | --------- | --------- |
+|      |           |           |
+
+### 회귀 테스트 필요 영역
+
+- [ ]
+
+---
+
+## 8. 롤백 계획
+
+- 롤백 방법: Git 스펙 단위 커밋 되돌리기
+- 롤백 기준: 테스트 실패 / 예상치 못한 동작 변경 발생 시
+
+---
+
+## 9. 완료 정의 (Definition of Done)
+
+- [ ] 기존 테스트 전체 통과
+- [ ] 신규 추가 테스트(있다면) 통과
+- [ ] 테스트 커버리지 감소 없음
+- [ ] 외부 동작 변경 없음 확인
+- [ ] 코드 리뷰 승인
+- [ ] 측정 지표 목표치 달성
+
+---
+
+## 10. 참고 자료
+
+-

package/README.md

@@ -43,6 +43,24 @@ sduck init --agents claude-code,cursor,codex
 
 ## 📖 주요 명령어
 
+### 빠른 시작 예시
+
+```bash
+# 1) 초기화
+sduck init --agents claude-code,codex
+
+# 2) 일반 흐름
+sduck start feature login-system
+sduck spec approve login-system
+sduck plan approve login-system
+
+# 3) 빠른 흐름
+sduck fast-track fix copy-bug
+
+# 4) 구현 완료 후
+sduck done login-system
+```
+
 ### 1. 작업 시작 (Start)
 
 작업 타입에 맞는 폴더와 템플릿 파일을 생성합니다.
@@ -53,6 +71,8 @@ sduck start feature login-system
 sduck start fix auth-bug
 ```
 
+생성 직후 상태는 `PENDING_SPEC_APPROVAL`입니다.
+
 ### 2. 스펙 승인 (Approve Spec)
 
 작성된 `spec.md`를 검토한 후 승인합니다. 상태가 `SPEC_APPROVED`로 변경됩니다.
@@ -66,6 +86,11 @@ sduck spec approve [slug]
 
 반복적이거나 범위가 명확한 작업은 minimal spec과 minimal plan을 한 번에 생성할 수 있습니다. `spec.md`는 생략되지 않으며, 비대화형 환경에서는 자동 승인 없이 생성만 수행합니다.
 
+- `spec.md`는 항상 생성됩니다
+- interactive 환경에서는 확인 1회 후 spec/plan 승인을 묶어 진행할 수 있습니다
+- 비대화형 환경에서는 생성만 수행하고, 이후 `sduck spec approve <slug>` → `sduck plan approve <slug>`로 이어집니다
+- 범위가 크거나 요구사항이 불명확한 작업은 일반 `start` 흐름을 권장합니다
+
 ```bash
 sduck fast-track <type> <slug>
 ```
@@ -83,10 +108,35 @@ sduck plan approve [slug]
 
 구현이 끝난 작업의 step 완료 여부, spec 체크리스트, task eval 자산을 확인한 뒤 `DONE` 상태로 마감합니다.
 
+- `steps.total`과 `steps.completed`가 모두 맞아야 합니다
+- `spec.md`의 체크리스트가 모두 완료돼야 합니다
+- target을 지정할 때는 정확한 `slug` 또는 전체 task `id`만 허용됩니다
+
 ```bash
 sduck done [slug]
 ```
 
+## ✅ 상태 전이
+
+```text
+PENDING_SPEC_APPROVAL -> SPEC_APPROVED -> IN_PROGRESS -> DONE
+```
+
+- `start`: `PENDING_SPEC_APPROVAL`
+- `spec approve`: `SPEC_APPROVED`
+- `plan approve`: `IN_PROGRESS`
+- `done`: `DONE`
+- `fast-track`: minimal spec/plan을 생성하고, 환경에 따라 `PENDING_SPEC_APPROVAL` 또는 `IN_PROGRESS`까지 진행
+
+## 🧭 일반 흐름 vs fast-track
+
+| 구분          | 일반 흐름                      | fast-track                                |
+| ------------- | ------------------------------ | ----------------------------------------- |
+| 문서 생성     | 타입 템플릿 기반 spec, 빈 plan | minimal spec + minimal plan               |
+| 승인 방식     | spec 승인, plan 승인 각각 진행 | interactive에서는 확인 1회로 묶을 수 있음 |
+| 비대화형 동작 | 각 명령 수동 실행              | 생성만 수행, 승인 자동 진행 없음          |
+| 추천 상황     | 범위가 크거나 애매한 작업      | 반복적이고 범위가 명확한 작업             |
+
 ## 🎨 자산 커스터마이징 (Asset Customization)
 
 sduck은 팀의 컨벤션을 자산(`.sduck/sduck-assets/`)으로 관리합니다. 이 폴더를 Git에 포함하여 팀원 모두가 동일한 기준을 공유하세요.
@@ -118,12 +168,26 @@ your-project/
 │   └── sduck-workspace/    # 📝 작업 이력 (Git 추적 권장)
 │       └── 20260319-1000-feature-login/
 │           ├── meta.yml    # 작업 상태 관리 (status, timestamps)
-│           ├── spec.md     # 요구사항 명세서
-│           └── plan.md     # 상세 구현 계획서
+│           ├── spec.md     # 요구사항 명세서 또는 minimal spec
+│           └── plan.md     # 상세 구현 계획서 또는 minimal plan
 ├── CLAUDE.md               # Claude Code용 규칙
 └── AGENT.md                # Codex/OpenCode용 규칙
 ```
 
+`meta.yml`에는 최소 아래 상태 정보가 들어갑니다.
+
+```yaml
+status: PENDING_SPEC_APPROVAL | SPEC_APPROVED | IN_PROGRESS | DONE
+spec:
+  approved: <boolean>
+plan:
+  approved: <boolean>
+steps:
+  total: <number | null>
+  completed: [<step numbers>]
+completed_at: <timestamp | null>
+```
+
 ## 🤖 지원 에이전트 (Rule Generation)
 
 `sduck init` 시 각 에이전트의 특성에 맞는 규칙 파일을 생성합니다.

package/dist/cli.js

@@ -1567,7 +1567,7 @@ async function runStartCommand(type, slug, projectRoot) {
 // package.json
 var package_default = {
   name: "@sduck/sduck-cli",
-  version: "0.1.2",
+  version: "0.1.3",
   description: "Spec-Driven Development CLI bootstrap",
   type: "module",
   bin: {
@@ -1575,7 +1575,7 @@ var package_default = {
   },
   files: [
     "dist",
-    "sduck-assets"
+    ".sduck/sduck-assets"
   ],
   engines: {
     node: ">=20"