AI 에이전트에게 Jira Issue를 주고 바로 코딩을 시키면 빠르다. 문제는 빠르게 틀릴 수 있다는 점이다. 이슈 설명이 충분하지 않거나, 완료 기준이 애매하거나, 댓글 속에 중요한 조건이 숨어 있으면 에이전트는 그럴듯한 구현을 만들어내지만 실제 요구사항과 어긋날 수 있다.
그래서 Jira 플러그인에는 /jira analyze 같은 요구사항 분석 인터페이스가 필요하다. 이 명령의 목적은 개발을 늦추는 것이 아니다. 잘못된 출발을 막는 것이다.
바로 코딩하면 생기는 문제
Jira Issue는 대개 완벽하지 않다. 사람도 맥락을 알고 있다는 전제로 짧게 쓴다.
예를 들어 이런 이슈가 있다고 하자.
Slack 알림 실패할 때 재시도 처리 필요
사람 개발자는 팀의 기존 코드와 운영 상황을 떠올리며 알아서 해석한다. 하지만 에이전트에게는 모호한 점이 많다.
- 어떤 실패를 재시도해야 하는가?
- 4xx도 재시도하는가?
- 429 rate limit은 어떻게 처리하는가?
- 최대 몇 번 재시도하는가?
- 재시도 간격은 얼마인가?
- 중복 알림은 어떻게 막는가?
- 실패 로그에 webhook URL이 남아도 되는가?
- 테스트는 어디까지 필요한가?
이 질문에 답하지 않고 구현하면, 결과는 운에 맡기는 것이 된다.
/jira analyze의 역할
/jira analyze PROJ-123는 Jira Issue를 읽고 다음을 분리해야 한다.
- 목표
- 명시 요구사항
- 암묵 요구사항
- 완료 기준
- 제약 조건
- 열린 질문
- 리스크
- 권장 다음 행동
출력 예시는 다음과 같다.
## Requirements Analysis
### Goal
Slack webhook 전송 실패로 인한 알림 유실을 줄인다.
### Explicit Requirements
- 실패 시 재시도 로직 추가
- 최종 실패 시 로그 기록
### Implicit Requirements
- 재시도 대상 오류를 분류해야 한다.
- 중복 알림 가능성을 고려해야 한다.
- webhook URL/token은 로그에서 마스킹해야 한다.
- 테스트에서 성공/실패 케이스를 분리해야 한다.
### Open Questions
- 429 rate limit은 이번 범위에 포함되는가?
- 재시도 간격은 고정인가, exponential backoff인가?
- 최종 실패 시 별도 알림이 필요한가?
### Suggested Acceptance Criteria
- 5xx 또는 network error는 최대 3회 재시도한다.
- 4xx 응답은 재시도하지 않는다.
- 재시도 간격은 1s, 2s, 4s backoff를 사용한다.
- 최종 실패 시 error log를 남긴다.
- 로그에 webhook URL/token을 남기지 않는다.
이 분석 결과를 Jira comment로 남기면 다음 작업자가 같은 맥락을 다시 추론할 필요가 없다.
명시 요구사항과 암묵 요구사항
에이전트에게 가장 중요한 구분은 명시 요구사항과 암묵 요구사항이다.
명시 요구사항은 Jira Issue에 직접 적힌 내용이다. 암묵 요구사항은 업무 맥락상 필요하지만 명시되지 않은 조건이다.
예를 들어 “실패 시 재시도”라는 요구사항에는 보통 다음 암묵 요구사항이 따라온다.
- 무한 재시도는 안 된다.
- 재시도 간격이 있어야 한다.
- 재시도해도 되는 오류와 안 되는 오류를 구분해야 한다.
- 중복 부작용을 고려해야 한다.
- 실패를 관측할 수 있어야 한다.
암묵 요구사항을 추정하는 것은 유용하지만, 확정하면 안 된다. 분석 comment에는 “추정”과 “확정”을 분리해야 한다.
완료 기준을 구체화하기
Jira Issue의 품질은 Acceptance Criteria에서 갈린다. 완료 기준이 애매하면 리뷰도 애매해진다.
나쁜 완료 기준은 다음과 같다.
Slack 알림 실패 대응 잘 되게 하기
좋은 완료 기준은 검증 가능하다.
- HTTP 500 응답이 발생하면 최대 3회 재시도한다.
- HTTP 400 응답은 재시도하지 않는다.
- network timeout은 재시도 대상이다.
- 모든 재시도 실패 후 error log를 남긴다.
- 로그에 webhook URL/token이 포함되지 않는다.
- 관련 단위 테스트가 통과한다.
에이전트는 모호한 요구사항을 검증 가능한 조건으로 바꾸는 데 강하다. 하지만 사람이 승인할 수 있도록 Jira에 남겨야 한다.
열린 질문은 작업을 막는 질문과 아닌 질문으로 나눈다
모든 질문이 작업을 막는 것은 아니다. 어떤 질문은 나중에 결정해도 되고, 어떤 질문은 구현 전에 반드시 답해야 한다.
예를 들어 재시도 간격은 구현 전에 결정하는 편이 좋다. 반면 운영 알림 대시보드에 지표를 추가할지는 후속 이슈로 뺄 수 있다.
따라서 open question은 이렇게 나누는 것이 좋다.
### Blocking Questions
- 429 rate limit을 재시도 대상에 포함할지 결정 필요
### Non-blocking Questions
- 재시도 실패 횟수를 대시보드 지표로 노출할지 여부
- Slack 외 다른 채널에도 같은 정책을 적용할지 여부
이 구분이 없으면 에이전트가 사소한 질문 때문에 작업을 멈추거나, 반대로 중요한 질문을 무시하고 진행할 수 있다.
분석 comment를 남기는 타이밍
요구사항 분석은 작업 시작 전에 Jira에 남겨야 한다. 그래야 사람이나 다른 에이전트가 방향을 수정할 수 있다.
추천 흐름은 다음과 같다.
/jira brief PROJ-123
/jira analyze PROJ-123
/jira comment PROJ-123 --type analysis
사람 또는 에이전트가 분석 검토
/jira start PROJ-123
작은 작업에서는 분석과 시작을 한 번에 해도 된다. 하지만 리스크가 있는 작업에서는 분석 comment를 먼저 남기는 편이 안전하다.
분석이 과하면 안 된다
반대로 모든 이슈에 과도한 분석을 붙이는 것도 문제다. 작은 UI 텍스트 변경이나 단순 문서 수정에 긴 요구사항 분석은 낭비다.
그래서 플러그인은 이슈 유형과 규모에 따라 분석 깊이를 조절해야 한다.
- 단순 작업: goal, acceptance criteria만 정리
- 일반 개발 작업: 요구사항, 리스크, 테스트 방향 포함
- 장애/보안/결제 관련 작업: open question, rollback, 관측성까지 포함
분석은 목적이 아니라 수단이다. 에이전트가 바로 코딩하지 않게 만들되, 작업 속도를 불필요하게 죽이면 안 된다.
결론
AI 에이전트에게 Jira Issue를 주고 바로 구현시키는 것은 빠르지만 위험하다. 좋은 Jira 플러그인은 먼저 이슈를 작업 가능한 요구사항으로 바꿔야 한다.
/jira analyze는 명시 요구사항, 암묵 요구사항, 완료 기준, 리스크, 열린 질문을 분리한다. 그리고 그 결과를 Jira에 남겨 사람과 다음 에이전트가 검토할 수 있게 한다.
에이전트 개발에서 중요한 것은 더 많은 코드를 빨리 쓰는 것이 아니라, 잘못된 요구사항을 빨리 구현하지 않는 것이다.