Jira 중복 티켓
효율적인 관리, AI로 시작하다
[ Github: https://github.com/james-kanghj/jira-ai-duplicate-detector.git ]
프로젝트가 커질수록 Jira 이슈의 수는 기하급수적으로 늘어나고, 그 과정에서 중복된 티켓은 자연스럽게 발생합니다.
하지만 중복 티켓을 적시에 식별하고 관리하지 못하면, 개발 일정, 테스트 일정, 그리고 팀 간 협업에도 심각한 혼란과 비효율을 초래할 수 있습니다.
특히, 서로 다른 팀, 다른 관점에서 작성된 이슈라도 같은 도메인 내에서는 비슷한 문제를 다루는 경우가 많습니다.
이런 유사 이슈를 초기에 파악하고 체계적으로 정리하는 것은 QA 엔지니어의 품질 관리 핵심 역량 중 하나라고 생각합니다.
그러나 현실은 쉽지 않습니다.
수백 개, 수천 개에 이르는 이슈를 사람이 일일이 확인하는 것은 시간 소모가 매우 크고, 놓치는 경우도 많기 때문입니다.
그래서, AI를 활용해 중복 이슈를 자동 탐지하고 싶다는 실질적인 필요성에서 이 프로젝트를 시작하게 되었습니다.
Jira AI Duplicate Detector는 바로 이 문제를 해결하기 위한 시작입니다.
시스템 설계 배경
이 프로젝트는 Python을 기반으로 설계되었습니다.
중복 이슈를 자동으로 탐지하기 위해, 텍스트 의미를 수치화하고 비교할 수 있는 방법이 필요했습니다.
그래서 선택한 것이 OpenAI의 text-embedding-ada-002 모델입니다.
이 모델은 이슈의 제목과 설명을 합쳐 하나의 문장으로 처리하고, 이를 벡터 형태로 임베딩(Embedding) 하는 데 최적화되어 있습니다.
이 과정을 통해, 각 이슈는 단순한 문자열이 아닌, 의미를 내포한 수치적 표현으로 변환됩니다.
변환된 임베딩 벡터들 간의 코사인 유사도(Cosine Similarity)를 계산하여 0.98 이상의 유사도를 보이는 경우 중복 이슈로 판단합니다.
[선택 이유]
사람이 일일이 읽지 않아도, 내용의 의미적 유사성까지 고려할 수 있습니다.
단어가 달라도 맥락이 비슷한 이슈를 잡아낼 수 있습니다.
수천 건 이슈를 빠르고 일관성 있게 비교할 수 있습니다.
결과적으로, ‘요약본’과 ‘본문 내용’을 모두 고려하는 임베딩 기반 비교는 중복 티켓 관리 자동화에 가장 효과적인 방법이었습니다.
중복 탐지 프로세스 개요
1. Jira API를 통해 이슈를 대량 조회
설정한 JQL(Query Language)을 기준으로 다수의 이슈를 한 번에 가져옵니다.
페이지네이션으로 수천 건 처리 가능
2. 필터 조건을 적용하여 필요한 이슈만 선별
특정 헤더(예: [UI])가 포함된 이슈를 제외하거나
특정 타입(Bug, Improvement, New Feature)만 조회합니다.
3. Summary + Description 결합
이슈 제목과 본문을 합쳐 하나의 의미 단위 데이터로 구성합니다.
4. OpenAI Embedding 변환
text-embedding-ada-002 모델로 의미 기반 벡터로 변환합니다.
5. Cosine Similarity 계산
이슈 간 유사도를 계산하여 0.98 이상인 경우만 중복 후보로 판단합니다.
6. 결과 저장
콘솔 출력 logs/ 폴더에 텍스트 파일 저장 outputs/ 폴더에 Excel(.xlsx) 파일 저장
7. .env를 통한 환경 설정 지원
코드 수정 없이 API 키, 쿼리, 최대 이슈 수 등을 쉽게 변경할 수 있습니다.
프로젝트 파일 구조 및 역할 설명
이 프로젝트는 Python 표준 프로젝트 구조를 기반으로 설계되었습니다.
코드의 가독성과 유지 보수성을 높이기 위해, 기능별로 모듈을 명확히 분리하여 관리했습니다.
구성은 다음과 같습니다.
1. main.py
프로그램의 시작점입니다.
환경 설정을 불러오고, Jira 이슈를 조회하고, 중복 이슈를 탐지하는 전체 프로세스를 순차적으로 실행합니다.
2. config.py
환경 변수(.env 파일)를 불러와 전역 설정값을 관리합니다.
Jira API 연결 정보, OpenAI API Key, JQL Query, 최대 이슈 수(MAX_ISSUES) 등이 이곳에서 설정됩니다.
3. setup_logger.py
콘솔과 파일(logs/)에 동시에 로그를 남기기 위한 로거(Logger)를 설정하는 모듈입니다.
각 실행마다 새로운 로그 파일이 생성되어, 실행 이력을 체계적으로 관리할 수 있습니다.
4. modules/ 디렉터리
기능별 핵심 로직을 다음과 같이 모듈화하여 관리합니다.
jira_client.py: Jira API를 호출하여 이슈를 조회하고, 필터링된 데이터를 반환합니다.
embedding_service.py: OpenAI Embedding API를 호출하여, Summary + Description을 임베딩 벡터로 변환합니다.
cache_manager.py: 생성된 임베딩 결과를 파일로 저장하고 불러오는 기능을 담당합니다.
(이미 계산된 이슈는 다시 임베딩할 필요 없이 캐시로 재사용합니다.)
duplicate_checker.py: 임베딩된 이슈 간 유사도를 계산하고, 중복 이슈를 식별하여 콘솔/로그/Excel 파일로 결과를 출력합니다.
5. /logs/ 디렉터리
실행 중 생성된 로그 파일이 저장됩니다.
날짜와 시간이 포함된 파일명으로 관리되어, 각 실행 세션별로 기록을 쉽게 추적할 수 있습니다.
6. /outputs/ 디렉터리
발견된 중복 이슈 쌍의 결과를 Excel(.xlsx) 파일로 저장합니다.
이 파일은 추후 검토나 리포팅에 바로 활용할 수 있습니다.
사용방법
이 프로젝트는 설치 후 간단한 환경 설정만으로 바로 사용할 수 있도록 설계되었습니다.
사용 흐름은 다음과 같습니다.
1. .env 파일을 작성하고 필요한 정보를 설정합니다.
루트 디렉터리에 .env 파일을 생성한 후, 다음과 같은 정보를 입력합니다.
OPENAI_API_KEY: OpenAI Embedding API 호출을 위한 키
JIRA_URL: Jira 인스턴스 URL
JIRA_USER: Jira 로그인 이메일 주소
JIRA_TOKEN: Jira API 토큰
JQL_QUERY: 이슈를 필터링할 JQL 쿼리
MAX_ISSUES: 가져올 최대 이슈 수
CACHE_FILE: 임베딩 결과를 저장할 캐시 파일명
✅ 별도의 코드 수정 없이, 이 .env 파일만 수정하면 프로젝트를 유연하게 설정할 수 있습니다.
2. 가상환경(venv)을 활성화합니다.
만약 가상환경을 설정해두었다면, 다음 명령어로 활성화합니다.
source .venv/bin/activate
(가상환경이 없다면 uv venv, python -m venv로 먼저 생성 가능합니다.)
3. 프로젝트 의존성 패키지를 설치합니다.
필요한 패키지는 requirements.txt에 모두 정의되어 있습니다.
pip install -r requirements.txt
✅ openai, requests, numpy, scikit-learn, python-dotenv, pandas, openpyxl, tiktoken 등 포함
4. main.py 파일을 실행합니다.
설정이 완료되었으면, 아래 명령어로 실행합니다.
python main.py
특별한 추가 입력 없이, 프로그램이 자동으로 다음 과정을 순서대로 수행합니다.
Jira 이슈 조회
이슈 Summary + Description 결합
OpenAI를 통한 Embedding 변환
이슈 간 Cosine Similarity 계산
유사 이슈 쌍 탐색
결과 출력 (콘솔, 로그 파일, Excel 파일)
5. (선택) 실행 시 threshold 값을 CLI로 조정할 수 있습니다.
유사도 임계값(threshold)을 기본값(예: 0.98) 대신 직접 지정하고 싶다면 다음처럼 실행할 수 있습니다.
python main.py --threshold 0.95
✅ CLI로 입력하면, 코드 수정 없이 유연하게 기준을 바꿀 수 있습니다.
API 키 획득 방법과 사용법
이 프로젝트를 정상적으로 실행하려면 OpenAI API Key와 Jira API Token 두 가지가 필요합니다.
발급 방법은 다음과 같습니다.
OpenAI API Key 발급 방법
- OpenAI 플랫폼 계정 페이지에 접속합니다.
- 로그인 후 “Create new secret key” 버튼을 클릭합니다.
- 발급된 Key를 복사해 둡니다.
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
(※ 보안상 한 번만 확인 가능하므로 반드시 안전한 곳에 저장해 주세요.)
✅ 발급한 API Key는 .env 파일의 OPENAI_API_KEY 항목에 입력합니다.
Jira API Token 발급 방법
- Atlassian 계정 보안 설정 페이지에 접속합니다.
- “Create API Token” 버튼을 클릭합니다.
- 토큰의 이름(Name)을 입력하고, “Create”를 누릅니다.
- 생성된 토큰을 복사해 둡니다.
JIRA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
(※ 이 역시 한 번만 표시되니 주의해주세요!)
✅ 발급한 API Token은 .env 파일의 JIRA_TOKEN 항목에 입력합니다.
Jira에 연결할 때는 이 토큰을 비밀번호 대신 사용합니다.
(Jira URL과 로그인 이메일(JIRA_USER)도 함께 설정해야 합니다.)
사용 비용
이 프로젝트는 OpenAI의 Embedding API를 활용하기 때문에, API 사용량에 따라 소액의 비용이 발생합니다.
저의 경우, 실제 테스트 결과, 약 49,819 tokens을 사용했을 때의 비용은 단 $0.00498 정도였습니다.
이는 한화로 환산해도 약 7원 내외에 불과한 수준입니다.
수천 건의 이슈를 비교하더라도
10원 미만의 비용으로
품질 높은 중복 이슈 탐지가 가능합니다.
고비용 걱정 없이, QA 업무 효율성을 극대화할 수 있도록 매우 경제적으로 설계되었습니다.
향후 개선 및 확장 계획
현재 프로젝트는 핵심 중복 탐지 기능을 완성한 상태지만, 더 높은 생산성과 협업 효율을 위해 다음과 같은 기능을 추가할 계획입니다.
[구현 완료된 기능]
CLI 옵션으로 threshold 값을 가변적으로 입력 가능
좌측 이슈를 기준으로 그룹핑하여 결과 출력
다중 키워드 제외 기능 추가
앞으로 추가하고 싶은 기능
1. Slack 등 메신저 플랫폼으로 결과 자동 전송 기능 개발
현재는 탐지 결과를 콘솔 출력, 로그 파일 저장, Excel 파일 저장 형태로 제공하고 있습니다.
앞으로는 외부 커뮤니케이션 플랫폼으로 결과를 자동 전송하는 기능을 확장할 예정입니다.
구체적인 동작 예시:
중복 이슈가 발견되면 Slack 채널로 실시간 알림 발송
주기적으로 Email로 요약 리포트 발송
향후 Microsoft Teams, Discord 같은 플랫폼으로도 확장 지원
✅ 예상 효과
탐지된 중복 이슈를 QA팀 전체에 실시간으로 공유할 수 있어, 즉각적인 대응과 조직 내 협업 속도 향상이 기대됩니다.
2. 발견된 중복 이슈에 Jira 자동 코멘트 달기
탐지된 유사 이슈 쌍 중 하나(또는 양쪽)에 “이 이슈는 다른 이슈와 높은 유사도를 보입니다” 같은 코멘트를 자동으로 Jira에 등록하는 기능을 추가할 계획입니다.
구체적인 동작 예시:
유사도가 임계값 이상인 이슈에 자동 코멘트 추가
코멘트에는 연관된 이슈 Key와 유사도 수치 표시
✅ 예상 효과
QA 담당자가 별도로 일일이 코멘트를 남기지 않아도 되며, Jira 내에서 중복 가능성을 직관적으로 확인하고 바로 병합 또는 정리 작업을 시작할 수 있습니다.
향후 추가 확장 가능성
현재 계획 외에도, 향후 프로젝트를 더욱 고도화하기 위해 고려할 수 있는 확장 아이디어는 다음과 같습니다.
3. 유사도에 따라 Priority(우선도) 자동 추천
단순히 유사도를 출력하는 것을 넘어, 유사도 값에 따라 병합 우선순위를 자동으로 추천하는 기능입니다.
구체적인 동작 예시:
유사도 0.99 이상: “병합 필수” 추천
유사도 0.95~0.98: “병합 검토 필요” 추천
✅ 예상 효과
QA 엔지니어가 대량 이슈를 검토할 때 우선 처리해야 할 이슈를 빠르게 식별할 수 있어, 업무 속도와 정확도가 크게 향상됩니다.
4. 중복 후보 이슈 병합 추천 기능 (Merge Suggestion)
발견된 중복 이슈 간의 상태(Status)나 흐름이 비슷한 경우, “이슈 병합 추천” 목록을 별도로 만들어 제공하는 기능입니다.
✅ 예상 효과
QA팀, PM팀이 이슈 병합 작업을 체계적이고 신속하게 진행할 수 있어, Jira 이슈 관리 품질이 높아집니다.
5. 사용자의 수동 Feedback 기반 AI 튜닝 기능
탐지된 이슈 쌍에 대해 사용자가 “중복이다” / “중복이 아니다” 라는 피드백을 수집하여, Embedding 기반 유사도 계산 방식을 점진적으로 보정(튜닝)하는 기능입니다.
✅ 예상 효과
시간이 지남에 따라 프로젝트 특성에 맞는 맞춤형 탐지 정확도를 스스로 높여갈 수 있습니다.
(→ Self-Optimizing Duplicate Detection)
앞으로도 이 프로젝트를 지속적으로 개선하여, 더 많은 QA팀이 스마트하게 중복 이슈를 관리할 수 있는 세상을 만들어 나가겠습니다.
이 프로젝트는 단순한 실험이 아니라, 실제 QA 업무 현장에서 마주한 문제를 해결하기 위한 필요성에서 출발했습니다.
수천 건에 이르는 Jira 이슈 속에서 중복된 티켓을 수작업으로 식별하는 것은 상상 이상으로 많은 시간과 리소스를 요구합니다.
이를 AI 기술을 통해 자동화함으로써, QA 엔지니어가 본질적인 품질 향상 업무에 더 집중할 수 있도록 돕고 싶었습니다.
Jira AI Duplicate Detector는 QA 업무의 비효율을 줄이고, 협업을 빠르게 만들며, 품질 관리 프로세스를 더 스마트하게 변화시킬 수 있는 작은 시작입니다.
앞으로도 이 프로젝트를 지속적으로 개선하고, 더 많은 QA 엔지니어와 팀이 중복 이슈 관리의 스트레스에서 벗어날 수 있도록 확장해 나갈 계획입니다.
