DongHyeonkaandClaude Fable 5.1
b25357c48a
- analysis/·source-index·state.json 을 final/document.md 제2부·제3부로 접었다. SSOT 는 하나다 - 파일럿 — commit-ambiguity-as-a-result 를 새 기준으로 재선별. 후보 14 → 글감 5 (PROMOTE 5 · MERGE_INTO 3 · KEEP_IN_SSOT 4 · 보류 2). 기록 5건을 다시 썼고 그림 1개를 techviz 로 만들었다 - 재선별이 잡은 것: 제1부 §6.2·§11.1 이 자기 §13.2 와 어긋나 있었다(레인을 안 돌렸다 vs 돌렸다) — 정정. 이미 답이 나와 있던 Question 을 HEAD 재실행 질문으로 다시 세웠다. Concept 이 인용한 코드가 SSOT 에 없어 뺐다 - candidateScope·sourceRepository 기록. 나머지 43개 주제는 재선별 대기(PENDING 905) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
---
|
|
kind: CASE
|
|
slug: doc-contract-test-boundary-predicted-the-drift
|
|
title: 문서 계약 테스트의 단언 경계 밖에 발견된 드리프트 세 건이 전부 있었다
|
|
topic: what-a-gate-does-not-prove
|
|
project: clean-architecture-backend-template
|
|
status: 게시 전
|
|
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
|
|
rootTreeNode: case:doc-contract-test-boundary-predicted-the-drift
|
|
evidenceCapturedOn: 2026-09-01
|
|
assets:
|
|
- key: doc-contract-test-boundary-predicted-the-drift
|
|
file: ../../../final/evidence/rendered/doc-contract-test-boundary-predicted-the-drift.svg
|
|
evidence:
|
|
- ../../../final/evidence/raw/doc-contract-test-boundary-predicted-the-drift.txt
|
|
source:
|
|
- 원본 분석 절은 final/document.md#7-4 · final/document.md#a19 §9.3 이다.
|
|
---
|
|
|
|
# 문서 계약 테스트의 단언 경계 밖에 발견된 드리프트 세 건이 전부 있었다
|
|
|
|
지원 문서가 코드와 어긋나는 것을 잡는 테스트가 있고 잘 작동한다. 이 분석이 찾은 문서 드리프트 세 건은 그 테스트의 단언 여덟 개가 닿지 않는 곳에만 있었다.
|
|
|
|
## 관계
|
|
|
|
- **문서와 상수가 서로 일치하는 것으로는 아무것도 증명되지 않는다**
|
|
이 사례와 짝을 이루는 규칙이다.
|
|
- **빠뜨림이 통과가 되는 게이트는 게이트가 아니다**
|
|
같은 계열의 상위 규칙이다.
|
|
|
|
## 문제
|
|
|
|
MessagingDocumentationContractTest 가 존재하고, 클래스 javadoc 이 목적을 정확히 적는다.
|
|
|
|
문서는 조용히 썩는다. 어댑터를 Stable 이라고 적은 지원 매트릭스는 누군가 그것을 강등한 날보다 오래 살아남고, 아무것도 실패하지 않는다. 테스트는 통과하고 빌드는 초록이며 유일한 신호는 몇 달 전에 사실이 아니게 된 페이지를 보고 결정을 내리는 운영자다.
|
|
|
|
단언은 의도적으로 좁다. 읽는 사람이 행동의 근거로 삼을 주장만 검사하고 산문은 검사하지 않는다. 표현을 단언하면 모든 편집이 테스트 실패가 되고 그 검사는 삭제될 것이기 때문이다.
|
|
|
|
의도도 이유도 명확하다. 문제는 그 경계가 어디인지를 아무 데도 적어 두지 않았다는 점이다.
|
|
|
|
## 결론
|
|
|
|
단언 여덟 개는 이렇다.
|
|
|
|
지원 매트릭스가 약속하는 문서 아홉 개의 존재
|
|
STABLE 어댑터 이름의 정확한 일치
|
|
EXPERIMENTAL 어댑터가 Stable 로 적히지 않음
|
|
문서화된 Kafka 버전 문자열의 일치
|
|
존재하지 않는 상수 두 개가 미지원 목록에 여전히 있음
|
|
그 두 상수가 코드에 실제로 없음
|
|
실험 정책 문서가 기본값 꺼짐을 명시하는지
|
|
각 문서가 500자를 넘는지
|
|
|
|
앞의 여섯은 정확하고 강하다. 뒤의 둘은 문자열 포함과 길이 검사라서 약하다.
|
|
|
|
경계 밖에 있는 것은 셋이다.
|
|
|
|
능력 표. 어댑터 다섯 곱하기 플래그 열둘로 60칸이다
|
|
런타임 멤버십 문장
|
|
브로커 등급 표의 제한 칸
|
|
|
|
이 분석이 찾은 문서 드리프트 세 건이 정확히 그 셋 안에 하나씩 있었다. 우연이 아니다. 테스트가 붙드는 항목인 등급 이름과 버전 문자열과 존재하지 않는 상수는 전부 옳았고, 붙들지 않는 항목만 틀렸다.
|
|
|
|
이것이 이 테스트를 결함으로 만들지는 않는다. 좁게 만든 것은 의도이고 그 이유도 타당하다.
|
|
|
|
결함은 그 경계가 어디인지가 문서에도 테스트에도 적혀 있지 않다는 것이다. 이 테스트를 통과한 문서는 코드와 일치하도록 검증됐다고 읽힌다. 실제로 검증된 것은 여덟 항목뿐이다.
|
|
|
|
## 검증 환경
|
|
|
|
OpenJDK : 21.0.12
|
|
Gradle : 9.0.0
|
|
확인 방식 : 테스트 메서드 열거와 문서 대조
|
|
소스 수정 : x
|
|
|
|
## 재현 조건
|
|
|
|
원문은 final/evidence/raw/261-messaging-documentation-contract-test-coverage.txt 와 255-messaging-capability-doc-vs-code-drift.txt 에 있다.
|
|
|
|
1. MessagingDocumentationContractTest 의 테스트 메서드를 열거한다. 여덟 개다.
|
|
2. 각 메서드가 무엇을 단언하는지 확인한다.
|
|
3. 지원 문서에서 그 여덟 개가 닿지 않는 영역을 식별한다.
|
|
4. 그 영역을 코드와 대조한다.
|
|
|
|
## 본문
|
|
|
|
<!-- body:start -->
|
|
|
|
doc rot를 막기 위해 존재하는 계약 테스트의 단언 여덟 개가 붙드는 것은 전부 정확하다 — 등급 이름·Kafka 버전 문자열·존재하지 않는 두 enum 상수.
|
|
|
|
## 계약 테스트의 단언 여덟 개
|
|
|
|
:::evidence key="doc-contract-test-boundary-predicted-the-drift" alt="분석 문서 final/document.md 에서 이 기록의 근거 절을 그대로 잘라낸 18줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="final/document.md 발췌 — 18줄" zoom="true"
|
|
:::
|
|
|
|
## 붙들지 않는 것에 드리프트 세 건이 전부 있다
|
|
|
|
capability 표 60칸·runtime membership 문장·브로커 등급표의 "제한" 칸이다. 테스트 javadoc은 좁은 단언을 고른 이유까지 옳게 적는다.
|
|
|
|
## 결함은 경계가 적혀 있지 않다는 점이다
|
|
|
|
좁게 고른 것이 결함이 아니다.
|
|
|
|
## 확인하지 못한 것
|
|
|
|
세 건의 드리프트 각각에 대해 그것을 잡는 단언을 실제로 추가해 보지 않았다. 능력 표 60칸을 코드와 대조하는 단언이 유지 가능한 형태인지는 별도 판단이 필요하다.
|
|
|
|
없음 — 단언 목록과 문서를 전수 대조했다
|
|
|
|
<!-- body:end -->
|