- Authors

- Name
- Youngju Kim
- @fjvbn20031
"코드는 한 번 쓰고 백 번 읽힌다. 티켓은 한 번 쓰고 그것이 만든 코드만큼 오래 산다."
프롤로그 — 티켓이 곧 스펙이다
소프트웨어 팀에서 가장 자주 쓰지만 가장 적게 가르치는 글이 있습니다. 바로 티켓입니다. Jira 이슈, GitHub Issue, Linear 태스크 — 이름은 달라도 본질은 같습니다. 누군가 무엇을 왜 만들어야 하는지를 적은 글입니다.
티켓을 가볍게 보는 사람이 많습니다. "어차피 말로 설명하면 되지", "코드 보면 알겠지" 하면서요. 하지만 현실은 다릅니다. 티켓은 스펙입니다. 개발자가 PR을 열 때 머릿속에 들고 있는 유일한 계약서이고, 리뷰어가 "이게 맞나?"를 판단하는 기준이며, 6개월 뒤 누군가 git blame을 타고 들어왔을 때 마주치는 마지막 단서입니다.
나쁜 티켓은 나쁜 결과를 만듭니다. 모호한 티켓은 모호한 PR을, 범위가 숨겨진 티켓은 리뷰 불가능한 디프를, 인수 조건이 없는 티켓은 "다 됐어요"와 "아직 멀었는데요"가 충돌하는 회의를 만듭니다.
그리고 2026년, 이 문제는 두 배로 커졌습니다. 이제 티켓을 읽는 것은 사람만이 아니기 때문입니다.
AI 에이전트가 티켓을 읽는다
코딩 에이전트에게 작업을 시킬 때, 입력은 결국 티켓입니다. 사람 동료는 모호한 티켓을 받으면 슬랙으로 되묻거나, 맥락을 추측하거나, 옆자리에 가서 물어봅니다. 에이전트는 그렇게 하지 않습니다. 에이전트는 티켓에 적힌 것만 가지고 일합니다. 적히지 않은 것은 환각하거나, 무시하거나, 가장 그럴듯한 디폴트로 채웁니다.
즉, 티켓 품질이 결과 품질의 상한선입니다. 사람에게는 "물어보면 되는" 안전망이 있었지만, 에이전트에게는 그 안전망이 없습니다. 좋은 티켓을 쓰는 기술은 이제 협업 스킬을 넘어 AI를 다루는 핵심 역량이 되었습니다.
좋은 소식은, 사람에게 좋은 티켓이 에이전트에게도 좋다는 점입니다. 명시적인 맥락, 검증 가능한 인수 조건, 좁은 범위 — 이 세 가지는 사람과 AI 모두에게 똑같이 작동합니다. 이 글은 그 세 가지를 어떻게 글로 옮기는지에 대한 실전 가이드입니다.
이 글에서 다룰 내용:
| 장 | 주제 |
|---|---|
| 1장 | 좋은 티켓의 해부학 — 다섯 가지 구성 요소 |
| 2장 | 체크박스형 인수 조건 |
| 3장 | 범위 설정 — 하나의 티켓 = 하나의 PR |
| 4장 | 버그 티켓 템플릿 |
| 5장 | 기능 티켓 템플릿 |
| 6장 | AI-ready 티켓 vs 사람 전용 티켓 |
| 7장 | 링킹, 추적성, 이슈 그래프 |
| 8장 | 티켓 작성 안티패턴 |
| 9장 | 복사해서 쓰는 템플릿 모음 |
| 에필로그 | 체크리스트 + 안티패턴 + 다음 글 예고 |
1장 · 좋은 티켓의 해부학
좋은 티켓에는 다섯 가지 구성 요소가 있습니다. 외워두면 어떤 트래커에서든 통합니다.
1.1 다섯 가지 구성 요소
| 구성 요소 | 답해야 할 질문 | 없으면 생기는 일 |
|---|---|---|
| 맥락(Context) | 왜 지금 이걸 하는가? | 잘못된 문제를 푼다 |
| 문제(Problem) | 무엇이 잘못됐거나 빠졌는가? | 증상만 고치고 원인을 놓친다 |
| 인수 조건(Acceptance Criteria) | 무엇이 충족되면 "완료"인가? | "다 됐어요" 분쟁이 발생한다 |
| 제약(Constraints) | 무엇을 건드리면 안 되는가? | 범위를 벗어난 변경이 들어온다 |
| 참조(References) | 관련 코드, 문서, 디자인은 어디 있는가? | 작업자가 30분간 탐색만 한다 |
이 다섯 가지가 채워진 티켓은 그 자체로 자급자족합니다. 작업자가 슬랙을 뒤지지 않아도, 옆자리에 묻지 않아도 시작할 수 있습니다. 그리고 자급자족하는 티켓은 정확히 AI 에이전트가 필요로 하는 것입니다.
1.2 맥락: "왜"를 먼저
맥락은 가장 자주 생략되고 가장 비싸게 대가를 치르는 부분입니다. "버튼 색을 파란색으로 바꿔주세요"는 지시이지 맥락이 아닙니다. 작업자가 알아야 할 것은 왜입니다.
브랜드 리뉴얼로 1차 액션 색상이 보라색에서 파란색으로 바뀌었습니다(디자인 시스템 v3 참조). 이 버튼은 결제 플로우의 핵심 CTA라 새 색상을 따라야 합니다.
이 한 문장이 있으면 작업자는 비슷한 다른 버튼들도 같이 봐야 하는지 판단할 수 있고, 에이전트는 "1차 액션 색상"이라는 토큰 기반 변경인지 단발성 하드코딩인지 추론할 수 있습니다.
1.3 문제: 증상이 아니라 사실
문제 진술은 관찰 가능한 사실이어야 합니다. 해석이나 추측을 섞지 마세요.
- 나쁨: "로그인이 가끔 이상해요"
- 좋음: "비밀번호에
+기호가 포함된 사용자가 로그인하면 401을 받습니다. URL 인코딩 누락으로 추정되지만 미확인."
좋은 버전은 재현 조건(+ 포함 비밀번호), 관찰된 결과(401), 그리고 추측과 사실을 분리("추정", "미확인")했습니다.
2장 · 체크박스형 인수 조건
인수 조건(Acceptance Criteria, AC)은 티켓에서 가장 중요한 한 부분입니다. AC가 하는 일은 단순합니다. "완료"의 정의를 작업 시작 전에 못 박는 것.
2.1 왜 체크박스인가
AC는 산문이 아니라 체크박스 목록으로 써야 합니다. 이유가 분명합니다.
## 인수 조건
- [ ] `+` 가 포함된 비밀번호로 로그인하면 200을 반환한다
- [ ] `&`, `=`, 공백이 포함된 비밀번호도 동일하게 동작한다
- [ ] 잘못된 비밀번호는 여전히 401을 반환한다 (회귀 방지)
- [ ] 이 케이스를 커버하는 통합 테스트가 추가된다
체크박스가 작동하는 이유:
| 관점 | 체크박스가 주는 것 |
|---|---|
| 작업자 | 할 일 목록. 하나씩 지우면 끝 |
| 리뷰어 | 검수 체크리스트. PR이 각 항목을 만족하는지 1:1 대조 |
| PM/보고 | 진행률이 그대로 보임 (3/4 완료) |
| AI 에이전트 | 검증 가능한 목표. 각 줄이 테스트 케이스로 번역됨 |
마지막 줄이 핵심입니다. 에이전트는 산문에서 "이 정도면 됐겠지"를 추론하지 못합니다. 하지만 - [ ] X가 Y를 반환한다는 그대로 검증 루프가 됩니다. 코드를 짜고, 그 줄이 참인지 확인하고, 아니면 다시 짭니다.
2.2 좋은 AC의 조건
좋은 AC 한 줄은 다음을 만족합니다.
- 검증 가능하다 — 참/거짓을 객관적으로 판정할 수 있다
- 관찰 가능한 행동을 말한다 — 구현이 아니라 결과를 말한다
- 하나의 사실만 담는다 — "그리고"로 두 개를 묶지 않는다
예시 비교:
| 나쁜 AC | 좋은 AC |
|---|---|
| 로그인이 잘 동작한다 | 유효한 자격 증명으로 로그인하면 /dashboard로 리다이렉트된다 |
| 성능을 개선한다 | 상품 목록 API의 p95 응답 시간이 200ms 이하다 |
| 에러 처리를 추가한다 | 네트워크 실패 시 토스트 "다시 시도해 주세요"가 노출된다 |
| 코드를 깔끔하게 한다 | (AC가 아님 — 인수 조건에서 제거) |
마지막 행을 보세요. "코드를 깔끔하게 한다"는 검증 불가능합니다. AC가 아니라 작업 노트나 별도 리팩터링 티켓으로 빼야 합니다.
2.3 Given-When-Then 변형
복잡한 동작은 Given-When-Then 형식이 모호함을 줄여줍니다.
## 인수 조건
- [ ] **Given** 장바구니에 재고 없는 상품이 있을 때
**When** 결제 버튼을 누르면
**Then** "재고가 부족한 상품이 있습니다" 모달이 뜨고 결제는 진행되지 않는다
- [ ] **Given** 모든 상품의 재고가 충분할 때
**When** 결제 버튼을 누르면
**Then** 결제 확인 페이지로 이동한다
이 형식은 사람에게는 시나리오를 명확히 하고, 에이전트에게는 거의 그대로 테스트 코드 골격을 제공합니다.
3장 · 범위 설정 — 하나의 티켓 = 하나의 PR
좋은 티켓 작성에서 가장 강력하지만 가장 자주 무시되는 원칙입니다.
하나의 티켓은 하나의 리뷰 가능한 PR로 끝나야 한다.
3.1 "리뷰 가능한"의 의미
리뷰 가능한 PR이란 한 사람이 한 자리에서 끝까지 읽고 자신 있게 승인할 수 있는 디프입니다. 경험칙으로 변경 줄 수 400줄 안팎, 핵심 파일 10개 안팎입니다. 이 선을 넘으면 리뷰어는 읽기를 포기하고 "LGTM"을 누릅니다 — 그러면 리뷰는 무의미해집니다.
티켓이 이 크기에 맞춰지면 연쇄적으로 좋은 일이 생깁니다.
| 티켓이 작으면 | 결과 |
|---|---|
| PR이 작다 | 리뷰가 빠르고 꼼꼼하다 |
| 변경이 격리된다 | 문제 생기면 되돌리기 쉽다 |
| 범위가 명확하다 | "이것도 해야 하나?" 고민이 없다 |
| 진행이 보인다 | 큰 작업이 작은 완료들로 쪼개진다 |
| 에이전트가 다룬다 | 컨텍스트 윈도우 안에 다 들어간다 |
마지막 행이 AI 시대의 새로운 이유입니다. 거대한 티켓은 에이전트의 컨텍스트를 넘쳐 흐릅니다. 작업 절반에서 앞부분을 "잊고" 일관성을 잃습니다. 작은 티켓은 시작부터 끝까지 한 맥락에 들어옵니다.
3.2 큰 티켓을 쪼개는 법
"사용자 인증 구현"은 티켓이 아니라 에픽입니다. 쪼개야 합니다.
에픽: 사용자 인증
├─ #101 이메일/비밀번호 회원가입 (DB 스키마 + 엔드포인트)
├─ #102 로그인 + 세션 토큰 발급
├─ #103 비밀번호 재설정 플로우 (이메일 발송 포함)
├─ #104 로그인 UI 컴포넌트
└─ #105 인증 미들웨어로 보호 라우트 적용
쪼개는 기준:
- 수직 슬라이스 우선 — "전체 백엔드" 같은 수평 분할보다 "회원가입 기능 끝까지"가 낫다
- 각 조각이 독립 배포 가능한가 —
#102가#101없이 의미 없다면 의존성을 명시 - 각 조각에 자체 AC가 있는가 — 없으면 아직 너무 크다
3.3 "숨은 범위"라는 함정
티켓 제목은 작아 보이는데 본문이 슬며시 커지는 경우가 가장 위험합니다.
제목: 헤더에 다크 모드 토글 추가 본문: ...토글을 추가하고, 김에 디자인 토큰 시스템도 정리하고, 색상 변수를 전부 CSS 변수로 마이그레이션해 주세요.
토글 하나가 전사 색상 마이그레이션으로 둔갑했습니다. 이런 티켓은 둘로 갈라야 합니다. 토큰 마이그레이션은 별도 티켓, 토글은 그 위에 의존성으로 얹습니다.
4장 · 버그 티켓 템플릿
버그 티켓에는 정해진 형태가 있습니다. 빠진 칸이 하나라도 있으면 작업자는 추측을 시작하고, 추측은 시간을 태웁니다.
4.1 버그 티켓의 필수 칸
| 칸 | 내용 |
|---|---|
| 재현 절차 | 1, 2, 3 번호로 — 따라 하면 똑같이 재현되어야 함 |
| 기대 결과 | 무엇이 일어나야 했는가 |
| 실제 결과 | 무엇이 일어났는가 |
| 환경 | OS, 브라우저/런타임 버전, 앱 버전, 배포 환경 |
| 증거 | 스택 트레이스, 로그, 스크린샷, 네트워크 응답 |
| 빈도 | 항상 / 가끔 / 한 번 — 디버깅 전략이 갈림 |
4.2 Before / After
Before — 추측을 강요하는 버그 티켓:
제목: 결제가 안 됨 결제 페이지에서 에러가 나요. 확인 부탁드립니다.
작업자가 모르는 것: 어떤 결제 수단? 어떤 금액? 어떤 에러? 어떤 환경? 항상? 재현 절차는? 이 티켓은 사실상 "당신이 알아내세요"입니다.
After — 바로 디버깅 가능한 버그 티켓:
## 요약
신용카드 결제 시 5만 원 초과 금액에서 500 에러 발생
## 재현 절차
1. 장바구니에 6만 원어치 상품 담기
2. 결제 페이지 진입, 신용카드 선택
3. 카드 정보 입력 후 "결제하기" 클릭
## 기대 결과
결제 승인 후 주문 완료 페이지로 이동
## 실제 결과
"일시적인 오류가 발생했습니다" 토스트, 결제 미완료
## 환경
- 배포 환경: production
- 브라우저: Chrome 124, Safari 17 모두 재현
- 발생 시작: 5월 12일 14:00 배포 이후로 추정
## 증거
- 서버 로그: `PaymentError: amount exceeds limit (50000)`
- 요청 ID: req_8f2a91c
- 스크린샷: 첨부
## 빈도
5만 원 초과 시 항상 재현 (100%)
After 버전은 작업자가 30초 만에 원인 가설을 세울 수 있습니다 — 5월 12일 배포에서 들어온 금액 한도 검증이 의심됩니다. 에이전트라면 로그의 에러 메시지와 요청 ID를 단서로 곧장 해당 코드 경로를 찾아갑니다.
4.3 스택 트레이스는 코드 블록에
스택 트레이스나 로그를 붙일 때는 반드시 코드 블록 안에 넣으세요. 산문에 그대로 붙이면 읽기 어렵고, 트래커에 따라 마크다운으로 깨집니다.
## 증거
```
TypeError: Cannot read properties of undefined (reading 'id')
at resolveUser (src/auth/resolver.ts:42:18)
at processRequest (src/server/handler.ts:118:9)
```
파일 경로와 줄 번호(src/auth/resolver.ts:42)가 들어간 트레이스는 사람에게도 에이전트에게도 최고의 진입점입니다.
5장 · 기능 티켓 템플릿
기능 티켓은 버그 티켓과 구조가 다릅니다. 버그는 "무엇이 깨졌나"를 다루지만, 기능은 "무엇을 새로 만드나"를 다룹니다. 핵심은 인수 조건과 범위 경계입니다.
5.1 기능 티켓의 필수 칸
| 칸 | 내용 |
|---|---|
| 배경/문제 | 어떤 사용자 또는 비즈니스 문제를 푸는가 |
| 제안하는 변경 | 무엇을 만들 것인가 (구현 디테일이 아니라 동작) |
| 인수 조건 | 체크박스 목록 — "완료"의 정의 |
| 범위 밖(Out of scope) | 명시적으로 이번에 하지 않는 것 |
| 제약 | 성능 예산, 호환성, 건드리면 안 되는 것 |
| 참조 | 디자인, 관련 코드, 선행 티켓 |
범위 밖 칸을 특히 강조합니다. 무엇을 안 하는지 적는 것은 무엇을 하는지 적는 것만큼 강력합니다. 이 칸이 숨은 범위 증식을 막습니다.
5.2 Before / After
Before — 모호한 기능 티켓:
제목: 검색 기능 개선 검색이 더 똑똑해졌으면 좋겠어요. 사용자들이 원하는 걸 잘 못 찾아요.
"똑똑하다", "잘"은 검증 불가능합니다. 작업자는 자동완성을 만들지, 오타 교정을 넣을지, 랭킹을 바꿀지 알 수 없습니다.
After — 작업 가능한 기능 티켓:
## 배경
상품 검색에서 사용자가 정확한 상품명을 모르면 결과가 0건이다.
지난주 검색 로그상 38%가 0건 결과로 끝났다.
## 제안하는 변경
검색어에 대해 상품명 부분 일치 + 오타 교정(편집 거리 1)을 적용한다.
## 인수 조건
- [ ] "맥북"으로 검색하면 "맥북 프로 16"이 결과에 포함된다
- [ ] "맥북" 오타인 "맥붓"으로 검색해도 동일한 결과가 나온다
- [ ] 결과가 없을 때 "이런 상품은 어떠세요" 추천 5건이 노출된다
- [ ] 검색 API p95 응답 시간이 300ms 이하를 유지한다
## 범위 밖
- 음성 검색
- 검색 결과 랭킹 알고리즘 변경 (별도 티켓 #210)
- 카테고리 필터 UI
## 제약
- 기존 `/api/search` 엔드포인트 응답 스키마는 바꾸지 않는다
- 검색 인덱스 재색인은 무중단으로 가능해야 한다
## 참조
- 디자인: Figma 링크
- 0건 결과 분석: 노션 문서 링크
- 관련 코드: `src/search/query-builder.ts`
After 버전은 작업자에게 명확한 종료선을 주고, 에이전트에게는 각 AC가 그대로 검증 단계가 됩니다. 범위 밖 칸은 "랭킹도 같이 해야 하나?"라는 30분짜리 고민을 0초로 만듭니다.
6장 · AI-ready 티켓 vs 사람 전용 티켓
모든 티켓이 에이전트에게 넘기기 좋은 것은 아닙니다. 어떤 티켓은 사람만 다뤄야 하고, 어떤 티켓은 약간만 손보면 에이전트가 끝낼 수 있습니다. 이 구분을 라벨로 명시하면 팀 전체가 같은 기준을 공유합니다.
6.1 무엇이 티켓을 AI-ready로 만드는가
| AI-ready 티켓의 특징 | 사람 전용으로 남겨야 할 신호 |
|---|---|
| 인수 조건이 검증 가능하다 | "느낌상 더 나아야 한다" 류의 주관적 목표 |
| 범위가 좁고 명확하다 | 여러 시스템에 걸친 모호한 탐색성 작업 |
| 참조 코드 경로가 명시됨 | 어디를 건드릴지 자체가 조사 대상 |
| 기존 패턴을 따르는 작업 | 새로운 아키텍처 결정이 필요한 작업 |
| 테스트로 결과 확인 가능 | 프로덕션 데이터/외부 시스템 의존이 큼 |
| 되돌리기 쉬운 변경 | 마이그레이션, 보안, 결제 등 고위험 영역 |
핵심 통찰: AI-ready 티켓은 사실 잘 쓴 티켓입니다. 별도의 종족이 아닙니다. 사람을 위해 명확하게 쓰면 에이전트도 다룰 수 있습니다. 거꾸로, 에이전트가 헤매는 티켓은 보통 사람 신입도 헤맵니다.
6.2 라벨 전략
트래커 라벨로 의도를 신호하세요. 예시 체계:
| 라벨 | 의미 |
|---|---|
agent-ready | AC가 검증 가능하고 범위가 좁음 — 에이전트에 위임 가능 |
agent-assisted | 에이전트가 초안을 만들고 사람이 마무리/판단 |
human-only | 아키텍처 결정, 고위험 영역, 모호한 탐색 |
needs-refinement | 아직 AC가 없거나 범위가 큼 — 그루밍 필요 |
needs-refinement가 중요합니다. 이 라벨은 "이 티켓은 아직 누구에게도 줄 수 없다"는 솔직한 신호입니다. 그루밍 회의에서 이 라벨이 붙은 티켓을 다듬어 agent-ready 또는 human-only로 졸업시킵니다.
6.3 에이전트에게 넘기기 전 체크
티켓에 agent-ready를 붙이기 전 확인할 것:
- [ ] 인수 조건이 모두 체크박스이고 검증 가능한가
- [ ] 관련 코드 경로/파일이 참조에 적혀 있는가
- [ ] "범위 밖" 칸으로 경계가 그어져 있는가
- [ ] 기존 코드의 어떤 패턴을 따라야 하는지 명시했는가
- [ ] 결과를 확인할 테스트 방법이 있는가
- [ ] 고위험 영역(인증, 결제, 마이그레이션)이 아닌가
이 여섯 줄을 통과하지 못하면 아직 needs-refinement입니다.
7장 · 링킹, 추적성, 이슈 그래프
티켓은 외딴 섬이 아닙니다. 좋은 팀의 트래커는 그래프입니다 — 티켓들이 서로, 그리고 코드와 연결되어 있습니다.
7.1 연결해야 할 다섯 가지 링크
| 링크 방향 | 예시 | 왜 |
|---|---|---|
| 티켓 → 상위 에픽 | #102는 "사용자 인증" 에픽 소속 | 큰 그림 안에서의 위치 |
| 티켓 → 의존 티켓 | #102는 #101 완료에 의존 | 작업 순서가 보임 |
| 티켓 → PR | #102 본문에 PR 링크 | 무엇이 이 티켓을 해결했나 |
| PR → 티켓 | PR 설명에 Closes #102 | 머지 시 자동 종료 |
| 티켓 → 문서/디자인 | RFC, Figma, 포스트모템 | 결정의 근거 |
Closes #102 같은 키워드는 GitHub/GitLab에서 PR 머지 시 이슈를 자동으로 닫아줍니다. 이 작은 습관 하나가 "닫는 걸 깜빡한" 좀비 티켓을 없앱니다.
7.2 추적성의 가치
6개월 뒤 누군가 이상한 코드를 발견했다고 합시다. 추적성이 살아 있다면 경로는 이렇습니다.
이상한 코드 한 줄
→ git blame → 커밋
→ 커밋 → PR
→ PR → 티켓 #102
→ 티켓 → 에픽 + RFC 링크
→ "아, 이래서 이렇게 짰구나"
이 사슬이 끊겨 있으면 그 코드는 영원히 미스터리로 남고, 아무도 손대기 무서워합니다. 티켓-PR-커밋 링크는 미래의 자신에게 보내는 편지입니다.
7.3 AI 에이전트와 이슈 그래프
에이전트에게 #102를 시킬 때, 의존성 링크가 있으면 에이전트는 #101의 결과물(스키마, 엔드포인트)을 맥락으로 끌어올 수 있습니다. 링크가 없으면 에이전트는 #102만 외딴섬으로 보고, 이미 존재하는 것을 다시 만들거나 일관성을 깹니다. 이슈 그래프는 에이전트의 컨텍스트 지도입니다.
8장 · 티켓 작성 안티패턴
좋은 티켓의 반대편을 알면 더 빨리 좋아집니다. 현업에서 가장 자주 보는 안티패턴들입니다.
8.1 모호한 동사
"개선한다", "최적화한다", "정리한다", "더 낫게 한다" — 이 동사들은 검증 불가능합니다. 항상 측정 가능한 결과로 바꾸세요.
| 모호한 동사 | 측정 가능한 버전 |
|---|---|
| 검색을 개선한다 | 0건 결과 비율을 38%에서 10% 이하로 낮춘다 |
| 페이지를 최적화한다 | LCP를 4.1초에서 2.5초 이하로 낮춘다 |
| 에러 처리를 정리한다 | 모든 API 실패에 사용자용 에러 메시지를 노출한다 |
8.2 숨은 범위
3장에서 다뤘습니다. 제목은 작은데 본문이 슬며시 커지는 패턴. "~하는 김에", "겸사겸사"가 본문에 보이면 거의 항상 별도 티켓 신호입니다.
8.3 인수 조건 누락
"완료"의 정의 없이 시작하는 티켓. 끝에 가서 "이게 다 된 거 맞나요?" 회의가 열립니다. AC 없는 티켓은 시작하면 안 됩니다.
8.4 한 티켓에 여러 작업
"로그인 버그 고치고, 회원가입 UI도 다듬고, 로깅도 추가"처럼 묶인 티켓. 리뷰가 불가능하고, 하나가 막히면 전부 막힙니다.
8.5 해결책을 지시하고 문제를 숨김
"users 테이블에 인덱스 추가" — 왜? 어떤 쿼리가 느린가? 문제가 없으면 작업자는 그게 맞는 해결책인지 검증할 수 없고, 더 나은 해결책을 제안할 수도 없습니다. 문제를 적고, 해결책은 제안 정도로.
8.6 안티패턴 요약표
| 안티패턴 | 증상 | 처방 |
|---|---|---|
| 모호한 동사 | "개선/최적화/정리" | 측정 가능한 결과로 |
| 숨은 범위 | 제목보다 큰 본문 | 티켓 분할 |
| AC 누락 | "완료" 정의 없음 | 체크박스 AC 추가 |
| 다중 작업 | 한 티켓에 여러 PR거리 | 하나씩 분할 |
| 해결책 지시 | "왜"가 없음 | 문제 진술 추가 |
| 맥락 부재 | "왜 지금"이 없음 | 배경 한 문단 추가 |
9장 · 복사해서 쓰는 템플릿 모음
아래 템플릿들을 리포지토리의 .github/ISSUE_TEMPLATE/ 또는 트래커 템플릿에 그대로 넣으세요.
9.1 버그 리포트 템플릿
## 요약
{한 문장으로 무엇이 깨졌는지}
## 재현 절차
1.
2.
3.
## 기대 결과
{무엇이 일어나야 했는가}
## 실제 결과
{무엇이 일어났는가}
## 환경
- 배포 환경: {production / staging / local}
- 브라우저/런타임: {버전}
- 앱 버전/커밋: {버전 또는 SHA}
## 증거
```
{스택 트레이스 / 로그 / 요청 ID}
```
{스크린샷 첨부}
## 빈도
{항상 / 가끔(N회 중 M회) / 한 번}
9.2 기능 요청 템플릿
## 배경
{어떤 사용자/비즈니스 문제를 푸는가, 가능하면 데이터와 함께}
## 제안하는 변경
{무엇을 만들 것인가 — 구현이 아니라 동작 수준으로}
## 인수 조건
- [ ] {검증 가능한 결과 1}
- [ ] {검증 가능한 결과 2}
- [ ] {회귀 방지 항목}
- [ ] {테스트 추가 항목}
## 범위 밖
- {이번에 하지 않는 것 1}
- {이번에 하지 않는 것 2}
## 제약
- {성능 예산 / 호환성 / 건드리면 안 되는 것}
## 참조
- 디자인:
- 관련 코드:
- 선행 티켓:
9.3 작업/태스크 템플릿 (리팩터링·잡무용)
## 무엇을
{한 문장 작업 설명}
## 왜
{왜 지금 이게 필요한가}
## 인수 조건
- [ ] {결과 1}
- [ ] {기존 동작이 깨지지 않음을 확인하는 항목}
## 범위 밖
- {확장 유혹을 명시적으로 차단}
## 참조
-
9.4 에이전트 위임 체크리스트 (PR 설명 또는 티켓 코멘트용)
## 에이전트 위임 전 점검
- [ ] AC가 모두 체크박스이고 검증 가능
- [ ] 관련 코드 경로가 참조에 명시됨
- [ ] "범위 밖"으로 경계가 그어짐
- [ ] 따라야 할 기존 패턴을 지정
- [ ] 결과 검증 방법(테스트)이 있음
- [ ] 고위험 영역 아님 (인증/결제/마이그레이션)
라벨: {agent-ready / agent-assisted / human-only / needs-refinement}
9.5 템플릿 운영 팁
- 템플릿은 출발점이지 족쇄가 아닙니다. 안 쓰는 칸은 지우되, 다섯 가지 구성 요소(맥락·문제·AC·제약·참조)는 남기세요.
- 칸 안의
{placeholder}안내문은 작성자가 채우면서 지워야 합니다. 빈 채로 제출된{placeholder}는 그 자체로 "이 티켓은 아직 미완성"이라는 신호입니다. - 팀 위키에 좋은 티켓 예시 3개를 박제해 두세요. 신입과 에이전트 모두 그것을 기준점으로 삼습니다.
에필로그 — 좋은 티켓은 미래에 보내는 투자
티켓은 소프트웨어에서 가장 레버리지가 큰 글입니다. 한 번 잘 쓰면, 그 티켓이 만든 코드만큼 오래 가치를 냅니다. 한 번 못 쓰면, 그 비용을 모든 후속 단계가 나눠 냅니다 — 그리고 AI 시대에는 그 비용이 두 배입니다. 사람에게는 "물어보면 되는" 안전망이 있었지만, 에이전트에게는 티켓이 전부이기 때문입니다.
하지만 결론은 단순합니다. 사람을 위해 명확하게 쓰면 에이전트도 다룰 수 있습니다. 별도의 기술이 아니라, 같은 기술의 두 배 보상입니다.
좋은 티켓 체크리스트
- 맥락 — "왜 지금 이걸 하는가"가 한 문단으로 적혀 있다
- 문제 — 증상이 아니라 관찰 가능한 사실로 적혀 있다
- 인수 조건 — 검증 가능한 체크박스 목록이다
- 하나의 사실 — AC 한 줄에 "그리고"로 두 개를 묶지 않았다
- 범위 — 하나의 리뷰 가능한 PR로 끝날 크기다
- 범위 밖 — 이번에 하지 않는 것이 명시되어 있다
- 제약 — 건드리면 안 되는 것, 성능 예산이 적혀 있다
- 참조 — 관련 코드 경로, 디자인, 선행 티켓이 링크되어 있다
- 추적성 — 에픽·의존 티켓·PR이 양방향으로 연결되어 있다
- 라벨 —
agent-ready/human-only등 의도가 신호되어 있다
피해야 할 안티패턴
- 모호한 동사 — "개선/최적화/정리"는 측정 가능한 결과로 바꾼다
- 숨은 범위 — "~하는 김에"가 보이면 티켓을 쪼갠다
- AC 누락 — "완료"의 정의 없이 작업을 시작하지 않는다
- 다중 작업 — 한 티켓에 여러 PR거리를 묶지 않는다
- 해결책 지시 — 문제를 숨기고 해결책만 적지 않는다
- 빈 placeholder — 템플릿의 안내문을 지우지 않은 채 제출하지 않는다
다음 글 예고
다음 글은 **"좋은 PR 설명 쓰기 — 리뷰어와 에이전트가 5분 만에 승인하게 만드는 법"**입니다. 티켓이 작업의 입력이라면 PR 설명은 작업의 출력입니다. 무엇을·왜 바꿨는지, 어떻게 검증했는지, 리뷰어가 어디부터 봐야 하는지를 적는 기술 — 그리고 그것이 어떻게 AI 코드 리뷰어와도 맞물리는지를 다룹니다.
좋은 티켓을 쓰는 데 드는 10분은, 잘못 만든 것을 되돌리는 10시간을 막습니다. 그 10분은 미래의 팀과 미래의 자신에게 보내는 투자입니다.