Generate a design document for a Jira task. Analyzes the codebase, references the planning document, then generates a structured design document. Use when user says "design task", "create design", "jira-task design", "설계 문서", "디자인 문서", or wants to design the implementation of a Jira issue.
모든 출력을 한국어로 작성한다: 사용자 응답, 생성 문서, Jira 코멘트 내용 등 모든 텍스트가 대상이다. 예외: 코드, 변수명, 브랜치명, 파일명, 명령어는 영어를 유지한다. Jira 코멘트: 섹션 제목(##, ###)은 영어로, 내용(설명·요약·노트)은 한국어로 작성한다.
docs/plan/<TASK-ID>.plan.md exists
/jira-task plan <TASK-ID> first (but proceed if user wants)mcp__atlassian__jira_get_issue to fetch current issue detailsUse Glob and Grep to understand the existing codebase:
Plan 문서 + 코드베이스 분석 결과를 기반으로 docs/design/<TASK-ID>.design.md 생성.
문서에 포함할 내용:
impl 단계에서만 작성impl 단계에서 구현과 함께 작성할 수 있을 정도로 구체적이어야 함Use mcp__atlassian__jira_add_comment to post:
## Design Document Created
이슈에 대한 기술 설계 문서가 생성되었습니다.
**아키텍처:**
- <주요 아키텍처 결정 사항>
**수정 파일:**
- <주요 파일 목록>
**테스트 전략:**
- <간단한 테스트 방식>
문서 경로: docs/design/<TASK-ID>.design.md
생성한 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")
.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>` — 설계 기반으로 구현을 시작합니다
---