DongHyeonkaandClaude Opus 5
024362d096
기반 가이드 7단계로 실험대를 철거하고 다시 세운 뒤 virtualization setup 9편과 keycloak-session-store 26편을 순서대로 밟았다. 24편은 끝까지, 11편은 되는 데까지 밟았고 밟은 범위를 편마다 적었다. 명령이 못 도는 것을 고쳤다. - kubectl 을 `kc-lab-1` 에서 치라고 적었는데 그 기계에 kubeconfig 가 없다. 라벨 639개와 각 편의 「어디서 치는가」를 `[lab host]` 로 옮겼다 - `-o custom-columns=…[0]…` 이 zsh 에서 글로브로 읽혀 안 돈다. 28곳에 따옴표 - busybox `sed` 가 끝 개행을 안 붙여 A-3 의 측정이 언제나 0 이었다 - `--token-file ~/node-token` 뒤에 그 파일을 지우면 k3s agent 가 재부팅을 못 견딘다. `/etc/rancher/node-token` 으로 옮기는 처방을 재서 넣었다 - 게스트에 없는 도구를 전제로 한 명령 넷 — `conntrack`·`dig`·`strings`·`nginx -v` - `echo` 와 JWT 헤더가 `"이름" : [ 값 ]` 으로 찍는데 문서는 공백 없이 옮겨 적어 그 실측으로 만든 grep·sed 가 한 줄도 못 잡는다 - B-0 이 `directAccessGrantsEnabled` 와 계정 완성을 빠뜨려 B-3 이 못 돈다 - D-4·D-4a 가 `test-server` 와 `certbot-renew.*` 를 가리키는데 실제로는 `kc-lab-edge` 의 `certbot.service` 다 - `virsh setmaxmem --config` 를 `dominfo` 로 판정하면 틀린다. `--inactive` 로 - `LIBVIRT_DEFAULT_URI` 를 rc 에만 넣으면 `ssh host '명령'` 에서 안 먹는다 결과가 조건부인 것을 갈랐다. - readiness 는 즉시 안 뒤집힌다. A-1·A-2 의 60초 창을 적었다 - 03 의 층 ②③ `301` 은 04 이후의 값이고 그 단계에서는 `404` 다 - A-0 의 로그 필터를 요청 직후에 치면 정반대 결론이 나온다 - A-5 의 한 방향 차단은 잠깐 `1` 이었다 `2` 로 돌아온다 증거는 두 프로젝트의 `evidence/raw/` 에 99벌을 README 와 함께 남겼다. 비밀은 길이만 적었고 화면에 찍힌 토큰은 가렸다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
7.0 KiB
기록 .md 의 어디가 Studio 의 어느 칸인가
세 자리
기록 .md |
Studio |
|---|---|
| frontmatter | 메타데이터. 화면 칸이 아니다 |
| 제목 바로 아래 첫 문단 | 요약 칸 |
## <이름> |
같은 이름의 칸 |
## 요약 이라는 절을 만들지 않는다 — Studio 에 그런 칸이 없어 통째로 사라진다. ## 출처 도
칸이 아니다. 원본 경로는 frontmatter 의 source 에 있다.
종류마다의 칸
| 종류 | 기록 .md 의 ## 이름 |
본문 |
|---|---|---|
| Case | 관계 · 문제 · 결론 · 검증 환경 · 재현 조건 · 본문 |
있음 |
| Concept | 관계 · 본문 |
있음 |
| Setup | 관계 · 본문 — 본문 안의 ## 는 칸이 아니다 |
있음 |
| Reference | 관계 · 목적 · 규칙 · 적용 조건 · 예외 · 예시 |
없음 |
| Question | 관계 · 사실 · 가정 · 미지수 · 제약 · 선택지 · 다음 검증 |
없음 |
| Decision | 근거 · 결정문 · 판단 이유 · 영향 |
없음 |
Decision 만 관계 절 이름이 근거 다. 그리고 근거가 1개 이상 없으면 게시가 거절된다.
환경 구성은 ## 를 칸으로 세지 않는다
다른 다섯은 ## <이름> 하나가 칸 하나다. 환경 구성은 화면 칸이 고정한 버전 과
절차 Markdown 둘뿐이고, ## 실행 절차 · ## 구성 값 · ## 확인 방법 은 그 절차 Markdown
안의 소제목이다. 계약이 bodyMarkdown 설명에 「절 이름을 강제하지 않는다 — 프로젝트마다
셋업의 모양이 다르다」고 적는다.
그래서 넣는 법이 다르다. 기록의 ## 본문 아래 전체가 bodyMarkdown 한 칸으로 들어가고, 화면
칸에 따로 옮길 값은 고정한 버전 하나뿐이다.
기록 .md |
어디로 |
|---|---|
frontmatter pinnedVersions[] |
고정한 버전 — 줄마다 이름·버전 입력 둘 |
## 본문 의 <!-- body:start -->~<!-- body:end --> |
절차 Markdown 통째로 |
## 관계 |
관계 |
작업본을 만들면 절차 Markdown 이 비어 있지 않다. Studio 가 위의 절 셋을 미리 넣어 두므로,
본문을 넣기 전에 그 내용을 지운다.
화면의 라벨은 기록의 절 이름과 다르다
이것이 이 문서에서 가장 자주 틀리는 자리다. 위 표는 기록 .md 가 쓰는 이름이고,
편집 화면의 라벨은 다른 말을 쓴다. 그리고 /studio/documents/new 의 종류 카드에 적힌 요약
(목적 · 규칙 · 적용 조건 · 예외 · 예시)은 카드 문구이지 편집 화면의 라벨이 아니다.
Reference 에서 실제로 확인한 대응이다.
기록의 ## |
편집 화면의 라벨 |
|---|---|
목적 |
이 기준을 쓰는 이유 |
규칙 |
판단 기준 — 제목과 본문 두 칸이 한 줄이다 |
적용 조건 |
적용할 때 |
예외 |
예외와 주의 |
예시 |
예시 |
관계 |
관계 |
종류 이름도 화면마다 달랐다. 상태 레일이 Reference 를 적용 기준 이라고 부르는 동안
새 문서 화면의 라디오는 Reference 였다. 2026-09-12 에는 새 문서 쪽도 여섯 다 한글이다 —
검증 기록 · 적용 기준 · 동작 원리 · 환경 구성 · 열린 질문 · 설계 결정.
화면을 먼저 스냅샷으로 읽고 그 라벨을 쓴다. 이 표를 외워서 넣지 않는다 — 화면이 바뀌면 표가 먼저 낡는다.
기록에 없는데 화면에 있는 칸
| 칸 | 무엇 |
|---|---|
축 |
주제 안의 변이(SPA · Mediator · BFF · Forward-Auth). 주제를 고른 뒤에 나타난다. 안 고르면 주제 공통 기록이 된다 |
마지막 검증일 |
기록의 verifiedOn 이다. 없으면 비워 둔다 |
근거가 없으면 비워 둔다. verifiedOn 이 없는 채로 저장하면 미리보기에 「마지막 검증」 절이
값 없이 뜬다. 그것은 날짜를 지어내는 것보다 낫다 — 게시 전에 사람이 채울지 정한다.
frontmatter 에서 화면으로 가는 값
| frontmatter | 어디로 |
|---|---|
id |
편집 주소 /studio/documents/<id>/edit |
kind |
새 문서를 만들 때 고르는 종류 |
slug · title |
화면 위쪽의 슬러그·제목 칸 |
topic · topicName · project |
주제·프로젝트 선택 |
basisVersion (Concept) |
기준 버전 칸 |
pinnedVersions (Setup) |
고정한 버전 칸. name · version 이 한 줄 |
questionStatus (Question) · decisionStatus (Decision) |
상태 선택 |
assets[].file |
올릴 Asset 파일 |
assets[].key |
본문 :::evidence key 의 저장소 쪽 이름. 올리면 서버 키로 바뀐다 |
계약이 화면에 주는 상태와 도메인이 들고 있는 상태가 다르다. QuestionStatus 는 화면에서
OPEN·RESOLVED 둘인데 도메인은 OPEN·INVESTIGATING·PAUSED·RESOLVED 넷이고,
Decision 의 도메인 ACCEPTED 가 화면에서는 ADOPTED 로 보인다. 화면에서 고른 값이 도메인
상태를 덮어쓰지는 않는다.
본문이 없는 세 종류
Reference·Question·Decision 의 칸은 평문으로 렌더링된다.
「평문」이 「전부 글자 그대로」라는 뜻은 아니다. 렌더러
(tech-log-frontend 의 presentation/shared/public-render/prose-text.tsx)가 셋을 해석한다.
| 무엇 | 평문 칸에서 |
|---|---|
| 백틱 쌍 | 인라인 <code> 로 산다. 빼지 않는다 — 빼면 식별자가 민무늬로 나온다 |
| 빈 줄 | 문단이 갈린다 |
| 한 줄 바꿈 | <br> |
별표 · 파이프 · # · 코드펜스 · 인용 표지 > |
글자 그대로 나온다. 넣지 않는다 |
전에 이 자리에 「백틱과 파이프가 글자 그대로 보인다」고 적혀 있었고 백틱 쪽은 틀렸다. 백틱이 글자로 나오던 것은 고쳐진 옛 버그이고 그 파일 주석에 그렇게 적혀 있다. 칸이 어떻게 보이는지는 렌더러가 정본이다 — 이 문서가 아니다.
- 나열은 쉼표로 잇지 말고
이름 : 값으로 줄을 나눈다
코드·표·그림이 필요하면 짝이 되는 Case·Concept·Setup 에 담고 관계 로 가리킨다.
본문을 넣기 전에
저장소의 .md 는 그림을 마크다운 이미지로 싣는다. Studio 는 :::evidence 를 쓴다. 바꾸는 것은
스크립트가 한다.
python3 scripts/studio-body.py <기록.md> --body-only # 저장소 key 그대로
python3 scripts/studio-body.py <기록.md> --key a=a-1a2b3c4d --body-only # 서버가 준 key 로
저장소 파일 자체는 고치지 않는다.
되돌아오는 값
저장이 끝나면 Studio 가 id 를 준다. 새로 만든 기록이면 frontmatter 의 id 와 studio: 를
채운다. 그 두 칸이 차면 색인이 publication 을 게시됨 으로 적는데, 그것은 「Studio 에
있다」는 뜻이고 공개됐다는 뜻이 아니다. 공개 여부는 status 와 public: 이 말한다.