# 기록 `.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:` 이 말한다.