jira-plan

name	jira-plan
description	jira-plan — Jira 이슈와 프로젝트 코드를 분석하여 스택 최고 개발자 페르소나로 개발 가이드 MD 파일(docs/<ISSUE-KEY>-dev-guide.md)을 생성합니다. 구현 계획이 필요할 때, '계획 세워줘', '개발 가이드 만들어줘', '플랜 짜줘', 'dev-guide 생성', '이슈 분석해줘', 'jira plan', '어떻게 구현할지 설계해줘' 등의 요청에 이 스킬을 사용하세요. harness-workflow 의 start·grill 단계 이후, /jira-execute 이전에 사용합니다 (구 /jira-start·/jira-clarify 는 2026-07-20 폐기).

jira-plan — Jira 이슈 분석 및 개발 가이드 MD 생성

Jira 이슈와 프로젝트 코드를 분석하여, 스택 최고 개발자 페르소나로 개발 가이드 MD 파일을 생성합니다. 지라에 댓글이나 설명을 작성할 때에는 한글로 작성합니다.

Usage

/jira-plan <ISSUE-KEY>

• ISSUE-KEY: Jira 이슈 키 (예: PROJ-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:, :[,,], :{
  :{:}, :{:,:[,]},
  :{:, :{:, :[,,],
  :{:{:,:[,]},:{:},:{:}}}} } }

()



 hasWiki =     
 hasMemory =   
 issueBody =   
  = [
  { :,  :, : },
  ...(hasWiki ? [{ :, :, : }] : []),
  { :, :, : },
  ...(hasMemory ? [{ :, :, : }] : []),
]
 results = ( (.( 
  (a., { :, :, :, :, :a. })
    .( r && ({ ...r, :a. }))))).()

 map = results.( (r.||[]).( ({ ...f, :r. })))
 digest = map.( ).()

()

 draftPath = 
 draft =  (, { : })

()
 dims = [
  { :, : },
  { :, : },
]
 v = ( (dims.( 
  (x., { :, :, :, :, : })))).()
 blockers = v.( (r.||[]).( i.===).( ({ :r., ...i })))
 { issueKey, draftPath, : map., : blockers. ?  : , blockers, : draft }

호출: 위 스크립트의 HAS_WIKI/HAS_MEMORY 를 true/false 로, ISSUE_BODY 를 §2 수집 본문(백틱/줄바꿈 escape)으로 치환한 뒤 Workflow({ script: <치환본>, args: "<ISSUE-KEY>" }) 로 실행. workflow 는 백그라운드 실행이며 완료 시 결과(JSON) 가 돌아온다.

모드 (A) 후처리:

1. workflow 결과의 verdict 확인 — REVISE 면 blockers 를 사용자에게 보고하고 보강(재실행 또는 수동 수정) 후 진행
2. PASS 면 docs/<KEY>-dev-guide.md.draft 를 검토 → 문제 없으면 docs/<KEY>-dev-guide.md 로 확정(rename/저장)
3. 이후 §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: <단계명>

목표: <이 단계에서 달성할 것>

1. path/to/File.java — <구체적 변경 내용>
2. path/to/File2.java — <구체적 변경 내용>

검증: <이 단계 완료 확인 방법>

Phase 2: <단계명>

...

Phase N: 테스트

1. <테스트 대상과 방법>

4. 기술 상세

핵심 로직

<페르소나 관점에서 가장 중요한 기술적 판단 사항>

위험 요소

위험	영향도	대응 방안
<위험1>	높음/중간/낮음	<대응>

외부 연동 (있는 경우)

<Feign, API, 다른 팀 작업 필요사항>

5. 병렬 작업 가이드 (선택)

이 섹션은 독립적으로 진행 가능한 작업이 2개 이상일 때만 작성합니다.

Workflow 레인 구성 (2026-07-20 — 구 "Agent Teams 구성" supersede, Agent Teams 신규 사용 금지)

⚠️ 이 표를 작성하면 jira-execute § 4A(dynamic Workflow 병렬 모드)가 진입 — 각 행이 Workflow agent() 레인 1개가 된다. 모든 레인에 model 을 명시(BE 복잡 도메인=opus / FE·기계적=sonnet — 미지정=메인 모델 상속 함정) + 웨이브 시작 시 모델 스모크 프로브. 공통 계약(DTO/interface/migration)은 Phase 0 scaffold 로 메인이 선행. 레인 간 합의가 필요 없는 disjoint fan-out 이 아니면 § 5 섹션 자체를 작성하지 말고 Phase 를 순차 설계하세요. 상세: harness-workflow/references/parallel-modes.md.

레인	담당 범위 (touched files)	model	subagent 타입
<레인1>	<파일/모듈>	opus/sonnet	<agent-type 또는 없음>
<레인2>	<파일/모듈>	opus/sonnet	<agent-type 또는 없음>

작업 의존성

Phase 0 scaffold (메인 직접)  →  Phase 1 (레인 병렬)  →  Phase 2 (Phase 1 완료 후)
  ├─ Task A (레인-1)
  └─ Task B (레인-2)

파일 충돌 방지

<어떤 레인이 어떤 파일을 소유하는지 명시 — 겹치면 같은 레인으로 클러스터링 또는 worktree 격리>

#### 병렬 작업 가이드 작성 기준

다음 **모든** 조건을 충족할 때만 "5. 병렬 작업 가이드" 섹션을 작성합니다:

1. 독립적으로 작업 가능한 모듈/파일 그룹이 **2개 이상**
2. 각 그룹 간 **파일 충돌이 없음** (동일 파일을 수정하지 않음)
3. 병렬 작업으로 **실질적 시간 단축** 효과가 있음 (단순 파일 2-3개 수정은 순차가 나음)
4. Agent Teams 코디네이션 오버헤드 대비 **이점이 명확함**

충족하지 않으면 Phase를 순차적으로 설계하고, 섹션 자체를 생략합니다.

### 5. Jira 코멘트 및 결과 출력

#### Jira 코멘트

📋 개발 가이드 생성 완료

📝 파일: docs/-dev-guide.md 🔧 스택: <감지된 스택> 📊 영향 범위: <수정 대상 파일 수>개 파일

주요 변경사항:

• <핵심 변경 1>
• <핵심 변경 2>

구현 단계: <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

> ⚠️ **2026-07-20 표면 폐지 (ADR-106)**: `--subtasks` 플래그 표면은 폐기 — 이 섹션은 하위이슈 **미러 규칙**(전이 동기화·짧은 댓글)으로만 유효하며, harness-workflow 가 플래그 없이 수행한다 (`_subtasks-convention.md` §7). slice 병렬 실행 단위는 Workflow 레인 (`harness-workflow/references/parallel-modes.md`).

사용자가 `/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