23 KiB
keycloak 7단계 하네스 기준 재검토 — 2026-09-19
최종 판정
keycloak = 아직 더 봐야댐
이번 리뷰의 정본 기준은 기술 정확성 자체가 아니라 다음 하네스 계약이다.
.agents/skills/running-tech-log-pipeline/SKILL.md
문서 작성은 다음 7단계를 기준으로 판단한다.
| 단계 | 계약 |
|---|---|
| S1 | 코드베이스 → SSOT |
| S2 | SSOT → 분해 계약 |
| S3 | 글감 → 기록 |
| S4 | 기록 → 그림 |
| S5 | AI 티 제거 |
| S6 | 일한 사람의 목소리 |
| S7 | Studio 저장 |
이번 리뷰에서 특히 확인하는 사용자 기준은 다음 세 가지다.
- AI 티를 제거하고 사람이 쓴 기술 문서처럼 읽히는가
- 그림이 필요한 곳에 적절한 SVG를 쓰고, 필요 없는 곳에 억지 그림을 넣지 않았는가
- 사람이 따라 치는 명령이 있다면 이해하기 쉬운 형태인가
기술 사실 오류는 이 세 기준과 별개로 버리지 않는다. S3의 evidence/fact review 범위에서 보조 finding으로 유지한다.
1. 7단계 절차 준수 상태
1.1 런 원장으로 확인되는 기록
현재 keycloak 기록은 24개다.
현재 런 원장:
- run.json 13개
- 고유 기록 기준 12개
question-bff-state-store.md만 두 런이 존재
따라서 24개 중 12개는 7단계 런 원장으로 절차를 확인할 수 있고, 나머지 12개는 현재 결과물로만 역검증할 수 있다.
이것은 과거 기록에 원장을 새로 만들어 채우라는 뜻이 아니다.
하네스 계약 자체가:
지나간 일에 원장을 소급해 만드는 것은 영수증 위조다.
라고 명시한다.
따라서 기존 12개 무원장 기록에 가짜 원장을 만들면 안 된다.
현재 존재하는 keycloak run.json 13개는 각각:
python3 scripts/verify-pipeline-run.py <run.json>
으로 다시 확인했고 전부 exit 0이다.
원장이 있는 기록의 공통 흐름은 다음과 같다.
- S1 SKIPPED — 기존 SSOT 사용
- S2 SKIPPED — 기존 PROMOTE/CONFIRMED tree node 사용
- S3 DONE
- S4 SKIPPED — 이번 수정에서 새 그림 소재 없음
- S5 DONE
- S6 DONE
- S7 SKIPPED — Studio 반입 요청 없음
skip reason도 전부 기록돼 있어 절차적으로는 유효하다.
판정
현재 존재하는 run ledger는 정상이다.
다만 전체 24개 기록에 대해:
“모든 문서가 실제로 7단계 파이프라인을 거쳤다”
고 말할 수는 없다.
12개는 procedural evidence 없음으로 남긴다.
2. S1 — 코드베이스 → SSOT
현재 상태
docs/keycloak/final/document.md 존재.
Project Layout:
- error 0
Tech Log Tree에서 source repository는:
/home/donghyeon/workspace/keycloak-pattern
을 가리킨다.
현재 머신에는 이 source repository가 없으므로 live reconciliation은:
UNVERIFIABLE
이다.
판정
S1 산출물 구조는 정상이다.
다만 현재 리뷰에서 source repo를 다시 대조할 수 없으므로:
- 기존 SSOT가 현재 코드와 정확히 같은가
- 최근 코드 변경이 SSOT에 빠졌는가
는 확인할 수 없다.
이를 PASS로 올리지 않는다.
3. S2 — SSOT → 분해 계약
현재:
- records = 24
- topics = 1
- nodes = 24
- written = 24
- unwritten = 0
- PROMOTE = 24
verify-tech-log-tree.py keycloak:
PASS
현재 24개 기록은 tree에 모두 연결되어 있다.
판정
S2는 현재 산출물 기준 정상이다.
4. S3 — 글감 → 기록
Required Content:
PASS — 24 records · error 0
Record Audit:
문제 0
종류 구성:
- Case 4
- Concept 6
- Decision 2
- Question 4
- Reference 8
- Setup 0
Reference / Question / Decision에 SVG를 억지로 넣지 않은 것도 하네스 계약과 맞다.
S3 보조 finding — 기술 사실
직전 기술 리뷰에서 남은 항목은 S3/fact-review 관점에서 유지한다.
F-S3-01 — Public/Confidential client 정의 scope 통일 필요
다음 위치에 shared client secret만으로 client type을 정의하는 문장이 남아 있다.
final/document.mdreference-public-confidential-client.mdcase-browser-credential-boundary.mdcase-ap2-split-custody.md
일반 OAuth client type 정의와 이 프로젝트의 client_secret_basic 구현 사실을 분리해야 한다.
F-S3-02 — Token Endpoint 제목 scope
reference-authorization-code-endpoints.md
현재:
Token Endpoint에서 비로소 클라이언트를 인증한다
본문은 이미 conditional/confidential scope로 수정됐으므로 제목도 같은 범위로 맞춘다.
F-S3-03 — Referrer-Policy 조건
Authorization Endpoint URL이 referrer에 남는다는 문장은 Referrer-Policy 조건을 붙여야 한다.
이 세 건은 이번 하네스 리뷰의 주축은 아니지만 S3 fact review에서 그대로 고쳐야 할 항목이다.
5. S4 — 기록 → 그림
이 단계가 이번 재검토에서 가장 중요한 차이를 만들었다.
하네스의 그림 판단 기준은 세 관문이다.
- Case / Concept / Setup인가
- 표로 해결되는 내용이 아닌가
- 그림이 없으면 독자가 보지 못하는 구조·순서·경계가 있는가
그리고 Concept은:
남의 것이 어떤 순서·구조로 동작하나
를 sequence, component-flow 등으로 표현한다.
5.1 현재 존재하는 SVG
TechViz spec은 10개다.
| SVG | profile | 판정 |
|---|---|---|
| ap1-browser-bearer-flow | sequence | 적절 |
| ap1-direct-architecture | component-flow | 적절 |
| ap2-mediator-architecture | component-flow | 적절 |
| ap2-mediator-handoff-flow | sequence | 적절 |
| ap3-bff-architecture | component-flow | 적절 |
| ap3-bff-session-flow | sequence | 적절 |
| ap3-csrf-boundary | component-flow | 적절 |
| ap4-edge-forward-auth-flow | sequence | 적절 |
| ap4-edge-trust-architecture | component-flow | 적절 |
| login-api-phase-split | component-flow | 적절 |
자동 검사:
- Figure Text PASS
- Figure Provenance PASS
- Figure Overlap PASS
- 현재 SVG 10개 모두 techviz 정본 존재
기존 그림 자체에 대한 판정
현재 연결된 SVG 10개에서 “이 기록에 왜 이 그림이 있는지 모르겠다”는 그림은 발견하지 않았다.
AP1~AP4 Case의 architecture + sequence 조합도 각기:
- custody / boundary
- 실제 요청 순서
를 나눠 보여 주므로 중복이라 보기 어렵다.
CSRF 그림과 Forward-Auth 그림의 Concept 재사용도 같은 관계를 설명하므로 허용 가능하다.
6. S4 누락 Finding
F-S4-01 — HIGH — Bearer JWT validation chain은 SVG가 있어야 한다
파일:
concept/concept-bearer-jwt-validation-chain.md
현재 본문은 다음 변환을 text fence로만 표현한다.
raw Bearer JWT
→ NimbusJwtDecoder(JWK signature)
→ default issuer + timestamp validators
→ AudienceValidator("keycloak-pattern-api")
→ validated Jwt
→ KeycloakRealmRoleConverter
→ authenticated principal + ROLE_* authorities
이 기록의 제목 자체가:
Bearer JWT가 인증된 principal이 되기까지
다.
즉 독자 질문이 명확하게 **“입력이 어떤 단계의 검증과 변환을 지나 principal이 되는가”**다.
이는 하네스의 Concept 그림 기준인:
- sequence
- component-flow
- 변환 사슬
에 정확히 해당한다.
왜 text fence만으로 부족한가
현재 text fence는 문장보다 낫지만:
- Spring이 맡는 구간
- 직접 구성한 validator/converter 구간
- 검증과 변환의 경계
를 공간적으로 구분하지 못한다.
권장 그림
예:
bearer-jwt-validation-chain
profile:
component-flow
핵심 노드:
Bearer input → JwtDecoder → issuer/time validation → audience validation → validated Jwt → role converter → principal
Spring framework-owned 단계와 project-owned 단계가 근거상 가능하면 group으로 나눈다.
판정
S4 누락.
F-S4-02 — HIGH — IdP Brokering은 SVG가 있어야 한다
파일:
concept/concept-idp-brokering.md
현재 text fence:
Google identity assertion
→ Keycloak broker validation
→ provider alias + upstream sub로 account identity 결정
→ Keycloak local user/session
→ Keycloak authorization code
→ AP1·AP2·AP3·AP4 중 선택한 downstream 경계
그리고 본문은:
두 개의 OAuth 왕복이 이어진다
를 핵심으로 삼는다.
이 Concept에서 독자가 봐야 하는 것은:
- upstream IdP ↔ Keycloak broker
- Keycloak broker ↔ application
- issuer가 어디에서 끊기는지
- 외부 IdP가 다섯 번째 application pattern이 아닌 이유
다.
이건 표보다 경계와 순서가 중요하다.
권장 그림
예:
idp-broker-upstream-downstream-boundary
profile:
two-zone-pipeline 또는 sequence
핵심 경계:
Google/upstream → Keycloak broker → AP1~AP4 application boundary
판정
S4 누락.
6.3 SVG가 없는 것이 맞는 Concept
파일:
concept-browser-credential-storage.md
이 기록의 핵심 비교는 이미:
| 위치 | 새로고침 뒤 | JavaScript가 읽나 | 요청에 자동으로 붙나 |
표로 표현돼 있다.
관계선을 제거해도 의미가 남는 비교이므로 하네스 기준상 표가 맞다.
따라서 이 기록에 SVG가 없는 것은 문제 아니다.
판정
S4 SKIP 적절.
7. S5 — AI 티 제거
기계 검사:
- Natural Prose: 24/24 hard error 0
하지만 하네스는 이것만으로 S5 완료라고 하지 않는다.
style_profile.mjs도 함께 보고, 마지막에는 사람이 읽어야 한다.
현재 24개 중 14개가 style profile의 참고 범위를 하나 이상 벗어난다.
이 수치 자체는 FAIL이 아니다.
하네스가 명시적으로:
수치를 맞추려고 문장을 넣지 않는다.
고 하기 때문이다.
따라서 아래는 수치 + 실제 문장 패턴이 함께 문제인 문서만 추렸다.
8. S5 재작업 Finding
F-S5-01 — HIGH — reference-pattern-selection에 작성 지시문이 남아 있다
파일:
reference/reference-pattern-selection.md
하네스 review checklist는 다음을 금지한다.
봐야 한다먼저 본다함께 적는다- 작성 방법을 독자에게 지시하는 문장
현재 실제 문장:
52행:
성공 응답과 실패 응답까지 봐야 한다.
68행:
어떤 보안 요구사항과 운영 조건 때문에 그 구조를 골랐는지 함께 적는다.
74행:
... 어떻게 복구할지를 따로 확인해야 한다.
76행:
... 운영 항목까지 같이 적는다.
이 Reference는 “선택 기준”을 설명해야 하는데 중간중간 문서를 어떻게 작성할지 지시하는 문체가 섞인다.
수정 방향
작성 지시를 기준 자체로 바꾼다.
예:
기존:
성공 응답과 실패 응답까지 봐야 한다.
방향:
비교 입력에는 실제 endpoint, method, 중간 credential, 성공·실패 응답이 포함된다.
기존:
운영 항목까지 같이 적는다.
방향:
선택 기준에는 재시작, replica 이동, 저장소 장애, secret rotation 같은 운영 조건도 포함된다.
판정
S5 재작업 필요.
F-S5-02 — HIGH — reference-public-confidential-client가 반복 정의 + 영문 밀도가 높다
style profile:
- 평균 문장 길이 77.6
- 120자 초과 문장 비율 0.125
- 문장당 bare English word 3.77
- 한글 비율 0.50
4개 지표가 동시에 범위를 벗어난 유일한 기록이다.
문제는 숫자가 아니라 실제 본문에서도 같은 정의가 반복된다는 점이다.
23행:
OAuth 클라이언트의 종류는 클라이언트 시크릿을 안전하게 보관할 수 있는지로 정한다.
41행:
OAuth client type은 authorization server에 대해 client credential의 기밀성을 유지하고 ...
47행:
클라이언트 종류는 client credential을 안전하게 보호하고 ...
85행:
클라이언트 종류는 authorization server에 대한 client credential 보호와 ...
같은 정의를 다른 영문 조합으로 여러 번 반복한다.
이건 S5가 제거해야 하는:
- 반복 문형
- 결론 재진술
- 과도한 technical English 밀도
에 해당한다.
수정 방향
정의는 앞에서 한 번 정확하게 고정한다.
그 뒤에는:
- AP1에서 왜 public인지
- AP2~AP4에서 왜 confidential인지
- client type과 token custody가 왜 다른 축인지
실제 프로젝트 예시로 바로 들어간다.
판정
S5 재작업 필요.
F-S5-03 — MEDIUM — reference-idp-federation-boundary의 문장이 과도하게 길다
style profile:
- 평균 79.5자
- 120자 초과 12%
특히:
34행 46행 66행 77~78행
은 조건과 예외가 한 문장에 너무 많이 들어간다.
기술 내용은 비교적 명확하지만 사람이 읽을 때 한 문장 안에서:
상황 → 조건 → 예외 → 판단
을 여러 번 되짚게 된다.
수정 방향
사실을 줄이지 않고:
- 현재 경계
- 경계가 깨지는 조건
- 아직 확인하지 않은 것
으로 문장을 나눈다.
판정
S5 한 번 더 필요.
F-S5-04 — MEDIUM — question-bff-state-store에 메타 안내 문장이 남아 있다
49행:
여기까지는 한 대에서 실행한 학습 환경에서 코드와 테스트로 확인한 것이다.
“확인 범위” 자체는 반드시 필요한 정보다.
문제는 여기까지라는 문서 진행 안내 표현이다.
하네스 checklist가 직접 금지하는 패턴이다.
수정 방향
현재 확인 범위는 단일 인스턴스 학습 환경이다.
처럼 사실을 바로 쓴다.
판정
S5 수정 필요.
F-S5-05 — MEDIUM — question-multi-instance-session의 선택지 리듬이 너무 균일하다
style profile:
- 독자 안내 표현 / 100문장 = 18.5
현재 선택지 1~4가 거의 같은 형태로 반복된다.
- 방식 정의
- 장점
- “다만/대신”
- 추가 설계 항목
Question 종류 자체가 선택지를 병렬로 보여 주므로 어느 정도 대칭은 정상이다.
하지만 현재는 문장 길이와 전환어까지 고르게 반복돼 생성형 문서의 템플릿 리듬이 남는다.
수정 방향
모든 선택지를 같은 길이로 맞추지 않는다.
각 선택지에서 실제로 다른 판단 재료만 남긴다.
예:
- shared store → consistency / availability
- sticky session → node loss
- browser token → policy conflict
- client-side cookie → trust boundary
로 중심이 다르므로 같은 문단 구조를 강제하지 않는다.
판정
S5 수동 재검토 필요.
9. S5 참고 검토 대상
다음은 style_profile이 벗어났지만 수치만으로 수정하면 안 되는 기록이다.
- case-ap2-split-custody
- case-browser-credential-boundary
- concept-authorization-code-and-pkce
- decision-bff-owns-token
- question-edge-authorization-scope
- question-refresh-rotation-replica
- reference-authorization-code-endpoints
- reference-bff-auth-design
- reference-pattern-selection
- reference-token-vs-session
기술 식별자와 OAuth 용어가 많아서 한글 비율이 낮은 문서는 단순 번역 대상으로 보면 안 된다.
S5는 보호 구간을 유지한 상태에서 실제 반복/번역투가 있는 문장만 고친다.
10. S6 — 일한 사람의 목소리
기계 검사:
Voice 24/24 PASS
하지만 check_voice는:
지어낸 목소리를 잡지만, 목소리가 모자란지는 재지 않는다.
현재 Case 쪽은 비교적 잘 되어 있다.
예:
case-ap3-bff-session-csrf.md
이 구성을 실행했을 때 브라우저 쪽 JavaScript가 받는 응답에는 OAuth 토큰이 없었다. 처음에는 토큰을 다루는 일도 함께 사라진 것처럼 보였다. BFF 코드를 따라가 보니 ...
이 서술은 SSOT에도 같은 관찰이 남아 있고, 실제로 본 것과 코드를 따라 확인한 것이 구분돼 있다.
이런 형태는 S6 의도와 맞다.
반대로 Reference와 Question은 사람 목소리를 억지로 넣지 않은 것도 맞다.
하네스가:
흔적이 없으면 멈춘다.
고 하기 때문이다.
판정
S6 전체 재작성까지는 필요 없다.
다만 S5에서 수정하는 문서들은 S5 뒤 반드시 S6을 다시 통과시킨다.
S5가 기존 사람의 선택·비교 문장을 깎아 버리지 않았는지 확인해야 한다.
11. 명령어 / Command Pedagogy
이번 프로젝트에는:
- Setup record = 0
- shell/CLI block = 0
- command-pedagogy finding = 0
따라서 사용자 기준:
이해하기 쉬운 명령어를 사용하고 있는가
는 이번 keycloak 프로젝트에서는 적용 대상 없음(N/A) 이다.
이는 문제를 놓친 것이 아니다.
하네스 계약도:
shell/CLI block이 없으면 command planner/editor/reviewer를 모두 SKIPPED
하도록 한다.
현재 기록에는 HTTP 요청, JSON, text flow, JavaScript 예시는 있지만 운영자가 직접 따라 치는 shell command는 없다.
중요한 점
명령어 리뷰 기준을 만족시키려고 이 프로젝트에 shell 명령을 억지로 추가하면 안 된다.
Setup이 생기는 시점에:
writing-practitioner-guides
를 적용한다.
판정
Command pedagogy = N/A / 정상 skip
12. S7 — Studio 저장
24개 기록 모두 studio: URL이 존재한다.
현재:
- 일부는
게시 중 - 일부는
게시 전
기존 7단계 재검토 run에서는 S7을:
사용자가 Studio 반입을 요청하지 않았다
는 이유로 SKIPPED했다.
이는 하네스 계약상 허용된다.
판정
현재 리뷰 작업에서 S7 자체는 결함으로 보지 않는다.
다만 이번 리뷰를 반영해 파일을 다시 수정한다면, 사용자가 Studio 반입을 요청하지 않은 한 저장소 파일까지만 고치고 임의로 Studio version을 올리지 않는다.
13. 기존 SVG가 실제로 적절한가
현재 10개 spec을 다시 확인했다.
profile 분포:
- component-flow
- sequence
중심이다.
이는 현재 문서의 주제와 맞다.
AP1~AP4의 핵심은:
- credential owner
- token custody
- API caller
- trust boundary
- request sequence
이므로 generic card나 comparison 그림보다 component-flow / sequence가 맞다.
현재:
- Figure Text PASS
- Figure Provenance PASS
- Figure Overlap PASS
이며, comparison profile을 억지로 쓴 그림도 없다.
판정
기존 10개 SVG 선택은 적절하다.
문제는 S4 누락 2건이다.
14. 현재 자동 검증 결과
| 검사 | 결과 |
|---|---|
| Tech Log Tree | PASS — 24/24 |
| Project Layout | PASS — error 0 |
| Record Audit | PASS |
| Required Content | PASS |
| Figure Text | PASS |
| Figure Provenance | PASS |
| Figure Overlap | PASS |
| Natural Prose hard gate | PASS — 24/24 |
| Voice hard gate | PASS — 24/24 |
| Command Pedagogy | PASS — shell blocks 0, findings 0 |
| Existing keycloak run ledgers | 13/13 verify exit 0 |
| Run coverage | 24 records 중 12 unique records만 ledger 있음 |
| Source reconciliation | UNVERIFIABLE |
15. 이번 리뷰의 실제 수정 대상
반드시 수정
A. S4
-
concept-bearer-jwt-validation-chain.md- validation chain SVG 추가
-
concept-idp-brokering.md- upstream / broker / application boundary SVG 추가
B. S5
-
reference-pattern-selection.md- “봐야 한다 / 함께 적는다” 등 작성 지시문 제거
-
reference-public-confidential-client.md- 반복 정의 축소
- 영문 용어 밀도 완화
- 기술 정의는 한 번 정확하게
-
reference-idp-federation-boundary.md- 장문 분리
-
question-bff-state-store.md- “여기까지” 같은 문서 진행 안내 제거
-
question-multi-instance-session.md- 선택지의 기계적인 동일 리듬 완화
C. S3/fact review
- Public/Confidential client 정의 scope 통일
- Token Endpoint client-auth 제목 scope 정리
- Referrer-Policy 조건 반영
16. 수정할 필요 없는 것
다음은 고치려고 건드리지 않는다.
command
shell/CLI가 없으므로 명령어를 새로 넣지 않는다.
browser credential storage SVG
concept-browser-credential-storage.md는 비교표가 핵심이라 SVG를 추가하지 않는다.
기존 10개 SVG
현재 그림을 “새 하네스를 적용한다”는 이유로 전부 다시 만들지 않는다.
의미와 profile이 맞고 provenance도 정상이므로 재사용한다.
과거 run ledger
원장이 없는 12개 기록에 과거 원장을 소급 생성하지 않는다.
17. 리뷰 반영 작업을 할 때의 올바른 절차
이번 리뷰를 실제로 반영할 때는 과거 원장을 수정하지 않고 현재 수정용 새 run을 연다.
수정 대상 기록마다:
- 새 run.json 생성
- S1 — 기존 SSOT면 SKIPPED 사유
- S2 — 기존 PROMOTE/CONFIRMED면 SKIPPED 사유
- S3 — 기록 수정
- command initial analysis
- S4 — 필요한 두 Concept은 SVG 생성, 나머지는 적절한 SKIP
- S5 — prose rewrite
- S6 — voice pass
- final command analysis
- fact review
- S7 — 사용자 요청이 없으면 SKIPPED
- verify-pipeline-run
- project gates
- standalone pipeline
- full unittest
특히 S4 → S5 → S6 순서를 바꾸지 않는다.
그림을 붙인 뒤 생기는 설명 문단도 S5/S6을 거쳐야 하기 때문이다.
18. 완료 조건
다음이 모두 충족돼야 keycloak = 완료로 판정한다.
- Bearer JWT validation chain SVG 존재
- IdP brokering boundary/flow SVG 존재
- 새 SVG가 techviz spec/context/provenance를 갖춤
- 새 SVG가 Figure Text/Overlap/Provenance PASS
- reference-pattern-selection 작성 지시문 제거
- public/confidential reference 반복 문형 정리
- idp federation 장문 정리
- bff-state-store 메타 안내 표현 제거
- multi-instance 선택지 기계적 리듬 수동 재검토
- S5 후 S6 재실행
- 기술 사실 3건 정리
- command lane은 shell/CLI 없음으로 정상 SKIP
- 수정한 기록마다 현재 시점의 새 run ledger 생성
- historical missing ledger는 소급 생성하지 않음
- 모든 새 run verify exit 0
- Tree/Layout/Required Content/Figure gates PASS
- standalone pipeline PASS
- unittest regression PASS
- source repo 부재 시 reconciliation은 UNVERIFIABLE로 그대로 표기
최종 결론
이번 프로젝트는 문서 구조 자체가 잘못된 상태는 아니다.
현재 판단은 다음과 같다.
- S1: 구조 정상 / live source 대조는 UNVERIFIABLE
- S2: 정상
- S3: 구조 정상 / fact-review 잔여 3건
- S4: 기존 SVG 10개 적절 / 필요한 SVG 2개 누락
- S5: hard gate 통과 / 사람이 읽으면 재작업 필요한 문서 5개
- S6: 전반적으로 정상 / S5 수정 뒤 다시 통과 필요
- S7: 현재 범위에서 정상 skip 가능
- Command pedagogy: 적용 대상 없음
따라서:
keycloak = 아직 더 봐야댐
이다.
이번 판정의 핵심 이유는 기술 오류 자체보다 7단계 하네스의 S4와 S5가 현재 결과물에 완전히 반영되지 않았기 때문이다.