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>
138 lines
7.0 KiB
Markdown
138 lines
7.0 KiB
Markdown
# 기록 `.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` 를 쓴다. 바꾸는 것은
|
|
스크립트가 한다.
|
|
|
|
```bash
|
|
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:` 이 말한다.
|