# SSOT에서 글감을 뽑는 기준

`final/`의 긴 글 하나가 정본(SSOT)이다. 거기서 Studio에 올릴 기록을 뽑아낸다. 이 문서는 **무엇을
몇 건으로 나눌지**를 정하는 기준이다. 나눈 결과는 `tech-log-tree.json`에 제목만 먼저 적고, 글은
그다음에 쓴다.

## 왜 먼저 나누는가

긴 글을 앞에서부터 잘라 기록으로 만들면 절 하나가 기록 하나가 된다. 그러면 Case의 칸도
Reference의 칸도 반쯤만 맞는 기록이 나온다. 종류를 먼저 정하고 그 종류가 요구하는 것이 SSOT에
있는지 확인해야 한다.

## 한 건으로 자르는 단위

**절이 아니라 주장이다.** SSOT의 `##` 하나가 기록 하나가 아니다. 다음 넷 중 하나가 한 건이다.

| 단위 | 무엇 | 종류 |
|---|---|---|
| 재현한 관측 하나 | 조건을 갖추고 돌려서 얻은 수치·실행계획·로그 | Case |
| 남의 것의 동작 하나 | 문서와 코드를 읽어 정리한 규칙·흐름 | Concept |
| 반복 적용할 기준 하나 | 다음에도 같게 하기로 한 규칙 | Reference |
| 프로젝트가 고른 방향 하나 | 대안을 두고 정한 것 | Decision |
| 닫히지 않은 판단 하나 | 아직 모르는 것과 무엇을 하면 닫히는지 | Question |

## 종류를 정하는 물음

순서대로 묻는다. 먼저 걸리는 것이 그 글감의 종류다.

1. **내가 돌려서 얻은 결과인가** → Case. 수치·실행계획·로그가 SSOT에 있어야 한다. 없으면 Case가 아니다
2. **남의 것이 어떻게 동작하는지인가** → Concept. 무엇을 보고 썼는지(버전)가 있어야 한다
3. **다음에도 같게 하기로 한 규칙인가** → Reference
4. **대안을 두고 고른 것인가** → Decision. 근거로 걸 기록이 최소 하나 필요하다
5. **아직 모르는 것인가** → Question. 미지수가 최소 하나 필요하다

## 나눌 때 지키는 것

**한 건에 종류를 섞지 않는다.** N+1을 재현해 고쳤고 그 과정에서 조회 기준을 굳혔다면 Case 하나와
Reference 하나로 나누고 `관계`로 잇는다.

**증거가 없는 Case는 만들지 않는다.** SSOT에 그 수치가 없으면 글감 목록에는 남기되 `file` 없이
두고, 측정을 먼저 한다. 없는 수치를 쓰지 않는다.

**Decision은 근거 없이 만들지 않는다.** 게시가 거절된다. 근거로 걸 Case나 Concept이 먼저 있어야
한다. 그래서 Decision은 대개 마지막에 뽑는다.

**같은 관측을 두 건으로 쪼개지 않는다.** 「N+1이 났다」와 「그래서 몇 개가 나갔다」는 한 건이다.
쪼개면 둘 다 반쪽이 된다.

**주제를 먼저 정한다.** Studio는 주제 아래에 다섯 종류를 나눠 보여 준다. 주제가 다르면 같은
프로젝트여도 폴더가 갈린다. 주제 slug는 Studio의 것을 그대로 쓴다.

## `tech-log-tree.json`

주제 → 종류 → 글감 순서로 담는다. 아직 쓰지 않은 글감은 `file` 없이 제목만 둔다.

```json
{
  "project": "n+1liner",
  "ssot": "final/document.md",
  "topics": {
    "jpa-feed-query-performance": {
      "topic": "jpa-feed-query-performance",
      "kinds": {
        "case": [
          { "title": "Fetch 타입이 아니라 조회 방식이 만든 ToOne N+1",
            "slug": "eager-toone-nplus1-without-access",
            "file": "jpa-feed-query-performance/case/case-eager-toone-nplus1-without-access.md",
            "status": "게시 전", "studioId": "32d0be7d-…", "assets": 1, "evidence": 3 },
          { "title": "아직 쓰지 않은 글감" }
        ],
        "concept": [], "reference": [], "question": [], "decision": []
      }
    }
  }
}
```

기록을 쓰거나 지운 뒤에는 다시 만든다. 스크립트는 기록 파일에서 값을 읽어 채우고, `file`이 없는
글감은 지우지 않는다.

```bash
python3 scripts/build-tech-log-tree.py [프로젝트]
```

## 순서

1. SSOT를 끝까지 읽는다. 절 제목만 훑지 않는다 — 수치와 근거가 어디 있는지 알아야 종류를 정한다
2. 위 물음으로 글감을 나누고 주제를 정한다
3. `tech-log-tree.json`에 제목만 적는다. 이때 글은 쓰지 않는다
4. 글감 하나를 골라 `<주제>/<종류>/`에 기록을 쓴다. 형식은 `writing-each-kind.md`
5. 트리를 다시 만든다
6. Studio에 넣고 저장한다