| name | jira-plan |
| description | jira-plan — Jira 이슈와 프로젝트 코드를 분석하여 스택 최고 개발자 페르소나로 개발 가이드 MD 파일(docs/<ISSUE-KEY>-dev-guide.md)을 생성합니다. 구현 계획이 필요할 때, '계획 세워줘', '개발 가이드 만들어줘', '플랜 짜줘', 'dev-guide 생성', '이슈 분석해줘', 'jira plan', '어떻게 구현할지 설계해줘' 등의 요청에 이 스킬을 사용하세요. /jira-start 및 /jira-clarify 이후, /jira-execute 이전에 사용합니다. |
jira-plan — Jira 이슈 분석 및 개발 가이드 MD 생성
Jira 이슈와 프로젝트 코드를 분석하여, 스택 최고 개발자 페르소나로 개발 가이드 MD 파일을 생성합니다.
지라에 댓글이나 설명을 작성할 때에는 한글로 작성합니다.
Usage
/jira-plan <ISSUE-KEY>
ISSUE-KEY: Jira 이슈 키 (예: SURINP-156, SCRUM-42)
Procedure
1. 스택 감지 및 페르소나 활성화
작업 디렉토리에서 프로젝트 스택을 자동 감지하고, 해당 스택의 시니어 전문가 페르소나를 즉시 활성화합니다. 감지 매핑 + 스택별 페르소나는 ~/.claude/skills/_stack-detection.md §1 + §2 참조.
페르소나가 활성화되면, 이후 모든 분석과 가이드 작성에 해당 페르소나의 관점이 적용됩니다.
2. Jira 이슈 심층 분석
MCP Atlassian 도구로 이슈 정보를 수집합니다:
mcp__atlassian__getJiraIssue → 이슈 상세 (제목, 설명, 우선순위, 라벨)
mcp__atlassian__searchJiraIssuesUsingJql → 관련 이슈/서브태스크 조회
수집하는 정보:
- 이슈 설명, 인수조건(Acceptance Criteria)
- 댓글 (특히 최신 댓글에 추가 요구사항이 있는 경우)
- 서브태스크 또는 체크리스트
- 관련 이슈 (linked issues)
- 첨부파일 목록 (있으면)
3·4 수행 모드 선택 — ultracode workflow vs 인라인
아래 §3 코드 분석 + §4 dev-guide 생성 은 두 모드 중 하나로 수행한다. 프로젝트·이슈 규모에 따라 자동 판단:
| 모드 | 진입 조건 | 방식 |
|---|
| (A) ultracode workflow | Workflow 기능 사용 가능(disableWorkflows≠true, 지원 버전) AND 영향 범위가 넓음(키워드상 다수 모듈/파일·교차 도메인) | Workflow 툴로 코드+위키+이슈+memory multi-modal fan-out → structured map → dev-guide 초안 → 반박 검증 |
| (B) 인라인 (기본·하위호환) | 위 조건 미충족 / 소규모 이슈 / workflow 비활성 | 메인 세션이 §3·§4 를 직접 수행 (아래 절차) |
트리거 워드 (2026-06 변경): workflow → ultracode. 이 모드의 명칭이 "ultracode workflow" 다. jira-plan 이 (A) 로 진입하는 것 자체가 Workflow 툴 opt-in 으로 인정되므로(Workflow 툴 규칙 — "사용자가 invoke 한 skill/슬래시 커맨드의 지시가 Workflow 를 호출하라고 하면 그게 opt-in"), 사용자가 프롬프트에 ultracode 를 따로 타이핑하지 않아도 위 진입 조건만 충족하면 자동 트리거된다.
(B) 가 기본값이다. Workflow 가 불확실하면 (B). (A) 는 "범위가 커서 컨텍스트 폭발이 우려될 때" 의 최적화이지 의무가 아니다.
(A) ultracode workflow 모드 — Understand / Design / Verify
⚠️ 범용 — 특정 프로젝트 경로를 하드코딩하지 말 것. 아래 축은 프로젝트에 실제 존재하는 소스만 포함한다 (조건부). 산출물은 docs/<KEY>-dev-guide.md.draft 로 저장 → 메인 세션이 검토 후 확정 rename. 위키 쓰기(jira-ingest)·사용자 승인은 workflow 밖(§6 / 호출자).
축 구성 (해당하는 것만):
code — 스택 자동 감지된 소스 디렉토리(§1) 영향 파일·기존 패턴·충돌 지점 (항상)wiki — docs/INDEX.md cross-ref + ADR(예: docs/08-decision-log.md)의 "NEVER 재도입 금지" 류 제약 + 유사 dev-guide 선례 → docs/INDEX-SCHEMA.md 존재 시에만issue — §2 에서 수집한 Jira 본문/AC 를 프롬프트로 주입 (항상)memory — 프로젝트 memory 인덱스가 있으면 (~/.claude/projects/<slug>/memory/MEMORY.md) 관련 함정 수집 → 있을 때만
Workflow 툴에 전달할 스크립트 골격 (issueKey·축 목록·수집한 이슈 본문을 채워서 호출):
export const meta = {
name: 'jira-plan-understand',
description: 'jira-plan Understand/Design/Verify — multi-modal sweep → dev-guide 초안 → 제약·영향범위 반박 검증',
phases: [{ title: 'Understand' }, { title: 'Design' }, { title: 'Verify', model: 'sonnet' }],
}
const issueKey = (typeof args === 'string' ? args : args?.issueKey)?.trim()
const FINDINGS = { type:'object', required:['axis','findings'], properties:{
axis:{type:'string'}, findings:{type:'array', items:{type:'object', required:['kind','ref','note'],
properties:{kind:{type:'string'},ref:{type:'string'},note:{type:'string'}}}} } }
const VERIFY = { type:'object', required:['dimension','verdict','issues'], properties:{
dimension:{type:'string'}, verdict:{type:'string',enum:['PASS','REVISE']},
issues:{type:'array', items:{type:'object', required:['severity','detail','evidence'],
properties:{severity:{type:'string',enum:['blocker','advisory']},detail:{type:'string'},evidence:{type:'string'}}}} } }
phase('Understand')
const hasWiki = HAS_WIKI
const hasMemory = HAS_MEMORY
const issueBody = ISSUE_BODY
const AXES = [
{ axis:'code', model:'sonnet', prompt:`${issueKey} 영향 파일·기존 패턴·충돌 지점을 스택 소스 디렉토리에서 READ ONLY 수집. kind=impacted-file|pattern, ref=파일경로:라인.` },
...(hasWiki ? [{ axis:'wiki', model:'sonnet', prompt:`${issueKey} 의 docs/INDEX.md cross-ref + ADR "NEVER 재도입 금지" 류 제약 + 유사 dev-guide 선례 수집(READ ONLY). kind=constraint|precedent, ref=ADR-NNN|STD-NNN|파일경로. 중복/모순 위험을 note 에.` }] : []),
{ axis:'issue', model:'haiku', prompt:`다음 이슈 요구사항·AC 를 정리: ${issueBody}. kind=requirement, ref=AC 번호 또는 ${issueKey}.` },
...(hasMemory ? [{ axis:'memory', model:'haiku', prompt:`${issueKey} 영역의 알려진 함정을 프로젝트 memory 인덱스에서 수집(READ ONLY). kind=trap, ref=memory slug.` }] : []),
]
const results = (await parallel(AXES.map(a => () =>
agent(a.prompt, { label:`understand:${a.axis}`, phase:'Understand', schema:FINDINGS, agentType:'Explore', model:a.model })
.then(r => r && ({ ...r, _axis:a.axis }))))).filter(Boolean)
const map = results.flatMap(r => (r.findings||[]).map(f => ({ ...f, axis:r._axis })))
const digest = map.map(f => `- [${f.axis}/${f.kind}] ${f.ref} — ${f.note}`).join('\n')
phase('Design')
const draftPath = `docs/${issueKey}-dev-guide.md.draft`
const draft = await agent(`너는 이 스택의 시니어다. 아래 map 근거로 ${issueKey} dev-guide 초안을 §4 템플릿 구조로 작성해 ${draftPath} 에 Write 하라. wiki constraint(ADR NEVER 룰)는 "준수"로 명시.\n## map\n${digest}`, { phase:'Design' })
phase('Verify')
const dims = [
{ d:'constraint-violation', p:`${draftPath} 가 ADR "NEVER 재도입 금지" 류 제약을 위반하는지 REFUTE. 위반=severity:blocker+evidence:ADR. 없으면 PASS.\n${map.filter(f=>f.kind==='constraint').map(f=>`- ${f.ref}: ${f.note}`).join('\n')||'(없음)'}` },
{ d:'scope-completeness', p:`${draftPath} 영향범위가 불완전한지 REFUTE. code sweep impacted-file 중 누락/연쇄영향. 누락=blocker+evidence:파일. 완전하면 PASS.\n${map.filter(f=>f.axis==='code').map(f=>`- ${f.ref}: ${f.note}`).join('\n')||'(없음)'}` },
]
const v = (await parallel(dims.map(x => () =>
agent(x.p, { label:`verify:${x.d}`, phase:'Verify', schema:VERIFY, agentType:'Explore', model:'sonnet' })))).filter(Boolean)
const blockers = v.flatMap(r => (r.issues||[]).filter(i => i.severity==='blocker').map(i => ({ dimension:r.dimension, ...i })))
return { issueKey, draftPath, findings: map.length, verdict: blockers.length ? 'REVISE' : 'PASS', blockers, designSummary: draft }
호출: 위 스크립트의 HAS_WIKI/HAS_MEMORY 를 true/false 로, ISSUE_BODY 를 §2 수집 본문(백틱/줄바꿈 escape)으로 치환한 뒤 Workflow({ script: <치환본>, args: "<ISSUE-KEY>" }) 로 실행. workflow 는 백그라운드 실행이며 완료 시 결과(JSON) 가 돌아온다.
모드 (A) 후처리:
- workflow 결과의
verdict 확인 — REVISE 면 blockers 를 사용자에게 보고하고 보강(재실행 또는 수동 수정) 후 진행
PASS 면 docs/<KEY>-dev-guide.md.draft 를 검토 → 문제 없으면 docs/<KEY>-dev-guide.md 로 확정(rename/저장)- 이후 §5·§6·§7 은 모드와 무관하게 동일하게 수행 (Jira 코멘트, wiki ingest forecast, 결과 출력)
모델 티어링 (performance.md 정합 — fan-out 워커는 경량 티어로 고정, 합성만 세션 최상위 모델 상속):
| 단계 | agent | 작업 성격 | model |
|---|
| Understand | code · wiki | 소스 영향·cascade 분석 / ADR "NEVER" 제약 탐지 (false-negative = blocker 누락) | sonnet |
| Understand | issue · memory | 주입된 이슈 본문 요약 / memory 인덱스 함정 retrieval (저난도) | haiku |
| Design | (합성) | dev-guide 초안 작성 — 시니어 페르소나, 추론 부담 최상 | 상속 (model 생략 → 세션 모델) |
| Verify | constraint · scope | 반박(REFUTE) 검증 — 통과 오판이 곧 누락 blocker | sonnet |
- Design 만
model 미지정 → 세션 최상위(현재 Opus / Sonnet 세션이면 Sonnet)를 상속. 사용자가 세션 모델로 "합성 품질 상한"을 제어하고, 워커는 명시 티어로 고정해 Opus 토큰 낭비를 막는다. (워크플로 agent() 기본값이 메인 루프 모델 상속이라, 과거 전 에이전트가 Opus로 뜬 건 세션이 Opus였기 때문.)
agentType:'Explore' 와 조합 시 model 이 Explore 정의의 frontmatter 모델보다 우선하므로 티어링이 확실히 적용된다.- 더 보수적:
code/wiki·verify 를 haiku 로 내림(비용↓, ADR 제약 누락 위험↑). 더 공격적: verify 를 상속(세션 Opus)으로 올림(반박 강도↑).
조정 가능(PoC 기본은 보수적): verifier 차원당 1명 → 신뢰도 필요 시 차원당 N=3 다수결, code 축 → BE/FE 2-reader 분할.
(B) 인라인 모드 — 프로젝트 코드 분석
페르소나 관점에서 관련 코드를 분석합니다:
3-1. CLAUDE.md 확인
- 프로젝트 아키텍처, 도메인 모듈, 핵심 규칙 파악
- 참조 문서(
.claude/docs/reference/)가 있으면 관련 문서 읽기
3-2. 영향 범위 파악
- 이슈 설명에서 키워드 추출 → 관련 파일 검색 (Grep/Glob)
- 수정 대상 Entity, DTO, Service, Controller, Repository 식별
- 연관된 테스트 파일 확인
3-3. 의존성 분석
- 수정 대상 코드의 호출 관계 (누가 호출하는지, 무엇을 호출하는지)
- DB 스키마 변경 필요 여부
- 외부 연동 (Feign, API) 영향 여부
- 기존 테스트 영향 여부
4. 개발 가이드 MD 파일 생성
docs/ 디렉토리에 <ISSUE-KEY>-dev-guide.md 파일을 생성합니다.
MD 파일 템플릿
# [<ISSUE-KEY>] <이슈 제목> — 개발 가이드
> 생성일: <날짜>
> 스택: <감지된 스택>
> 페르소나: <활성화된 페르소나명>
## 1. 요구사항 요약
### 비즈니스 목표
<이슈 설명에서 추출한 핵심 목표 2-3줄>
### 인수조건
- [ ] <AC1>
- [ ] <AC2>
- [ ] <AC3>
### 제약사항 / 주의사항
<기존 코드, 비즈니스 규칙, 성능 제약 등>
## 2. 영향 범위 분석
### 수정 대상 파일
| 파일 | 변경 유형 | 설명 |
|------|----------|------|
| `path/to/File.java` | 수정 | <변경 내용> |
| `path/to/NewFile.java` | 신규 | <생성 이유> |
### 연관 파일 (읽기 전용 — 수정하지 않지만 이해 필요)
| 파일 | 참조 이유 |
|------|----------|
| `path/to/Related.java` | <참조 이유> |
### DB 변경 (있는 경우)
```sql
-- DDL
ALTER TABLE ...
-- 마이그레이션
UPDATE ...
3. 구현 계획
Phase 1: <단계명>
목표: <이 단계에서 달성할 것>
path/to/File.java — <구체적 변경 내용>path/to/File2.java — <구체적 변경 내용>
검증: <이 단계 완료 확인 방법>
Phase 2: <단계명>
...
Phase N: 테스트
- <테스트 대상과 방법>
4. 기술 상세
핵심 로직
<페르소나 관점에서 가장 중요한 기술적 판단 사항>
위험 요소
| 위험 | 영향도 | 대응 방안 |
|---|
| <위험1> | 높음/중간/낮음 | <대응> |
외부 연동 (있는 경우)
<Feign, API, 다른 팀 작업 필요사항>
5. 병렬 작업 가이드 (선택)
이 섹션은 독립적으로 진행 가능한 작업이 2개 이상일 때만 작성합니다.
Agent Teams 구성 (권장)
⚠️ 이 표를 작성하면 jira-execute § 4A 가 자동으로 진입 — lead 가 TaskCreate × N 후 자연어로 teammate spawn(사용자 승인) → teammate 가 공유 Task self-claim + SendMessage 협업 (v2.1.178+ : TeamCreate/team_name 없이 팀 자동 형성. lead 가 Agent() 를 직접 도구 호출하면 sub-agent 로 회귀). 단 self-claim 협업은 interactive claude 터미널 전제 — SDK/통합앱/CI 환경이면 jira-execute § 4A 진입 가드가 § 4A-FB(sub-agent fan-out)로 분기한다. 진짜 협업(teammate 간 contract 합의)이 필요 없는 disjoint fan-out 이면 § 5 섹션 자체를 작성하지 말고 Phase 를 순차 설계하세요. 자세한 패턴은 jira-execute/SKILL.md § 4A 의 ⚠️ 안티패턴 박스 참조.
| 역할 | 담당 범위 | subagent 타입 |
|---|
| <역할1> | <파일/모듈> | <agent-type 또는 없음> |
| <역할2> | <파일/모듈> | <agent-type 또는 없음> |
작업 의존성
Phase 1 (독립) → Phase 2 (Phase 1 완료 후)
├─ Task A (teammate-1)
└─ Task B (teammate-2)
파일 충돌 방지
<어떤 teammate가 어떤 파일을 소유하는지 명시>
#### 병렬 작업 가이드 작성 기준
다음 **모든** 조건을 충족할 때만 "5. 병렬 작업 가이드" 섹션을 작성합니다:
1. 독립적으로 작업 가능한 모듈/파일 그룹이 **2개 이상**
2. 각 그룹 간 **파일 충돌이 없음** (동일 파일을 수정하지 않음)
3. 병렬 작업으로 **실질적 시간 단축** 효과가 있음 (단순 파일 2-3개 수정은 순차가 나음)
4. Agent Teams 코디네이션 오버헤드 대비 **이점이 명확함**
충족하지 않으면 Phase를 순차적으로 설계하고, 섹션 자체를 생략합니다.
### 5. Jira 코멘트 및 결과 출력
#### Jira 코멘트
📋 개발 가이드 생성 완료
📝 파일: docs/-dev-guide.md
🔧 스택: <감지된 스택>
📊 영향 범위: <수정 대상 파일 수>개 파일
주요 변경사항:
구현 단계: <Phase 수>단계
#### 터미널 출력
📋 개발 가이드 생성 완료
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 파일: docs/-dev-guide.md
🔧 스택: <감지된 스택>
👤 페르소나: <페르소나명>
📊 분석 결과:
수정 대상: 개 파일
신규 생성: 개 파일
DB 변경: <있음/없음>
외부 연동: <있음/없음>
📐 구현 계획: <Phase 수>단계
<각 Phase 한줄 요약>
병렬 작업: <가능/불필요>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
다음 단계: /jira-execute
### 6. Wiki Ingest 자동 Chain (forecast 단계) — **MANDATORY**
> ⛔ **이 단계는 선택 사항 아님.** dev-guide 가 막 생성된 시점은 wiki INDEX 에 forecast entry 를 등록하는 **유일한 정상 시점**이다. `docs/INDEX-SCHEMA.md` 가 존재하는데 본 chain 을 누락하면 wiki 가 drift 한다 (orphan dev-guide, planned 누락 → 이후 closure 단계에서 row 가 갑자기 튀어나오는 비대칭).
>
> 본 절은 §1~§5 가 끝난 직후 **반드시** 실행한다. 사용자에게 "ingest 할까요?" 라고 물어보지 않는다 (조용한 누락 방지 — 명시적 `--no-ingest` 플래그만 인정).
>
> Karpathy LLM Wiki 패턴 적용 프로젝트는 `docs/INDEX-SCHEMA.md` 존재로 식별.
조건: docs/INDEX-SCHEMA.md 존재 AND 사용자가 --no-ingest 플래그 전달 안 함
호출: Skill('jira-ingest', ' forecast 모드로 ingest — dev-guide 가 방금 생성됨')
`--subtasks` 모드면 flag 자동 전파 (`_subtasks-convention.md` § 7 패턴):
Skill('jira-ingest', ' forecast --subtasks')
**자기 점검 (skill 종료 직전 last-mile check)**:
1. `docs/INDEX-SCHEMA.md` 존재? → 존재하면 본 §6 chain 호출 흔적이 conversation 에 있어야 함
2. 호출 흔적 없으면 → **지금 즉시 호출** + 사용자에게 "§6 chain 누락 감지 → 사후 호출함" 1줄 보고
3. 그래도 호출 못 한 사유 (skill 부재 등) 가 있으면 사용자에게 명시 경고
**조건 미충족 시 (wiki 미설정 프로젝트) 만 skip**:
- `docs/INDEX-SCHEMA.md` 부재 → "wiki 미설정 프로젝트 — ingest skip" 한 줄 로그만 출력
- jira-ingest 가 first-run onboarding 으로 진입하지 않도록 **jira-plan 안에서는 호출 자체를 skip** (사용자가 명시적으로 wiki 셋업 의도를 보일 때만 first-run flow 진입이 자연스러움)
**실패 격리**: ingest chain 실패해도 jira-plan 자체는 PASS — 위 §5 결과 출력은 이미 완료된 상태. 실패 시 경고만 출력하고 다음 단계 (/jira-execute) 안내 계속. 단 실패 자체는 **반드시 사용자에게 가시화** — 조용한 skip 금지.
### 7. 결과 출력 (Wiki ingest 후 보강)
§5 출력에 다음 라인 1개 추가 (ingest chain 이 호출된 경우만):
📚 Wiki ingest: forecast 등록 완료 (INDEX.md row added, LOG.md append)
ingest 가 skip 된 경우:
📚 Wiki ingest: skip (docs/INDEX-SCHEMA.md 부재 — wiki 미설정)
## Error Handling
- 이슈가 존재하지 않으면 오류 메시지 출력
- 스택을 감지할 수 없으면 사용자에게 스택 입력 요청
- CLAUDE.md가 없으면 경고 후 코드 분석만으로 진행
- 영향 범위가 너무 넓으면 (20개 파일 초과) 사용자에게 범위 축소 확인
## Notes
- 생성된 MD 파일은 `/jira-execute`에서 직접 소비하도록 설계됨
- CLAUDE.md에 프로젝트별 규칙이 있으면 가이드에 반영
- 페르소나는 "조언자"가 아닌 "실무자" — 추상적 조언이 아닌 **구체적인 파일 경로와 코드 변경** 제시
- 이미 `docs/<ISSUE-KEY>-dev-guide.md`가 존재하면 덮어쓸지 사용자에게 확인
## --subtasks Mode
사용자가 `/jira-plan <KEY> --subtasks` 로 호출하고 부모 이슈에 하위 작업이 있으면, 부모 dev-guide 처리 후 **추가로**:
1. 부모 dev-guide (`docs/<KEY>-dev-guide.md`) 에 § DAG / § Cross-cutting 결정 / § slice 진입점 표 포함
2. 각 하위 키마다 slice dev-guide 작성: `docs/<KEY>-<SUB-KEY>-dev-guide.md` (ADR-070 형식 — `### 0. Touched Files` 섹션 의무)
3. **각 하위 이슈에 짧은 댓글** 추가:
📝 dev-guide 작성 완료: docs/<KEY>-<SUB-KEY>-dev-guide.md
부모 통합 가이드: docs/<KEY>-dev-guide.md
4. 출력에 부모 + 하위별 dev-guide 경로 표 포함
자세한 정책: `~/.claude/skills/_subtasks-convention.md` § 3, § 5
