DongHyeonkaandClaude Opus 5
b2963105a8
The keycloak project ended with four open questions that design could not
settle. A two-VM lab was built to answer them by measurement, and this is
that material: 26 experiments, 125 raw command outputs, 22 browser captures.
Follows the import procedure in README.md.
source/ the originating repository verbatim — 78 documents, 28 SVGs,
8 manifests, plus .source-revision recording the commit
final/ the SSOT
document.md 729 lines written from the 29 experiment documents, not
concatenated: what was predicted, what was measured, and
where the measurement itself was wrong
evidence/raw 125 outputs, flattened to <experiment>__<file> because
the originals collided (01-baseline.txt appeared three
times) and the audit only globs the top level
evidence/meta one per raw file; command and exitCode are null and the
README says why rather than inventing them
evidence/browser 22 captures
assets/ three diagrams through techviz
.techviz/ their VizSpecs
A separate project rather than an addition to keycloak: the B-layer answers
that project's four questions, but the A, C and D layers are about cluster
failure, SSO and operations, and one document.md should hold one subject.
The four question records there can point here through 관계.
Recorded rather than papered over: only three of the 28 diagrams were
remade. The repository forbids hand-drawn SVG and forbids titles inside the
canvas; all 28 originals carry both, so converting them is redrawing, not
reformatting. They stay in source/ and the gap is written into the document.
verify-pipeline.py passes. audit-records.py reports no issues.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
---
|
|
kind: REFERENCE
|
|
slug: numbers-in-docs-should-be-derived
|
|
title: 문서의 수치는 세지 말고 파생하거나 게이트로 붙든다
|
|
topic: drift-direction
|
|
project: clean-architecture-backend-template
|
|
status: 게시 전
|
|
sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
|
|
rootTreeNode: reference:numbers-in-docs-should-be-derived
|
|
verifiedOn: # 이 기록은 이번 회차에 실행 확인을 하지 않았다
|
|
---
|
|
|
|
# 문서의 수치는 세지 말고 파생하거나 게이트로 붙든다
|
|
|
|
## 목적
|
|
|
|
문서에 손으로 적은 수가 코드보다 뒤처져, 그 수를 근거로 한 서술 전체가 언제 것인지 알 수 없게 되는 것을 막는다.
|
|
|
|
## 규칙
|
|
|
|
1. 셀 수 있는 것은 세지 말고 파생한다
|
|
모듈 수 어댑터 수 규칙 수는 레지스트리나 소스 트리에서 계산할 수 있다.
|
|
|
|
2. 파생할 수 없으면 게이트로 붙든다
|
|
문서의 수와 실제의 수를 비교하는 검사를 만든다. 검사가 없으면 그 수는 작성 시점의 스냅숏이다.
|
|
|
|
3. 같은 수가 여러 문서에 있으면 출처를 하나로 만든다
|
|
흩어진 수는 한 번에 갱신되지 않는다.
|
|
|
|
4. 수를 근거로 한 서술을 함께 표시한다
|
|
그 수가 틀리면 그 서술도 틀린다. 어느 서술이 그 수에 의존하는지 알 수 있어야 한다.
|
|
|
|
## 적용 조건
|
|
|
|
모듈 수 리프 수 규칙 수 지원 버전 수처럼 코드에서 셀 수 있는 모든 수치
|
|
|
|
지원 매트릭스와 아키텍처 개요 문서
|
|
|
|
## 예외
|
|
|
|
운영상의 가정으로 정한 임계값은 세는 수가 아니다. 그런 값은 출처가 판단이므로 근거를 적는 것으로 충분하다.
|
|
|
|
## 예시
|
|
|
|
여러 문서가 리프 수를 19 로 적고 레지스트리는 62 다. 빌드 설정에 그 수를 검사하는 코드가 없다.
|
|
|
|
반대 사례로, 오류 코드 태그의 카디널리티 상한은 오류 코드 정의 파일의 행 수와 동기화된다고 상수 주석에 적혀 있다.
|
|
|
|
## 관계
|
|
|
|
- **여러 문서가 19개 리프라고 적고 레지스트리는 62다**
|
|
이 규칙을 만든 사례다.
|
|
- **빠뜨림이 통과가 되는 게이트는 게이트가 아니다**
|
|
두 번째 규칙이 기대는 상위 규칙이다.
|
|
- **과대 진술 문서를 과소보다 먼저 고친다**
|
|
드리프트가 이미 생겼을 때의 우선순위다.
|
|
|