docs(keycloak-session-store): import the session-storage lab as a new project
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>
This commit is contained in:
co-authored by
Claude Opus 5
parent
43bccd08a8
commit
b2963105a8
@@ -3,9 +3,12 @@
|
||||
칸 목록과 상한은 `record-kinds.md`, 문장 규칙은 `explaining.md`, 문서군의 리듬은 `ai-tells.md`에
|
||||
있다. 이 문서는 **그 칸을 무엇으로 채우는가**다.
|
||||
|
||||
**이미 쓴 47건에서 뽑았다.** keycloak 23건(Case 4·Concept 6·Reference 7·Question 4·Decision 2),
|
||||
n+1liner 24건(Case 5·Reference 7·Question 5·Decision 7). 「대개 이렇게 쓴다」는 말은 그 47건이
|
||||
그렇게 돼 있다는 뜻이다.
|
||||
**Studio 에 실제로 올라간 47건에서 뽑았다.** keycloak 23건(Case 4·Concept 6·Reference 7·
|
||||
Question 4·Decision 2), n+1liner 24건(Case 5·Reference 7·Question 5·Decision 7).
|
||||
「대개 이렇게 쓴다」는 말은 그 47건이 그렇게 돼 있다는 뜻이다.
|
||||
|
||||
`clean-architecture-backend-template` 의 949건은 다른 절 이름으로 쓰여 있었고 이 기준에 맞춰
|
||||
고쳤다. 올라간 적 없는 초안이 아니라 **올라간 것**이 기준이다.
|
||||
|
||||
## 파일 뼈대 — 다섯 종류가 같다
|
||||
|
||||
@@ -30,6 +33,18 @@ id · kind · slug · title · topic · project · status · studio
|
||||
|
||||
frontmatter 는 메타데이터, `##` 는 Studio 의 칸, 제목 아래 첫 문단은 요약이다. 47건 모두 이 모양이다.
|
||||
|
||||
**`## 요약` 이라는 절을 만들지 않는다.** 요약은 제목 바로 아래 문단이다. 절로 만들면 Studio 에
|
||||
그런 칸이 없어서 통째로 사라진다.
|
||||
|
||||
**`## 출처` 도 칸이 아니다.** 원본 분석 문서나 파일 경로는 frontmatter 의 `source` 에 적는다.
|
||||
본문 마지막에 두면 게시된 글에 저장소 내부 경로가 그대로 실린다.
|
||||
|
||||
```yaml
|
||||
source:
|
||||
- analysis/05-adapter-outbound-persistence-jpa.md#L354
|
||||
module: adapter-inbound-graphql
|
||||
```
|
||||
|
||||
**관계 항목은 굵은 제목 한 줄 + 이유 한 줄**이다.
|
||||
|
||||
```markdown
|
||||
@@ -58,6 +73,8 @@ frontmatter 는 메타데이터, `##` 는 Studio 의 칸, 제목 아래 첫 문
|
||||
테스트로 확인한 범위」, 「Redirect URI와 CORS에서 아직 확인하지 않은 부분」), 2건이 「다음 선택」,
|
||||
나머지가 지표 읽는 법이나 남긴 이유다. **재지 않은 것을 적지 않고 닫는 Case 는 없다**
|
||||
|
||||
그 마지막 절은 **본문 안**이다. 칸으로 빼면 Studio 에 그런 칸이 없어 사라진다.
|
||||
|
||||
코드블록에는 무엇을 보라는 한 줄을 붙인다. 표 앞이나 뒤에 그 표를 어떻게 읽는지 적는다. 예시는
|
||||
한 규모로 고정한다 — 표가 전체 계열을 이미 보여 준다.
|
||||
|
||||
@@ -131,3 +148,35 @@ basisVersion: oauth2-proxy 7.15.2 · Nginx auth_request
|
||||
- 그림 안에는 이름만 넣는다. 문장은 `<desc>` 와 옆 문단에 둔다
|
||||
- 그림과 증거는 frontmatter 의 `assets` · `evidence` 로 잇는다. 같은 파일을 기록 옆에 복사하지 않는다
|
||||
- 본문은 `<!-- body:start -->` 와 `<!-- body:end -->` 사이다. 그 밖은 Studio 로 가지 않는다
|
||||
|
||||
## 관계를 어디서 가져오나
|
||||
|
||||
관계는 **다른 기록을 가리키는 링크**다. 지어내지 않는다. 분해 계약(`root-tree.md`)이 노드마다
|
||||
`relations` 를 적어 두면 그것을 그대로 옮긴다.
|
||||
|
||||
계약이 관계를 적지 않은 노드는 한 가지 규칙만 쓸 수 있다 — **Reference 의 근거 사건은 같은
|
||||
`source` 리프의 판정이 소유한다.** 그래서 같은 분석 문서에서 나온 Reference 와 Case 는 서로
|
||||
걸 수 있다. 그 밖의 짝은 읽고 정해야 한다. 「같은 모듈이다」는 관계가 아니라 분류다.
|
||||
|
||||
```markdown
|
||||
## 관계
|
||||
|
||||
- **SQL 실패가 재시도 불가로 분류된다**
|
||||
이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
|
||||
```
|
||||
|
||||
Studio 는 Decision 만 관계를 1개 이상 요구한다. 나머지는 비어도 게시되지만, 관계 없는 기록은
|
||||
다른 기록에서 도달할 수 없다.
|
||||
|
||||
## Studio 파서가 거절하는 세 가지
|
||||
|
||||
`check_body.mjs` 가 잡는다. 셋 다 글자를 바꾸지 않고 고칠 수 있다.
|
||||
|
||||
| 쓴 것 | 파서가 읽는 것 | 고치는 법 |
|
||||
|---|---|---|
|
||||
| `` `:11`~`:14` `` | `~…~` 를 취소선으로 | `` `:11`\~`:14` `` |
|
||||
| `afterPropertiesSet(:43)` | `:43` 을 인라인 디렉티브로 | `(\:43)` 또는 백틱으로 감싼다 |
|
||||
| `:::note` 안에 문단 둘 | 거절 | 문단 하나만 담거나 절 제목 아래 평문으로 푼다 |
|
||||
|
||||
`## 확인하지 못한 것` 처럼 절 제목이 이미 무엇인지 말하는 자리에서는 `:::note` 로 다시 감싸지
|
||||
않는다. 제목과 콜아웃이 같은 말을 두 번 한다.
|
||||
|
||||
Reference in New Issue
Block a user