# Smart Linear Issue

> Linear 이슈 생성/수정/코멘트 기능을 제공하는 스킬. 한글 키워드 ("이슈 생성", "이슈 수정", "코멘트 추가") 및 영문 키워드 ("create issue", "update issue", "add comment")로 자동 활성화. Gitmoji 기반 한글 제목과 사용자 승인 필수 워크플로우로 일관된 이슈 관리를 지원합니다.

- Skill: `muheun/smart-linear-issue` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add muheun/smart-linear-issue`
- Raw SKILL.md: https://api.skillmd.com/api/skills/muheun/smart-linear-issue/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: muheun (https://skillmd.com/u/muheun)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/muheun/smart-linear-issue

---


# Smart Linear Issue

Linear MCP 서버를 활용하여 Gitmoji 기반 한글 이슈를 생성/수정하고, 작업 히스토리를 코멘트로 기록하는 스킬입니다.

## When to Use This Skill

**Auto-activate when users request Linear issue operations:**

### 이슈 생성 트리거
한글:
- "이슈 생성해줘" / "이슈 만들어줘" / "이슈 등록"
- "Linear 이슈 생성" / "버그 리포트" / "새 태스크"
- "티켓 만들어" / "이슈 추가"

영문:
- "create issue" / "new issue" / "add issue"
- "create Linear issue" / "bug report" / "new task"

### 이슈 수정 트리거
한글:
- "이슈 수정해줘" / "이슈 업데이트"
- "우선순위 변경" / "상태 변경" / "담당자 변경"
- "이슈 상태 바꿔줘"

영문:
- "update issue" / "modify issue"
- "change priority" / "change status" / "assign to"

### 코멘트 추가 트리거 (작업 히스토리)
한글:
- "코멘트 추가" / "작업 기록" / "히스토리 추가"
- "진행상황 업데이트" / "작업 로그"

영문:
- "add comment" / "log work" / "add history"
- "update progress" / "work log"

**Do NOT activate for:**
- Linear 관련 일반 질문이나 설명 요청
- 이슈 목록 조회만 하는 경우
- 프로젝트/팀 정보 확인

## Workflow A: 이슈 생성

이슈 생성 요청 시 다음 단계를 순차적으로 수행합니다.

### Step 1: 요청 분석

사용자 요청에서 핵심 정보를 추출합니다.

**1.1 이슈 유형 파악:**
- 버그/오류 → 🐛 bug
- 새 기능 → ✨ feature
- 리팩토링 → ♻️ refactor
- 문서 → 📝 docs
- 성능 → ⚡ perf
- 디자인/UI → 🎨 design
- 설정/환경 → 🔧 config
- 테스트 → ✅ test
- 보안 → 🔒 security

**1.2 핵심 내용 추출:**
- 문제 상황 또는 구현할 기능
- 영향 범위
- 기대 동작

*Gitmoji 선택 가이드: `references/gitmoji_mapping.md`*

### Step 2: Linear 정보 조회

Linear MCP 도구로 필요한 정보를 조회합니다.

**2.1 팀 목록 조회:**
```
mcp__linear-server__list_teams
```

**2.2 프로젝트/사이클/라벨 조회 (팀 선택 후):**
```
mcp__linear-server__list_projects (team 파라미터)
mcp__linear-server__list_cycles (teamId 파라미터)
mcp__linear-server__list_issue_labels (team 파라미터)
```

**2.3 사용자 목록 조회:**
```
mcp__linear-server__list_users
```

### Step 3: 이슈 내용 생성

**3.1 제목 생성:**

**Format:**
```
<gitmoji> 한글 핵심 요약 (max 50자)
```

**3.2 Description 생성:**

*템플릿 참조: `references/field_templates.md`*

**버그 템플릿:**
```markdown
## 문제 상황
[현재 발생하는 문제 설명]

## 재현 방법
1. [단계 1]
2. [단계 2]

## 기대 동작
[정상 동작 설명]

## 영향 범위
[영향받는 기능/사용자]
```

**기능 템플릿:**
```markdown
## 배경
[왜 필요한지]

## 구현 내용
- [핵심 기능 1]
- [핵심 기능 2]

## 성공 기준
[완료 조건]
```

**3.3 품질 규칙:**

✅ **MUST follow:**
- 한글 우선 (기술 용어는 영어 허용)
- 제목 50자 이내
- Description 300자 이내 권장
- 도메인 중심 언어 (기능 설명)

❌ **MUST NOT include:**
- AI 서명 (`- Claude`, `Generated by AI`, `Co-Authored-By: Claude`)
- 코드 참조 (클래스명, 메서드명, 변수명, 파일명)
- 추적 코드 (TASK-123, SC-003)

*좋은/나쁜 예시: `references/issue_examples.md`*

### Step 4: 사용자 확인 (⚠️ 필수)

**CRITICAL RULE - NEVER SKIP THIS STEP**

반드시 AskUserQuestion 도구를 사용하여 사용자 승인을 받아야 합니다.

**4.1 미리보기 표시:**

```markdown
📋 생성할 이슈:

**제목**: <gitmoji> <한글 제목>

**내용**:
<description>

---
**필드 설정**:
| 항목 | 값 |
|------|---|
| 팀 | [team name] |
| 담당자 | [assignee or "미지정"] |
| 우선순위 | [priority emoji + level] |
| 예상 소요 | [estimate or "미지정"] |
| 라벨 | [labels or "없음"] |
| 프로젝트 | [project or "미지정"] |
| 사이클 | [cycle or "미지정"] |
| 마일스톤 | [milestone or "미지정"] |
```

**4.2 옵션 제공:**

1. ✅ 이대로 생성
2. ✏️ 제목/내용 수정
3. 🔧 필드 변경
4. ❌ 취소

**4.3 사용자 선택 처리:**
- **Choice 1**: Step 5 진행
- **Choice 2**: 수정 내용 입력받고 Step 4 다시
- **Choice 3**: 필드 변경 옵션 표시 후 Step 4 다시
- **Choice 4**: 워크플로우 종료

### Step 5: 이슈 생성 실행

**5.1 이슈 생성:**
```
mcp__linear-server__create_issue
```

필수 파라미터:
- title: 생성된 제목
- team: 선택된 팀
- description: 생성된 내용

선택 파라미터 (사용자 지정 시):
- assignee, priority, estimate, labels, project, cycle, milestone

### Step 6: 결과 보고

**성공:**
```
✅ 이슈 생성 완료

📋 이슈 ID: [identifier]
🔗 URL: [issue URL]
👤 담당자: [assignee]
📊 우선순위: [priority]
```

**실패:**
```
❌ 이슈 생성 실패

원인: [error message]
확인 사항:
- 팀 접근 권한
- 필수 필드 누락
- Linear 연결 상태
```

## Workflow B: 이슈 수정

### Step 1: 이슈 확인

**1.1 이슈 ID 확인:**
- 사용자가 제공한 ID 사용
- 또는 최근 이슈 목록에서 선택

**1.2 현재 상태 조회:**
```
mcp__linear-server__get_issue (id, includeRelations: true)
```

### Step 2: 변경 사항 분석

사용자 요청에서 변경할 필드를 파악합니다.

**변경 가능 필드:**
- title: 제목
- description: 내용
- state: 상태 (Backlog, Todo, In Progress, Done, Canceled)
- assignee: 담당자
- priority: 우선순위 (0-4)
- estimate: 예상 소요
- labels: 라벨
- project: 프로젝트
- cycle: 사이클

### Step 3: 변경 미리보기 (⚠️ 필수)

**CRITICAL RULE - NEVER SKIP THIS STEP**

**3.1 변경사항 표시:**

```markdown
📝 이슈 수정 미리보기

**이슈**: [identifier] - [현재 제목]

**변경 내용**:
| 필드 | 현재 값 | → | 새 값 |
|------|---------|---|-------|
| [field] | [old] | → | [new] |
```

**3.2 옵션 제공:**

1. ✅ 변경 적용
2. ✏️ 다른 필드도 수정
3. ❌ 취소

### Step 4: 이슈 수정 실행

```
mcp__linear-server__update_issue
```

### Step 5: 상태 변경 시 코멘트 제안 (✨ 신규 기능)

상태가 변경된 경우, 관련 코멘트 작성을 제안합니다.

**In Progress 변경 시:**
```markdown
💡 작업 시작 코멘트를 추가할까요?

제안 내용:
---
## 🚀 작업 시작
- 시작 일시: [현재 날짜/시간]
- 예상 완료: [estimate 기반 또는 미정]
- 접근 방식: [간단한 계획]
---

선택:
1. ✅ 코멘트 추가
2. ✏️ 내용 수정 후 추가
3. ⏭️ 건너뛰기
```

**Done 변경 시:**
```markdown
💡 완료 보고 코멘트를 추가할까요?

제안 내용:
---
## ✅ 작업 완료
- 완료 일시: [현재 날짜/시간]
- 구현 내용: [변경 요약]
- 테스트: [검증 방법]
---

선택:
1. ✅ 코멘트 추가
2. ✏️ 내용 수정 후 추가
3. ⏭️ 건너뛰기
```

### Step 6: 결과 보고

```
✅ 이슈 수정 완료

📋 이슈: [identifier]
🔗 URL: [issue URL]
📝 변경된 필드: [changed fields]
```

## Workflow C: 코멘트 추가 (작업 히스토리)

### Step 1: 이슈 확인

```
mcp__linear-server__get_issue (id)
mcp__linear-server__list_comments (issueId)
```

### Step 2: 코멘트 내용 생성

**2.1 기본 구조:**

```markdown
## [이모지] [작업 유형]

**날짜**: [YYYY-MM-DD]

### 진행 상황
- [완료한 작업 1]
- [완료한 작업 2]

### 다음 단계
- [예정 작업]

### 차단 요소 (있는 경우)
- [블로커 설명]
```

**2.2 작업 유형별 이모지:**
- 🚀 작업 시작
- 📝 진행 상황 업데이트
- ✅ 작업 완료
- 🔍 조사/분석 완료
- ⚠️ 블로커 발생
- 💡 해결책 발견

### Step 3: 사용자 확인

**3.1 미리보기:**

```markdown
💬 추가할 코멘트:

이슈: [identifier] - [title]

---
[코멘트 내용]
---

선택:
1. ✅ 이대로 추가
2. ✏️ 내용 수정
3. ❌ 취소
```

### Step 4: 코멘트 생성 실행

```
mcp__linear-server__create_comment (issueId, body)
```

### Step 5: 결과 보고

```
✅ 코멘트 추가 완료

📋 이슈: [identifier]
💬 코멘트 ID: [comment id]
📅 작성 시간: [timestamp]
```

## Edge Cases

### 팀/프로젝트 선택
- 팀이 여러 개인 경우 → 선택 옵션 제공
- 프로젝트 미지정 요청 → 프로젝트 없이 생성

### 이슈 ID 확인
- ID 형식 오류 → 올바른 형식 안내 (예: ABC-123)
- 이슈 없음 → 검색 또는 목록 제공

### 권한 오류
- 팀 접근 권한 없음 → 관리자 연락 안내
- 수정 권한 없음 → 담당자/생성자 확인 안내

### 네트워크 오류
- Linear API 연결 실패 → 재시도 또는 나중에 시도 안내

## Checklist

### 이슈 생성 전:
- [ ] 사용자가 명시적으로 이슈 생성 요청
- [ ] 이슈 유형 파악 완료
- [ ] 적절한 Gitmoji 선택
- [ ] 한글 제목 (50자 이내)
- [ ] 도메인 중심 언어 사용 (코드 참조 없음)
- [ ] AI 서명 없음
- [ ] 사용자 승인 완료

### 이슈 수정 전:
- [ ] 이슈 ID 확인
- [ ] 현재 상태 조회 완료
- [ ] 변경 내용 미리보기 표시
- [ ] 사용자 승인 완료

### 코멘트 추가 전:
- [ ] 이슈 ID 확인
- [ ] 코멘트 내용 미리보기 표시
- [ ] 사용자 승인 완료

## References

상세 참조 자료:

- **`references/gitmoji_mapping.md`** - 이슈 타입별 Gitmoji 매핑 및 선택 가이드
- **`references/field_templates.md`** - 필드 템플릿, 우선순위, 예상 소요 기준
- **`references/issue_examples.md`** - 좋은/나쁜 이슈 예시 및 변환 사례

## Integration with MY_RULES.md

이 스킬은 MY_RULES.md 규칙을 준수합니다:

✅ **Enforced:**
- 한글 우선 사용 (제목, 내용, 코멘트)
- AI 서명 절대 금지
- 사용자 승인 필수 (생성/수정 전)
- 도메인 중심 언어 (코드 참조 금지)

✅ **Triggers:**
- "이슈 생성", "이슈 수정", "코멘트 추가"
- "create issue", "update issue", "add comment"

✅ **Quality:**
- Gitmoji + 한글 제목 자동 생성
- 50자 제목 제한 준수
- 300자 내용 권장
- 사용자 승인 워크플로우