요구사항은 티켓 본문이 아니라 댓글 속에 살고 있었습니다 — AI 워크플로우팀의 분석 현장기
티켓 한 장을 배정받고 구현을 시작했는데, 알고 보니 진짜 요구사항은 다섯 장의 티켓과 마흔 개의 댓글에 흩어져 있었던 경험 — 있으실 겁니다. 이 글은 그 벽 앞에서 반나절을 보낸 기록입니다.
안녕하세요, AI 워크플로우팀에서 개발을 맡고 있는 니콜입니다. 저희 팀은 상담 자동화 워크플로우를 만드는 곳이라 기획, 운영, 개발 사이에 오가는 티켓이 많은 편입니다. 아래는 특정한 하루의 이야기이지만, Jira로 요구사항을 주고받는 팀이라면 어디서든 비슷하게 벌어지는 장면일 거라고 생각합니다. 같은 벽 앞에 서 보신 분들을 위해 적습니다.
1. 요구사항은 본문이 아니라 댓글에 삽니다
그날 오후에 배정받은 티켓은 "상담 자동 분류 규칙 개선" — 본문은 다섯 줄이었습니다. 다섯 줄이면 금방이겠다 싶었는데, 본문 아래가 문제였습니다. 링크된 선행 티켓이 네 장, 댓글이 스레드로 마흔 개 남짓, 첨부된 화면설계가 세 벌.
티켓 본문에는 "무엇을" 만들지가 적혀 있습니다. 그런데 "왜" 그렇게 하기로 했는지, 그리고 "결국 어떻게 하기로 확정됐는지"는 댓글 속에 삽니다. 그것도 곱게 살지 않습니다 — 이 티켓에서는 분류 기준이 댓글에서 세 번 뒤집혔고, 최종 결론은 서른두 번째 댓글쯤에 한 줄로 적혀 있었습니다. 첨부 화면설계도 v1과 v3의 내용이 달랐는데, 어느 쪽이 최종본인지는 역시 댓글 중간에만 언급되어 있었습니다.
이런 티켓을 앞에 두면 팀 대화가 이렇게 흘러갑니다.
💬 "그거 결국 B안으로 가기로 했잖아요."
💬 "어? 저는 A안으로 알고 있었는데요. 어느 댓글에 있어요, 그거?"
같은 티켓을 읽고도 결론이 다른 것은 누가 게을러서가 아닙니다. 요구사항이 문서가 아니라 대화의 퇴적층이 되어 있기 때문입니다. 그날 저의 첫 한 시간은 코드가 아니라 이 퇴적층을 파 내려가는 고고학이었습니다.
2. 알탭 지옥 — 그리고 AI 세션은 그 벽을 못 넘습니다
저는 평소 클로드 코드 같은 AI 코딩 도구와 함께 일합니다. 그래서 자연스럽게 이렇게 말하고 싶어집니다 — "이 티켓들 요구사항 좀 정리해줘." 그런데 AI 세션은 사내 Jira에 들어갈 수 없습니다. 티켓은 브라우저에, 코드는 에디터에, AI는 또 다른 창에. 세 개의 창을 알탭으로 오가며 댓글을 골라 복사해 붙여 넣는 노동이 시작됩니다.
복붙의 문제는 귀찮음이 아니라 선별입니다. 마흔 개의 댓글 중 무엇을 줄지 사람이 고르는 순간, 놓친 맥락은 AI에게 존재하지 않는 정보가 됩니다. 실제로 그날 아찔한 순간이 있었습니다. 제가 붙여 넣은 댓글 조각에는 두 번째 결정까지만 담겨 있었고, AI는 그걸 근거로 아주 그럴듯한 구현 계획을 제안했습니다 — 이미 뒤집힌 결정 위에 세운 계획이었습니다. AI가 틀린 게 아닙니다. 제가 준 세계가 거기까지였던 것입니다.
3. 티켓을 통째로 내 폴더에 — jiraget 한 줄
그래서 그날 오후, 도구 하나를 꺼냈습니다. 개발 과정에서 같은 벽을 겪는 커뮤니티를 지원하고 싶어서 제가 직접 만들어 공개한 CLI(Command-Line Interface, 명령줄 인터페이스) 도구, jiraget입니다. 하는 일은 단순합니다 — Jira 티켓을 통째로 로컬 마크다운으로 내려받습니다.
먼저 관련 티켓을 훑었습니다.
$ jiraget search --limit 20 --title-only "project = DEMO AND text ~ '자동 분류'"
{"key":"DEMO-38","summary":"상담 자동 분류 1차 규칙 정의"}
{"key":"DEMO-40","summary":"분류 예외 케이스 정리"}
{"key":"DEMO-42","summary":"상담 자동 분류 규칙 개선"}
그리고 필요한 티켓들을 내려받았습니다. --with-content로 바꾸면 검색된 티켓이 전부, 티켓 하나당 폴더 하나로 떨어집니다. 폴더를 열어 보면 본문과 마흔 개의 댓글 전부, 첨부 화면설계 세 벌까지 마크다운 한 세트로 담겨 있습니다. 서른두 번째 댓글을 찾으려 스크롤하던 그 티켓이, 에디터에서 검색되는 파일이 된 것입니다.
팀원들이 가장 좋아한 디테일은 따로 있었습니다. 작업 브랜치 바로 옆에 내려받아도 git status가 깨끗합니다 — 번들마다 .gitignore가 자동으로 들어 있어서, 티켓을 코드 옆에 두는 습관이 커밋을 더럽히지 않습니다.
만든 사람으로서, 설계 이야기를 조금 하자면
이 절만 잠깐 기술적인 이야기를 하겠습니다. 도구를 만들며 정한 원칙이 몇 가지 있는데, 회사 Jira에 붙는 도구라면 어떤 것이든 같은 고민을 만나실 것 같아서입니다.
첫째, 철저하게 읽기 전용입니다. 이 도구가 호출할 수 있는 Jira API(Application Programming Interface)는 아래 네 가지가 전부이고, 티켓을 만들거나 고치는 코드는 아예 존재하지 않습니다.
| 동작 | 용도 |
|---|---|
| 이슈 1건 조회 | 티켓 본문·필드 |
| 댓글 조회 | 페이지네이션을 끝까지 따라가 전체 수집 |
| 첨부 다운로드 | 화면설계·캡처 등 |
| JQL(Jira Query Language) 검색 | 읽기 전용 검색 |
여기에 리다이렉트 추종 금지(인증 정보가 다른 서버로 흘러가지 않도록), 프록시 환경변수 무시, 첨부 파일명의 UUID(Universally Unique Identifier, 범용 고유 식별자) 치환 — 원본 파일명이 로컬에 흔적을 남기지 않습니다 — 같은 안전장치를 겹쳐 두었습니다. 팀에, 그리고 커뮤니티에 마음 놓고 공유할 수 있었던 근거입니다.
둘째, 결과물은 항상 '완성된 번들'입니다. 티켓 하나의 본문은 Jira가 렌더링한 HTML(HyperText Markup Language)을 마크다운으로 변환해 담고, 변환이 불가능한 경우엔 원본 데이터를 JSON(JavaScript Object Notation) 블록으로 보존합니다 — 어떤 경우에도 댓글 하나가 조용히 사라지지 않습니다. 다운로드는 임시 폴더에서 전부 완성된 뒤에만 제자리로 옮겨지므로(원자적 게시), 반쯤 받다 만 폴더가 남지 않고 기존 폴더를 덮어쓰지도 않습니다.
셋째, 어디서든 한 줄로 씁니다. Rust로 만든 단일 바이너리라 윈도우·맥·리눅스 어디서나 같은 파일 하나로 동작하고, 설정은 .jiragetrc.toml 파일 하나(Jira 주소·이메일·API 토큰)가 전부입니다. 이름에서 짐작하셨겠지만 wget의 정신 — 인터넷의 문서를 로컬로 — 을 Jira에 옮긴 것이고, 옵션도 wget에서 출력 디렉터리 지정(-P) 하나만 계승했습니다.
설계의 세부(전체 동작을 규범 언어로 못 박은 스펙 문서 포함)가 궁금하시면 저장소와 도구 소개 편에 정리되어 있습니다. 다시 그날의 이야기로 돌아가겠습니다.
4. AI와 함께 읽는 요구사항 — 결정의 타임라인
이제 아까 하고 싶었던 그 말을 할 수 있게 됐습니다. AI 세션을 열고, 내려받은 티켓 폴더들을 가리키며 이렇게 부탁했습니다.
"이 티켓 다섯 개의 본문과 댓글을 시간순으로 읽고, 뒤집힌 결정과 최종 결론을 타임라인으로 정리해줘. 서로 어긋나는 요구가 있으면 따로 표시해줘."
몇 분 뒤 받아 든 것은 제가 한 시간 동안 파던 퇴적층의 단면도였습니다. 분류 기준이 언제 어떤 이유로 세 번 바뀌었는지, 최종 결론이 무엇인지가 시간순으로 정리됐고 — 더 중요한 것은 그다음이었습니다. 타임라인의 서로 다른 두 지점에서, 여전히 살아 있는 요구 두 개가 서로 모순된다는 표시가 있었습니다. 하나는 예외 케이스를 자동 분류에 포함하라는 결정, 다른 하나는 같은 케이스를 상담사 수동 배정으로 남기라는 결정. 댓글 스레드가 길어지며 아무도 눈치채지 못한 채 둘 다 '확정'되어 있었던 것입니다.
구현을 시작하기 전에 기획자분께 이 모순을 들고 갔고, 그 자리에서 정리됐습니다. 만약 이걸 구현 중간에, 혹은 QA(Quality Assurance, 품질 검증) 단계에서 발견했다면 — 반나절이 아니라 며칠을 되돌렸을 것입니다.
분명히 해 두고 싶은 것이 있습니다. 그날 잘한 것은 AI가 아닙니다. AI에게 조각이 아니라 전체 맥락을 준 것이 잘한 일입니다. 2장의 아찔한 장면과 4장의 차이는 모델의 성능이 아니라, 건네준 세계의 크기였습니다.
5. 우리 팀의 작은 규칙이 된 것
그날 이후 저희 팀에는 작은 규칙이 하나 생겼습니다. "구현 시작 전, 티켓 번들부터." 브랜치를 파면 그 옆에 관련 티켓 폴더가 함께 생깁니다. 요구사항 질문이 생기면 브라우저 대신 옆 폴더를 먼저 검색하고, AI에게 무언가를 시킬 때는 그 폴더를 통째로 쥐여 줍니다.
요구사항 분석은 여전히 사람의 일입니다. 모순을 들고 기획자에게 가는 것도, 결정의 무게를 판단하는 것도 도구가 대신해 주지 않습니다. 도구가 걷어낸 것은 그 판단에 도달하기까지 찾아 헤매던 시간뿐입니다. 다만 그 시간이 하루 업무에서 차지하던 비중을 생각하면, '뿐'이라고 부르기엔 꽤 큰 조각이었습니다.
티켓과 댓글의 퇴적층 앞에서 오늘도 스크롤하고 계신 분들께, 이 반나절의 기록이 작은 참고가 되었으면 합니다.
참고
- jiraget (GitHub) — 이 글의 화자가 만들어 공개한 티켓 다운로더 (스펙 문서 포함)
- wget처럼 Jira를 내려받다 — 티켓이 AI의 컨텍스트가 되는 순간 — 도구 자체가 궁금하시면 (기능·보안 설계 소개 편)