muno-claude-plugin 1.16.3 → 1.16.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muno-claude-plugin",
-  "version": "1.16.3",
+  "version": "1.16.4",
   "description": "Unleash Claude Code's full power - Complete development workflow with expert personas, TDD-based agents, and automated documentation",
   "main": "bin/cli.js",
   "bin": {

package/templates/agents/story-reviewer.md

@@ -1,9 +1,9 @@
 ---
 name: story-reviewer
 description: |
-  Automatically reviews Story documents generated by story-generator to ensure they follow
-  Agile Scrum best practices and have well-defined acceptance criteria for Task extraction.
-  Triggered after story-generator saves a Story file. Returns "OK" if story is Task-ready,
+  Reviews User Story documents to ensure they follow Agile best practices.
+  Story should be a conversation starter (3 C's: Card, Conversation, Confirmation), NOT a detailed spec.
+  Triggered after story-generator saves a Story file. Returns "OK" if story follows Agile principles,
   or specific feedback with severity (Critical/Major/Minor).
 tools: Read, Glob, Grep
 model: sonnet
@@ -17,62 +17,87 @@ ${{file:.claude/personas/sm.md}}
 
 ---
 
-## 역할
+## 핵심 철학
 
-**Task 생성 관점**에서 Story를 검토합니다.
-- Task 추출 가능하면 "OK" 하고 끝
-- 문제 있을 때만 피드백 (심각도별)
-- 직접 수정하지 않음
+> "스토리는 소프트웨어 기능에 대한 **비공식적이고 일반적인 설명**으로, 최종 사용자 관점에서 작성됩니다."
+> — Atlassian
 
-**핵심 원칙**: Task는 Story AC에서 도출됨 → AC가 구체적이어야 함
+**Story는 대화의 시작점이지 상세 스펙이 아닙니다.**
+
+### 3 C's (Card, Conversation, Confirmation)
+
+| C | 의미 | 검토 포인트 |
+|---|------|------------|
+| **Card** | 간결한 핵심 요구사항 | 20줄 이내로 표현 가능? |
+| **Conversation** | 팀 대화 촉진 | 협의 여지가 있음? |
+| **Confirmation** | 완료 조건 (AC) | 테스트 가능? |
 
 ---
 
-## 검토 체크리스트
+## 검토 기준
 
 ### 1. Story 구조 (필수 요소)
-- [ ] Story ID와 Title 명시
-- [ ] User Story 문장 (As a / I want / So that)
-- [ ] Description (배경/맥락)
-- [ ] Acceptance Criteria (Given-When-Then 또는 체크리스트)
-- [ ] Definition of Done
+
+- [ ] Story ID와 Title
+- [ ] User Story 문장 (As a / I want / so that)
+- [ ] Acceptance Criteria (체크리스트 형식 권장)
+- [ ] Notes (선택 - 협의 필요 사항)
 
 ### 2. INVEST 원칙
+
 - [ ] **Independent**: 다른 미완료 Story 의존 없음
-- [ ] **Negotiable**: 과도하게 상세하지 않음
+- [ ] **Negotiable**: 구현 방법이 열려있음 (과도한 세부사항 금지)
 - [ ] **Valuable**: 사용자/비즈니스 가치 명확
-- [ ] **Estimable**: 추정 가능한 상세 수준
-- [ ] **Small**: 한 스프린트 내 완료 가능
-- [ ] **Testable**: AC가 검증 가능
+- [ ] **Estimable**: 팀이 크기 추정 가능
+- [ ] **Small**: 1 스프린트 내 완료 가능
+- [ ] **Testable**: AC로 완료 여부 판단 가능
 
 ### 3. Acceptance Criteria 품질
-- [ ] 각 AC가 독립적으로 테스트 가능
-- [ ] Happy Path + Edge Case 포함
-- [ ] 모호한 표현 없음 ("적절히", "잘 동작" 등 금지)
-- [ ] User Story 목표와 일치
-- [ ] 경계 조건 정의
-- [ ] 에러 처리 시나리오 포함
-
-### 4. Task 추출 가능성 (핵심)
-- [ ] AC가 구체적 구현 작업으로 분해 가능
-- [ ] 각 AC가 실제 개발 Task로 매핑 가능
-- [ ] 기술적 고려사항 언급 (해당 시)
-- [ ] 스코프가 명확하여 범위 이탈 방지 가능
-
-### 5. 연결성
-- [ ] 상위 Epic 참조
-- [ ] 관련 PRD/HLD 참조 (해당 시)
-- [ ] 의존성 Story 명시 (해당 시)
+
+**Good AC (체크리스트)**:
+```markdown
+- [ ] 유효한 이메일/비밀번호로 로그인 시 홈 화면 이동
+- [ ] 잘못된 자격증명 시 에러 메시지 표시
+- [ ] 로그인 상태 유지
+```
+
+**Bad AC (과도한 세부사항)**:
+```gherkin
+Scenario: 유효한 이메일과 비밀번호로 로그인
+  Given 등록된 이메일 "user@example.com"이 있다
+  When 이메일 필드에 "user@example.com"을 입력한다
+  And 비밀번호 필드에 올바른 비밀번호를 입력한다
+  Then JWT 토큰이 발급된다
+  And 토큰이 localStorage에 저장된다
+  And "환영합니다" 토스트가 3초간 표시된다
+```
+
+### 4. 과도한 세부사항 체크 (Red Flags)
+
+스토리에 다음이 포함되면 **Major Issue**:
+
+- [ ] 구현 기술 명시 (JWT, Redis, localStorage 등)
+- [ ] UI 세부사항 (색상, 위치, 애니메이션 시간)
+- [ ] API 스펙 (HTTP 메서드, 엔드포인트, 상태 코드)
+- [ ] 데이터베이스 스키마
+- [ ] Story Points / 추정 근거 (팀 플래닝에서 결정)
+- [ ] 50줄 이상의 문서 길이
+
+### 5. 가치 표현 체크
+
+- [ ] "so that" 절이 동어반복이 아님
+- [ ] 최종 사용자 관점의 가치 (개발자 관점 X)
+- [ ] 비즈니스/사용자에게 의미있는 결과
 
 ---
 
 ## 심각도 정의
 
-| 심각도 | 정의 | 판정 |
+| 심각도 | 정의 | 예시 |
 |--------|------|------|
-| **Critical** | Task 추출 불가 | FAIL |
-| **Major** | AC 모호 → Task 품질 저하 위험 | 3개 이상이면 FAIL |
-| **Minor** | 개선하면 좋으나 Task 추출 가능 | PASS with warnings |
+| **Critical** | 스토리의 본질 훼손 | User Story 문장 없음, 가치 불명확 |
+| **Major** | 대화 촉진 방해 | 과도한 세부사항, 협상 불가능한 구조 |
+| **Minor** | 개선하면 좋음 | 모호한 표현 일부, Notes 부재 |
 
 **판정 기준:**
 - FAIL: Critical 1개 이상 OR Major 3개 이상
@@ -81,29 +106,25 @@ ${{file:.claude/personas/sm.md}}
 
 ---
 
-## AC 품질 판단 기준
+## 주요 Red Flags
 
-### Good AC 예시
-```
-Given: 사용자가 로그인 페이지에 있을 때
-When: 이메일 형식이 잘못된 값을 입력하면
-Then: "유효하지 않은 이메일 형식입니다" 에러 메시지가 표시됨
-```
+### Critical (즉시 수정 필요)
+- User Story 문장 없음
+- AC 없음
+- "so that" 동어반복 또는 가치 없음
+- 사용자가 아닌 "개발자", "시스템" 관점
 
-### Bad AC 예시 (Critical)
-```
-- 사용자가 적절한 에러 메시지를 볼 수 있다
-- 시스템이 올바르게 동작한다
-- 입력값이 검증된다
-```
+### Major (대화 촉진 방해)
+- Given-When-Then이 100줄 이상
+- 구현 기술 스택 명시
+- UI 세부 디자인 포함
+- Story Points 포함
+- 추정 근거 표 포함
 
-### 주요 Red Flags
-- "적절한", "올바른", "빠르게" 등 모호한 형용사
-- 테스트 불가능한 조건
-- 암묵적 지식 가정
-- 경계값 미정의
-- 에러 시나리오 누락
-- 단일 스프린트 불가능한 규모
+### Minor (품질 개선)
+- 모호한 표현 ("빠르게", "적절히")
+- Notes 섹션 없음 (협의 사항 미명시)
+- Epic 참조 누락
 
 ---
 
@@ -113,41 +134,36 @@ Then: "유효하지 않은 이메일 형식입니다" 에러 메시지가 표시
 ```
 # Story 검토 완료 ✅
 
-체크리스트 통과. Task 생성 가능합니다.
+스토리가 애자일 원칙을 따르고 있습니다.
+- 간결한 Card ✓
+- 대화 촉진 가능 ✓
+- AC로 완료 판단 가능 ✓
 ```
 
 ### 문제 발견 시
 ```
 # Story 검토 피드백 - [FAIL/PASS with warnings]
 
-## Critical Issues (Task 추출 불가)
+## Critical Issues (스토리 본질 훼손)
 1. **[기준명]**: [문제] → [개선안]
 
-## Major Issues (Task 품질 저하 위험)
+## Major Issues (과도한 세부사항)
 1. **[기준명]**: [문제] → [개선안]
 
 ## Minor Issues (품질 개선)
 1. **[기준명]**: [문제] → [개선안]
-```
 
 ---
 
-## 파일 위치 컨텍스트
-
-**Story 파일 위치:**
-`documents/epics/{epic-name}/stories/{story-id}-{name}/story.md`
-
-**관련 파일:**
-- Epic: `documents/epics/{epic-name}/epic.md`
-- HLD/LLD: `documents/epics/{epic-name}/design/`
-- PRD: `documents/prd/`
+**참고**: Story는 대화의 시작점입니다. 구현 세부사항은 팀 대화에서 결정하세요.
+```
 
 ---
 
 ## 원칙
 
-1. **무조건 피드백 금지**: 통과하면 OK
-2. **체크리스트 기반**: 정해진 항목만 검토
-3. **직접 수정 금지**: 피드백만, 수정은 story-generator 몫
-4. **간결하게**: 문제 있는 것만 언급
-5. **Task 관점 우선**: AC가 Task로 분해 가능한지가 핵심
+1. **간결함 우선**: 스토리가 짧을수록 좋음
+2. **과도한 세부사항 경고**: 너무 상세하면 Major Issue
+3. **대화 촉진 관점**: 팀이 협의할 여지가 있는지 확인
+4. **직접 수정 금지**: 피드백만, 수정은 story-generator 몫
+5. **3 C's 기반**: Card-Conversation-Confirmation 균형 확인

package/templates/skills/story-generator/SKILL.md

@@ -1,10 +1,16 @@
 ---
 name: story-generator
 description: |
-  Creates User Stories from Epic documents with Given-When-Then Acceptance Criteria following INVEST principles.
-  Use when user requests "create story", "add story to epic", "break down epic", "스토리 만들어",
-  "스토리 분해", "백로그 작성". Each Story represents one user-centric feature deliverable in 1 sprint.
-  Never guesses - asks when Epic info is insufficient. Output serves as input for TC/Task generation.
+  Creates User Stories - informal, general descriptions of software features from the end user's perspective.
+  Story is a conversation starter following the 3 C's (Card, Conversation, Confirmation), NOT a detailed spec.
+
+  Trigger when user requests:
+  - "create story", "write story", "add story", "story 생성", "스토리 만들어", "스토리 작성"
+  - "break down epic", "divide epic into stories", "Epic 분해", "Epic을 Story로"
+  - "user story 추출", "백로그 작성", "backlog item 생성"
+  - "story from PRD", "PRD에서 Story 도출"
+
+  Prerequisites: Epic document must exist. Never guesses - asks when info is insufficient.
 allowed-tools: Read, Write, Edit, Glob, Grep, WebSearch, WebFetch
 ---
 
@@ -14,9 +20,17 @@ allowed-tools: Read, Write, Edit, Glob, Grep, WebSearch, WebFetch
 
 ## 개요
 
-Story는 **사용자 관점의 기능 단위**입니다. 1 Sprint 내 완료 가능해야 합니다.
+**User Story란?**
+
+> "스토리는 소프트웨어 기능에 대한 비공식적이고 일반적인 설명으로, 최종 사용자 관점에서 작성됩니다."
+> — Atlassian
+
+Story는 **최종 목표(end goal)**이지 기능 명세가 아닙니다. Story의 목적은 **대화를 시작하는 것**입니다.
 
-**핵심**: 추측 금지. Epic 정보 부족 시 질문. **AC 없는 Story는 Story가 아님**.
+**핵심 철학**:
+- Story는 간결해야 합니다 (상세 스펙 X)
+- Story는 협상 가능해야 합니다 (구현 방법은 팀이 결정)
+- Story는 사용자에게 전달할 가치를 표현합니다
 
 ---
 
@@ -25,12 +39,13 @@ Story는 **사용자 관점의 기능 단위**입니다. 1 Sprint 내 완료 가
 1. **Epic 확인**: Epic 문서 읽고 비즈니스 목표 파악
    - Epic 없으면 진행 불가 → 사용자에게 질문
 
-2. **Story 도출**: 사용자 관점 기능 분해
-   - 2-3개 질문으로 요구사항 명확화
-   - INVEST 원칙 검증
+2. **Story 도출**: 사용자 관점에서 가치 단위로 분해
+   - "사용자가 무엇을 할 수 있게 되는가?"
+   - 기술적 구현이 아닌 사용자 가치에 집중
 
-3. **AC 작성**: Given-When-Then 형식 필수
-   - 정상/예외/엣지 케이스 모두 포함
+3. **간단한 AC 작성**: 완료 조건을 체크리스트로
+   - 과도한 세부사항 금지 (구현 제약 X)
+   - 팀이 대화할 수 있는 수준의 정보만
 
 4. **검토 후 저장**
 

package/templates/skills/story-generator/reference/examples/bad-story.md

@@ -0,0 +1,167 @@
+# Bad Story Example
+
+피해야 할 User Story 패턴들입니다.
+
+---
+
+## Bad Example 1: 과도한 세부사항 (스펙 문서가 됨)
+
+```markdown
+---
+id: STORY-001
+title: 이메일로 로그인
+epic: documents/epics/user-authentication/epic.md
+status: todo
+priority: must_have
+story_points: 3
+created_at: 2024-01-15
+sprint: Sprint 5
+assignee: dev-team
+---
+
+# [STORY-001] 이메일로 로그인
+
+## User Story
+
+**AS A** 등록된 사용자
+**I WANT** 이메일과 비밀번호로 로그인하고 싶다
+**SO THAT** 내 계정의 개인화된 콘텐츠를 이용할 수 있다
+
+---
+
+## Acceptance Criteria
+
+### 시나리오 1: 유효한 자격증명으로 로그인
+
+```gherkin
+Scenario: 유효한 이메일과 비밀번호로 로그인
+  Given 등록된 이메일 "user@example.com"이 있다
+  And 데이터베이스에 해당 사용자가 활성 상태로 존재한다
+  When 이메일 필드에 "user@example.com"을 입력한다
+  And 비밀번호 필드에 올바른 비밀번호를 입력한다
+  And "로그인" 버튼을 클릭한다
+  Then JWT 토큰이 발급된다
+  And 토큰이 localStorage에 저장된다
+  And 홈 화면 "/home"으로 리다이렉트된다
+  And 상단 네비게이션에 사용자 이름이 표시된다
+  And "환영합니다, {사용자명}님" 토스트가 3초간 표시된다
+```
+
+### 시나리오 2: 잘못된 비밀번호
+
+```gherkin
+Scenario: 잘못된 비밀번호 입력
+  Given 등록된 이메일 "user@example.com"이 있다
+  When 이메일 필드에 "user@example.com"을 입력한다
+  And 비밀번호 필드에 잘못된 비밀번호를 입력한다
+  And "로그인" 버튼을 클릭한다
+  Then HTTP 401 응답이 반환된다
+  And "이메일 또는 비밀번호가 올바르지 않습니다" 에러 메시지가 빨간색으로 표시된다
+  And 비밀번호 필드가 초기화된다
+  And 로그인 페이지에 남아있다
+```
+
+### 시나리오 3: 5회 연속 실패 시 계정 잠금
+
+```gherkin
+Scenario: 연속 로그인 실패로 계정 잠금
+  Given 4회 연속 잘못된 비밀번호로 시도했다
+  And Redis에 실패 카운터가 4로 저장되어 있다
+  When 5번째 잘못된 비밀번호로 시도한다
+  Then 계정 상태가 'LOCKED'로 변경된다
+  And "계정이 5분간 잠겼습니다. 5분 후 다시 시도해주세요." 메시지 표시
+  And 로그인 버튼이 disabled 상태로 변경
+  And 5분 타이머가 화면에 표시됨
+```
+
+---
+
+## 의존성
+
+### 선행 Story
+- [ ] 없음
+
+### 후행 Story
+- [ ] STORY-002: 비밀번호 재설정 (이 Story 완료 후 진행)
+- [ ] STORY-003: 소셜 로그인 연동
+
+---
+
+## 추정 근거
+
+**Story Points**: 3
+
+| 구성요소 | 복잡도 | Points |
+|----------|--------|--------|
+| 로그인 폼 UI | 단순 | 0.5 |
+| API 연동 | 보통 | 1 |
+| 세션/토큰 관리 | 보통 | 1 |
+| 계정 잠금 로직 | 약간 복잡 | 0.5 |
+
+---
+
+## 기술 스택
+
+- Frontend: React + TypeScript
+- API: REST POST /api/auth/login
+- 인증: JWT (access token + refresh token)
+- 저장소: localStorage (access), httpOnly cookie (refresh)
+- 실패 카운터: Redis
+```
+
+---
+
+## 문제점
+
+1. **100줄 이상**: 스토리가 아니라 기술 스펙 문서
+2. **Given-When-Then 강제**: BDD 테스트 시나리오를 AC로 사용
+3. **구현 세부사항**: JWT, localStorage, Redis, HTTP 상태 코드 등
+4. **UI 디테일**: 버튼 상태, 색상, 토스트 시간까지 명시
+5. **추정 근거**: 이건 팀이 플래닝 때 하는 것
+6. **기술 스택**: 스토리에 포함되면 안 됨
+7. **협상 불가**: 팀이 결정할 여지가 없음
+
+---
+
+## Bad Example 2: 동어반복, 가치 없음
+
+```markdown
+## User Story
+
+**As a** 사용자
+**I want** 로그인하고 싶다
+**so that** 로그인할 수 있다
+```
+
+**문제**: "so that"이 동어반복. 왜 로그인이 필요한지 가치가 없음.
+
+---
+
+## Bad Example 3: 개발자 관점
+
+```markdown
+## User Story
+
+**As a** 개발자
+**I want** JWT 토큰을 localStorage에 저장하고 싶다
+**so that** 인증 상태를 유지할 수 있다
+```
+
+**문제**:
+- 개발자는 사용자가 아님
+- 구현 방법(How)을 명시
+- 최종 사용자에게 전달되는 가치가 아님
+
+---
+
+## Bad Example 4: 모호한 표현
+
+```markdown
+## Acceptance Criteria
+
+- [ ] 로그인이 빠르게 처리되어야 함
+- [ ] 에러 메시지가 적절하게 표시되어야 함
+- [ ] 보안이 잘 되어야 함
+```
+
+**문제**: "빠르게", "적절하게", "잘" - 측정/테스트 불가능

package/templates/skills/story-generator/reference/examples/good-story.md

@@ -0,0 +1,48 @@
+# Good Story Example
+
+실제 프로젝트에서 사용할 수 있는 올바른 User Story 예시입니다.
+
+---
+
+```markdown
+---
+id: STORY-001
+title: 이메일 로그인
+epic: documents/epics/user-authentication/epic.md
+status: ready
+---
+
+# [STORY-001] 이메일 로그인
+
+## User Story
+
+**As a** 등록된 사용자
+**I want** 이메일과 비밀번호로 로그인하고 싶다
+**so that** 내 개인화된 콘텐츠와 주문 내역에 접근할 수 있다
+
+---
+
+## Acceptance Criteria
+
+- [ ] 유효한 이메일/비밀번호로 로그인 시 홈 화면으로 이동
+- [ ] 잘못된 자격증명 시 에러 메시지 표시
+- [ ] 로그인 상태가 유지됨
+
+---
+
+## Notes
+
+- 기존 소셜 로그인(Google, Kakao)과 공존해야 함
+- 비밀번호 재설정은 STORY-002로 분리
+- 보안팀과 세션 유지 시간 협의 필요
+```
+
+---
+
+## 좋은 점
+
+1. **간결함**: 전체 문서가 20줄 미만
+2. **가치 명확**: "개인화된 콘텐츠와 주문 내역 접근" - 왜 필요한지 명확
+3. **AC가 체크리스트**: 완료 여부 판단 가능
+4. **Notes로 대화 유도**: 협의 필요 사항 명시
+5. **구현 세부사항 없음**: JWT, localStorage 등 기술 결정은 팀에 위임

package/templates/skills/story-generator/reference/principles.md

@@ -1,88 +1,155 @@
 # Story Writing Principles
 
-## 핵심 원칙
+## User Story란?
 
-1. **추측 금지**: Epic 정보 없으면 질문. 절대 가정하지 않음
-2. **사용자 중심**: 기술이 아닌 사용자 관점. "개발자가" 아닌 "사용자가"
-3. **AC 필수**: AC 없는 Story는 Story가 아님
-4. **1 Sprint 완료**: 8 SP 이상이면 분해
+> 사용자 스토리는 소프트웨어 시스템 요구사항을 고객이나 최종 사용자의 관점에서 일상적 언어로 작성하여 개발팀에 컨텍스트를 제공하는 것입니다.
+
+**핵심**: 스토리는 **상세 요구사항이 아니라 대화의 중심**입니다.
+
+---
+
+## 3 C's: Card, Conversation, Confirmation
+
+### Card (카드)
+
+간결한 문장으로 핵심 요구사항을 적습니다:
+
+```
+나는 {사용자 유형}으로서
+{무엇을} 하고 싶다
+왜냐하면 {이유/가치} 때문이다
+```
+
+**예시**:
+> "나는 웹사이트 방문객으로서, 신상품 목록을 볼 수 있다. 왜냐하면 최신 제품 정보를 빠르게 확인하고 싶기 때문이다."
+
+### Conversation (대화)
+
+- 개발팀, 디자이너, PO가 모여 스토리에 대해 깊이 있는 대화
+- 이해를 공유하고 세부사항을 협의
+- **카드는 대화의 시작점일 뿐**, 모든 것을 담을 필요 없음
+
+### Confirmation (확인)
+
+- 스토리가 "완료"되었다고 판단할 수 있는 조건
+- **Acceptance Criteria (수용 기준)** 으로 정의
+- 테스트 가능해야 함
 
 ---
 
 ## INVEST 원칙
 
-| 원칙 | 질문 |
-|------|------|
-| **I**ndependent | 다른 Story 없이 개발/테스트 가능? |
-| **N**egotiable | 구현 방식 협의 가능? (What만 정의) |
-| **V**aluable | 사용자/비즈니스 가치 명확? |
-| **E**stimable | 팀이 크기 추정 가능? |
-| **S**mall | 1 Sprint 내 완료? (8 SP 이하) |
-| **T**estable | AC로 테스트 가능? |
+| 원칙 | 설명 | 체크 질문 |
+|------|------|-----------|
+| **I**ndependent | 독립적 | 다른 스토리 없이 개발 가능? |
+| **N**egotiable | 협상 가능 | 구현 방법은 팀이 결정? |
+| **V**aluable | 가치 중심 | 사용자/비즈니스에 가치 제공? |
+| **E**stimable | 추정 가능 | 팀이 크기를 추정할 수 있음? |
+| **S**mall | 작은 단위 | 1 스프린트 내 완료 가능? |
+| **T**estable | 테스트 가능 | AC로 검증 가능? |
 
 ---
 
-## Acceptance Criteria (Given-When-Then)
+## Acceptance Criteria 작성
+
+### 기본: 체크리스트 형식 (권장)
 
-### 필수 시나리오
+```markdown
+## Acceptance Criteria
+
+- [ ] 로그인 성공 시 홈 화면으로 이동
+- [ ] 잘못된 비밀번호 시 에러 메시지 표시
+- [ ] 세션은 30분간 유지
+```
 
-1. **정상 케이스**: Happy path
-2. **예외 케이스**: 에러 상황
-3. **엣지 케이스**: 경계값, 보안
+### 선택: Given-When-Then 형식
 
-### Good vs Bad
+테스트 시나리오를 명확히 해야 할 때 선택적으로 사용:
 
 ```gherkin
-# ✅ Good - 구체적, 측정 가능
-Scenario: 유효한 자격증명으로 로그인
-  Given 등록된 이메일 "user@example.com"이 있다
-  When 올바른 비밀번호를 입력하고 로그인 클릭
-  Then 홈 화면으로 리다이렉트
-    And "환영합니다" 토스트 3초간 표시
-
-# ❌ Bad - 모호, 측정 불가
-- 로그인이 잘 되어야 함
-- 에러 처리가 적절해야 함
+Given 로그인 상태일 때
+When '장바구니' 버튼을 클릭하면
+Then 장바구니 페이지로 이동한다
 ```
 
+**주의**: Given-When-Then은 테스트 케이스(TC) 단계에서 더 상세히 작성합니다.
+스토리 AC에서는 **간결함 우선**.
+
+---
+
+## 작성 팁
+
+### Do
+
+- 사용자 유형 명확히 정의 ('관리자', '방문객', '회원')
+- '왜' 하는지에 집중 (기능 뒤의 목적)
+- 대화의 시작점으로 활용
+- 큰 스토리(Epic)는 작은 스토리로 분할
+
+### Don't
+
+- 처음부터 UI/UX 세부사항 정의
+- 구현 방법(How) 명시
+- 모호한 표현 ("빠르게", "적절히", "잘")
+- 8 SP 초과 (분해 필요)
+
 ---
 
-## User Story 형식
+## Good vs Bad
 
 ```markdown
-# ✅ Good
-**AS A** 등록된 사용자
-**I WANT** 이메일과 비밀번호로 로그인하고 싶다
-**SO THAT** 개인화된 콘텐츠를 이용할 수 있다
-
-# ❌ Bad
-**AS A** 사용자
-**I WANT** 로그인하고 싶다
-**SO THAT** 로그인할 수 있다  ← 동어반복, 가치 없음
+# Good - 가치 중심, 간결
+
+**As a** 등록된 사용자
+**I want** 비밀번호를 재설정하고 싶다
+**so that** 비밀번호를 잊어버려도 계정에 접근할 수 있다
+
+## Acceptance Criteria
+- [ ] 이메일로 재설정 링크 발송
+- [ ] 링크는 24시간 유효
+- [ ] 새 비밀번호로 로그인 가능
 ```
 
----
+```markdown
+# Bad - 동어반복, 가치 없음
 
-## 금지 사항
+**As a** 사용자
+**I want** 비밀번호 재설정
+**so that** 비밀번호를 재설정할 수 있다  ← 동어반복
+```
 
-❌ Epic 정보 없이 Story 작성
-❌ AC 없는 Story
-❌ 모호한 표현 ("빠르게", "적절히", "잘")
-❌ 기술 중심 Story ("JWT 구현" 대신 "로그인 상태 유지")
-❌ 8 SP 초과 (분해 필요)
-❌ Given-When-Then 형식 미준수
+```markdown
+# Bad - 구현 세부사항 포함
+
+**As a** 사용자
+**I want** JWT 토큰을 localStorage에 저장  ← 구현 방법
+**so that** 로그인 상태를 유지할 수 있다
+```
 
 ---
 
-## 기술 부채 → 가치로 표현
+## 기술 부채를 가치로 표현하기
 
 ```markdown
-# ❌ Bad
-**AS A** 개발자
-**I WANT** 레거시 코드 리팩토링
-
-# ✅ Good
-**AS A** 개발팀
-**I WANT** 인증 모듈 코드 구조 개선
-**SO THAT** 신규 기능 추가 시간 50% 단축
+# Bad - 개발자 관점, 가치 불명확
+**As a** 개발자
+**I want** 레거시 코드 리팩토링
+
+# Good - 팀/비즈니스 가치 표현
+**As a** 개발팀
+**I want** 인증 모듈 코드 구조 개선
+**so that** 신규 기능 추가 시간을 단축할 수 있다
 ```
+
+---
+
+## 스토리 분할 전략
+
+큰 스토리(Epic)를 작은 스토리로 분할하는 방법:
+
+1. **워크플로우 단계별**: 가입 → 로그인 → 프로필 수정
+2. **사용자 유형별**: 관리자용, 일반 사용자용
+3. **데이터 유형별**: 텍스트, 이미지, 동영상
+4. **비즈니스 규칙별**: 정상 케이스, 예외 케이스
+
+**1 스프린트 내 완료 가능한 크기로 유지!**

package/templates/skills/story-generator/reference/story-template.md

@@ -11,151 +11,121 @@
 ```markdown
 ---
 id: STORY-XXX
-title: [Story 제목]
+title: [간결한 제목]
 epic: documents/epics/{epic-name}/epic.md
-status: todo
-priority: must_have
-story_points: 3
-created_at: YYYY-MM-DD
+status: draft | ready | in_progress | done
 ---
 
 # [STORY-XXX] Story 제목
 
-## 1. User Story
+## User Story
 
-**AS A** [사용자 역할]
-**I WANT** [원하는 기능]
-**SO THAT** [비즈니스 가치]
+**As a** [사용자 유형]
+**I want** [달성하고 싶은 것]
+**so that** [얻고자 하는 가치/이유]
 
 ---
 
-## 2. Acceptance Criteria
+## Acceptance Criteria
 
-### 시나리오 1: [정상 케이스]
+스토리가 "완료"되었다고 판단할 수 있는 조건들:
 
-```gherkin
-Scenario: [제목]
-  Given [전제 조건]
-  When [사용자 행동]
-  Then [기대 결과]
-```
+- [ ] [조건 1]
+- [ ] [조건 2]
+- [ ] [조건 3]
 
-### 시나리오 2: [예외 케이스]
-
-```gherkin
-Scenario: [제목]
-  Given [전제 조건]
-  When [사용자 행동]
-  Then [기대 결과]
-```
+---
 
-### 시나리오 3: [엣지 케이스]
+## Notes
 
-```gherkin
-Scenario: [제목]
-  Given [전제 조건]
-  When [사용자 행동]
-  Then [기대 결과]
+팀과 논의가 필요한 사항, 제약 조건, 참고 정보 등 (선택 사항)
 ```
 
 ---
 
-## 3. 의존성
-
-### 선행 Story
-- [ ] 없음 / [STORY-XXX]: [이유]
+## 핵심 포인트
 
-### 후행 Story
-- [ ] 없음 / [STORY-XXX]: 이 Story 완료 후 가능
+1. **간결함 유지** - 스토리는 대화의 시작점이지 상세 스펙이 아님
+2. **AC는 체크리스트** - 완료 여부를 판단할 수 있는 간단한 조건들
+3. **구현 세부사항 금지** - "어떻게"가 아닌 "무엇을" 표현
+4. **협상 가능** - 팀이 구현 방법을 결정할 여지를 남김
 
 ---
 
-## 4. 추정 근거
+## Good vs Bad 예시
 
-**Story Points**: X
-
-| Points | 복잡도 | 예시 |
-|--------|--------|------|
-| 1-2 | 단순 | CSS 수정, 필드 추가 |
-| 3-5 | 보통 | API 엔드포인트, 폼 구현 |
-| 8+ | 분해 필요 | 여러 컴포넌트 |
-```
-
----
-
-## 예시
+### Good Example
 
 ```markdown
 ---
 id: STORY-001
-title: 이메일로 로그인
+title: 이메일 로그인
 epic: documents/epics/user-authentication/epic.md
-status: todo
-priority: must_have
-story_points: 3
-created_at: 2024-01-15
+status: ready
 ---
 
-# [STORY-001] 이메일로 로그인
+# [STORY-001] 이메일 로그인
 
-## 1. User Story
+## User Story
 
-**AS A** 등록된 사용자
-**I WANT** 이메일과 비밀번호로 로그인하고 싶다
-**SO THAT** 내 계정의 개인화된 콘텐츠를 이용할 수 있다
+**As a** 등록된 사용자
+**I want** 이메일과 비밀번호로 로그인하고 싶다
+**so that** 내 개인화된 콘텐츠에 접근할 수 있다
 
 ---
 
-## 2. Acceptance Criteria
+## Acceptance Criteria
 
-### 시나리오 1: 유효한 자격증명으로 로그인
+- [ ] 유효한 이메일/비밀번호로 로그인하면 홈 화면으로 이동
+- [ ] 잘못된 자격증명 시 에러 메시지 표시
+- [ ] 로그인 후 세션 유지
 
-```gherkin
-Scenario: 유효한 이메일과 비밀번호로 로그인
-  Given 등록된 이메일 "user@example.com"이 있다
-  When 이메일과 올바른 비밀번호를 입력한다
-    And "로그인" 버튼을 클릭한다
-  Then 홈 화면으로 리다이렉트된다
-    And 상단에 사용자 이름이 표시된다
-```
+---
 
-### 시나리오 2: 잘못된 비밀번호
+## Notes
 
-```gherkin
-Scenario: 잘못된 비밀번호 입력
-  Given 등록된 이메일 "user@example.com"이 있다
-  When 잘못된 비밀번호를 입력한다
-  Then "이메일 또는 비밀번호가 올바르지 않습니다" 표시
-    And 로그인 페이지에 남아있다
+- 기존 OAuth 로그인과 공존해야 함
+- 비밀번호 재설정은 별도 스토리로 분리
 ```
 
-### 시나리오 3: 5회 연속 실패 시 계정 잠금
+### Bad Example (피해야 할 것)
 
-```gherkin
-Scenario: 연속 로그인 실패로 계정 잠금
-  Given 4회 연속 잘못된 비밀번호로 시도했다
-  When 5번째 잘못된 비밀번호로 시도한다
-  Then "계정이 5분간 잠겼습니다" 메시지 표시
-    And 로그인 버튼 비활성화
-```
-
----
+```markdown
+# ❌ 너무 상세함 - 스토리가 아니라 스펙 문서가 됨
 
-## 3. 의존성
+## Acceptance Criteria
 
-### 선행 Story
-- [ ] 없음
+```gherkin
+Scenario: 유효한 이메일과 비밀번호로 로그인
+  Given 등록된 이메일 "user@example.com"이 있다
+  And 데이터베이스에 해당 사용자가 존재한다
+  When 이메일 필드에 "user@example.com"을 입력한다
+  And 비밀번호 필드에 올바른 비밀번호를 입력한다
+  And "로그인" 버튼을 클릭한다
+  Then JWT 토큰이 발급된다
+  And 토큰이 localStorage에 저장된다
+  And 홈 화면 "/home"으로 리다이렉트된다
+  And 상단 네비게이션에 사용자 이름이 표시된다
+  And "환영합니다" 토스트가 3초간 표시된다
+```
 
-### 후행 Story
-- [ ] STORY-002: 비밀번호 재설정
+## 문제점:
+- Given-When-Then은 테스트 케이스 형식 (BDD)
+- JWT, localStorage 등 구현 세부사항 포함
+- UI 디테일까지 명시 → 팀의 창의성/협상 여지 없음
+- 스토리 하나가 문서 수십 줄 → 대화 대신 문서 읽기
+```
 
 ---
 
-## 4. 추정 근거
+## 스토리 vs 테스트 케이스
 
-**Story Points**: 3
+| 구분 | User Story | Test Case |
+|------|------------|-----------|
+| 목적 | 대화 시작점 | 검증 시나리오 |
+| 상세도 | 간략 | 상세 |
+| 형식 | 자유 체크리스트 | Given-When-Then |
+| 작성 시점 | 기획 단계 | 개발 직전/중 |
+| 변경 | 협상 가능 | 구체적 기대값 |
 
-- 로그인 폼 UI: 단순 (1 SP)
-- API 연동/세션 관리: 보통 (1 SP)
-- 보안 처리 (계정 잠금): 약간 복잡 (1 SP)
-```
+**Given-When-Then은 TC(Test Case) 생성 단계에서 작성합니다.**