Agent Skills: generate-spec Skill

시스템 메시지: [SEMO] Skill: generate-spec 호출 - {기능명/Epic 번호}

generate-spec Skill

Purpose: Speckit 워크플로우 통합 실행 (Epic → spec → plan → tasks → Task Issues)

핵심 원칙

Source of Truth: Task Issue가 Speckit 워크플로우의 진실 소스 통합 워크플로우: spec 생성과 Task Issue 생성을 하나의 스킬에서 처리 DDD Layer 기반: Task를 CONFIG → PROJECT → DATA → TESTS → CODE 순서로 분해

Workflow Overview

[Epic Issue]
      ↓
Phase 1: /speckit.specify → spec.md
      ↓
Phase 2: /speckit.plan → plan.md
      ↓
Phase 3: /speckit.tasks → tasks.md (DDD Layer 분해)
      ↓
Phase 4: /speckit.issues → Task Issues 생성
      ↓
[구현 시작]

Phase Flow

| Phase | Command | Output | 설명 | |-------|---------|--------|------| | 1 | /speckit.specify | spec.md | 요구사항 명세 | | 2 | /speckit.plan | plan.md | 구현 계획 | | 3 | /speckit.tasks | tasks.md | DDD Layer 기반 Task 분해 | | 4 | /speckit.issues | Task Issues | GitHub Issue 자동 생성 |

🔴 Phase 1: Specify (spec.md)

Epic Issue 파싱

# Epic 본문 조회
EPIC_BODY=$(gh issue view $EPIC_NUMBER --repo semicolon-devteam/docs --json body --jq '.body')
EPIC_TITLE=$(gh issue view $EPIC_NUMBER --repo semicolon-devteam/docs --json title --jq '.title')

Epic에서 추출할 정보:

| 섹션 | spec.md 매핑 | |------|-------------| | Problem Statement | Background, Problem Statement | | Goals | Goals & Non-goals | | User Scenarios | User Stories | | Constraints | Technical Constraints | | Success Metrics | Success Criteria |

spec.md 생성

# {Feature Name} Specification

## Background
{Epic의 Problem Statement - 현재 상황}

## Problem Statement
{Epic의 Problem Statement - 문제점, 영향}

## Goals & Non-goals

### Goals
- **Primary**: {Epic의 Primary Goal}
- **Secondary**: {Epic의 Secondary Goal}

### Non-goals
- {Epic의 Non-goals}

## User Stories
{Epic의 User Scenarios를 User Story 형식으로 변환}

## Technical Constraints
{Epic의 Constraints}

## Acceptance Criteria
{Epic의 Success Metrics 기반 AC}

🔴 Phase 2: Plan (plan.md)

# {Feature Name} Implementation Plan

## Overview
{spec.md 요약}

## Technical Approach
{기술 스택, 아키텍처 결정}

## Dependencies
{외부 의존성, 선행 작업}

## Risk Assessment
{기술적 리스크, 대안}

🔴 Phase 3: Tasks (tasks.md + DDD Layer 분해)

DDD Layer 기반 Task 분해

Layer 순서: CONFIG → PROJECT → DATA → TESTS → CODE

| Layer | 버전 | 설명 | 예시 Task | |-------|------|------|----------| | CONFIG | v0.1.x | 환경 설정, 의존성 | 패키지 설치, 환경변수 | | PROJECT | v0.2.x | 프로젝트 구조 | 폴더 구조, 라우팅 | | DATA | v0.3.x | 데이터 스키마, API | DB 스키마, API 엔드포인트 | | TESTS | v0.4.x | 테스트 작성 | 유닛 테스트, E2E | | CODE | v0.5.x | 비즈니스 로직 | UI 컴포넌트, 핵심 기능 |

Layer별 정보 선별 위임

| Layer | 위임할 Dev Checklist | 위임할 Constraints | |-------|---------------------|-------------------| | CONFIG | - | 기술적.의존성 | | PROJECT | - | 기술적.아키텍처 | | DATA | 데이터 흐름, 시간/계산 | 기술적.데이터 | | TESTS | 엣지 케이스 | - | | CODE | 플랫폼 제약, 도메인 지식 | 기술적.플랫폼 |

tasks.md 생성

# {Feature Name} Tasks

## Task Overview

| ID | Layer | Task | Complexity | Dependencies |
|----|-------|------|------------|--------------|
| T1 | v0.1.x CONFIG | 환경 설정 | S | - |
| T2 | v0.2.x PROJECT | 폴더 구조 생성 | S | T1 |
| T3 | v0.3.x DATA | DB 스키마 정의 | M | T2 |
| T4 | v0.5.x CODE | UI 컴포넌트 구현 | L | T3 |

## Task Details

### T1: [v0.1.x CONFIG] 환경 설정
- **Complexity**: S
- **Dependencies**: -
- **Description**: {상세 설명}
- **Acceptance Criteria**: {AC 목록}

🔴 Phase 4: Issues (Task Issues 생성)

Task Issue 본문 템플릿

## 📋 {task_description}

## 🔄 Speckit Progress
- [x] specify → [spec.md]({spec_url})
- [x] plan → [plan.md]({plan_url})
- [x] tasks → [tasks.md]({tasks_url})
- [ ] implement

## 🎯 Problem Context
<!-- Epic에서 위임 (이 Task 관련 부분만) -->
{Epic Problem Statement에서 관련 부분}

## 🎯 Goals
- {관련 Primary Goal}

## 👤 User Scenario
| Step | 사용자 액션 | 이 Task의 역할 |
|------|------------|---------------|
| {N} | {액션} | {역할} |

## ⚠️ Constraints
### 기술적 제약
- {이 Layer 관련 제약}

### 개발자 체크리스트
- [ ] {해당 카테고리 항목}

## 🎯 Acceptance Criteria
- [ ] {AC 1}
- [ ] {AC 2}

## 🧪 테스트 요구사항
### 엔지니어 테스트
- [ ] {테스트 케이스}: {예상 결과}

### QA 테스트
| Step | Action | Expected |
|------|--------|----------|
| 1 | {동작} | {결과} |

## 🔗 Dependencies
- Depends on: #{issue}
- Blocks: #{issue}

## 📊 Metadata
| Field | Value |
|-------|-------|
| Layer | {v0.x.x LAYER} |
| Domain | {domain} |
| Epic | #{epic_number} |

GitHub 연동

# 1. Task Issue 생성
TASK_NUMBER=$(gh issue create \
  --repo semicolon-devteam/{project_repo} \
  --title "[v0.1.x CONFIG] {task_title}" \
  --body "$TASK_BODY" \
  --label "{project_label}" \
  | grep -oE '[0-9]+$')

# 2. Projects에 추가
ISSUE_NODE_ID=$(gh api repos/semicolon-devteam/{project_repo}/issues/$TASK_NUMBER \
  --jq '.node_id')

ITEM_ID=$(gh api graphql -f query='
  mutation($projectId: ID!, $contentId: ID!) {
    addProjectV2ItemById(input: {projectId: $projectId, contentId: $contentId}) {
      item { id }
    }
  }
' -f projectId="PVT_kwDOC01-Rc4AtDz2" -f contentId="$ISSUE_NODE_ID" \
  --jq '.data.addProjectV2ItemById.item.id')

# 3. Issue Type을 Task로 설정
gh api graphql -f query='
  mutation {
    updateIssue(input: {
      id: "'"$ISSUE_NODE_ID"'"
      issueTypeId: "IT_kwDOC01-Rc4BdOub"
    }) {
      issue { id title }
    }
  }
'

# 4. Status를 "검수대기"로 설정
STATUS_RESULT=$(gh api graphql -f query='
query {
  organization(login: "semicolon-devteam") {
    projectV2(number: 1) {
      field(name: "Status") {
        ... on ProjectV2SingleSelectField {
          id
          options { id name }
        }
      }
    }
  }
}')

STATUS_FIELD_ID=$(echo "$STATUS_RESULT" | jq -r '.data.organization.projectV2.field.id')
STATUS_OPTION_ID=$(echo "$STATUS_RESULT" | jq -r '.data.organization.projectV2.field.options[] | select(.name == "검수대기") | .id')

gh api graphql -f query='
  mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
    updateProjectV2ItemFieldValue(input: {
      projectId: $projectId
      itemId: $itemId
      fieldId: $fieldId
      value: { singleSelectOptionId: $optionId }
    }) {
      projectV2Item { id }
    }
  }
' -f projectId="PVT_kwDOC01-Rc4AtDz2" \
  -f itemId="$ITEM_ID" \
  -f fieldId="$STATUS_FIELD_ID" \
  -f optionId="$STATUS_OPTION_ID"

🔴 Branch Context (필수)

Spec 작성은 반드시 dev 브랜치에서 수행합니다.

| 조건 | 설명 | |------|------| | 필수 브랜치 | dev | | 금지 브랜치 | main, master, feature/* |

Output Format

Speckit 완료

[SEMO] Skill: generate-spec 완료

## 📋 Speckit 결과

### Epic
- 번호: #{epic_number}
- 제목: {epic_title}

### 생성된 파일
- specs/{feature}/spec.md
- specs/{feature}/plan.md
- specs/{feature}/tasks.md

### 생성된 Task Issues

| Layer | Task | Issue |
|-------|------|-------|
| v0.1.x CONFIG | {task_1} | #{issue_1} |
| v0.2.x PROJECT | {task_2} | #{issue_2} |
| v0.3.x DATA | {task_3} | #{issue_3} |
| v0.5.x CODE | {task_4} | #{issue_4} |

### Speckit 상태
모든 Task에 Speckit 체크리스트 포함:
- [x] specify → spec.md
- [x] plan → plan.md
- [x] tasks → tasks.md
- [ ] implement

### 다음 단계
1. **Spec 커밋**: `git add specs/ && git commit -m "📝 Add spec for {feature}"`
2. **구현 시작**: Feature 브랜치에서 구현

Issue Title Format

[v0.1.x CONFIG] Set up project dependencies
[v0.2.x PROJECT] Create folder structure for comments
[v0.3.x DATA] Define comment schema and API
[v0.5.x CODE] Implement comment UI components

Issue Type ID Reference

| Type | ID | 사용 시점 | |------|-----|----------| | Task | IT_kwDOC01-Rc4BdOub | 일반 태스크 (기본값) | | Bug | IT_kwDOC01-Rc4BdOuc | 버그 리포트 | | Feature | IT_kwDOC01-Rc4BdOud | 기능 요청 | | Epic | IT_kwDOC01-Rc4BvVz5 | 에픽 생성 시 |

Usage

// Epic 기반 전체 Speckit 실행 (권장)
skill: generate-spec({ epic: 144 });

// 자연어 트리거
"태스크 만들어줘"
"spec 작성해줘"
"태스크카드 생성해줘"

// 특정 Phase만 실행
skill: generate-spec({ epic: 144, phase: "specify" });
skill: generate-spec({ epic: 144, phase: "tasks" });

Related Skills

• ideate - 러프한 아이디어 → Epic (이 스킬 전에 호출)
• create-epic - Epic Issue 생성 헬퍼
• implement - 구현 단계 (이 스킬 후에 호출)
• explore-approach - 기술 불확실성 탐색 (spike)

References

• Phase Details - Phase 1-4 상세
• Layer Delegation - Layer별 정보 위임 상세
• Output Format - 완료 리포트 형식