devoks:data-verification

data-verification

데이터가 입력 → 계산/변환 → 적용 → 영속화 → 재로드 전 과정에서 의도대로 흐르고 저장되는지를 실측으로 검증하는 7 Phase 워크플로우. 런타임 흐름 추적(코드 계측)과 정적 무결성 검증(스키마/제약/대조)을 모두 다룬다.

왜 이 워크플로우인가

데이터 버그는 "값은 맞아 보이는데 어딘가에서 틀어진다"가 대부분이다. 추론만으로는 어느 레이어에서 틀어졌는지 못 짚는다. 그래서 각 레이어에 실측 증거를 심고, 의도값과 실제 저장값을 직접 대조한다. 계측은 검증 전용 임시 코드이므로, 끝나면 흔적 없이 회수하는 것까지가 한 사이클이다.

호출 방법

/data-verification [target=<검증 대상 데이터/필드>] [spec=<기준 문서 경로>] [flow=<실행 시나리오>] [env=<browser|server|db|cli>]

예시:

/data-verification target="추출 보정 B2·override·brewAmountWeight" spec=doc/brew_adjustment_workflow.md flow="보정 2세트 완주" env=browser

인자가 없어도 동작한다. Phase 0 에서 1회 확인한다.

추상 슬롯 (프로젝트별 사용자가 채움)

슬롯	의미	입력 방법
<TargetData>	검증 대상 데이터 값/필드 목록 (인벤토리)	target 인자 또는 Phase 0 확인
<SpecSource>	검증 기준 — 공식/임계값/스키마/제약 정의 문서	spec 인자 또는 Phase 0 확인
<DataFlowLayers>	입력/계산/적용/영속 레이어의 코드 경로	Phase 1 에서 코드 탐색으로 도출
<PersistenceLayer>	최종 영속화 SSOT (DB 테이블 / localStorage / 파일 / API)	Phase 1 확인
<TriggerFlow>	데이터를 발생시키는 실행 시나리오	flow 인자 또는 Phase 0 확인
<CollectionMethod>	로그/스냅샷 수집 방법	<Environment> 에 따라 Phase 0 결정
<Environment>	실행 환경 (browser / server / db / cli)	env 인자 또는 Phase 0 확인
<AuditTag>	계측 로깅 태그	기본 DATA_AUDIT
<AuditMarker>	임시 코드 식별 마커	기본 AUDIT-TEMP
<VerifyCommands>	회수 후 검증 명령 (lint/test/build)	Phase 0 확인

슬롯 값은 실행 시점에만 사용하며 SKILL.md 에 저장하지 않는다.

---

핵심 원칙

• 증거 우선 (Evidence first) — 추론이 아니라 각 레이어의 실측 로그로 판정한다. "맞을 것이다"는 결론이 아니다.
• 3중 대조 (Intent ↔ Persisted ↔ Reloaded) — 적용 의도값, 저장소에 실제 쓰인 값, 다시 읽은 값 셋이 일치해야 정합이다. 한 축만으로는 부족하다.
• 영속 지점은 단일 관문에서 캡처 — 모든 쓰기가 통과하는 저장 SSOT(예: DB write 함수, localStorage setter)에 watch-key 필터 로깅을 두면 적은 코드로 결정적 증거를 얻는다.
• 계측은 임시, 반드시 회수 — 추가 코드 전부에 <AuditMarker> 주석을 달고 Phase 6 에서 grep 으로 전량 제거한다. 남은 로깅은 그 자체로 버그다.
• 기준과 대조 (Spec-driven) — 계산값·제약은 반드시 <SpecSource> 의 공식/임계값/스키마와 직접 대조한다. 기준 없는 "그럴듯함"은 검증이 아니다.
• 읽기 전 변경 금지 — 계측 지점을 정하기 전에 해당 코드를 먼저 읽는다. 흐름을 모르고 로깅을 심으면 엉뚱한 레이어를 본다.

---

데이터 품질 차원 (판정 기준)

Phase 4 판정은 아래 차원으로 점검한다 (DAMA-DMBOK / ISO/IEC 25012 기반). 대상에 해당하는 차원만 선택 적용. 상세 체크리스트는 references/data-quality-dimensions.md 참조.

차원	질문
완전성 Completeness	필수 값이 누락 없이 모두 존재하는가
유효성 Validity	타입·범위·형식·enum 제약을 지키는가
정확성 Accuracy	계산·변환 결과가 기준(공식)과 일치하는가
일관성 Consistency	레이어 간(의도/저장/재로드) 값이 어긋나지 않는가
무결성 Integrity	참조/관계/누적이 깨지지 않는가 (이중 합산·고아 참조 등)
유일성 Uniqueness	중복 없이 한 번만 반영되는가
적시성 Timeliness	다음 사용 시점에 갱신값이 반영되는가

---

Phase 0 — 검증 대상 합의 (입력)

목적: 무엇을, 어떤 기준으로, 어떻게 실행해 확인할지를 사용자와 1회 합의한다. 여기서 어긋나면 이후 전부 헛수고다.

1. $ARGUMENTS 에서 슬롯 파싱.
2. 미충족 슬롯을 1회 확인:
   • "검증할 데이터(값/필드), 기준 문서(공식/임계값/스키마), 실행 시나리오, 실행 환경(browser/server/db/cli), 회수 후 검증 명령을 알려주세요."
3. 검증 대상 인벤토리 표를 작성한다 — 값마다 의미 / 자료형·범위 / 기준 출처 / 예상 저장 위치. 이 표가 Phase 4 체크리스트가 된다.
4. <SpecSource> 가 있으면 관련 공식·임계값·스키마 섹션을 Read 하여 판정 기준을 미리 확보한다.

---

Phase 1 — 데이터 흐름 레이어 매핑

목적: 대상 값마다 입력 → 계산/변환 → 적용 → 영속화 → 재로드 경로를 코드에서 짚는다.

1. 대상 값을 코드에서 추적(Serena/grep)하여 각 레이어의 함수·파일을 식별한다.

2. 데이터 흐름 표를 만든다:

   값	입력 지점	계산/변환	적용 함수	영속 SSOT	재로드
   예: offset	사용자 입력/센서	computeX()	applyX()	db.save()	loadX()

3. 영속 SSOT(<PersistenceLayer>)를 반드시 특정한다 — 모든 쓰기가 통과하는 단일 관문. 여기가 3중 대조의 핵심 캡처 지점이다.

4. 정적 무결성 검증(런타임 계측 없이 기존 데이터 점검)이면, source ↔ target 대조 지점과 제약(스키마/FK/unique)을 식별한다.

---

Phase 2 — 계측 (instrumentation)

목적: 각 레이어에 임시 로깅을 심어 흐르는 값을 드러낸다. 상세 패턴은 references/instrumentation-patterns.md 참조.

1. 일관 태그 <AuditTag> 로 로거 1개를 레이어마다 둔다. 이벤트명은 단계.항목 형식(apply.offset, persist.localSettings)으로 콘솔 가독성을 확보한다.
2. 레이어별 무엇을 찍나:
   • 입력/계산: 원자료 + 계산 결과 (+ 적용된 공식 파라미터)
   • 적용: 적용 의도값 + before → after
   • 영속 SSOT: watch-key 집합에 속한 키가 변경될 때만 before(현재값) → after(저장된 값) — 이것이 결정적 증거
   • 완료 시점: 전 대상 값 최종 스냅샷(재로드값) 1회 덤프
3. 모든 추가 코드(로거 인스턴스·로깅 호출·deps 추가)에 // [<AuditMarker>] 주석을 단다.
4. 정적 검증이면 계측 대신 쿼리/스냅샷 스크립트를 작성한다 (references/collection-by-environment.md §DB/파일).
5. 계측 후 lint 통과를 확인한다(특히 React deps).

---

Phase 3 — 실행 + 수집

목적: <TriggerFlow> 를 실행하고 증거를 모은다. 환경별 수집 절차는 references/collection-by-environment.md 참조.

1. 수집을 깨끗한 상태에서 시작하도록 준비한다 (브라우저면 계측 코드 반영 위해 리로드, 서버면 로그 시점 표시).
2. 사용자에게 <TriggerFlow> 실행을 요청한다. 가능하면 분기 경로(재시도·이상치·누적)도 한 번씩 태우도록 안내한다.
3. 실행 후 로그/스냅샷을 수집한다.
4. 대용량 로그 처리 — 출력이 크면 raw 를 통째로 읽지 말고 <AuditTag> 로 필터해 핵심만 추출한다. 브라우저 콘솔의 객체 payload 펼침 등 환경별 함정은 reference 에 정리돼 있다.

---

Phase 4 — 대조 분석 (정합성·무결성 판정)

목적: 수집 증거로 데이터가 유효하게 흘렀는지 판정한다.

1. 3중 대조: 각 대상 값에 대해 적용 의도값(Phase2) == 영속 저장값(SSOT 로그) == 최종 재로드값(스냅샷) 인지 확인.
2. 기준 대조: 계산·변환값을 <SpecSource> 의 공식/임계값/스키마와 직접 계산해 비교한다 (직접 산식을 재현해 일치 확인).
3. 품질 차원 점검: 위 «데이터 품질 차원» 표에서 대상에 해당하는 항목을 점검한다 — 특히 무결성(이중 합산·누적 오류), 유효성(범위·clamp), 정확성(공식).
4. 불일치·이상치·미검증 경로를 분류한다: 정합 / 불일치(버그) / 정합이나 관찰 필요 / 미검증.

---

Phase 5 — 검증 리포트

references/report-template.md 템플릿으로 리포트를 작성한다. 기본 저장 위치는 프로젝트 문서 디렉토리(예: doc/)이며, 파일명은 <대상>-data-verification-result.md.

리포트는 반드시 포함한다: 종합 판정(✅/⚠️/❌) → 단계별 대조 표 → 기준 대조(공식 재현) → 발견 사항(severity) → 미검증 경로 → 원시 증거 출처.

---

Phase 6 — 회수 + 검증

1. 임시 계측 전량 식별:

   grep -rn "<AuditMarker>" <소스 루트>
   

2. 식별된 로깅·로거·마커를 모두 제거(원복)한다. 검증용으로 바꾼 로직(임시 게이트 등)이 있으면 함께 정리하되, 최종 처리 방향은 사용자와 합의한다.
3. 회수 후 검증:

   <VerifyCommands>   # 예: npm run lint
   git diff --stat    # → 의도한 변경만 남고 계측 흔적은 0 이어야 함
   

4. 수집 산출물(대용량 로그 덤프 등) 정리 여부를 확인한다.

---

Reference 파일 목록

파일	내용	언제 읽나
references/instrumentation-patterns.md	계측 로깅 패턴(일관 태그·마커·before/after·영속 watch-key·deps)	Phase 2
references/collection-by-environment.md	환경별 수집(브라우저 콘솔/서버 로그/DB 쿼리/파일) + 대용량·객체 펼침 함정	Phase 3
references/data-quality-dimensions.md	데이터 품질 차원 체크리스트 + 정적 무결성 점검 항목	Phase 0·4
references/report-template.md	검증 리포트 템플릿	Phase 5