종류마다 무엇을 어떤 순서로 쓰나

칸 목록과 상한은 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건이 그렇게 돼 있다는 뜻이다.

파일 뼈대 — 다섯 종류가 같다

---
id · kind · slug · title · topic · project · status · studio
(종류별) basisVersion · decisionStatus · questionStatus · lastVerifiedOn
(있으면) assets · evidence
---

# 제목

리드 문단. 이것이 Studio 의 `요약` 칸이다.        ← 47건 모두 있다

## 관계          ← Decision 만 「근거」다
## <칸 이름>     ← 종류마다 다르다
## 본문          ← Case · Concept 만
<!-- body:start -->
...
<!-- body:end -->

frontmatter 는 메타데이터, ## 는 Studio 의 칸, 제목 아래 첫 문단은 요약이다. 47건 모두 이 모양이다.

관계 항목은 굵은 제목 한 줄 + 이유 한 줄이다.

- **Keyset Pagination 설계 기준**
  이 결정을 규칙으로 편 기준이다.

Case — 9건

칸은 관계 · 문제 · 결론 · 검증 환경 · 재현 조건 · 본문. 9건 모두 여섯 칸을 채웠다.

칸	무엇을
문제	무엇이 어떠해야 했는데 어떻게 됐나. 요구를 먼저, 실제를 다음에
결론	재현해서 확정한 것. 수치를 그대로. 「~일 것이다」가 아니라 「~였다」
검증 환경	런타임·버전·DB·측정 도구. `이름 : 값`으로 줄을 나눈다
재현 조건	다른 사람이 같은 값을 얻는 순서. 번호를 매긴다

본문은 5~12절, 대개 6절이다.

첫 절은 무대를 세운다. 잰 코드나 구조를 먼저 보여 준다 — 「측정한 loadFeed 구현」, 「무대 — 페이징 한 줄만 추가」, 「가시성을 얹기 전 — 인덱스로 커서 이후만」, 「Mediator에서 Access Token과 Refresh Token을 관리하는 위치」
가운데는 측정값(표) → 그 값을 어떻게 읽나 → 실행계획이나 로그 순서다
마지막 절은 범위나 다음이다. 9건 중 4건이 확인 범위(「증명하지 않는 것」, 「현재 자동 테스트로 확인한 범위」, 「Redirect URI와 CORS에서 아직 확인하지 않은 부분」), 2건이 「다음 선택」, 나머지가 지표 읽는 법이나 남긴 이유다. 재지 않은 것을 적지 않고 닫는 Case 는 없다

코드블록에는 무엇을 보라는 한 줄을 붙인다. 표 앞이나 뒤에 그 표를 어떻게 읽는지 적는다. 예시는 한 규모로 고정한다 — 표가 전체 계열을 이미 보여 준다.

Concept — 6건

칸은 관계 · 본문 둘뿐이다. 문제도 결론도 재현 조건도 없다. 내가 잰 결과가 아니라 이미 그렇게 동작하는 것을 적기 때문이다.

basisVersion 은 frontmatter 에 있고 본 것을 · 로 잇는다.

basisVersion: Keycloak 26.7.0 · oidc-client-ts 3.3.0
basisVersion: oauth2-proxy 7.15.2 · Nginx auth_request

본문은 5~8절, 대개 6절이다.

첫 절은 무엇이 무엇을 주고받는지다 — 「두 개의 OAuth 왕복이 이어진다」, 「Resource Server가 받는 입력」, 「요청 하나가 두 번 평가된다」
가운데는 단계마다 실제로 일어나는 일이다
마지막 절은 막지 않는 것이나 확인한 범위다 — 「PKCE가 막지 않는 것」, 「CSRF가 XSS를 대신하지 않는다」, 「현재 검증한 범위」, 「지금 구성이 보여 주지 않는 것」

「확인했다」는 Case 의 말이다. Concept 은 「~한다」로 적는다. 규격이 정한 것과 그 구현이 그렇게 한 것을 구분한다.

Reference — 14건

칸은 관계 · 목적 · 규칙 · 적용 조건 · 예외 · 예시. 14건 모두 여섯 칸을 채웠다. 본문이 없다.

칸	무엇을
목적	이 기준이 무엇을 막는가. 막으려는 실패를 먼저
규칙	제목은 무엇을 하는지/하지 않는지로. 본문에 왜인지
적용 조건	언제 이 기준이 걸리는가
예외	걸리지 않는 경우. 이 칸이 비면 규칙이 과잉 적용된다
예시	짧은 문장. 코드가 아니다

규칙 제목만 읽어도 무엇을 금지하는지 알아야 한다. 「지표를 정확히 읽는다」보다 「지표 이름이 뜻하는 것을 그대로 읽는다」가 낫다. 코드가 필요하면 그 코드가 있는 Case 를 만들고 관계로 가리킨다 — Reference 칸은 평문이라 백틱이 글자로 보인다.

Question — 9건

칸은 관계 · 사실 · 가정 · 미지수 · 제약 · 선택지 · 다음 검증. 9건 모두 일곱 칸을 채웠다. questionStatus 는 frontmatter 에 있다.

가정을 사실 칸에 넣지 않는 것이 이 종류의 전부다. 사실은 확인한 것, 가정은 확인하지 않고 전제한 것이다.

다음 검증은 실행할 수 있는 문장으로 적는다. 「더 알아본다」로는 닫히지 않는다 — 「seed(1000) 뒤 ANALYZE highlights 를 돌리고 Plan B 를 다시 잰다」처럼 적는다.

Decision — 9건

칸은 근거 · 결정문 · 판단 이유 · 영향. 다른 넷과 달리 관계 절 이름이 「근거」다. decisionStatus 는 frontmatter 에 있다. 근거가 1개 이상 없으면 게시가 거절된다.

칸	무엇을
결정문	「~한다」로 끝나는 문장. 조건이 있으면 한 문단 더
판단 이유	무엇을 보고 그렇게 정했나. 근거로 건 기록을 가리킨다
영향	감수한 비용을 포함한다. 좋아진 것만 적지 않는다

대안을 적고 왜 고르지 않았는지 적는다. 대안이 없으면 결정이 아니라 사실이다. 자료가 뒷받침하지 않는 이유를 만들지 않는다.

본문이 있는 두 종류의 공통 규칙

그림은 technical-visualizer 로 만든다. 손으로 SVG 를 그리지 않는다
그림 안에는 이름만 넣는다. 문장은 <desc> 와 옆 문단에 둔다
그림과 증거는 frontmatter 의 assets · evidence 로 잇는다. 같은 파일을 기록 옆에 복사하지 않는다
본문은  와  사이다. 그 밖은 Studio 로 가지 않는다

6.5 KiB Raw Blame History