fz-fix

name: fz-fix description: >- 버그 수정 + 에러 해결. 빠른 원인 분석과 수정-빌드 사이클. 예: 고쳐줘, 버그 있어, 크래시 나, 에러 떠, 안 돼 user-invocable: true argument-hint: "[버그/에러 설명] [--codex]" allowed-tools: >- mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__serena__replace_symbol_body, mcp__serena__insert_after_symbol, mcp__serena__find_referencing_symbols, mcp__serena__read_memory, mcp__serena__write_memory, mcp__sequential-thinking__sequentialthinking, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__lsp__diagnostics_delta, mcp__lsp__hover, mcp__lsp__peek_definition, Edit, Read, Bash(xcodebuild *), Bash(cd *), Workflow team-agents: primary: impl-correctness supporting: [review-arch, impl-quality, review-quality]

review-arch 조건부: 복잡도 3+ 또는 아키텍처 관련 버그에서만 활성

impl-quality + review-quality: Swift/iOS 안티패턴 차단 (역방향 트리거 발동 시)

composable: false provides: [code-changes] needs: [none] intent-triggers: - "수정|고쳐|버그|크래시|에러" - "fix|bug|crash|error|patch" model-strategy: main: opus verifier: null

/fz-fix - 버그 수정 스킬

행동 원칙: 빠른 수정-빌드 사이클로 버그를 해결한다. 복잡도가 초과하면 즉시 적절한 스킬로 전환을 제안한다.

개요

탐색 → 분석 → 수정 → 빌드 (실패 시 반복) → 리뷰(선택) 루프 프리미티브: ReAct + Generate-Test-Repair (H6, Inside the Scaffold)

• 빠른 수정-빌드 반복에 최적화
• 검증 선택적 (복잡할 때만)
• 복잡도 초과 시 자동 전환 제안
• 코드 탐색만 필요한 경우 → /fz-search 사용

사용 시점

/fz-fix "API 응답이 null일 때 크래시 발생"     # 버그 수정
/fz-fix "타임아웃을 30초로 변경해줘"            # 간단한 수정
# 코드 탐색이 필요하면 → /fz-search "PlayerRIB 구조"

Prerequisites

• 팀 에이전트 모드(Workflow pilot)는 네이티브 Workflow 도구 가용 환경 필요 — 미가용 시 SOLO 수정 폴백
• 참조: guides/agent-team-guide.md §8 (공식 사양)

모듈 참조

Plugin 참조 (SwiftUI + Swift Concurrency)

참조: modules/plugin-refs.md — SwiftUI Expert(수정 시) + Swift Concurrency(수정 시) 섹션 SwiftUI View 작업 시 swiftui-expert 플러그인 패턴 참조 최소 타겟 제약: CLAUDE.md ## Plugins 참조. 최소 타겟 이상 API 사용 시 availability 가드 필수 자동 감지: 코드에 SwiftUI/Concurrency 패턴 발견 시 플러그인 적극 참조 (트리거 목록: modules/plugin-refs.md)

⛔ 역방향 트리거 (absence-pattern detection)

참조: modules/plugin-refs.md "역방향 감지 트리거" 섹션. 동시성 키워드(@MainActor, actor, async)가 부재해도 다음 패턴이 감지되면 안전성 분석을 활성화한다.

수정 대상이 다음 3 패턴 중 하나라도 해당하면 동시성 안전성 검증 의무:

1. 싱글톤 가변 상태: static let shared + 가변 stored property (var X: T) — 동기화 메커니즘(@MainActor / actor / NSLock / OSAllocatedUnfairLock / serial queue) 부재 시 data race 위험. 수정 시 동기화 추가 또는 actor 전환 검토.

2. 콜백 스레드 모호: completion handler / pathUpdateHandler / delegate callback 내부에 DispatchQueue.main / @MainActor 보호 부재 — 콜백 실행 스레드 ≠ 소비자 스레드 가능성. context7로 API 콜백 스레드 확인 후 수정.

3. ObservableObject + @Published + @MainActor 부재: @Published var 쓰기가 background 스레드에서 발생할 수 있는데 클래스/메서드에 @MainActor 부재 — UI 스레드 위반 런타임 경고. 수정 시 @MainActor 추가 또는 await MainActor.run 래핑.

수정 자체가 안티패턴 도입할 위험이 있으므로 fix 시작 전 위 3 패턴 사전 점검 의무.

sc: 활용 (SuperClaude 연계)

⛔ Phase 0: ASD Pre-flight

참조: modules/context-artifacts.md → "Work Dir Resolution" 섹션

Phase 1 시작 전에 반드시 실행:

1. 인자에서 ASD-\d+ 패턴 추출
2. 패턴 있으면 → {CWD}/ASD-xxxx/ 폴더 + index.md 생성 (없으면) + WORK_DIR 설정
3. 패턴 없으면 → 브랜치명 확인 → 없으면 AskUserQuestion(저장 여부) → 예: {CWD}/NOTASK-{YYYYMMDD}/ + index.md 생성 / 아니오: Serena fallback

Gate 0: Work Dir Ready

• ⛔ ASD 패턴 또는 저장 여부 질문 완료?
• WORK_DIR 결정됨? (ASD / NOTASK / Serena fallback)
• index.md 존재 확인 완료? (없으면 생성)

ASD 컨텍스트 로딩 (ASD 폴더 활성 시):

• {WORK_DIR}/fix/fix-analysis.md 읽기 → 이전 수정 분석 복원 (있으면)
• {WORK_DIR}/search/search-result.md 읽기 → fz-search 탐색 결과 (있으면)

revert/되돌리기 감지

지시에 "되돌리기", "revert", "원상복구", "undo", "롤백" 키워드 감지 시: → cross-validation.md § origin-equivalence 게이트 활성 → 키워드 기반이 아닌 상태 기반으로 범위 정의 (참조: modules/lead-reasoning.md) → 완료 후 원본과의 동등성(origin-equivalence) 확인 필수

Mode A: 버그 수정 (Bug Fix)

빠른 수정-빌드 사이클로 버그를 해결합니다.

프로젝트 규칙: CLAUDE.md ## Code Conventions 섹션을 따른다.

Step 1a: Reproduce — 재현 조건 확인

1. 증상 파악: 에러 메시지, 크래시 로그, 재현 경로 먼저 확인
2. 재현 가능한 정확한 경로를 식별 (UI 흐름, API 호출 순서 등)

Step 1b: Isolate — 최소 범위로 좁히기

1. 관련 코드 탐색 (Serena):
   • Grep → 에러 메시지/키워드 검색
   • mcp__serena__find_symbol → 의심 심볼 찾기
   • mcp__serena__find_referencing_symbols → 호출 관계 파악
2. 원인 후보를 2-3개로 좁힘

Step 1c: Root-Cause — 증상이 아닌 원인 추적

1. 구조적 추론 (복잡한 버그):
   • mcp__sequential-thinking__sequentialthinking → 5 Whys 기법
   • /sc:troubleshoot → 자동 진단
   • /sc:explain → 프레임워크/라이브러리 깊은 에러의 교육적 설명
2. ⛔ Step 1c 완료 전 코드 수정 금지. root-cause가 불명확하면 AskUserQuestion.

Step 2: 수정

⛔ 패턴 변환 감지 (수정이 비동기/네트워크/UI 패턴 변환을 포함할 때):

• modules/code-transform-validation.md 참조. 원본 런타임 특성(스레드, 에러) 확인 후 수정
• Context7로 원본 API 동작 확인. 수정 후 Behavioral Equivalence Check 수행

Step 3: 빌드 검증

참조: modules/build.md — 빌드 검증 패턴

/ralph-loop 에스컬레이션 래더 적용 (참조: modules/execution-modes.md)

Step 4: Verify Fix (필수)

수정이 재현 경로(Step 1a)에서 문제를 해결했는지 확인:

• mcp__serena__find_referencing_symbols → 참조 무결성 확인
• /sc:analyze → 빠른 품질 체크
• /sc:reflect --type task → 수정이 근본 원인을 해결했는지 자체 검증 (트리거: 복잡한 버그 수정 완료 후, 단순 수정은 스킵)
• (옵션 --codex) /fz-codex check 호출 → cross-model 검증
  • verdict 분기: pass → 다음 단계 / warn → 사용자 보고 / fail → Step 1c 재진입
• 또는 /fz-review로 전환

팀 에이전트 모드 (복잡한 버그 — Workflow 오케스트레이션, Wave 3)

TEAM(TeamCreate+SendMessage) 모드를 네이티브 Workflow 결정적 스크립트로 대체. 복잡한 버그(여러 파일, 아키텍처 영향)에서 활성화. Pair Programming(경량) canonical: modules/patterns/pair-programming.md (보존 — 평탄화 출처). 스크립트: workflows/code-pair.js (mode='light') — fz-code와 동일 스크립트, stage 수만 분기. 규약: guides/skill-authoring.md §12. ⛔ 책임 재배분 (사용자 승인): 에이전트는 changeset JSON만 반환 — Lead가 적용 + 빌드 검증.

실행 절차 (Lead)

1. args 조립: mode:'light' / stepSpec={id,title,goal,files,verify,complexity} / contextPath(버그 분석 요약 파일) / changesetTarget / buildFeedback(재시도 시)
   • ⛔ complexity 측정 계약: 수정 대상 파일 수 또는 아키텍처 영향 범위를 1-5로 점수화 — Lead가 invoke마다 재평가하여 주입. 3+ → review-arch 검토 포함, 미만 → impl 단독(1-call). 누락 시 스크립트가 review 포함(안전 default)
2. Workflow 호출: Workflow({ scriptPath: '{플러그인 루트}/workflows/code-pair.js', args }) — Stage 1 impl(opus) → 조건부 Stage 2 review(sonnet). 1-2 call
3. changeset 적용 + 빌드 검증 (Lead): fz-code 절차 4-5와 동형. 실패 재시도 = buildFeedback 포함 새 invoke
4. mode:'fallback' 반환 시: SOLO 폴백 = Mode A Bug Fix Step 1-4 진입 — --codex 처리 책임도 fallback 경로에서 유효 + 사유 experiment-log 기록
5. 지표 기록: 세션당 1행 → experiment-log.md §5.7 fz-fix 테이블. 단일 Step 다수 — Step 루프 1회면 invoke 1회로 종료

복잡도 판단 및 스킬 전환

자동 전환 트리거

Gate: Bug Fix Complete

• ⛔ ASD 패턴 또는 저장 여부 질문 완료?
• WORK_DIR 결정됨? (ASD / NOTASK / Serena fallback)
• 빌드 성공?
• 원인-수정 대응 명확?
• 아티팩트 기록 완료? (ASD: {WORK_DIR}/fix/fix-analysis.md, 비ASD: write_memory("fz:checkpoint:fix-{bug}", "원인: {요약}. 수정: {파일}. 빌드: OK"))

Few-shot 예시

BAD (원인 분석 없이 수정):
증상: "탭 전환 시 크래시"
수정: guard let 추가
→ 근본 원인(nil 상태 도달 경로) 미분석. 증상만 숨김.

GOOD (원인 분석 → 수정 → 빌드):
증상: "탭 전환 시 크래시"
Phase 1: 크래시 로그 분석 → HomeInteractor.didBecomeActive()에서 nil
Phase 2: find_symbol → listener가 detach 후 nil인데 호출됨 → weak var 미적용
Phase 3: weak var + optional chaining 적용 → 빌드 성공

BAD (복잡 버그에 fz-fix 사용):
"5개 모듈에 걸친 상태 불일치 버그"
→ 영향 범위가 넓어 fz-fix 범위 초과. /fz-search → /fz-plan → /fz-code가 적절.

GOOD (복잡도 초과 시 전환):
Phase 1 분석 후 영향 범위 3개 모듈+ → "복잡도 초과. /fz-search로 전환 권장" 보고.

BAD (Codex 직접 호출):
수정: codex exec review --uncommitted ... 직접 호출
→ fz-fix allowed-tools에 Bash(codex *) 없음. 권한 에러.

GOOD (--codex 위임 패턴):
수정: --codex 옵션 + /fz-codex check 위임
→ fz-codex가 Hybrid Routing/Bash Hygiene/severity 파싱 처리. fz-fix는 verdict 분기만.

Boundaries

/ralph-loop 한도 후에도 실패하면 근본 원인을 재분석한다. 복잡도 초과 시 즉시 전환한다.

Will:

• 빠른 버그 수정 + 빌드 검증
• 복잡도 초과 시 적절한 스킬 전환 제안
• (옵션 --codex) /fz-codex check 호출 위임 (cross-model 검증)

Will Not:

• 코드 탐색/구조 분석 (→ /fz-search)
• 새 기능 구현 (→ /fz-plan + /fz-code)
• 대규모 리팩토링 (→ /fz-plan)
• 풀 코드 리뷰 (→ /fz-review)
• Codex CLI 직접 호출 (→ /fz-codex 위임)
• 팀 공유 영역 자동 변경 (36차): fast fix 시에도 .swiftlint.yml / .github/ / Package.swift / *.xcconfig 등 팀 영역 보호. 사용자 명시 합의 없이 자동 변경 금지

에러 대응

Completion → Next

• 버그 수정 완료: 사용자에게 보고 + 테스트 방법 안내
• 복잡한 수정: /fz-review 제안
• 탐색 필요: /fz-search 제안
• 탐색 후 변경 필요: /fz-plan 또는 /fz-code 제안