Discovery Audit & Fix-Fanout#

한마디로 (비개발자용)#

한 곳에서 버그를 하나 고쳤는데, "혹시 같은 실수가 코드 전체에 더 있지 않을까?"가 궁금할 때 쓰는 절차입니다. 건물 한 곳에서 화재 원인을 하나 찾았다고 바로 전체를 다 고치는 게 아니라, 먼저 비슷한 곳을 넓게 훑어 "의심되는 곳 목록"을 만들고(Triage), 그 목록을 다른 점검반이 처음부터 다시 확인해 "진짜 위험한 곳"만 추려낸 뒤(Verify), 확정된 곳들만 여러 팀이 동시에 나눠 고치는(Fix-Fanout) 3단계 절차입니다. 넓게 찾는 사람과 확정하는 사람을 분리해야 오탐(가짜 경보)이 그대로 작업 지시로 이어지는 사고를 막을 수 있습니다.

무엇을·언제 (비개발자용)#

• 무엇을 해주나요
  • 1단계(Triage): "이런 패턴의 버그"라는 설명을 여러 조수에게 나눠주고, 코드 전체에서 의심 후보 목록을 빠르게 뽑습니다.
  • 2단계(Verify): 후보 하나하나를 Triage와 다른 조수가 원본 코드를 처음부터 다시 읽고 "진짜 문제인지" 재확인합니다. 이미 안 쓰는 죽은 코드인지, 정말 멈추는지 아니면 그냥 조금 늦게 갱신되는 정도인지까지 따집니다.
  • 3단계(Fix-Fanout): 확정된 목록만 각각 독립된 작업 공간(git worktree)에서 동시에 고치고, 검사→커밋→합치기 요청(PR)까지 각자 끝냅니다.
• 언제 쓰나요
  • "이 버그, 다른 데도 있을 것 같은데" 싶을 때 — 즉 한 번 찾은 결함 패턴이 코드베이스 다른 곳에도 반복됐을 가능성이 있을 때.
  • 확정된 문제가 여러 건이라 한 명이 순서대로 고치면 오래 걸릴 때.
• 주의할 점: 넓게 찾는 사람이 스스로 "이건 진짜 문제다"까지 확정해버리면 안 됩니다. 반드시 별도의 확인 단계를 거쳐야 가짜 경보가 실제 작업으로 이어지는 것을 막습니다.

핵심 용어 (비개발자용)#

언제 이 패턴을 쓰는가#

버그를 하나 고치고 나서 "이 패턴이 코드베이스 다른 곳에도 있을 수 있다"는 확신이 들 때. 예를 들어:

• 특정 언어/프레임워크 함정(예: [cc-flutter-dev:swr-pattern]의 unawaited() + Error 침묵 실패 함정)을 하나 발견했고, grep으로 후보를 넓게 찾을 수 있는 경우
• 같은 안티패턴(예: 특정 API의 잘못된 사용법)이 여러 모듈에 반복됐을 가능성이 있는 경우

이 패턴은 한 에이전트가 "찾고 → 확정하고 → 고치는" 것을 전부 혼자 하지 않는다는 원칙 위에 서 있습니다. 찾기(넓게, 빠르게)와 확정(좁게, 느리게, 적대적)을 분리해야, 후보 단계의 오탐이 그대로 수정 PR로 이어지는 사고를 막을 수 있습니다.

3단계 구조#

Phase 1: Triage (넓게, 빠르게, 후보 위주)
  → gray-list 생성 → 청크 분할 → 병렬 에이전트에 배분
Phase 2: Verify (좁게, 느리게, 적대적/독립적)
  → 후보마다 별도 에이전트가 원본 소스를 처음부터 재확인
  → dead code / self-healing / 오진단 여부까지 재평가
Phase 3: Fix-Fanout (worktree 격리 병렬 수정)
  → 확정된 항목만 각자 독립 worktree에서 브랜치→수정→검증→PR

한 세션에서 Phase 1→2→3을 순서대로(Verify를 통과한 것만 Phase 3로) 진행하는 것이 원칙이며, Phase 2가 Phase 1의 결과(특히 severity)를 그대로 믿지 않고 재평가한다는 점이 핵심입니다.

Phase 1 — Triage (넓게, 빠르게, 후보 위주)#

목표#

정확도보다 **재현율(recall)**을 우선합니다. 이 단계의 목적은 확정이 아니라 "다음 단계에서 검토할 가치가 있는 후보 목록"을 만드는 것입니다.

절차#

1. grep 등으로 결함 패턴이 있을 만한 파일의 gray-list(전수 목록)를 만듭니다.
   • 예: grep -rl "unawaited(" --include="*.dart" feature/ package/ app/ | grep -v _test.dart
2. gray-list를 큰 청크(예: 파일 18~40개씩)로 나눠 병렬 에이전트에 배분합니다.
3. 각 에이전트 프롬프트에는 정확히 어떤 패턴을 찾는지와 스코프 축소 문구를 반드시 포함합니다.
   • "unawaited() 호출 자체가 나쁘다는 게 아니다 — 그 안의 호출 체인이 Error를 놓치는 catch만 있는 경우만 후보로 표시하라"처럼, 무엇이 아닌지도 명시해야 오탐이 줄어듭니다.

Workflow 스크립트 예시 (Triage)#

export const meta = {
  name:  ' unawaited-error-triage ' ,
  description:  ' unawaited() 호출 체인의 Error 누락 후보 감사 ' ,
  phases: [{ title:  ' Triage '   }],
}

// gray-list는 스크립트 본문에 리터럴로 직접 박아넣는다 (아래  " 운영상 주의점 "   참조)
const GRAY_LIST = [/* 274개 파일 경로 */]
const CHUNK_SIZE = 30 // rate limit 시 늘려서 동시성을 줄인다

const chunks = []
for (let i = 0; i  <   GRAY_LIST.length; i += CHUNK_SIZE) {
  chunks.push(GRAY_LIST.slice(i, i + CHUNK_SIZE))
}

const CANDIDATES_SCHEMA = { /* { file, function, line, callChain, reason } 배열 */ }

const results = await parallel(chunks.map(chunk = >   () = > 
   agent(
    `다음 파일들에서 unawaited(fn()) 패턴을 찾아라: ${chunk.join( ' ,  ' )}\n` +
    `찾을 것: fn()의 전체 호출 체인에서 모든 catch 절이 on Exception만 잡고 Error(TypeError, ` +
    `StateError, NoSuchMethodError, JsonUnsupportedObjectError 등)를 놓치는 경우.\n` +
    `주의: unawaited() 자체가 나쁜 게 아니다 — 위 조건에 해당하는 것만 후보로 보고하라.`,
    { phase:  ' Triage ' , schema: CANDIDATES_SCHEMA }
  )
))

const candidates = results.filter(Boolean).flatMap(r = >   r.candidates)

Phase 2 — Verify (좁게, 느리게, 적대적/독립적)#

원칙: 찾은 에이전트가 스스로 확정하지 않는다#

Triage에서 나온 각 후보는 Triage와 별도의, 독립적인 에이전트가 실제 소스코드를 처음부터 다시 읽고 재확인합니다. 같은 에이전트가 찾고 스스로 확정까지 하면, 오탐(false positive)이 그대로 확정된 결함으로 굳어집니다.

반드시 확인해야 하는 3가지#

Triage의 주장(특히 severity)을 그대로 믿지 말고, 위 3가지를 반드시 재평가한 뒤 confirmed/rejected를 판정합니다.

Workflow 스크립트 예시 (Verify)#

const VERDICT_SCHEMA = { /* { confirmed: bool, severity, reason, isDead, isSelfHealing } */ }

const verified = await parallel(candidates.map(c = >   () = > 
   agent(
    `다음 후보를 처음부터 재확인하라(Triage 결과를 신뢰하지 말 것): ` +
    `${c.file}:${c.line} (${c.function})\n` +
    `1) grep으로 실사용 호출부가 있는지 확인 — 없으면 dead code로 기각\n` +
    `2) 컨슈머가 정말 영원히 멈추는지, 아니면 값만 stale해지는지 확인\n` +
    `3) 다음 이벤트/네비게이션에서 재시도되는 self-healing 경로가 있는지 확인\n` +
    `Triage severity를 그대로 쓰지 말고 재평가하라.`,
    { phase:  ' Verify ' , schema: VERDICT_SCHEMA }
  ).then(v = >   ({ ...c, verdict: v }))
))

const confirmed = verified.filter(Boolean).filter(v = >   v.verdict.confirmed)

Phase 3 — Fix-Fanout (git worktree 격리 병렬 수정)#

언제 worktree 격리가 필요한가#

확정된 항목이 여러 건이고, 서로 다른 파일/모듈을 각각 독립적으로 고쳐야 할 때. agent()의 isolation: 'worktree' 옵션을 쓰면 항목당 별도 git worktree가 자동 생성되어, N개 에이전트가 동시에 브랜치 생성 → 코드 수정 → 검증 → 커밋 → 푸시 → PR 생성까지 각자 독립적으로 수행해도 같은 working tree를 공유하지 않으므로 서로 충돌하지 않습니다.

Serverpod 4 풀스택을 worktree마다 띄우는 포트·MCP 격리는 [cc-serverpod:serverpod-worktree-parallel] 참조. Agent Teams(파일 소유권 분리로 병렬화)와의 차이는 [cc-dev-cycle:agent-teams]의 "파일시스템 격리가 필요하면 git worktree와 상호보완" 참조.

각 에이전트 프롬프트에 반드시 포함할 것#

프롬프트에 아래를 명시적으로 넣을수록 정확도가 높았습니다:

• 정확한 결함 설명 — 파일/함수/라인/호출 체인. Verify 단계에서 이미 확보한 정보를 그대로 재사용하고, 에이전트가 처음부터 재조사하지 않게 한다.
• 정확한 수정 방향 — 가능하면 "이 한 줄을 이렇게 바꿔라" 수준까지 구체적으로.
• git/PR 표준 작업 순서 — 브랜치명 규칙, 커밋 메시지 컨벤션, dart analyze --fatal-infos/dcm analyze 통과 필수, 기존 테스트 파일이 있으면 회귀 테스트 1개 추가, gh pr create, 머지는 하지 말 것.
• pre-push hook(lefthook 등) 실패 시 우회 금지 — 실패하면 원인을 수정하라고 명시 (LEFTHOOK=0 금지는 [cc-dev-cycle:dev] 스킬의 공통 규칙과 동일).

Workflow 스크립트 예시 (Fix-Fanout)#

phase( ' Fix ' )
const fixResults = await parallel(confirmed.map(c = >   () = > 
   agent(
    `다음 확정된 결함을 수정하라: ${c.file}:${c.line} (${c.function})\n` +
    `결함: ${c.verdict.reason}\n` +
    `수정 방향: unawaited(fn()) 대신 fn()의 catch 절을 on Object catch (또는 ` +
    `on Exception catch + on Error catch 병행)로 넓혀 Error도 로깅/처리하라.\n` +
    `작업 순서: fix/{issue}-{slug} 브랜치 생성 → 수정 → 회귀 테스트 1개 추가 → ` +
    `dart analyze --fatal-infos  & &   dcm analyze 통과 → 커밋 → 푸시 → gh pr create.\n` +
    `머지는 하지 마라. pre-push hook 실패 시 우회하지 말고 원인을 고쳐라.`,
    { isolation:  ' worktree ' , label: `fix:${c.file}` }
  )
))

운영상 주의점 (실측)#

• args 파라미터로 큰 배열(270+ 항목)을 넘기면 파싱이 실패하는 경우가 있다 → 데이터를 스크립트 본문에 JS 리터럴로 직접 박아넣는 방식으로 우회한다 (위 Triage 예시의 GRAY_LIST 참조).
• "Server is temporarily limiting requests" rate limit → 청크 크기를 키워 동시 에이전트 수 자체를 줄여서 재실행하면 해결된다 (예: 16개 동시 → 5개 동시). 동시성을 낮추려면 CHUNK_SIZE를 늘려 청크(=에이전트) 개수를 줄인다.
• Verify phase도 동일하게 rate limit에 걸릴 수 있다 (후보 수만큼 동시 실행되므로) → 전체를 재실행하지 말고 실패한 것만 골라 별도로 재실행한다. Workflow의 resumeFromRunId를 쓰면 이미 성공한 호출은 캐시에서 즉시 반환되고 실패/신규 호출만 재실행된다.

⚠️ Fix-Fanout 후 머지 충돌 함정 — 원본 fix PR을 먼저 머지하라#

같은 근본 원인의 여러 인스턴스를 감사로 찾아 파생 fix들을 병렬 브랜치로 딸 때, 원본 문제의 최초 수정 PR이 아직 머지되지 않은 상태에서 파생 fix 브랜치들을 만들면, 원본 PR이 먼저 머지된 뒤 파생 브랜치들이 같은 파일의 다른 부분을 건드리고 있어 머지 시 충돌이 날 수 있습니다.

실측 사례: swr_strategy_impl.dart의 중첩된 unawaited(saveToCache) 수정 PR 1건이, 이미 머지된 원본 수정 PR(#7746/#7748)과 별도로 같은 파일의 다른 함수를 고치고 있었고, 양쪽이 회귀 테스트를 각각 추가해 병합 시 테스트 파일에서만 충돌이 발생(본체 코드는 자동 병합됨). 해결: 해당 브랜치에 최신 origin/development를 merge → lib 코드 충돌 없음 확인 → test 파일만 "두 테스트 케이스 모두 유지"로 수동 정리 → dart analyze/테스트 재확인 → merge commit push. 상세 해소 절차는 [cc-dev-cycle:merge-conflict-resolution] 참조.

교훈 (체크리스트화):

• Fix-Fanout을 시작하기 전에, 같은 파일/함수를 건드리는 원본 결함의 최초 수정 PR이 이미 머지됐는지 확인하라. 아직 open 상태라면, 가능하면 원본 PR을 먼저 머지한 뒤 파생 fix 브랜치들을 따라.
• 이미 파생 브랜치들을 다 만든 상태에서 원본 PR이 머지됐다면, 각 파생 브랜치에 origin/development(또는 base) merge를 선행하고 충돌(대개 회귀 테스트 파일)을 정리한 뒤 PR을 올려라.
• 병렬 수정 PR들이 실제로 서로 다른 파일만 건드리는지 Fix-Fanout 전에 한 번 확인하면, 이런 충돌 가능성을 미리 줄일 수 있다.

체크리스트#

Triage#

• gray-list가 grep 등으로 전수 생성됐는가 (임의 샘플링 아님)
• 각 에이전트 프롬프트에 "이 패턴이 아닌 것"이 명시됐는가 (스코프 축소)
• 청크 크기가 rate limit을 고려해 적절한가

Verify#

• Triage와 별도의 에이전트가 검증하는가 (동일 에이전트 자체 확정 금지)
• dead code / self-healing / stale-only(멈추지 않음) 3가지를 재확인했는가
• Triage의 severity를 그대로 신뢰하지 않고 재평가했는가

Fix-Fanout#

• 결함 설명(파일/함수/라인/호출체인)과 수정 방향이 프롬프트에 구체적으로 포함됐는가
• isolation: 'worktree'로 항목별 격리가 적용됐는가
• 원본 root-cause fix PR이 먼저 머지됐는지(또는 머지 후 파생 브랜치에 rebase/merge할 계획인지) 확인했는가
• 각 fix 에이전트가 머지까지는 하지 않고 PR 생성에서 멈추는가

실제 사례 — kobic #7746#

kobic(Flutter/Dart melos 모노레포) 프로젝트에서 SwrStrategyImpl._revalidate의 무한 로딩 버그(#7746, 상세는 [cc-flutter-dev:swr-pattern] 참조)를 고친 뒤, 같은 unawaited() + on Exception catch(Error 누락) 패턴이 다른 곳에도 있는지 이 절차로 감사했습니다.

• Triage: unawaited(을 포함하는 프로덕션 파일 274개를 gray-list로 만들어 30개씩 청크 분할, 병렬 에이전트 배분
• Verify: 후보 중 severity "high" 2건이 죽은 코드(@Deprecated)로 기각, 1건이 BehaviorSubject.seeded()라 멈추지 않고 stale만 발생하는 것으로 기각
• Fix-Fanout: 확정 11건 + 부수 발견 죽은 코드 정리 1건, 총 12건을 isolation: 'worktree'로 동시 수정 (EPUB 리더 전체 멈춤 등 high severity 포함)
• 머지 후: 12건 중 1건에서 위 "머지 충돌 함정"이 실제로 발생 — origin/development merge + 테스트 파일 수동 정리로 해결

관련 스킬#

• [cc-flutter-dev:swr-pattern] — 이 사례의 근본 원인이 된 Dart unawaited() + Error 침묵 실패 함정 상세
• [cc-dev-cycle:merge-conflict-resolution] — Fix-Fanout 후 발생하는 머지 충돌의 파일 유형별 해소 전략
• [cc-dev-cycle:agent-teams] — Agent Teams(파일 소유권 분리) vs git worktree(파일시스템 격리) 병렬화 비교
• [cc-serverpod:serverpod-worktree-parallel] — worktree별 Serverpod 풀스택 포트/MCP 격리 (풀스택 검증이 필요한 fix에 적용)