jira-task-design

jira-task-design: Generate Design Document

Language Rule

모든 출력을 한국어로 작성한다: 사용자 응답, 생성 문서, Jira 코멘트 내용 등 모든 텍스트가 대상이다. 예외: 코드, 변수명, 브랜치명, 파일명, 명령어는 영어를 유지한다. Jira 코멘트: 섹션 제목(##, ###)은 영어로, 내용(설명·요약·노트)은 한국어로 작성한다.

Workflow

Step 1: Check Prerequisites

1. Check if docs/plan/<TASK-ID>.plan.md exists
   • If yes, read it for context
   • If no, suggest running /jira-task plan <TASK-ID> first (but proceed if user wants)
2. Use mcp__atlassian__jira_get_issue to fetch current issue details

Step 2: Analyze Codebase

Use Glob and Grep to understand the existing codebase:

• Find related files by searching for keywords from the issue summary
• Identify existing patterns (architecture, naming conventions, file structure)
• Check for existing similar implementations that can be referenced
• Note the tech stack and frameworks in use

Step 3: Generate Design Document

Plan 문서 + 코드베이스 분석 결과를 기반으로 docs/design/<TASK-ID>.design.md 생성.

문서에 포함할 내용:

• Architecture: 관련 컴포넌트/모듈 구조
• Sequence Diagram: 주요 플로우 (Mermaid 형식)
• Implementation Plan: 구현 순서와 파일별 변경 사항 요약
  • 각 파일에 대해 "무엇을 변경하는지"를 1-2줄로 기술 (예: "인증 미들웨어 추가", "API 엔드포인트 정의")
  • 코드 작성 금지: 실제 코드 스니펫, 함수 구현체, 클래스 정의 등을 포함하지 않음. 코드는 impl 단계에서만 작성
  • 필요한 인터페이스/타입은 이름과 역할만 기술 (시그니처 수준까지만 허용)
• Error Handling: 에러 시나리오와 처리 전략
• Security Checklist: 해당하는 보안 고려사항
• Test Plan: 테스트 전략 및 구체적 테스트 케이스 명세
  • Unit test: 함수/모듈별 테스트 케이스 목록 (입력, 기대 결과, 경계 조건)
  • E2E test: 사용자 시나리오별 테스트 케이스 (해당하는 경우)
  • 각 케이스는 impl 단계에서 구현과 함께 작성할 수 있을 정도로 구체적이어야 함
  • 테스트 케이스도 코드가 아닌 명세(설명) 수준으로 작성

Step 4: Post Summary to Jira

Use mcp__atlassian__jira_add_comment to post:

## Design Document Created

이슈에 대한 기술 설계 문서가 생성되었습니다.

**아키텍처:**
- <주요 아키텍처 결정 사항>

**수정 파일:**
- <주요 파일 목록>

**테스트 전략:**
- <간단한 테스트 방식>

문서 경로: docs/design/<TASK-ID>.design.md

Step 4.5: Attach Design Document to Jira

생성한 docs/design/<TASK-ID>.design.md를 Jira 이슈에 첨부파일로 업로드:

# 1. 자격증명 확보 (환경변수 → .mcp.json → ~/.claude.json → settings)
JIRA_URL="${JIRA_URL:-}"
JIRA_USERNAME="${JIRA_USERNAME:-}"
JIRA_API_TOKEN="${JIRA_API_TOKEN:-}"

if [ -z "$JIRA_URL" ]; then
  _root="$(git rev-parse --show-toplevel 2>/dev/null)"
  # worktree인 경우 .jira-context.json의 repoRoot 사용
  if [ -f ".jira-context.json" ]; then
    _ctx_root=$(node -e "try{console.log(require('./.jira-context.json').repoRoot||'')}catch{console.log('')}" 2>/dev/null)
    [ -n "$_ctx_root" ] && _root="$_ctx_root"
  fi
  _top='const m=s.mcpServers?.atlassian||s.mcpServers?.jira||{};'
  _proj='const p=Object.values(s.projects||{}).find(p=>p.mcpServers?.atlassian||p.mcpServers?.jira);const pm=p?(p.mcpServers.atlassian||p.mcpServers.jira):{};'
  _env='const e=(m.env&&m.env.JIRA_URL?m:pm).env||{}'
  _extract="${_top}${_proj}${_env}"
  # $HOME(MSYS2: /c/Users/...)도, os.homedir()(Win: C:\Users\...)도
  # Node.js require() 안에서 문제 발생 → 슬래시 변환 필수
  _home=$(node -p "require('os').homedir().split(String.fromCharCode(92)).join('/')")
  for _f in "${_root}/.mcp.json" "${_home}/.claude.json" "${_root}/.claude/settings.local.json" "${_home}/.claude/settings.json"; do
    [ -f "$_f" ] || continue
    JIRA_URL=$(node -e "const s=require('$_f');${_extract};console.log(e.JIRA_URL||'')" 2>/dev/null)
    [ -n "$JIRA_URL" ] || continue
    JIRA_USERNAME=$(node -e "const s=require('$_f');${_extract};console.log(e.JIRA_USERNAME||'')" 2>/dev/null)
    JIRA_API_TOKEN=$(node -e "const s=require('$_f');${_extract};console.log(e.JIRA_API_TOKEN||'')" 2>/dev/null)
    break
  done
fi

# 2. 첨부파일 업로드
AUTH=$(printf '%s:%s' "$JIRA_USERNAME" "$JIRA_API_TOKEN" | base64 | tr -d '\n')
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
  -H "Authorization: Basic $AUTH" \
  -H "X-Atlassian-Token: no-check" \
  -F "file=@docs/design/<TASK-ID>.design.md" \
  "${JIRA_URL}/rest/api/3/issue/<TASK-ID>/attachments")

• HTTP 200: 첨부 성공
• 그 외: 업로드 실패를 사용자에게 알리고 계속 진행 (로컬 파일 경로 안내)

Step 5: Completion Summary

.jira-context.json의 completedSteps에 "design" 추가 후, 아래 형식으로 완료 요약 출력:

---
✅ **Design Complete** — <TASK-ID>

- 설계 문서 생성: `docs/design/<TASK-ID>.design.md`
- Jira 코멘트 게시됨
- Jira 첨부파일 업로드됨 (또는 실패 시 로컬 경로 안내)

**Progress**: init → start → plan → **design ✓** → impl → test → review → merge → pr → done

**Next**: `/jira-task impl <TASK-ID>` — 설계 기반으로 구현을 시작합니다
---