ADR·기획서의 진단 수치는 Phase 착수 전에 실측으로 재검증하라¶

맥락¶

신규 기술 도입·대규모 마이그레이션 ADR을 작성할 때 "교체 대상이 N곳"이라는 식의 진단 수치가 흔히 포함된다. 이 수치는 보통 작성 시점에 grep을 한두 번 돌려 뽑은 추정치이고, 때로는 패턴이 누락되어 실제와 큰 차이가 난다. 이 차이를 모르고 Phase 일정·범위를 짜면 마지막 Phase에서 일정이 무너진다.

자산관리 웹 Phase 9(shadcn/ui 전면 도입)에서 실제로 발생한 사례:

항목	ADR-007 진단 수치	실측 (9-B 사전 분석)	배율
직접 선언된 `<button>`	18곳	91곳	5배
직접 선언된 `<input>`	5곳	76곳	15배
직접 선언된 `<select>`	10곳	40곳	4배
하드코딩 색상 클래스	1,359곳	(미실측 — 추후 확인)	?

ADR은 Phase 9-G(나머지 페이지 + 색상 일괄 교체)를 "1~2주"로 추정했지만, 실측치 기준 작업량은 그 범위에 들어오지 않을 가능성이 높다. 다행히 9-B 시작 직전 사전 분석에서 발견되어 9-G 분할로 대응 가능했다.

가이드¶

1. 진단 수치는 "발견 시점"이 아니라 "사용 시점"에 다시 측정¶

ADR 작성 시점에 측정한 수치는 참고용으로만 신뢰한다. 그 수치를 기반으로 한 Phase가 시작되기 직전에 다시 측정하여 ADR 수치와 비교한다. 두 수치 사이에 2배 이상 차이가 있으면 Phase 범위·일정을 재조정한다.

2. 측정 패턴은 명시적·재현 가능하게¶

ADR에 "1,359곳"이라는 숫자만 적는 것은 안 된다. 어떤 패턴으로 측정했는지를 함께 기록한다:

| 항목 | 측정 명령 | 결과 | 측정일 |
|------|---------|------|--------|
| 하드코딩 색상 | `grep -rn "bg-blue-\|text-gray-\|border-red-" src/ \| wc -l` | 1,359 | 2026-04-09 |
| <button> 직접 선언 | `grep -rn "<button" src/ --include="*.tsx" \| wc -l` | 18 | 2026-04-09 |

이렇게 두면 다음 측정자가 동일 명령을 실행해서 차이를 즉시 확인할 수 있다. ADR 작성자가 어떤 패턴을 누락했는지(예: <button 검색 시 <button\n처럼 다음 줄에 속성이 오는 케이스 누락)도 추적 가능하다.

3. 사전 분석을 Phase별 의무 단계로 고정¶

각 Phase의 첫 작업은 항상 Explore 위임 또는 직접 grep으로 실측치 재검증으로 시작한다. 검증 결과를 작업지시서 또는 devlog에 다음 형식으로 기록한다:

## Phase 시작 전 실측 검증 (YYYY-MM-DD)

| 항목 | ADR 예상 | 실측 | 배율 | 조치 |
|------|---------|------|:----:|------|
| <button> | 18 | 91 | 5x | Phase 분할 검토 |
| <input> | 5 | 76 | 15x | Phase 분할 검토 |

4. 차이가 클 때의 조치 옵션 (3가지)¶

배율	권장 조치
1.5배 미만	수용. ADR 수치 옆에 실측치 주석. 일정 그대로
1.5~3배	Phase 일정만 재추정. 범위 분할은 보류. ADR에 실측 보정 메모
3배 이상	Phase 분할 또는 범위 축소 검토 필수. ADR은 보존(의사결정 시점 기록), 헌장에 분할 결정

5. ADR과 헌장의 역할 분리¶

ADR은 의사결정 시점의 스냅샷이므로 사후에 수정하지 않는다. 진단 수치도 작성 시점 그대로 둔다. 대신 헌장(또는 Phase 추적 문서)에 다음을 기록한다:

> 2026-04-10 Phase 9-B 완료 — ADR-007 수치 실측 차이 발견:
> button 91(vs ADR 18), input 76(vs ADR 5), select 40(vs ADR 10).
> 9-G 단일 Phase → 9-G1/9-G2/9-G3 도메인별 3분할로 조정.

이 분리 원칙 덕분에 "ADR 결정의 근거가 무엇이었는지"는 보존되고, "현재 실제 상황은 어떤지"도 추적된다.

왜 중요한가¶

진단 수치가 틀리면 마지막 Phase에서 일정이 폭발한다¶

대규모 마이그레이션의 마지막 Phase는 보통 나머지 일괄 정리 단계다. 앞 Phase는 기반 작업·핵심 컴포넌트라 양이 적고, 일정이 잘 맞는다. 하지만 마지막 일괄 정리 Phase는 앞 Phase의 누적 부채를 모두 떠안는다. 여기에 ADR 진단 수치까지 과소평가되어 있으면, "1~2주"가 "5~6주"로 변하는 것이 흔한 실패 패턴이다.

발견을 늦게 하면 재계획 비용이 더 든다¶

진단 수치 차이를 마지막 Phase에서 발견하면, 이미 앞 Phase의 작업 결과·문서·커밋이 누적된 상태이므로 재계획에 드는 비용이 크다. 반대로 첫 Phase 직전에 발견하면, ADR은 그대로 두고 Phase 분할만 적용해도 충분하다. 사전 분석을 Phase별 첫 단계로 고정하는 것이 가장 저렴한 안전망이다.

"사전 분석 + 파일럿"의 결합 효과¶

자산관리 9-B에서 사전 분석으로 함정 11개를 추출했고, 파일럿 1페이지(LogsPage)로 검증했다. 결과:

함정 11개 중 실제 발생 0건 (전부 generator 프롬프트에서 회피)
파일럿 외 회귀 0건
evaluator 지적은 파일럿 범위 내에서만 발생(skeleton.tsx React import, 44px 터치 영역)

사전 분석은 함정의 사전 차단, 파일럿은 남은 함정의 범위 제한을 담당한다. 두 단계가 함께 있어야 대규모 마이그레이션이 안정적으로 진행된다. 둘 중 하나만 있으면 함정이 새어 나오거나 범위가 폭발한다.

적용 시기¶

적용: 모든 ADR·기획서가 "교체 대상 N곳" 같은 정량 수치를 포함할 때.
적용: 대규모 마이그레이션·리팩터링·기술 도입의 각 Phase 첫 단계.
적용: ADR의 일정 추정이 "1~2주" 같은 범위로 적혀 있을 때 — 범위 상단·하단의 근거 검증 필요.
비적용: 단일 버그 수정·소규모 기능 추가 (수치가 의미 없는 작업).
비적용: ADR의 정성 결정(예: "shadcn 채택" 같은 선택 결정) — 이건 수치 검증 대상 아님.