SSOT에서 글감을 뽑는 기준

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

왜 먼저 나누는가

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

한 건으로 자르는 단위

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

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

종류를 정하는 물음

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

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

나눌 때 지키는 것

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

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

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

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

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

`tech-log-tree.json`

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

{
  "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이 없는 글감은 지우지 않는다.

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

순서

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

4.3 KiB Raw Blame History