테마
Bugfix Spec
목표
Bugfix Spec이 일반 Feature Spec과 무엇이 다른지, bugfix.md에 무엇을 적는지, IDE·CLI·Web에서 어떻게 시작하는지 파악합니다.
개념
Bugfix Spec은 숙련된 개발자가 버그를 고치는 순서를 따릅니다. 근본 원인을 찾고, 무엇을 바꿔야 하는지 정하고, 바뀌면 안 되는 동작을 명시적으로 보존합니다.
얻는 것:
- 좁은 수정 범위: 명시한 제약 덕분에 꼭 필요한 변경만 들어갑니다.
- 회귀 방지: 바뀌지 않아야 할 동작을 문서로 남기고 테스트합니다.
- 기록: 버그, 수정, 판단 근거가 남습니다.
- 안정성: 즉흥적인 수정에서 흔히 생기는 실수를 줄입니다.
적합한 버그
- 근본 원인 분석이 필요한 복잡한 버그
- 회귀 비용이 큰 핵심 코드 경로의 버그
- 컴플라이언스나 팀 지식으로 기록이 필요한 버그
- 이전 수정 시도가 회귀를 일으킨 경우
동작 방식
Feature Spec과 같은 3단계(Requirements → Design → Tasks)지만 내용이 버그 수정에 맞춰져 있습니다.
1. Bugfix 분석: bugfix.md
요구사항 문서 대신 bugfix.md에 세 가지 동작을 적습니다.
| 구분 | 형식 |
|---|---|
| 현재 동작 (결함) | WHEN [조건] THEN the system [잘못된 동작] |
| 기대 동작 (올바름) | WHEN [조건] THEN the system SHALL [올바른 동작] |
| 유지할 동작 (회귀 방지) | WHEN [조건] THEN the system SHALL CONTINUE TO [기존 동작] |
세 번째 항목이 있어서 Kiro는 무엇이 고장 났는지뿐 아니라 무엇이 계속 동작해야 하는지도 압니다.
2. Design: design.md
Kiro가 코드베이스를 탐색해 근본 원인을 찾고 다음을 담은 design.md를 만듭니다.
- 근본 원인 분석
- 수정 방법
- 테스트할 속성(property)
- 현재 구현이 잘못된 동작을 낸다 (버그가 존재함을 확인)
- 수정된 구현이 올바른 동작을 낸다 (수정이 동작함을 확인)
- 바꾸지 않은 동작이 계속 동작한다 (회귀 방지)
3. Tasks
구현 작업은 property-based 테스트와 함께 생성되며, 버그 재현·수정 확인·회귀 없음을 검증합니다.
시작하기
| 환경 | 방법 |
|---|---|
| IDE | 새 세션의 "Let's build" 화면에서 Bug Fix를 고릅니다. 세션 중에는 채팅 입력창 하단 바의 에이전트 이름을 눌러 Bug Fix로 바꿉니다. |
| CLI | /spec new <name>으로 시작하면 Spec 모드로 바뀝니다. 버그를 설명하고 Fix a Bug를 고릅니다. 산출물은 .kiro/specs/<name>/에 생기고, /spec run <name>으로 수정을 자율 실행합니다. |
| Web | app.kiro.dev에서 새 세션을 열고 저장소를 고른 뒤 채팅 입력창에서 Spec을 선택합니다. 버그를 설명하고 Bug를 고르면, 구현이 끝났을 때 에이전트가 PR을 엽니다. |
버그를 설명할 때 넣을 내용:
- 언제 발생하는지 (재현 단계)
- 대신 어떻게 동작해야 하는지
- 제약 (수정하면 안 되는 코드)
해볼 것
- 연습 프로젝트에 일부러 경계값 버그를 하나 넣습니다(예: 빈 목록에서 오류가 나는 함수).
- Bug Fix 세션을 열고 재현 단계, 기대 동작, 건드리지 말 함수를 적습니다.
- 생성된
bugfix.md에 "SHALL CONTINUE TO" 항목이 들어갔는지,design.md의 근본 원인이 실제 원인과 맞는지 확인합니다. - Tasks를 실행하고, 테스트가 수정 전에는 실패하고 수정 후에는 통과하는지 봅니다.
더 알아보기
- Spec 세션: Feature Spec의 기본 흐름
- Property-based 테스트: 회귀 검증에 쓰이는 테스트 방식
- Specs Best practices — Bugfix Specs
출처: Bugfix Specs (2026-10-26 확인)