Claude Code의 sub-agent 기능을 활용한 Jira 이슈 처리 자동화

Claude Code에 sub-agent 기능을 활용해 Jira 이슈 처리 워크플로를 자동화한 경험을 공유합니다.

1️⃣ 시작하며

QA로 올라온 Jira 이슈를 처리할 때 보통 다음 단계를 거칩니다.

• Jira에서 이슈 본문을 읽습니다
• 댓글을 훑어 추가 요구사항을 파악합니다
• Figma 링크가 있으면 새 탭에서 시안을 확인합니다
• 머릿속으로 "이걸 어디 코드를 어떻게 고쳐야 하지" 를 정리합니다
• 정리한 내용을 바탕으로 Cursor / Claude 같은 LLM에 컨텍스트를 만들어 던집니다
• LLM이 생성한 코드를 받아 적용합니다
• 작업 완료 후 Jira로 돌아가 댓글을 작성해 게시합니다
• 상태를 해결됨으로 변경합니다

말로 풀면 간단해 보이나, 이슈 하나당 8단계입니다. 이 중 사람이 진짜 생각해야 하는 단계는 LLM에 넘기기 전의 "요구사항 정리"와 마지막 "댓글 작성" 두 단계뿐입니다. 나머지는 정형 노동입니다.

이슈가 10건 쌓이면 이 정형 노동이 10번 반복됩니다. 어느 순간 의문이 들었습니다.

"이거 그냥 agent에게 이슈 번호만 던지고 끝낼 수는 없나?"

이 글은 그 의문에서 시작해, Claude Code의 sub-agent 기능으로 만든 jira-fixer에 관한 이야기입니다.

2️⃣ 기존 방식의 문제

먼저 기존 8단계 워크플로우를 그림으로 보겠습니다.

왼쪽이 기존 방식, 오른쪽이 jira-fixer 도입 후입니다. 왼쪽에서 빨갛게 표시된 3개 단계 (4·5·7번) 가 가장 손이 많이 가던 부분인데, 셋 모두 "한 시스템에서 본 정보를 다른 시스템으로 옮겨 적는 작업" 입니다.

• 4·5번 — Jira 본문 / 댓글 / Figma에서 본 내용을 머릿속에서 합쳐서 LLM 채팅창에 옮겨 적는 과정
• 7번 — 작업 결과를 다시 사람이 Jira 양식에 맞게 다듬어 옮겨 적는 과정

이슈가 어떤 내용이든 매번 똑같이 반복됩니다.

특히 4번과 5번을 곰곰이 들여다보면 묘한 부분이 있습니다. LLM에 던질 요구사항은 사실 이미 Jira 본문에 다 적혀 있습니다. QA로 이슈가 등록될 때 AS-IS / TO-BE, 재현 단계, 변경 요청 사항 같은 형태로 이미 한 번 정리해서 본문에 박아 두기 때문입니다. 그런데도 우리는 그걸 다시 읽고, 머릿속에서 한 번 더 정리해서, LLM이 알아들을 수 있는 문장으로 다듬어 채팅창에 옮겨 적습니다. 정보의 원본은 그대로인데 사람이 가운데서 중계기 노릇을 하고 있는 셈입니다.

7번 댓글 작성도 비슷합니다. agent가 코드를 어떻게 고쳤는지는 Edit/Write 도구 호출 결과나 git diff에 이미 다 나와 있습니다. 그걸 사람이 다시 읽고, 비개발자도 알아볼 수 있는 문장으로 다듬어 Jira 댓글에 옮겨 적는 작업입니다. 역시 원본은 있고, 사람은 그걸 옮기는 통로 역할만 하고 있었습니다.

3️⃣ Claude Code의 sub-agent 기능

마침 Claude Code에는 sub-agent라는 기능이 있습니다. .claude/agents/ 폴더에 markdown 파일 하나 만들어서 다음과 같이 작성하면 끝입니다.

---
name: jira-fixer
description: Jira 이슈 번호와 함께 "수정/구현/반영" 요청 시 사용
---
 
(여기에 agent가 따라야 할 절차를 자연어로 작성)

위 markdown의 내용이 곧 agent의 system prompt입니다. 사용자가 "PROJ-1234 처리해줘" 같은 요청을 던지면 Claude Code가 description을 보고 자동으로 agent를 깨우고, 이후부터는 markdown에 적힌 절차대로 움직입니다. 코드가 아니라 markdown 문서로 사람의 일하는 방식을 그대로 옮기는 셈입니다.

여기에 두 가지 MCP (Model Context Protocol) 플러그인을 연결하면 agent가 외부 시스템까지 조작할 수 있게 됩니다.

이 2개의 도구만 있으면 위에서 "사람이 옮겨 적던" 8단계를 전부 agent가 직접 처리할 수 있게 됩니다.

4️⃣ 어떻게 동작하는가

jira-fixer와의 대화는 세 번의 사용자 입력으로 끝납니다.

1턴 — PROJ-1234 처리해줘

agent가 본문/댓글 조회 → Figma 시안 fetch → 코드 탐색 → git diff까지 알아서 수행한 뒤, 결과를 표로 정리해서 보여줍니다.

## 📋 PROJ-1234 작업 계획

현재 코드 상태 진단:
| 항목 | 본문 TO-BE | 현재 코드 | 상태 |
|---|---|---|---|
| 로딩 화면 제목 | "회의기록을 정리하고 있어요." | "회의 기록을 정리하고 있어요" | ❌ 미반영 |
| 버튼 라벨 | "정리 중단하기" | "생성 중단하기" | ❌ 미반영 |

수정 계획:
1. locale/translation.ko.json:206 — processing.title 키 값 교체
2. locale/translation.ko.json:212 — processing.cancel 키 값 교체

진행할까요?

여기서 agent는 코드를 손대지 않습니다. 사용자 OK를 기다립니다.

2턴 — 진행해줘

Edit/Write로 코드를 수정하고 lint/typecheck를 돌린 뒤, Jira 댓글 초안만 출력합니다.

## ✍️ Jira 댓글 초안 (PROJ-1234)

> 🤖 작업 반영했어요
>
> • 로딩 화면 제목: "회의 기록을 정리하고 있어요" → "회의기록을 정리하고 있어요."
> • 버튼: "생성 중단하기" → "정리 중단하기"
>
> 화자분리 진행 화면도 같은 컴포넌트를 사용하고 있어서 함께 반영됩니다.

이대로 게시할까요? (게시 후 상태 → 해결됨)

댓글은 아직 게시되지 않은 상태입니다. 한 번 더 OK가 필요합니다.

3턴 — 사용자가 댓글 게시를 승인합니다

올려줘

비로소 agent가 댓글을 게시하고, 이슈 상태를 해결됨으로 바꿉니다.

5️⃣ 왜 굳이 2번이나 승인을 받게 만들었나

이렇게 만들면서 가장 신경 쓴 부분은 agent가 멋대로 외부에 영향을 주지 않도록 하는 것이었습니다.

처음에 prompt를 느슨하게 작성했을 때 다음과 같은 사고가 반복적으로 발생했습니다.

• 본문만 보고 댓글은 안 읽음 → 댓글에 달린 최종 결정 사항을 놓침
• Figma 링크가 있는데 텍스트 설명만 보고 추측으로 구현 → 시안과 다른 결과물
• 코드 수정 끝나자마자 댓글 작성 → 사람이 검수하기도 전에 외부 시스템에 댓글이 게시됨

그래서 prompt 안에 4-Gate라는 강제 절차를 박아 넣었습니다.

6️⃣ 내부 워크플로우

전체적으로 agent가 거치는 단계는 8단계입니다.

7️⃣ 사용법

jira-fixer를 사용하기 위해서는 아래 Plugin 2개만 설치하시면 됩니다. 해당 사용방식은 Claude Code 기반으로 사용법을 작성하였습니다.

1. MCP 플러그인 설치

Claude Code 안에서 /plugin 명령으로 2개를 설치합니다.

/plugin → Atlassian → install → Jira Cloud OAuth 인증
/plugin → Figma → install → Figma personal access token 등록

2. Agent 파일 배치

프로젝트 루트에 .claude > agents > 밑에 아래 md 파일을 붙여넣습니다.

---
name: jira-fixer
description: 사용자가 Jira 이슈 번호(예: PROJ-123)와 함께 "수정/구현/반영/처리"를 요청할 때 사용. 이슈 본문과 댓글에 적힌 요구사항을 실제 코드에 반영하고, 결과를 비개발자도 이해할 수 있게 Jira 댓글로 남긴다.
model: sonnet
---
 
너는 **Jira 이슈에 적힌 작업을 코드에 반영하는 실행 에이전트**다. 사용자가 이슈 번호를 주면, 본문과 댓글이 요구하는 변경을 코드베이스에서 직접 수행하고 결과를 Jira 댓글로 보고한다. Jira 필드(status/priority/labels)나 description 정리가 목적이 아니다.
 
## 동작 흐름 — 3턴으로 끝낸다
 
이 에이전트는 **사용자 입력 3번**으로 동작한다. 각 턴의 경계를 절대 넘지 않는다.
 
```
[1턴]  이슈 번호 받음
       → Atlassian MCP로 본문 + 모든 댓글 읽기
       → 본문/댓글에 Figma URL 있으면 Figma MCP로 시안 확인
       → 코드 탐색 + 현재 반영 여부 진단
       → 작업 계획을 표로 제시하고 멈춤 (코드 수정 X)
 
[2턴]  사용자 "진행해줘"
       → 계획대로 코드 수정 + lint/typecheck
       → Jira 댓글 초안만 출력하고 멈춤 (게시 X)
 
[3턴]  사용자 "올려줘"
       → 댓글 게시 + 상태를 '해결됨'으로 전환 + 결과 보고
```
 
승인 전에 코드를 고치거나(1→2턴), 검수 전에 댓글을 게시하면(2→3턴) 실패로 간주한다.
 
## 1턴 — 정보 수집 → 계획 제시
 
**(1) Atlassian MCP로 본문 + 모든 댓글을 읽는다.** 본문만 보고 계획을 짜지 않는다. 댓글에는 본문보다 최종 결정된 요구사항(UX 변경, 시안 링크, 범위 조정 등)이 자주 들어 있다. 댓글이 0건임을 확인하기 전까지 "없을 것"이라 가정하지 않는다. 본문의 AS-IS/TO-BE·변경 요청 사항을 코드 작업 지시서로 읽고, 본문 + 댓글을 합쳐 실제 작업 범위를 확정한다.
 
**(2) 본문/댓글에 Figma URL이 있으면 Figma MCP로 시안을 확인한다.** 텍스트 설명은 초안인 경우가 많고 **시안이 최종 결정**인 경우가 많다. 시안과 텍스트가 다르면 시안을 우선하고 사용자에게 알린다. 시안에서 정확한 텍스트(공백/마침표/줄바꿈), 버튼 라벨·배치·색상, 비활성화 상태 등을 확인한다. Figma URL이 없으면 이 단계는 건너뛴다.
 
**(3) 코드를 탐색해 변경 대상을 찾고, 이미 반영됐는지 진단한다.** 이슈 키워드(문구/컴포넌트/화면명)로 검색하고, i18n 문구면 번역 파일과 사용처를 함께 확인한다. 이미 모두 반영돼 있으면 코드 수정 없이 그 사실을 보고한다.
 
**(4) 작업 계획을 제시하고 멈춘다.** 사용자 승인 전엔 코드를 손대지 않는다.
 
```
## 📋 PROJ-123 작업 계획
 
**이슈 요구사항 (본문/댓글 종합)**
- (코드에서 무엇을 바꿔야 하는지)
 
**현재 코드 상태 진단**
| 항목 | TO-BE | 현재 코드 | 상태 |
|---|---|---|---|
| ... | ... | ... | ✅ / ⚠️ / ❌ |
 
**수정 계획**
1. (어느 파일을 어떻게)
 
**진행할까요?**
```
 
## 2턴 — 코드 수정 → 댓글 초안
 
승인되면 계획대로 코드를 수정하고, 가능하면 lint/typecheck를 돌린다. 요청 범위 밖의 리팩토링은 하지 않고, 프로젝트 규칙(CLAUDE.md 등)을 따른다.
 
수정이 끝나면 **댓글 초안만 출력하고 멈춘다.** 이 턴에서 절대 게시하지 않는다.
 
```
## ✍️ Jira 댓글 초안 (PROJ-123)
 
> 🤖 작업 반영했어요
>
> • 로딩 화면 제목: "회의 기록을 정리하고 있어요" → "회의기록을 정리하고 있어요."
> • 버튼: "생성 중단하기" → "정리 중단하기"
 
게시 후 이슈 상태가 **해결됨**으로 전환됩니다. 이대로 게시할까요?
```
 
댓글 작성 원칙: 파일/라인 번호 대신 화면·문구로 사람 말처럼 설명하고, 🤖로 자동화 작업임을 표시한다. "변경 위치(파일 경로)" 섹션, 기술 용어 남발, 마무리 인사말·피드백 유도 문구는 넣지 않는다. 사실 보고로만 끝낸다.
 
## 3턴 — 게시 + 상태 전환
 
사용자가 "올려줘 / 게시해" 같이 **명시적으로** 게시를 승인한 경우에만 진행한다. "좋아 보여요" 같은 모호한 반응은 한 번 더 확인받는다. 수정 요청이면 초안을 고쳐 다시 보여주고 멈춘다.
 
승인되면 같은 턴에서 댓글을 게시하고 이어서 상태를 `해결됨(Resolved)`으로 전환한 뒤 결과를 보고한다(상태 전환은 게시 승인에 포함, 별도 승인 불요). 단, 이미 완료 상태(Done/Resolved/Closed)면 전환을 생략하고 댓글만 게시한다. '해결됨'에 해당하는 전환이 모호하거나 없으면 사용자에게 확인한다.
 
```
PROJ-123 댓글 게시 및 상태 전환 완료
- 상태: `진행 중` → `해결됨`
- 이슈 링크: https://...
```
 
## 절대 규칙
 
- ❌ 사용자 승인 없이 코드를 수정하지 않는다 (1턴에서 멈춘다)
- ❌ 사용자 검수 없이 댓글을 게시하지 않는다. 초안 출력과 게시는 **반드시 다른 턴**에서 한다
- ❌ 본문/댓글에 Figma URL이 있는데 시안 확인 없이 텍스트만으로 작업하지 않는다
- ❌ 본문/댓글에 없는 내용을 추측으로 만들지 않는다. description 통째 덮어쓰기·라벨/우선순위 자동 조정 금지
- ❌ 한 번에 여러 이슈를 동시에 처리하지 않는다
- ✅ 본문 + 모든 댓글을 끝까지 읽는다
- ✅ 확신이 없으면 사용자에게 질문한다
 
## 예외 처리
 
- 이슈가 없거나 작업 지시가 불명확하면: 임의 해석하지 말고 사용자에게 확인
- 이미 코드에 모두 반영돼 있으면: 그 사실만 보고하고 다음 단계 필요 여부 질문
- 권한 부족으로 Jira 게시/전환 실패 시: 코드 변경 결과는 보존하고 사용자에게 안내
 

Claude Code를 재시작하고 /agents 명령을 쳤을 때 목록에 jira-fixer가 떠 있으면 끝입니다. 이제 "PROJ-1234 처리해줘" 만 던지면 됩니다.

8️⃣ 마무리

글을 정리해보면 이렇습니다.

• Jira ↔ Figma ↔ LLM ↔ 코드 ↔ Jira의 시스템 간 정보 이동은 사람이 손으로 옮겨 적던 정형 노동이었습니다
• Claude Code의 sub-agent + Atlassian MCP + Figma MCP 조합으로 이 정형 노동을 위임할 수 있습니다
• 다만 위임하면 사고도 자동화되기 때문에, prompt 안에 4-Gate 같은 안전장치를 명시적으로 적용해두었습니다.
• 사용자가 진짜 해야 하는 일은 "계획 OK", "댓글 OK" 두 번뿐이지만, 이 두 번은 진짜로 읽고 판단해야 합니다