---
name: bug-fix
description: 신고된 결함의 기대 동작과 실패를 재현하고 회귀 검사·최소 수정·영향 검증을 수행한다. 문서나 루프 유무와 관계없이 필요한 범위로 진행하며 BUG 기록과 미검증·재개 근거를 남긴다. 사용자가 'xx가 안 돼', '예전엔 됐는데 이상해', '이 버그 고쳐줘'처럼 제품 동작 결함 수정을 요청하면 코드를 고치기 전에 사용한다. 하네스·루프 실행 문제는 harness-update·loop-update가 다룬다.
---

# 버그 수정

## 목적과 입력

신고된 실패를 재현해 원인을 고치고 같은 문제가 다시 생기면 잡을 수 있는 증거를 남긴다.
신고·기대 동작, 관련 코드·데이터·테스트, 기존 문서·운영 합의·실행 상태를 읽는다.
전체 문서화·현행 고정 phase 완료는 선행 조건이 아니다. 작은 독립 버그에 네 게이트·자식 실행을 강제하지 않으며 기존 Loop 제품 변경은 아래 계약을 따른다.

## 최소 산출물

`plan_setup/LOG.md`의 `BUG-NN`에 재현·관찰/기대·원인·회귀 검사·수정·검증 결과를 연결한다.
LOG가 없으면 해당 파일만 만든다. NN은 기존 BUG 최댓값 다음이며 재개할 때 같은 번호를 쓴다.
기존 날짜별 로그에 `### BUG-NN`으로 덧붙이고 과거 줄을 보존한다.
실행 요청이면 필요한 코드/회귀 검사도 산출물이다. 조사·계획만 요청하면 그 범위에서 끝낸다.

## 진행

1. 사용자 지시·합의된 요구·API 계약·화면 표현에서 기대 동작의 근거를 찾아 결과와 비교한다.
   as-is 문서에 적혔다고 결함을 의도된 동작으로 확정하지 않는다.
   새 제품 규칙이 필요하면 요구 변경으로 구분한다. 사용자가 그 규칙을 명확히 요청했으면 `feature-add`의 필요한 절차를 이어 수행하고, 아니면 다음 스킬로 `feature-add`를 제안해 승인을 받는다.
   명확히 요청한 규칙을 재승인받거나 다른 스킬로 돌려보내고 끝내지 않는다.
2. 실제 실행 주체·소유권·테스트 데이터·명령을 조사한다. `in_progress`나 미커밋만으로 중단하지 않는다.
   현재 태스크의 실패면 기존 실행 주체의 실패 처리에 합류하고 공유 상태는 그 필자가 안전한 경계에서 반영한다.
   독립 신고면 충돌하지 않는 재현/조사를 진행하고 겹치는 수정만 직렬화한다.
3. 격리 데이터로 재현하고 수정 전에 BUG 기록에 관찰 가능한 기대 결과를 남긴다.
   실제 재현과 분석 가설을 구분하며 API/CLI 재현과 화면 전체 검증의 범위를 구분해 적는다.
4. 원인을 추적하고 해당 경로를 잡는 진짜 단언의 회귀 검사를 쓴다.
   기존 러너를 우선 쓰고 검사 부재 시 필요한 최소 수단을 만든다.
   수정 전 같은 결함 때문에 실패함을 실제 확인한다. 환경 연결 실패는 결함 재현 증거가 아니다.
5. 원인과 연결된 코드를 최소한으로 고친다. 여러 파일에 걸친 원인이면 함께 수정한다.
   관련 없는 정리·새 기능·옆 결함으로 범위를 넓히지 않는다. 함께 요청된 변경은 기준과 증거를 구분한다.
6. 회귀 검사를 다시 돌리고 영향 범위의 기존 검사와 실제 동작을 확인한다.
   화면은 브라우저 등 실행 관찰로, 비화면은 적합한 HTTP·CLI·DB 등으로 확인한다.
   경계 입력과 고치다 깨질 수 있는 주요 성공·실패 경로도 검증한다.
7. 새 검사/명령이 기존 실행에 포함되지 않을 때만 `harness-update` 절차로 연결한다.
   문서가 과거 결함을 기준으로 남기면 관련 부분에 BUG 참조와 정정 근거를 보완한다.
   새 phase·전체 문서·DAG·루프 갱신은 수정 규모와 운영에 필요할 때만 한다.
8. LOG에 수정 전 실패/수정 후 결과, 명령·실행 사례·미검증을 기록한다.
   기존 작업에 영향이 있을 때만 담당 필자가 STATE/태스크를 맞춘다. 완료 작업을 다시 열지 않는다.

## 필수 제약과 복구

- 사용자 편집·메모·후미 절·기존 ID·완료 이력·합의를 보존한다. 대체된 요구·TD 원래 위치에 현재 기준 포인터를 둔다. 깨진 동작을 붙잡던 테스트는 기대 동작의 근거와 함께
  갱신하며 단언을 제거하거나 통과를 위해 기준을 낮추지 않는다. 스텁/0건 실행은 증거가 아니다.
- 실데이터·외부 전송·비용·커밋/게시 권한을 확인한다. 버그 수정에 자동 커밋을 강제하지 않는다.
  다른 프로세스를 임의 종료하거나 사용자 데이터를 원복 명령으로 덮지 않는다.
- 실행 전 사용자만 정할 결정·권한·예산을 해소하고 합의를 재사용한다.
  Loop 이후 합의 안에서 코드·테스트·환경을 조정하고 질문·재승인·수동 조치 요청 없이 복구한다.
- 실패를 코드·검사/문서 불일치·환경·흔들림·판정 불가로 가르고 예산과 개선 증거로 재시도한다.
  같은 방식의 수정은 3회 이내 심층 분석·새 전략으로 전환한다. 자동 포기·사람 호출 기준이 아니며 누적 실패/예산을 초기화하지 않는다.
- 작은 독립 수정은 위험에 따라 독립 검토를 사용한다. 기존 Loop 제품 변경의 task_validation은 아래 별도 세션 계약을 따른다.
  검토자는 기대 동작과 실행 증거를 우선하고 필요하면 diff/코드를 읽는다.
- 권한/예산/새 결정으로 해소 불가하면 관련 작업/의존만 차단하고 독립 작업을 마친다.
  변경·시도·실패 증거·남은 범위·재개 명령/조건을 보존한 미완료로 종료한다. 질문 대기로 끝내지 않는다.

- 시작·중요한 범위/결정·검증·분석 전환에서 해당 문서 또는 기존 STATE/LOG를 증분 저장한다.
  현재 단계·확정/미결·누적 시도/전략·사용/잔여 예산·다음 행동과 대상 코드/지속 증거를 연결한다.
  새 세션은 이 기록과 실제 코드·미커밋·살아 있는 실행/미반영 결과를 대조해 이어가며 완료·실패 이력을 초기화하지 않는다.
  작은 문서/계획 요청은 해당 문서의 짧은 재개 기록으로 충분하며 전체 계획 체계를 만들지 않는다.

시각을 보존하는 수정에는 새 디자인 승인을 요구하지 않는다. 새 방향·승인 범위 밖 시각 변경이 필요할 때만 PRD의 미리보기·사용자 확정을 본격적인 화면 구현·관련 Loop 전에 연결한다.

## 기존 Loop의 제품 변경

현재 요청·유효한 합의·태스크 연결상 기존 Loop의 재개·추가·검증·복구에 속하는 제품 변경은 계약을 계승한다.
LOOP.md의 존재나 과거 완료 이력만으로 새 독립 요청을 편입하지 않는다. 적용 범위와 근거를 기록하고 Loop 작업을 작게 나눠 면제하지 않는다.
`loop_setup/LOOP.md`·STATE와 HARNESS를 읽고 `lint → unit → e2e → task_validation` 판정 순서를 계승한다.
task_validation은 해당 변경 미구현·구현 대화/추론/자체 통과 결론을 비상속한 별도 세션이 맡는다. 앞 실패 뒤 후행 완료 판정을 하지 않는다.
환경 선택(Orca/일반/Others)·충돌/자원 조건·누적 시도와 전체 예산을 보존한다. 같은 방식의 수정은 3회 이내 심층 분석·새 전략으로 전환하며 이력/예산을 초기화하지 않는다.
상세 검증·복구·배정은 `harness-setup`·`harness-update`·`loop-setup`·`loop-update`의 필요한 절차로 이어 수행한다.
새 사용자 지시·계획만·자식 실행 금지가 우선하며 변경된 보장과 미검증을 기록한다. 금지된 실행을 강행하거나 독립 검증 PASS를 꾸미지 않는다.

## 완료 증거

재현된 실패가 해소되고 회귀 검사와 관련 수용 관찰이 통과했을 때 실행 완료다.
수정 전 실패를 확인 못 했거나 환경 때문에 검증 못 했으면 한계와 완료 여부를 명확히 보고한다.
BUG 번호·원인·변경 파일·결과·미완료/재개 조건을 남기며 코드 작성만으로 성공 처리하지 않는다.

## 환경 참고

- [Claude Code](references/claude-code.md)
- [Codex](references/codex.md)