---
title: 사람과 AI가 함께 읽는 Jira 티켓 — 템플릿과 자동화로 입력 품질 높이기
description: 티켓 성격에 맞는 템플릿으로 필요한 맥락은 놓치지 않고, 불필요한 정보는 걷어낸 과정.
series: harness-engineering
seriesOrder: 2
publishedAt: 2026-06-29
tags: [harness-engineering, claude-code, ai-coding, jira, team-process]
period: 2026.04 ~ 2026.05
techStack: [Claude Code, Jira, Figma, Bitbucket]
draft: false
internal: false
---

하네스를 만들면 AI 작업 흐름이 꽤 균일해질 거라고 생각했습니다.

`/plan`으로 계획을 세우고, `/step`으로 구현하고, `/review`로 점검하는 흐름을 만들었으니까요. 그런데 실제 작업에 적용해보니 결과는 티켓마다 달랐습니다. 어떤 티켓은 바로 계획이 잡혔고, 어떤 티켓은 `/plan` 단계에서 질문과 탐색이 계속 늘어났습니다.

차이는 모델이나 하네스가 아니라, 작업을 시작하기 전에 주어진 **Jira 티켓의 포맷과 맥락 정보**에 있었습니다. 티켓이 잘 정리되어 있으면 사람도 빠르게 이해했고, AI 에이전트도 덜 헤맸습니다. 반대로 맥락이 Figma 댓글이나 회의 기억 속에 흩어져 있으면, 같은 워크플로우를 돌려도 질문과 탐색 비용이 커졌습니다.

이 글은 Jira 티켓을 성격별로 나누고, 필요한 맥락이 빠지지 않도록 템플릿과 자동화로 정리한 과정입니다.

---

## 문제 — 같은 하네스, 다른 결과

처음에는 하네스의 질문 방식이나 모델 설정을 더 조정해야 한다고 생각했습니다. 하지만 작업 기록을 다시 보니 차이는 더 앞단에 있었습니다.

차이는 티켓이 작업의 맥락을 얼마나 잘 담고 있느냐였습니다. 잘 풀린 작업은 배경과 목적, 변경 가설, 확정된 요구사항, 검증 절차가 티켓 안에서 구분되어 있었습니다. 반대로 헤맨 작업은 필요한 정보가 Figma 댓글, 회의 기억, 이전 PR 사이에 흩어져 있었고, 확정된 요구사항과 아직 논의 중인 내용이 한데 섞여 있었습니다.

같은 프로젝트 안에서도 차이는 분명했습니다.

| 구분 | 정리된 티켓 | 정리되지 않은 티켓 |
| --- | --- | --- |
| 기획 맥락 | 배경, 목적, 변경 가설이 보임 | 왜 바꾸는지 티켓만으로 알기 어려움 |
| 요구사항 | 확정된 내용과 논의사항이 분리됨 | 결정된 내용과 의견이 섞여 있음 |
| 참고 정보 | 화면, 컴포넌트, API, 이전 작업이 연결됨 | Figma 댓글, 회의 기억, PR을 다시 찾아야 함 |
| 검증 기준 | 확인할 플로우와 완료 기준이 있음 | 무엇을 확인해야 끝나는지 모호함 |
| `/plan` 결과 | 영향 범위를 잡고 구현 계획으로 진입 | 배경 탐색과 재질문부터 반복 |

결국 같은 하네스, 같은 모델을 써도 입력이 정리되어 있으면 바로 계획을 세울 수 있었고, 입력이 비어 있으면 먼저 맥락을 복원해야 했습니다.

---

## 판단 — 티켓을 입력 계약으로 본다

이 문제를 프롬프트만으로 풀기는 어려웠습니다. 티켓에 필요한 맥락이 빠져 있으면 사람도 다시 물어봐야 하고, AI 에이전트도 같은 자리에서 질문과 탐색을 반복합니다. 반대로 작업 배경, 참고 화면, 관련 컴포넌트, API 정보가 한곳에 정리되어 있으면 계획 수립과 영향 범위 파악이 훨씬 빨라졌습니다.

그래서 다음 개선 방향은 하네스를 더 복잡하게 만드는 일이 아니라, **하네스에 들어가는 입력인 티켓을 표준화하는 것**이었습니다.

핵심은 모든 티켓을 하나의 양식으로 밀어붙이지 않는 것이었습니다. 티켓 종류에 따라 필요한 맥락이 달랐기 때문입니다. 버그에는 재현 절차가 필요하고, 개선에는 기대 효과와 변경 범위가 필요하고, 개발 하위 일감에는 기술적 판단과 구현 메모가 필요했습니다.

또 하나의 현실적인 이유도 있었습니다. 하네스가 Figma나 Jira의 외부 맥락을 항상 안정적으로 읽어주지는 못했습니다. Figma 링크를 본문에 그냥 붙이면 못 읽고 넘어가는 경우가 있었고, Figma 안의 댓글·주석에 들어있는 결정 사항은 인식하지 못했습니다. 도구 쪽을 붙잡고 고치는 대신, **티켓 안에 맥락을 남기는 방식**을 바꾸기로 했습니다.

---

## 티켓 성격에 맞게 문서 구조를 나누다

티켓을 하나의 공통 양식으로 통일하지는 않았습니다. 버그, 개선, 에픽, 개발 하위 일감은 읽는 목적도 다르고 필요한 정보도 달랐기 때문입니다. 그래서 먼저 티켓의 성격을 나누고, 각 성격마다 반드시 보여야 하는 항목을 정했습니다.

| 종류 | 언제 쓰나 | 주요 작성 주체 |
|------|-----------|-----------|
| 기본 운영 일감 | 일상 운영 / 단건 작업 | 기획/PM 중심 |
| 에픽 (프로젝트) | 여러 일감을 묶는 프로젝트 단위 | 기획/PM 중심 |
| 버그 | 기대 동작과 다르게 동작하는 문제 | 기획/PM 중심 |
| 개선 | 기존 기능의 품질 / 경험 개선 | 기획/PM 중심 |
| 개발 하위 일감 | 개발자가 직접 작성하는 테크 스펙 | 개발자 중심 |

각 티켓에서 필요한 정보를 기준으로, 기본 섹션을 정했습니다.

| 티켓 종류 | 기본으로 넣은 섹션 |
| --- | --- |
| 버그 | 현재 동작, 기대 동작, 재현 절차, 발생 환경, 참고 화면/로그/링크 |
| 개선 | 문제 배경, 기대 효과, 변경 범위, 영향받는 화면, 완료 기준 |
| 개발 하위 일감 | 구현 방향, 참고 컴포넌트/API, 영향 범위, 확인할 케이스, 제외할 범위 |

각 템플릿은 별도 문서로만 두지 않고, **[Jira 자동화](https://www.atlassian.com/ko/software/jira/guides/automation/overview#what-is-automation)**로 티켓 종류에 맞는 섹션 플레이스홀더가 설명란에 들어가도록 설정했습니다.

출발점은 에이전트의 `/plan` 효율이었지만, 실제로 줄이고 싶었던 건 팀이 일감을 파악하는 데 드는 시간과 커뮤니케이션 비용이었습니다. 티켓 안에서 “무엇을 바꿔야 하는지”, “왜 바꾸는지”, “어디를 보면 되는지”, “어디까지는 하지 않아도 되는지”가 보이면 사람도 더 빨리 같은 맥락에 도달하고, 에이전트도 불필요한 탐색을 줄일 수 있습니다.

---

## 마치며

첫 버전은 최종 규칙이 아니라, 팀이 써보며 조정하기 위한 기준선에 가까웠습니다. 버그 티켓의 구조를 잡기 쉬워졌다는 피드백도 있었고, Jira 자동화가 바로 반영되지 않아 새로고침이 필요하다는 사용성 이슈도 발견했습니다. 템플릿은 앞으로도 실제 사용 경험에 맞춰 계속 바뀔 예정입니다.

좋은 입력은 한 번 규약을 정한다고 완성되지 않습니다. 팀이 실제로 쓰면서 빠지는 항목과 불필요한 항목을 발견하고, 템플릿과 자동화를 계속 조정해야 합니다. AI를 잘 쓰는 일도 결국은 사람이 이미 알고 있는 맥락을 더 잘 전달하는 구조를 만드는 일에 가까웠습니다.

---

## 같이 보면 좋은 글

- [Claude Code 에이전트를 우리 팀처럼 일하게 만드는 법](./01-overview) — 시리즈 마스터 글