--- description: 데이터가 입력·계산·저장·재사용 전 과정에서 유효하게 흐르는지 검증한다. 검증 대상 인벤토리 합의 → 데이터 흐름 레이어 매핑(입력→계산→적용→영속→재로드) → 임시 계측 로깅 주입 → 실행 로그/스냅샷 수집 → 의도값↔저장값↔재로드값 대조 + 데이터 품질 차원(완전성·유효성·정확성·일관성·무결성·유일성) 판정 → 검증 리포트 작성 → 임시 계측 회수. 데이터 정합성 / 무결성 / 데이터 흐름 추적 / 저장값 대조 / 입력·계산·저장 검증 / reconciliation / data integrity / 값이 제대로 반영·저장되는지 확인 키워드에서 호출. 코드 변경 후 "데이터가 제대로 들어가는지" 의심되는 모든 상황에서 사용한다. metadata: author: ridsync version: 1.0.0 --- # verify-data-flow — 데이터 흐름 정합성 검증 데이터가 **입력 → 계산/변환 → 적용 → 영속화 → 재로드** 전 과정에서 의도대로 흐르고 저장되는지를 실측으로 검증하는 7 Phase 워크플로우. 런타임 흐름 추적(코드 계측)과 정적 무결성 검증(스키마/제약/대조)을 모두 다룬다. ## 왜 이 워크플로우인가 데이터 버그는 "값은 맞아 보이는데 어딘가에서 틀어진다"가 대부분이다. 추론만으로는 어느 레이어에서 틀어졌는지 못 짚는다. 그래서 **각 레이어에 실측 증거를 심고, 의도값과 실제 저장값을 직접 대조**한다. 계측은 검증 전용 임시 코드이므로, 끝나면 흔적 없이 회수하는 것까지가 한 사이클이다. ## 호출 방법 ``` /devoks-sdlc:verify-data-flow [target=<검증 대상 데이터/필드>] [spec=<기준 문서 경로>] [flow=<실행 시나리오>] [env=] ``` **예시:** ``` /devoks-sdlc:verify-data-flow target="주문 합계·할인율·override" spec=doc/order_discount_workflow.md flow="쿠폰 적용 후 결제 완료" env=browser ``` 인자가 없어도 동작한다. Phase 0 에서 1회 확인한다. ## 추상 슬롯 (프로젝트별 사용자가 채움) | 슬롯 | 의미 | 입력 방법 | |------|------|----------| | `` | 검증 대상 데이터 값/필드 목록 (인벤토리) | `target` 인자 또는 Phase 0 확인 | | `` | 검증 기준 — 공식/임계값/스키마/제약 정의 문서 | `spec` 인자 또는 Phase 0 확인 | | `` | 입력/계산/적용/영속 레이어의 코드 경로 | Phase 1 에서 코드 탐색으로 도출 | | `` | 최종 영속화 SSOT (DB 테이블 / localStorage / 파일 / API) | Phase 1 확인 | | `` | 데이터를 발생시키는 실행 시나리오 | `flow` 인자 또는 Phase 0 확인 | | `` | 로그/스냅샷 수집 방법 | `` 에 따라 Phase 0 결정 | | `` | 실행 환경 (`browser` / `server` / `db` / `cli`) | `env` 인자 또는 Phase 0 확인 | | `` | 계측 로깅 태그 | 기본 `DATA_AUDIT` | | `` | 임시 코드 식별 마커 | 기본 `AUDIT-TEMP` | | `` | 회수 후 검증 명령 (lint/test/build) | Phase 0 확인 | > 슬롯 값은 실행 시점에만 사용하며 SKILL.md 에 저장하지 않는다. --- ## 핵심 원칙 - **증거 우선 (Evidence first)** — 추론이 아니라 각 레이어의 실측 로그로 판정한다. "맞을 것이다"는 결론이 아니다. - **3중 대조 (Intent ↔ Persisted ↔ Reloaded)** — 적용 의도값, 저장소에 실제 쓰인 값, 다시 읽은 값 셋이 일치해야 정합이다. 한 축만으로는 부족하다. - **영속 지점은 단일 관문에서 캡처** — 모든 쓰기가 통과하는 저장 SSOT(예: DB write 함수, localStorage setter)에 watch-key 필터 로깅을 두면 적은 코드로 결정적 증거를 얻는다. - **계측은 임시, 반드시 회수** — 추가 코드 전부에 `` 주석을 달고 Phase 6 에서 grep 으로 전량 제거한다. 남은 로깅은 그 자체로 버그다. - **기준과 대조 (Spec-driven)** — 계산값·제약은 반드시 `` 의 공식/임계값/스키마와 직접 대조한다. 기준 없는 "그럴듯함"은 검증이 아니다. - **읽기 전 변경 금지** — 계측 지점을 정하기 전에 해당 코드를 먼저 읽는다. 흐름을 모르고 로깅을 심으면 엉뚱한 레이어를 본다. --- ## 데이터 품질 차원 (판정 기준) 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. `` 가 있으면 관련 공식·임계값·스키마 섹션을 Read 하여 판정 기준을 미리 확보한다. --- ## Phase 1 — 데이터 흐름 레이어 매핑 목적: 대상 값마다 **입력 → 계산/변환 → 적용 → 영속화 → 재로드** 경로를 코드에서 짚는다. 1. 대상 값을 코드에서 추적(Serena/grep)하여 각 레이어의 함수·파일을 식별한다. 2. **데이터 흐름 표**를 만든다: | 값 | 입력 지점 | 계산/변환 | 적용 함수 | 영속 SSOT | 재로드 | |----|----------|-----------|-----------|-----------|--------| | 예: offset | 사용자 입력/센서 | `computeX()` | `applyX()` | `db.save()` | `loadX()` | 3. **영속 SSOT(``)를 반드시 특정**한다 — 모든 쓰기가 통과하는 단일 관문. 여기가 3중 대조의 핵심 캡처 지점이다. 4. 정적 무결성 검증(런타임 계측 없이 기존 데이터 점검)이면, source ↔ target 대조 지점과 제약(스키마/FK/unique)을 식별한다. --- ## Phase 2 — 계측 (instrumentation) 목적: 각 레이어에 **임시** 로깅을 심어 흐르는 값을 드러낸다. 상세 패턴은 `references/instrumentation-patterns.md` 참조. 1. 일관 태그 `` 로 로거 1개를 레이어마다 둔다. 이벤트명은 `단계.항목` 형식(`apply.offset`, `persist.localSettings`)으로 콘솔 가독성을 확보한다. 2. **레이어별 무엇을 찍나:** - 입력/계산: 원자료 + 계산 결과 (+ 적용된 공식 파라미터) - 적용: 적용 의도값 + `before → after` - **영속 SSOT**: watch-key 집합에 속한 키가 변경될 때만 `before(현재값) → after(저장된 값)` — 이것이 결정적 증거 - 완료 시점: 전 대상 값 최종 스냅샷(재로드값) 1회 덤프 3. 모든 추가 코드(로거 인스턴스·로깅 호출·deps 추가)에 `// []` 주석을 단다. 4. 정적 검증이면 계측 대신 쿼리/스냅샷 스크립트를 작성한다 (`references/collection-by-environment.md` §DB/파일). 5. 계측 후 lint 통과를 확인한다(특히 React deps). --- ## Phase 3 — 실행 + 수집 목적: `` 를 실행하고 증거를 모은다. **환경별 수집 절차는 `references/collection-by-environment.md` 참조.** 1. 수집을 깨끗한 상태에서 시작하도록 준비한다 (브라우저면 계측 코드 반영 위해 리로드, 서버면 로그 시점 표시). 2. 사용자에게 `` 실행을 요청한다. 가능하면 분기 경로(재시도·이상치·누적)도 한 번씩 태우도록 안내한다. 3. 실행 후 로그/스냅샷을 수집한다. 4. **대용량 로그 처리** — 출력이 크면 raw 를 통째로 읽지 말고 `` 로 필터해 핵심만 추출한다. 브라우저 콘솔의 객체 payload 펼침 등 환경별 함정은 reference 에 정리돼 있다. --- ## Phase 4 — 대조 분석 (정합성·무결성 판정) 목적: 수집 증거로 데이터가 유효하게 흘렀는지 판정한다. 1. **3중 대조**: 각 대상 값에 대해 `적용 의도값(Phase2) == 영속 저장값(SSOT 로그) == 최종 재로드값(스냅샷)` 인지 확인. 2. **기준 대조**: 계산·변환값을 `` 의 공식/임계값/스키마와 직접 계산해 비교한다 (직접 산식을 재현해 일치 확인). 3. **품질 차원 점검**: 위 «데이터 품질 차원» 표에서 대상에 해당하는 항목을 점검한다 — 특히 무결성(이중 합산·누적 오류), 유효성(범위·clamp), 정확성(공식). 4. 불일치·이상치·미검증 경로를 분류한다: `정합 / 불일치(버그) / 정합이나 관찰 필요 / 미검증`. --- ## Phase 5 — 검증 리포트 `references/report-template.md` 템플릿으로 리포트를 작성한다. 기본 저장 위치는 프로젝트 문서 디렉토리(예: `doc/`)이며, 파일명은 `<대상>-verify-data-flow-result.md`. 리포트는 반드시 포함한다: **종합 판정(✅/⚠️/❌) → 단계별 대조 표 → 기준 대조(공식 재현) → 발견 사항(severity) → 미검증 경로 → 원시 증거 출처**. --- ## Phase 6 — 회수 + 검증 1. 임시 계측 전량 식별: ```bash grep -rn "" <소스 루트> ``` 2. 식별된 로깅·로거·마커를 모두 제거(원복)한다. 검증용으로 바꾼 로직(임시 게이트 등)이 있으면 함께 정리하되, 최종 처리 방향은 사용자와 합의한다. 3. 회수 후 검증: ```bash # 예: 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 |