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>
2.3 KiB
2.3 KiB
kind, slug, title, topic, project, status, sourceRevision, rootTreeNode, verifiedOn
| kind | slug | title | topic | project | status | sourceRevision | rootTreeNode | verifiedOn |
|---|---|---|---|---|---|---|---|---|
| REFERENCE | numbers-in-docs-should-be-derived | 문서의 수치는 세지 말고 파생하거나 게이트로 붙든다 | drift-direction | clean-architecture-backend-template | 게시 전 | 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916 | reference:numbers-in-docs-should-be-derived |
문서의 수치는 세지 말고 파생하거나 게이트로 붙든다
목적
문서에 손으로 적은 수가 코드보다 뒤처져, 그 수를 근거로 한 서술 전체가 언제 것인지 알 수 없게 되는 것을 막는다.
규칙
-
셀 수 있는 것은 세지 말고 파생한다 모듈 수 어댑터 수 규칙 수는 레지스트리나 소스 트리에서 계산할 수 있다.
-
파생할 수 없으면 게이트로 붙든다 문서의 수와 실제의 수를 비교하는 검사를 만든다. 검사가 없으면 그 수는 작성 시점의 스냅숏이다.
-
같은 수가 여러 문서에 있으면 출처를 하나로 만든다 흩어진 수는 한 번에 갱신되지 않는다.
-
수를 근거로 한 서술을 함께 표시한다 그 수가 틀리면 그 서술도 틀린다. 어느 서술이 그 수에 의존하는지 알 수 있어야 한다.
적용 조건
모듈 수 리프 수 규칙 수 지원 버전 수처럼 코드에서 셀 수 있는 모든 수치
지원 매트릭스와 아키텍처 개요 문서
예외
운영상의 가정으로 정한 임계값은 세는 수가 아니다. 그런 값은 출처가 판단이므로 근거를 적는 것으로 충분하다.
예시
여러 문서가 리프 수를 19 로 적고 레지스트리는 62 다. 빌드 설정에 그 수를 검사하는 코드가 없다.
반대 사례로, 오류 코드 태그의 카디널리티 상한은 오류 코드 정의 파일의 행 수와 동기화된다고 상수 주석에 적혀 있다.
관계
- 여러 문서가 19개 리프라고 적고 레지스트리는 62다 이 규칙을 만든 사례다.
- 빠뜨림이 통과가 되는 게이트는 게이트가 아니다 두 번째 규칙이 기대는 상위 규칙이다.
- 과대 진술 문서를 과소보다 먼저 고친다 드리프트가 이미 생겼을 때의 우선순위다.