feat(studio): 반입에서 빠졌던 setup 두 편을 Studio 에 만든다 — 35편 전부 자리를 갖는다

virtualization 의 setup 9편은 같은 커밋(2109f72)에서 한꺼번에 생겼는데 그때 Studio 반입이 7편만 덮고 둘을 빠뜨렸다. 둘 다 readiness 가 READY 이고 관문도 통과하는데 frontmatter 에 id 도 studio 도 없었다 — Studio 문서가 아예 없었다는 뜻이다. 빼놓을 이유가 없어서 만들었다. - setup-tear-down-the-lab-and-know-what-survives -> 87e0138d-… - setup-power-cycle-the-lab-and-reallocate-guest-memory -> 8a9ca3d4-… 주제는 새로 만들지 않고 같은 폴더의 기존 편에서 topicId·projectId 를 읽어 같은 값을 썼다. 둘 다 저장까지만 하고 게시하지 않았다(currentPublication: null). pinnedVersions 의 40자 상한 - power-cycle 의 「기준 배치」 값이 51자여서 서버가 422 로 거절했다 (size must be between 1 and 40) - 그 칸에 문장이 들어가 있었다. CLAUDE.md 는 Setup 에 대해 「명령이 본문에 들어가고 버전만 pinnedVersions 에 남는다」고 적는다 - 잘라내기 전에 그 설명이 본문에 있는지 먼저 봤다. 셋 다 있었다 — 63행이 호스트 RAM 증설, 176행이 2026-09-03, 215행이 2026-09-10 과의 날짜 엇갈림. 그래서 날짜만 남겼고 잃은 내용이 없다 - 저장소 전체를 훑어 40자를 넘는 값은 이것 하나뿐이었다 기록 두 편의 diff 는 frontmatter 뿐이고, tech-log-tree.json 은 파생 칸 (publication · studioId) 넷만 바뀌었다. 「게시됨」은 Studio 에 있다는 뜻이지 공개됐다는 뜻이 아니다. 관문: check_body PASS · check_prose error 0 · check_evidence 문제 없음 · verify-tech-log-tree error 0 · verify-project-layout error 0 · check-studio-whitespace PASS Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs(skill): GET 을 그대로 되보내면 400 이라는 것을 PUT 설명 옆에 적는다
2026-09-17 20:58:10 +09:00 · 2026-09-17 20:34:56 +09:00 · 2026-09-17 20:29:27 +09:00 · 2026-09-17 20:16:45 +09:00 · 2026-09-17 20:03:53 +09:00 · 2026-09-17 20:00:13 +09:00
6907 changed files with 3875740 additions and 24767 deletions
@@ -0,0 +1,74 @@
 ---
 name: analyzing-codebase-for-tech-log
 description: Use when a project under <분석 대상 저장소> must be deeply analyzed and documented under docs, especially when the repository is too large for one pass and analysis must proceed by bounded module or subsystem.
 metadata:
  version: "1.0.0"
  language: "ko-KR"
 ---
 # Analyzing Codebase For Tech Log
 ## Goal
 Produce a highly detailed, source-traceable engineering analysis. This stage discovers facts and evidence; it does **not** write Tech Log records yet.
 ## Required sequence
 0. **Fix the two roots before anything else.** `<분석 대상 저장소>` is the repository being analyzed — an absolute path outside this repository, given by the caller. `docs/<프로젝트>/` is inside *this* repository. Never write into the analyzed repository, and never read analysis state from it.
 1. **Read `<분석 대상 저장소>/analysis-queue.yaml` if it exists.** It exists only when several repositories are queued. Apply `references/queue-contract.md`: reconcile newly discovered project directories, preserve queue order, and determine the single active project. **If there is no queue, analyze the one repository the caller named and skip to step 3.** A missing queue is not a blocker — it means nothing is queued.
 2. If an `IN_PROGRESS` project exists, analyze only that project. If none exists, activate the first `PENDING` project in queue order. Never preempt an active project because a new project appeared.
 3. For the selected `<분석 대상 저장소>`, check the nearest `AGENTS.md` or equivalent repository instructions.
 4. Record Git revision and `git status` when Git is available. Never modify or reset user source as part of analysis.
 5. Read `docs/<프로젝트>/state.json` if it exists; otherwise initialize the working material from `templates/` in this skill. The project folder template (`docs/_templates/`) holds only the finished shape and does not carry it.
 6. Map repository/build/module boundaries before choosing a scope.
 7. If the repository is large, select one bounded unanalysed module/subsystem and analyze it completely. Do not skim the whole repository and call that detailed analysis.
 8. Update `source-index.md`, the bounded analysis file, coverage ledger, evidence, and `state.json`.
 9. Capture runtime evidence only where it resolves a material uncertainty or verifies a significant claim.
 10. Continue the same project across runs until all intended scopes are complete.
 11. **Fold the analysis into `final/document.md`.** Not a summary of it — the material
    itself, with provenance and limitations intact. The test is that every claim a Tech Log
    record will cite can be anchored in `final/document.md` alone. Anything that survives
    only in `analysis/**` has not been folded in.
 12. **Remove the working material.** `analysis/`, `notes/`, `checkpoints/`, `state.json`,
    and `source-index.md` exist only while the analysis runs. A finished project folder
    holds `final/` and `tech-log-studio/` (and `source/` when the material came from
    outside). Then mark the queue entry `COMPLETE` and clear `activeProject`. Do not start
    the next project before this completion transition.
 `python3 scripts/fold-analysis-into-final.py <project>` performs steps 11 and 12: it moves
 the module analyses into part 2 of `final/document.md`, the source index, scope coverage and
 process notes into part 3, rewrites every `analysis/NN` anchor to `final/document.md#aNN`,
 and removes the working material.
 `analysisStatus: COMPLETE` while the working material is still on disk means step 11 was
 skipped — the analysis was summarized rather than folded in, and downstream records will
 anchor on `analysis/**` instead of the SSOT. `scripts/verify-project-layout.py` and
 `scripts/verify-tech-log-tree.py` count that state.
 Read `references/queue-contract.md`, `references/analysis-contract.md`, `references/deep-analysis-standard.md`, and `references/evidence-contract.md` before analysis.
 ## Evidence vocabulary
 Label statements internally as:
 - **observed:** directly seen in code/config/test/runtime/git evidence;
 - **inferred:** conclusion logically derived from observed sources;
 - **hypothesis:** plausible explanation not yet verified;
 - **unknown:** material information not available;
 - **external:** knowledge from outside the codebase, clearly separated from project observation.
 Do not turn inference into observation in the final document.
 ## Depth rule
 A selected bounded scope is an **exhaustive-reading unit**, not a representative-sampling unit. Build an inventory first, then account for every production source/config/build/migration/test file that materially belongs to that scope. Each item must be marked `FULL_READ`, `STRUCTURAL_ONLY`, or `EXCLUDED` with a reason. `EXCLUDED` is allowed only when dependency/import/ownership evidence shows it does not contribute to the scope being documented.
 For the selected scope, trace representative behavior end-to-end where applicable: entry point → application policy → domain/state → persistence/external adapter → observable result. Also trace failure paths, transactions, concurrency, lifecycle, configuration, tests, build-time enforcement, runtime wiring, dead/unwired paths, and historical bug/decision evidence when they materially affect the architecture.
 Do not stop at "what classes exist". Explain **why the shape exists** only when code comments, tests, design docs, Git history, runtime evidence, or a clearly labeled inference supports the explanation.
 There is no target document length. A 3,000+ line module analysis is acceptable when the source warrants it; artificial verbosity is not. Completeness is judged by the coverage ledger and source traceability, not by prose length.
 ## Stop conditions
 Do not run destructive/state-changing commands merely to create evidence. Do not expose secrets. If a runtime check would alter production or shared external state, leave it as an evidence task instead.
@@ -0,0 +1,67 @@
 # Detailed Analysis Contract
 ## First pass: project map
 Before interpreting architecture, establish:
 - repository revision/snapshot;
 - build system and top-level build graph;
 - modules and their declared dependencies;
 - runtime applications/entry points;
 - persistence/messaging/cache/object storage/external service adapters;
 - test modules and test types;
 - configuration sources and environment boundaries.
 The map is evidence, not a taxonomy exercise. Do not infer module responsibilities from names alone; inspect representative source and wiring.
 ## Bounded analysis
 A bounded scope should be small enough that one run can answer all of these:
 1. What public/consumed surface does the scope expose?
 2. What does it depend on and why?
 3. How is it wired into a running application?
 4. What state/data does it read or change?
 5. What are its main success and failure paths?
 6. What tests exercise it, and what do those tests actually prove?
 7. What behavior/configuration is declared but not actually connected?
 8. What operational or build-time constraints affect it?
 9. Which observations could become Case/Reference/Question/Decision material later?
 ## Code tracing
 Prefer symbol/path-based traces over broad summaries. Record exact source anchors in `source-index.md` and analysis prose.
 Where useful, trace:
 - inbound request/event/command;
 - DTO/contract mapping;
 - application use case/port;
 - domain invariants/state transitions;
 - transaction boundary;
 - outbound port and adapter;
 - ORM/query behavior;
 - cache/messaging semantics;
 - error translation;
 - logs/metrics/tracing;
 - response/event side effect.
 ## Tests
 Do not equate a green test suite with a verified architectural claim. For each important test, state what input is exercised, which real components are replaced, and what assertion proves. When a rule is enforced by build configuration or architecture tests, identify the failure point that would catch a violation.
 ## Git history
 Use history when current code cannot explain why a boundary/decision exists or when a Case depends on an evolution sequence. A current code shape alone proves existence, not historical motivation.
 ## Final synthesis
 `final/document.md` is not a shortened executive summary. It is the detailed project analysis assembled from bounded documents. Preserve:
 - measured/observed behavior;
 - failed approaches when evidenced;
 - alternatives actually considered;
 - unresolved questions;
 - explicit decisions;
 - limitations of the analysis;
 - evidence/source references.
@@ -0,0 +1,133 @@
 # Deep Analysis Standard
 This is the completion standard for one bounded module/subsystem. A run may stop mid-scope, but it may not mark the scope complete until every gate below is satisfied.
 ## 1. Quantified scope map
 Measure before interpreting. Record at least when applicable:
 - module/leaf path and declared dependencies;
 - production file count and approximate LOC;
 - package/directory count and top-level children;
 - public interfaces/ports;
 - entities/tables/repositories;
 - migrations and independent migration streams;
 - unit/integration/contract/performance/architecture test counts;
 - runtime memberships/entry applications;
 - major feature flags/config namespaces.
 Do not claim "fully read" without a countable denominator.
 ## 2. Coverage ledger
 Create a ledger for the selected scope. Every materially relevant file or coherent file group receives one disposition:
 - `FULL_READ` — contents read and incorporated into analysis;
 - `STRUCTURAL_ONLY` — structure/signature inspected because internals add no further information;
 - `EXCLUDED` — intentionally outside this document, with concrete dependency/ownership evidence explaining why.
 Record counts by disposition. A scope cannot be `COMPLETE` while relevant files are `UNCLASSIFIED`.
 ## 3. Architecture reconstruction
 Reconstruct from code rather than names:
 - why the module exists and what it explicitly is not;
 - package/component ownership;
 - allowed and observed dependency edges;
 - source dependency versus runtime call flow;
 - composition-root wiring and conditional activation;
 - build/ArchUnit/registry gates and the exact failure point;
 - optional/experimental/stable boundaries.
 If a design document says one thing and the current code says another, record the drift; do not silently reconcile it.
 ## 4. Contract and invariant extraction
 For important types/functions/configuration, identify:
 - constructor/type invariants;
 - bounds, allowlists, fail-closed behavior;
 - state machines and legal transitions;
 - transaction/retry/idempotency semantics;
 - concurrency and lifecycle assumptions;
 - security/privacy/redaction constraints;
 - database/provider-specific behavior.
 Prefer the exact enforcing code path over a generic explanation.
 ## 5. Success and failure mechanics
 For each major capability, cover both:
 - normal execution path;
 - material failure paths and their translation/recovery behavior.
 Look for silent failure modes: configuration that looks enabled but is not wired, green tests that replace the real failing component, unused beans/classes, fallback behavior that hides typos, provider differences, partial migration states, cache coherence assumptions, or retry paths that production never calls.
 ## 6. Tests as evidence
 Inventory test lanes and explain what they prove. For important claims, identify:
 - test class/path;
 - real versus replaced components;
 - input/fixture;
 - decisive assertion;
 - what remains unproved.
 Run safe tests or focused probes when needed. Do not infer production behavior solely from test names.
 ## 7. History and rationale
 Use comments/docs/Git history when needed to distinguish:
 - current fact;
 - explicit historical rationale;
 - inferred rationale;
 - old behavior/bug;
 - fix and regression guard.
 Preserve useful failure history. A bug fix is more valuable when the document explains why the bug was possible and what now prevents recurrence.
 ## 8. Static reachability and wiring checks
 For major abstractions and registered components, check whether production code actually consumes them. Search injection sites, references, registration, conditional imports, and runtime membership. Record:
 - active path;
 - duplicate path;
 - dead/unwired path;
 - configuration mismatch;
 - declared capability with insufficient evidence.
 ## 9. Runtime / database evidence
 When safe and useful, verify claims with the real engine/runtime rather than an in-memory substitute. Preserve command/output in raw evidence and render terminal UI only from that captured output. State the environment and what the result does **not** generalize to.
 ## 10. Improvement backlog
 End each completed bounded analysis with findings discovered while reading. Prioritize `P0/P1/P2/P3` (or justify another scheme). Each item should contain:
 - fact/evidence;
 - why it matters;
 - exact verification command/test;
 - candidate options when supported;
 - whether it belongs to Case, Reference, Open Question, or Decision later.
 Do not invent a defect merely to fill this section. An empty backlog is allowed if the evidence supports it.
 ## 11. Completion gate
 A bounded scope is complete only when:
 - quantified scope denominator exists;
 - coverage ledger has no unclassified relevant items;
 - top-level package/component map is accounted for;
 - build/runtime wiring is traced;
 - important invariants and failure paths are documented;
 - tests and evidence are mapped to claims;
 - explicit rationale is separated from inference;
 - dead/unwired/duplicate paths were checked;
 - limitations and excluded areas are stated;
 - improvement backlog was considered.
 If this cannot fit reliably in one run, keep the scope `IN_PROGRESS` and continue it on the next scheduled run. Never lower the depth standard to finish on schedule.
@@ -0,0 +1,39 @@
 # Evidence Contract
 ## Primary evidence first
 Store command output, logs, generated query plans, benchmark results, browser observations, and other primary material under `docs/<프로젝트>/final/evidence/raw/` before creating presentation assets.
 ## Terminal evidence
 For a command used as evidence, retain:
 - exact command (without embedded credentials);
 - working directory;
 - executed timestamp;
 - exit code;
 - raw stdout/stderr;
 - source revision when relevant.
 Render terminal UI with `scripts/terminal-evidence/render_terminal.py`.
 The visual asset is explanatory. The raw evidence is the provenance.
 ## Browser evidence
 A screenshot record should state:
 - URL/origin;
 - code revision/environment;
 - setup state;
 - action performed;
 - what visible/network fact the screenshot demonstrates;
 - what it does not demonstrate.
 ## Diagram evidence
 Architecture/sequence/state SVGs are derived explanations. Their nodes/edges must be traceable to code/config/runtime evidence. Do not draw a desired architecture and present it as the current architecture.
 ## Measurements
 Every metric needs a context: dataset/workload, environment, relevant configuration, measurement method, and comparison condition. Preserve raw measurement results where practical.
@@ -0,0 +1,87 @@
 # Analysis Queue Contract
 `<분석 대상 저장소>/analysis-queue.yaml` is the first control file read by every detailed-analysis run. It is the SSOT for project order, active-project ownership, and explicit reanalysis requests.
 ## State model
 Allowed project states:
 - `PENDING` — queued, never started for the current analysis history;
 - `IN_PROGRESS` — the project currently owned by the 09:00 analysis run;
 - `COMPLETE` — all intended scopes and `final/document.md` are complete for the recorded source snapshot;
 - `REANALYZE` — a previously completed project explicitly queued for another analysis cycle after source changes or a requested re-review;
 - `BLOCKED` — the active project cannot continue because required source, instructions, or environment are unavailable;
 - `SKIPPED` — explicitly excluded by the user or queue owner.
 At most one project may be `IN_PROGRESS`. `activeProject` must be `null`, or name the project currently owned by the analysis worker. An owned project may be `IN_PROGRESS` or `BLOCKED`. A `REANALYZE` entry is queued, not active, until a scheduled run activates it.
 ## Mandatory run order
 1. **Read `analysis-queue.yaml` before scanning project contents.**
 2. Discover direct project directories under `<분석 대상 저장소>`. Ignore control files and hidden infrastructure directories.
 3. Append newly discovered, unlisted projects to the **end** of `projects` as `PENDING`. Never insert them ahead of existing entries automatically.
 4. If `activeProject` names an `IN_PROGRESS` project, continue only that project.
 5. If `activeProject` names a `BLOCKED` project, do not start another project. Re-check only the blocking prerequisite; resume as `IN_PROGRESS` when resolved, otherwise leave it blocked and stop.
 6. If there is no active project, scan queue entries from top to bottom and choose the first actionable entry whose state is `PENDING` or `REANALYZE`.
 7. For `PENDING`, set it to `IN_PROGRESS`, set `activeProject`, initialize/continue `docs/<프로젝트>/state.json`, and run the normal exhaustive analysis cycle.
 8. For `REANALYZE`, execute the reanalysis activation procedure below, then set it to `IN_PROGRESS` and set `activeProject`.
 9. Continue the active project across scheduled runs until its required scopes are complete and `final/document.md` is synthesized for the target source snapshot.
 10. Only then mark the entry `COMPLETE`, update the completed source revision, clear `activeProject`, and allow a later scheduled run to select the next actionable entry.
 Do not begin another project in the same run after completing one. Completion creates a clean scheduling boundary.
 ## Reanalysis activation
 `REANALYZE` is an explicit user request to analyze a project again **without deleting the previous detailed analysis**.
 Before changing `REANALYZE` to `IN_PROGRESS`:
 1. Read the existing `docs/<프로젝트>/state.json` and `final/document.md`.
 2. Resolve the previous completed source snapshot. Prefer `finalDocument.sourceRevision`; fall back only to another explicitly recorded completed revision. If no trustworthy baseline exists, mark the project `BLOCKED` with a note rather than pretending this is incremental reanalysis.
 3. Resolve the current target source revision. For Git repositories, record `git rev-parse HEAD` and working-tree status. Do not modify/reset source.
 4. Compare baseline → target before reopening scopes. Record changed paths and the evidence used to map those paths to bounded scopes.
 5. Set `reanalysis.baselineRevision`, `reanalysis.targetRevision`, `reanalysis.changedPaths`, `reanalysis.impactedScopes`, increment `analysisCycle`, and set `reanalysis.requestedAt`.
 6. Choose a reanalysis mode:
   - `IMPACTED_SCOPES` when changed paths can be mapped confidently to bounded scopes and project/module boundaries remain stable;
   - `FULL_PROJECT` when module/build boundaries, shared contracts, architecture rules, cross-cutting configuration, migration ownership, generated sources, or scope mapping itself changed, or when impact cannot be bounded confidently.
 7. Reopen only the impacted scopes for `IMPACTED_SCOPES`, but keep previous analysis as historical baseline. Rebuild the project-wide synthesis after those scopes complete.
 8. For `FULL_PROJECT`, re-establish the project inventory and coverage ledger from the target snapshot and revalidate every intended scope.
 A reanalysis cycle must never silently overwrite the fact that earlier documents described an earlier source snapshot. Preserve revision provenance in state and analysis prose where it matters.
 ## Reanalysis completion
 When reanalysis finishes:
 - update every reopened scope to complete for the target revision;
 - synthesize `final/document.md` again, including material changes from the prior snapshot when relevant;
 - set `finalDocument.sourceRevision` to the target revision;
 - set `reanalysis.completedAt`;
 - mark the queue entry `COMPLETE`;
 - clear `activeProject`.
 The 10:00 decomposition stage will see the changed final document and may then update decomposition/readiness. The 11:00 generation stage remains grounded in that updated tree.
 ## New projects and ordering
 A new directory may appear while another project is being analyzed. Append it as `PENDING`; **do not preempt the active project**. `REANALYZE` also does not preempt the active project. The user may reorder queued `PENDING` and `REANALYZE` entries manually. Automatic runs never reorder existing entries.
 ## Blocked projects
 If the active project disappears, cannot be read, lacks a trustworthy reanalysis baseline, or requires an unavailable prerequisite, mark it `BLOCKED`, retain it as `activeProject`, record the reason, and stop. Do not silently jump to the next project. Resuming means returning the same entry to `IN_PROGRESS`; skipping requires explicit `SKIPPED` and clearing `activeProject`.
 ## Example: explicit reanalysis request
 ```yaml
 version: 1
 activeProject: null
 projects:
  - name: backend-clean-architecture
    status: REANALYZE
  - name: tech-log-backend
    status: PENDING
  - name: ca-tmpl
    status: PENDING
 ```
 On the next run, if the first project has a trustworthy completed baseline, it becomes the active `IN_PROGRESS` project and begins a new analysis cycle.
@@ -0,0 +1,11 @@
 분석하는 동안에만 있는 작업 재료의 틀이다.
    docs/<프로젝트>/state.json        분석 상태 — 어디까지 봤나, 어느 리비전을 봤나
    docs/<프로젝트>/source-index.md   분석한 코드의 목록
    docs/<프로젝트>/analysis/         모듈·서브시스템 단위 분석
    docs/<프로젝트>/notes/            분석 중에 남긴 메모
    docs/<프로젝트>/checkpoints/      중간 저장
 프로젝트 폴더 틀(docs/_templates/)에는 이것들이 없다. 분석이 끝나면 내용을
 final/document.md 로 옮기고 폴더에서 지우기 때문이다. 끝난 프로젝트의 폴더는
 final/ 과 tech-log-studio/ 둘이다.
@@ -0,0 +1,25 @@
 # Project Overview
 ## 분석 기준 revision
 - repository: `<분석 대상 저장소의 절대 경로>`
 - revision: `<git revision or non-git snapshot note>`
 ## Build and module map
 ## Dependency direction
 ## Runtime entry points
 ## Persistence / messaging / external systems
 ## Test topology
 ## Configuration and operational surfaces
 ## 분석할 bounded scopes
 | scope | why separate | status | analysis file |
 |---|---|---|---|
 ## 아직 단정하지 않는 것
@@ -0,0 +1,60 @@
 # <module/subsystem> 완전 해부
 > 상태: IN_PROGRESS | COMPLETE  
 > 기준 revision: <git-sha>  
 > 분석 범위: <path/module>
 ## 0. 커버리지와 숫자 지도
 - production files:
 - production LOC:
 - packages/directories:
 - tests by lane:
 - migrations/config/build files:
 - runtime membership:
 ### Coverage ledger
 | scope/file group | count | disposition | reason |
 |---|---:|---|---|
 | | | FULL_READ / STRUCTURAL_ONLY / EXCLUDED | |
 ## 1. 모듈의 정체와 경계
 ## 2. 의존성과 런타임 배선
 ## 3. 패키지/컴포넌트 지도
 ## 4. 계약·불변식·상태 모델
 ## 5. 주요 실행 경로
 ## 6. 실패 경로와 복구/번역
 ## 7. 트랜잭션·동시성·수명주기
 ## 8. 설정·기능 플래그·환경 차이
 ## 9. 퍼시스턴스/외부 시스템 세부
 ## 10. 테스트 레인과 실제 증명 범위
 ## 11. 빌드/ArchUnit/CI 강제 지점
 ## 12. 실제 사용 여부와 dead/unwired/duplicate 경로
 ## 13. Git/설계 문서에서 확인한 변화와 실패 기록
 ## 14. 런타임·터미널·브라우저 Evidence
 ## 15. 명시적 설계 이유와 추론을 구분한 정리
 ## 16. 확인한 것 / 확인하지 못한 것
 ## 17. 손볼 것
 각 항목: 우선순위 → 사실 → 근거 → 왜 문제인가 → 확인 방법 → 후보/다음 단계.
 ## Source anchors
 모든 핵심 주장에 source-index의 파일/심볼/테스트/evidence anchor를 연결한다.
@@ -0,0 +1,7 @@
 # Source Index
 상세 문서의 주장과 근거를 다시 찾을 수 있게 code/config/test/git/runtime source를 색인한다.
 | id | kind | path / command / URL | revision or time | what it proves | limitations |
 |---|---|---|---|---|---|
 | SRC-001 | code | `<path>` | `<revision>` | `<grounded fact>` | `<limit>` |
@@ -0,0 +1,30 @@
 {
  "schemaVersion": 2,
  "project": "<project>",
  "codebasePath": "<분석 대상 저장소의 절대 경로>",
  "gitRevision": null,
  "analysisStatus": "NOT_STARTED",
  "analysisCycle": 1,
  "scopes": [],
  "reanalysis": {
    "baselineRevision": null,
    "targetRevision": null,
    "mode": null,
    "changedPaths": [],
    "impactedScopes": [],
    "requestedAt": null,
    "completedAt": null
  },
  "finalDocument": {
    "path": "final/document.md",
    "status": "NOT_STARTED",
    "sourceRevision": null
  },
  "evidenceTasks": [],
  "lastRunAt": null,
  "techLogTree": {
    "path": "tech-log-studio/tech-log-tree.json",
    "status": "NOT_STARTED",
    "sourceDocumentHash": null
  }
 }
@@ -0,0 +1,189 @@
 ---
 name: deriving-tech-log-root-tree
 description: Use when a completed or substantially completed docs project analysis must be decomposed into grounded Tech Log Topics and candidate Case, Concept, Setup, Reference, Open Question, and Decision records.
 metadata:
  version: "1.0.0"
  language: "ko-KR"
 ---
 # Deriving Tech Log Root Tree
 ## Core rule
 **Select what is worth publishing. Do not emit everything the analysis found.**
 Recall is the objective function of an analysis-coverage audit. It is not the objective
 function of an editorial decomposition. When the two are measured on one axis, every
 analysis by-product becomes a record. A decomposition that excludes nothing has not
 selected anything.
 ## SSOT hierarchy
 Four layers, and only one of them is the input for finding candidates.
 | Layer | Role |
 |---|---|
 | code · config · execution evidence | ground truth for facts |
 | `final/document.md` | **SSOT for the candidate scope** — the only input for discovering candidates |
 | `analysis/**/*.md` | supporting detail for a claim `final` already adopted — exists only while the analysis is running |
 | `tech-log-tree.json` | the decomposition contract and the index at once, and the source of truth. Written by hand; a script refreshes only the fields it can read back from the record files |
 Do not open `analysis/**` to discover candidates. Open it to check the detail of a claim
 that is already in `final/document.md`. If the analysis holds material that `final` does
 not, **fix `final/document.md` first**, then decompose. Otherwise 61 module documents
 become 61 competing SSOTs and the tree grows to their combined section count.
 ## Candidate scope
 A folded `final/document.md` is not uniformly candidate material. Part 1 is the integrated
 analysis and it is where candidates come from. Part 2 holds the module analyses that were
 folded in, and Part 3 holds the analysis material — both are supporting evidence, and
 reading them as candidate material recreates the failure the fold was meant to end: one
 candidate per module-analysis heading.
 Declare the boundary in the contract so it is checkable rather than remembered.
 ```json
 "candidateScope": {
  "document": "final/document.md",
  "sections": ["§3", "§4", "§5", "§6", "§7", "§8", "§9", "§10", "§11"],
  "excluded": ["제2부 — 모듈 분석 전문", "제3부 — 분석 재료"]
 }
 ```
 An anchor outside that scope is a source anchor, not a candidate. Cite it from a node whose
 candidate came from Part 1.
 ## Which files exist, and when
 Decomposition happens after the analysis has been folded in, and the folded project has
 fewer files than the one that was being analyzed. Read what is actually there.
 | Phase | Files | Where candidates come from |
 |---|---|---|
 | analysis running | `state.json` · `source-index.md` · `analysis/**` · `final/document.md` | `final/document.md` |
 | analysis folded in | `final/document.md` only | `final/document.md`, candidate scope |
 | decomposition | `final/document.md` · `tech-log-tree.json` | candidate scope |
 `state.json` and `source-index.md` say how far the analysis got and which code it covered.
 They do not hold candidates, and in a folded project they are gone.
 ## Required sequence
 1. Read the candidate scope of `final/document.md` end to end.
 2. Pick representative **Cases** from the confirmed-problem and execution sections
   (in the standard layout, §3–§8).
 3. Pick **References** from the reusable-criteria section (§9).
 4. Pick **Decisions** from the explicit-decision section (§10).
 5. Pick **Questions** from the unresolved section (§11).
 6. Only now add the **Concepts** those four need in order to be understood. Concept is
   derived backwards from the records that require it, never by sweeping headings. Add the
   **Setups** the analysis actually supports in the same pass — the section below says which
   ones those are.
 7. Give every candidate a disposition — `references/candidate-disposition.md` — and set
   `dispositionReview` to `CONFIRMED` only for the ones a person actually re-read.
 8. Group `PROMOTE` candidates into Topics. Write one reader question per Topic.
 9. Write every promoted candidate into `tech-log-tree.json` as a node under its Topic,
   with the fields its kind requires. There is no second tree to keep in step.
 10. Run `references/decomposition-checklist.md`.
 11. Record `candidateScope`, the source document hash, and the project revision.
 12. `python3 scripts/build-tech-log-tree.py <project>` first, then
    `python3 scripts/verify-tech-log-tree.py <project>` — errors must be 0. Build fills
    `ssotSha256`; verify errors when it is absent, so verifying before building always fails.
 ## When a Setup belongs in the tree
 Add a **Setup** where the analysis records the commands and configuration values that stand
 an environment up and someone other than the author has to run them.
 Its test is not the one the other five take. They ask whether a claim is worth publishing on
 its own; this one asks whether a reader would type these lines. A reproduction that only
 re-obtains one measurement stays inside that Case's `재현 조건` field, and a procedure nobody
 but the author would run is that Case's environment section.
 Setup nodes need a project. A Topic is optional, and a Setup without one reads as that
 project's shared configuration. Instead of a verification date it carries `pinned-versions`
 — the versions the procedure was established on.
 ## Three fields the verifier requires and this procedure does not otherwise name
 Write them by hand. `verify-tech-log-tree.py` counts each as an error when missing.
 | Field | What goes in it |
 |---|---|
 | `candidateScope` | the range candidates were found in — above |
 | `sourceRepository` | `path` of the analyzed repository, its `revision`, and how that was established. Leave `revision` `null` rather than inventing one; when the work is split across branches, pair names and commits under `revisions` |
 | `ssotSha256` | filled by `build-tech-log-tree.py`. Its job is to catch a tree whose SSOT changed after the candidates were chosen |
 ```json
 "sourceRepository": {
  "path": "/absolute/path/to/analyzed-repo",
  "revision": null,
  "revisions": {"AP1 develop-pattern1": "64175266"},
  "verified": "how the revision was established, or why it is null"
 }
 ```
 Use `.agents/skills/writing-tech-log-records/references/tech-log-tree-contract.md` as the
 output contract.
 ## Topic boundary
 **A Topic is one reader question.** Write it under the topic slug:
 ```text
 TOPIC
 OAuth 자격증명과 세션의 보관 경계
 oauth-oidc-auth-boundary
 독자 질문 — 자격증명과 세션을 누가 보관하고, 누가 API 요청을 만들며, 보호 자원은 무엇을 신뢰하는가?
 ```
 A node that does not help answer that question belongs to another Topic. If a Topic needs
 two questions, it is two Topics. If two Topics share one question, they are one Topic.
 This is the test that catches both failures at once — splitting one problem space across
 `state-machines-and-ownership`, `state-ownership-and-concurrency`, and
 `owner-safe-state-machines`, and packing forwarded-header trust, fileserver mapping,
 Redis key APIs, and permission normalization into one `admission-budget-and-backpressure`.
 Do not create one Topic per source file or module. A directory is not a Topic.
 ## Classification discipline
 - **Case** — one problem, an observation or reproduction, a diagnosis, a closed conclusion.
 - **Concept** — structure or behavior that must be explained from the beginning before a
  Case can be understood. Has a `basis-version`.
 - **Reference** — a rule that applies to the next project, with scope and exceptions.
 - **Open Question** — no answer yet, the design turns on the answer, and there is a next
  verification and a closing criterion.
 - **Decision** — the project actually chose a direction, with grounds and an accepted cost.
 - **Setup** — a procedure the reader runs to stand the environment up. Carries
  `pinned-versions` instead of a verification date, and always belongs to a project.
 The independence test decides the first five:
 > Delete this record and fold it into a related Case or Concept as one section. If
 > understanding, decisions, and reuse are unchanged, it is not an independent record.
 Setup does not answer that question, because folding a procedure into a Case is exactly what
 this kind exists to stop — the commands end up in a plain-text `검증 환경` field where they
 cannot be copied. Ask instead who runs it. If only the author ever will, it is that Case's
 environment, not a record.
 Branches may be empty. Symmetry is not a quality goal. Neither is volume — a large
 denominator justifies a long `final/document.md`, not a long tree.
 ## Refreshing the derived fields
 There is one file. `tech-log-tree.json` is written by hand, and the build refreshes only
 what it can read back from the record files — `file`, `publication`, `status`, `studioId`,
 `assets`, `evidenceFiles` — plus `counts`, `ssotSha256`, and the `unlisted` list.
 ```bash
 python3 scripts/build-tech-log-tree.py <project>
 ```
 `readiness`, `source`, `classification`, `relations`, and the rest of each kind's fields
 survive a rebuild untouched. The build never reads the directory listing for Topics: a
 folder left behind after a node is dropped from the contract shows up in `unlisted`, and it
 does not come back as a Topic.
@@ -0,0 +1,100 @@
 # 후보의 처분 — 무엇을 독립 기록으로 만들고 무엇을 만들지 않는가
 분석에서 나온 항목마다 처분을 하나 적는다. 처분은 `tech-log-tree.json` 의 `candidates` 에
 남고, `PROMOTE` 만 같은 파일의 `topics` 로 올라간다.
 ## 목표 함수
 **빠짐없이 방출하는 것이 아니라 고르는 것이다.** 분석 누락을 검증할 때는 recall 100%
 가 맞다. 공개할 글을 정할 때는 아니다. 「분석에서 보존할 가치」와 「독립된 글로 읽을
 가치」는 다른 물음이고, 둘을 한 축으로 재면 분석 부산물이 전부 글이 된다.
 제외가 0 건인 분해는 선별하지 않은 분해다.
 ## 여섯 가지 처분
 | 처분 | 뜻 | 어디로 |
 |---|---|---|
 | `PROMOTE` | 독립 Tech Log 로 쓴다 | `tech-log-tree.json` 의 노드가 된다 |
 | `MERGE_INTO` | 다른 기록의 한 절·표 행으로 흡수한다 | 흡수한 기록의 slug 를 `target` 에 적는다 |
 | `KEEP_IN_SSOT` | 중요한 분석 결과지만 독립 기록은 아니다 | `final/document.md` 와 `analysis/**` 에 남는다 |
 | `NEEDS_EVIDENCE` | 주장에 아직 검증이 없다 | 측정한 뒤에 다시 판정한다 |
 | `NEEDS_DECISION` | 방향이 그럴듯하지만 프로젝트가 정하지 않았다 | 정해진 뒤에 다시 판정한다 |
 | `BLOCKED` | 원본이 불완전하거나 서로 어긋난다 | 원본을 고친 뒤에 다시 판정한다 |
 **`KEEP_IN_SSOT` 은 실패가 아니다.** 정보를 버리지 않으면서 글로 과분류하지 않는
 상태다. 분석 범위, 호출자 수, 미배선 사실, 커버리지 원장, 재현에 쓴 레인 같은 것이
 여기 온다 — 분석에는 반드시 남아야 하고 공개 기록으로는 읽을 사람이 없다.
 `REJECTED` 는 쓰지 않는다. 무엇을 버렸는지가 아니라 무엇이 어디에 남았는지를 적는다.
 ## 독립성 검사
 처분을 정하는 물음은 하나다.
 > **이 기록을 없애고 관련 Case 나 Concept 의 한 절로 넣어도 이해·결정·재사용성이
 > 그대로라면 독립 기록으로 만들지 않는다.**
 그대로면 `MERGE_INTO`. 넣을 자리조차 없으면 `KEEP_IN_SSOT`.
 ## 종류마다 독립 기록이 되는 조건
 | 종류 | 독립 기록이 되는 조건 | 되지 않는 것 |
 |---|---|---|
 | Case | 하나의 문제 · 관측·재현 · 진단 · 결론이 닫힌다 | 단순 정적 카운트, 문구 수정, 같은 원인의 부분 증상 |
 | Concept | 내부 구조나 동작을 처음부터 설명해야 Case 를 이해할 수 있다. 기준 버전이 있다 | 분석 범위, 호출자 수, 미배선 사실, 한두 문장으로 Case 안에 설명되는 것 |
 | Reference | 다음 프로젝트에도 적용할 규칙이며 적용 조건과 예외가 있다 | Case 결론을 선언문으로 바꾼 것 |
 | Question | 답이 아직 없고, 답에 따라 설계가 달라지며, 다음 검증과 종료 기준이 있다 | 실행하지 않은 테스트 목록, 막연한 "다른 방법은?" |
 | Decision | 대안 중 프로젝트가 실제 방향을 정했고 근거와 감수한 비용이 있다 | 기술이 존재한다는 사실, 권장사항, 아직 정하지 않은 방향 |
 | Setup | 남이 자기 기계에서 실행할 명령과 구성 값이 있고 프로젝트가 정해져 있다 | 글쓴이만 다시 돌릴 재현 순서(그 Case 의 재현 조건이다), 명령 없는 구성 설명 |
 ## Case 를 언제 합치나
 **같은 질문에서 나와 같은 결론에 닿는 관측이면 한 Case 다.** 인과 단위·의미 단위·검증
 단위가 셋 다 같아야 합친다는 기준은 너무 좁다 — 그 기준에서는 같은 결함의 다섯 증상이
 다섯 편이 된다.
 관측이 여럿이면 한 Case 안에 표나 하위 절로 넣는다. 표의 행 하나가 될 것을 기록
 하나로 만들지 않는다.
 ## Concept 을 언제 만드나
 **Case·Decision·Question 을 먼저 고른 뒤 거꾸로 뽑는다.** "이 Case 를 읽는 사람이 미리
 알아야 하는 구조가 있는가"를 묻고, 있으면 그때 Concept 을 만든다. 메커니즘처럼 보이는
 절을 훑어 채우면 어느 Case 도 필요로 하지 않는 개념이 쌓인다.
 Concept 에는 `basis-version` 이 있어야 한다. 무엇을 보고 쓴 글인지 없으면 언제 낡았는지
 읽는 사람이 알 방법이 없다.
 제목이 이런 꼴이면 Concept 이 아니다.
 ```text
 호출자가 없다                      → 부재는 Case 의 관측이다
 프로덕션에서 실행되지 않는다        → 같은 이유
 구현 클래스 51개를 전부 읽었다      → 분석 범위. KEEP_IN_SSOT
 보류한 항목과 보류한 이유           → 분석 진행 기록. KEEP_IN_SSOT
 (8.4) 문서/구현 드리프트 — …       → 분석 문서의 절 제목을 그대로 옮긴 것
 Confirmed — …                      → 같은 것. finding 등급이 제목에 남아 있다
 ```
 ## 대장에 적는 것
 ```json
 {
  "id": "A05-F012",
  "kindCandidate": "CASE",
  "sourceRefs": ["final/document.md#8-3"],
  "summary": "…",
  "disposition": "MERGE_INTO",
  "dispositionReview": "CONFIRMED",
  "target": "case:two-owners-popped-the-evidence-frame",
  "reason": "같은 결함의 두 번째 증상이다. 그 Case 의 재현 절에 행으로 들어간다"
 }
 ```
 `dispositionReview` 는 `CONFIRMED` 와 `PENDING` 둘이다. 사람이 위 물음으로 판정했으면
 `CONFIRMED`, recall 로 자동 방출된 것이면 `PENDING` 이다. **`PENDING` 이 남아 있는
 프로젝트는 글감 선별이 끝나지 않은 것이다.**
 `python3 scripts/verify-tech-log-tree.py <프로젝트>` 가 남은 건수를 error 로 센다. 경고가
 아니라 error 인 이유는 하나다 — 경고로 두면 재판정하지 않은 트리로 글을 쓰기 시작할 수 있다.
@@ -0,0 +1,81 @@
 # Tech Log Tree Decomposition Checklist
 ## Selection
 - [ ] Every analysis candidate carries a disposition, and `KEEP_IN_SSOT` is used.
 - [ ] `dispositionReview: PENDING` is 0 — nothing reached the tree by recall alone.
 - [ ] Each `PROMOTE` node passes the independence test.
 - [ ] Candidates were discovered from `final/document.md`, not from `analysis/**`.
 - [ ] Material found only in `analysis/**` was added to `final/document.md` first.
 - [ ] `candidateScope` is declared, and no candidate came from outside it.
 ## Source integrity
 - [ ] The tree records the source document hash, ledger hash, and project revision.
 - [ ] Every node has at least one source anchor.
 - [ ] Source anchors actually contain the material implied by the title.
 - [ ] Runtime-dependent claims name evidence or use `NEEDS_EVIDENCE`.
 - [ ] `readiness` states how well evidenced the node is. It does not state whether the
      record has been written or published.
 ## Topic quality
 - [ ] Every Topic has one reader question, and every node in it helps answer that question.
 - [ ] No two Topics share a reader question.
 - [ ] Topic is an engineering problem space rather than a directory name.
 - [ ] A large Topic is split when its records no longer share useful relations/criteria.
 ## Case
 - [ ] There is a specific incident, experiment, failure, diagnosis, or verification sequence.
 - [ ] The title can be understood without inventing a historical story.
 - [ ] The conclusion is bounded by actual evidence.
 - [ ] Observations that answer the same question with the same conclusion are one Case,
      as a table or sub-sections — not several partial Cases.
 ## Concept
 - [ ] It was added because a Case, Decision, or Question needs it, not by sweeping headings.
 - [ ] `basis-version` names what the explanation was written against.
 - [ ] The title names a mechanism, not an absence, a count, or an analysis-scope fact.
 - [ ] No analysis section number or finding grade survives in the title.
 ## Setup
 - [ ] Someone other than the author has to run it; it is not one Case's reproduction steps.
 - [ ] The commands and configuration values come from the analysis, not from memory.
 - [ ] `pinned-versions` names the versions the procedure was established on.
 - [ ] A project is set. No verification date is invented to stand in for the versions.
 ## Reference
 - [ ] The rule is reusable beyond the originating incident.
 - [ ] It is not the Case summary rewritten declaratively.
 - [ ] Scope and exception can be stated from sources.
 ## Open Question
 - [ ] The answer is not already in the analysis.
 - [ ] Known/unknown/next verification are separable.
 - [ ] The design or a decision actually turns on the answer.
 - [ ] Candidate options are included only when sources really considered them.
 ## Decision
 - [ ] A project choice is explicitly recorded or user-supplied.
 - [ ] `technology is present` is not being treated as rationale.
 - [ ] The accepted cost is stated, not only the benefit.
 - [ ] `NEEDS_DECISION` is used if the direction is only a recommendation.
 ## Duplication and shape
 - [ ] No two nodes have the same primary purpose.
 - [ ] Relations are used instead of copying one record into another.
 - [ ] Node count is bounded by what a reader would read, not by the analysis denominator.
 ## Parity
 - [ ] Every node traces back to a `PROMOTE` candidate, and every `PROMOTE` candidate has a node.
 - [ ] `counts` matches what `build-tech-log-tree.py` produces.
 - [ ] `unlisted` is empty — no record file exists outside the contract.
 - [ ] `python3 scripts/verify-tech-log-tree.py <project>` reports 0 errors.
@@ -0,0 +1,154 @@
 # `tech-log-tree.json` 예시
 **구조 예시다.** 실제 분석을 수행해 만든 결과가 아니므로 이 값을 그대로 옮겨 쓰지 않는다.
 실제 프로젝트에서는 같은 모양에 진짜 source anchor 와 evidence 를 채우고 readiness 를 판정한다.
 트리는 이 파일 하나다. 사람이 읽는 트리와 Node Specification 을 따로 쓰고 대조하던 절차는 없다 —
 계약과 색인이 같은 파일이라 어긋날 자리가 없다.
 ```json
 {
  "schemaVersion": 4,
  "project": "n+1liner",
  "ssot": "final/document.md",
  "ssotSha256": "<sha256>",
  "sourceRevision": "<git-revision>",
  "generatedAt": "<YYYY-MM-DD>",
  "candidateScope": {
    "document": "final/document.md",
    "sections": ["§3", "§4", "§5", "§6", "§7", "§8", "§9", "§10", "§11"],
    "excluded": ["제2부 — 모듈 분석 전문", "제3부 — 분석 재료"]
  },
  "contract": {
    "readinessValues": ["READY", "OPEN", "NEEDS_EVIDENCE", "NEEDS_DECISION", "BLOCKED"],
    "dispositionValues": {
      "PROMOTE": "독립 Tech Log 로 쓴다",
      "MERGE_INTO": "다른 기록의 한 절로 흡수한다",
      "KEEP_IN_SSOT": "분석에는 남기고 독립 기록으로 만들지 않는다",
      "NEEDS_EVIDENCE": "주장에 아직 검증이 없다",
      "NEEDS_DECISION": "방향이 그럴듯하지만 프로젝트가 정하지 않았다",
      "BLOCKED": "원본이 불완전하거나 서로 어긋난다"
    }
  },
  "topics": {
    "jpa-feed-query-performance": {
      "topic": "jpa-feed-query-performance",
      "title": "JPA 피드 조회 성능",
      "readerQuestion": "피드 한 화면을 그리는 데 쿼리가 몇 번 나가고, 조회 전략을 바꿀 때 무엇이 함께 바뀌는가?",
      "kinds": {
        "case": [
          {
            "title": "필드 접근 없이 발생한 EAGER ToOne N+1",
            "kind": "case",
            "slug": "eager-to-one-n-plus-one",
            "readiness": "READY",
            "source": ["final/document.md#user-page-연관-숨은-추가-쿼리-정량화"],
            "code": ["FeedQueryRepository.java:loadFeed"],
            "evidence": ["evidence/raw/explain/highlights-child-plan-A.txt"],
            "classification": "조회 한 번에 나간 쿼리 수를 세어 재현했고 실행계획으로 확인했다",
            "missing-verification": "동시 트래픽에서는 재지 않았다",
            "relations": ["reference:fetch-type-vs-fetch-strategy"]
          }
        ],
        "concept": [
          {
            "title": "Fetch Type 과 Fetch Strategy 가 갈라지는 자리",
            "kind": "concept",
            "slug": "fetch-type-and-fetch-strategy",
            "readiness": "READY",
            "source": ["final/document.md#fetch-type과-fetch-strategy"],
            "basis-version": "Hibernate 6.4 · Spring Data JPA 3.2",
            "classification": "이 구분을 먼저 알아야 위 Case 의 관측을 읽을 수 있다",
            "relations": ["case:eager-to-one-n-plus-one"]
          }
        ],
        "reference": [
          {
            "title": "Fetch Type 과 Fetch Strategy 를 구분한다",
            "kind": "reference",
            "slug": "fetch-type-vs-fetch-strategy",
            "readiness": "READY",
            "source": ["final/document.md#fetch-type과-fetch-strategy"],
            "classification": "다음 프로젝트에도 적용할 조회 기준이다",
            "scope": "JPA 연관을 하나라도 조회하는 모듈",
            "exceptions": "단건 조회만 있는 경로에는 걸리지 않는다",
            "relations": ["case:eager-to-one-n-plus-one"]
          }
        ],
        "question": [
          {
            "title": "ANALYZE 이후 Cardinality Estimate 는 어떻게 달라지는가",
            "kind": "question",
            "slug": "cardinality-estimate-after-analyze",
            "readiness": "OPEN",
            "source": ["final/document.md#query-plan-측정"],
            "known": "현재 통계에서 Plan B 의 추정 행 수는 실제의 1/8 이다",
            "unknown": "통계를 갱신하면 플래너가 같은 계획을 고르는지",
            "next-verification": "seed(1000) 뒤 ANALYZE highlights 를 돌리고 Plan B 를 다시 잰다",
            "decision-criterion": "추정치가 실제의 2배 안이면 닫고, 벗어나면 통계 갱신 주기를 정하는 Decision 으로 넘긴다",
            "relations": ["case:eager-to-one-n-plus-one"]
          }
        ],
        "decision": [
          {
            "title": "Collection Fetch Join 과 Pagination 을 같이 쓰지 않는다",
            "kind": "decision",
            "slug": "no-collection-fetch-join-with-pagination",
            "readiness": "READY",
            "decision-status": "ADOPTED",
            "source": ["final/document.md#컬렉션-fetch-join-페이징"],
            "decision-evidence": ["case:eager-to-one-n-plus-one"],
            "grounds": "메모리 페이징으로 떨어지는 것을 실행계획에서 확인했다",
            "classification": "대안을 두고 프로젝트가 실제로 고른 방향이다",
            "relations": ["case:eager-to-one-n-plus-one"]
          }
        ],
        "setup": []
      }
    }
  },
  "candidates": [
    {
      "id": "F012",
      "kindCandidate": "CASE",
      "sourceRefs": ["final/document.md#user-page-연관-숨은-추가-쿼리-정량화"],
      "summary": "필드 접근 없이 EAGER ToOne 이 추가 쿼리를 냈다",
      "disposition": "PROMOTE",
      "dispositionReview": "CONFIRMED",
      "target": "case:eager-to-one-n-plus-one",
      "reason": "재현·진단·결론이 한 사건 안에서 닫힌다"
    },
    {
      "id": "F013",
      "kindCandidate": "CASE",
      "sourceRefs": ["final/document.md#컬렉션-n1-정량화"],
      "summary": "같은 원인으로 컬렉션 쪽에서도 추가 쿼리가 났다",
      "disposition": "MERGE_INTO",
      "dispositionReview": "CONFIRMED",
      "target": "case:eager-to-one-n-plus-one",
      "reason": "같은 결함의 두 번째 증상이다. 그 Case 의 표에 행으로 들어간다"
    },
    {
      "id": "F014",
      "kindCandidate": "CONCEPT",
      "sourceRefs": ["final/document.md#분석-범위"],
      "summary": "이번 분석에서 읽은 리포지터리 메서드는 41개다",
      "disposition": "KEEP_IN_SSOT",
      "dispositionReview": "CONFIRMED",
      "target": null,
      "reason": "분석 범위 계수다. 분석에는 남아야 하고 공개 기록으로는 읽을 사람이 없다"
    }
  ],
  "counts": { "topics": 1, "nodes": 5, "written": 0, "unwritten": 5, "unlisted": 0, "candidates": 3 },
  "unlisted": [],
  "history": {}
 }
 ```
 ## 이 예시가 보여 주는 것
 - 후보 셋 중 하나만 글감이 됐다. `MERGE_INTO` 와 `KEEP_IN_SSOT` 이 없는 분해는 선별하지 않은 분해다.
 - Concept 은 Case 를 먼저 고른 뒤에 그것을 읽는 데 필요해서 더했다.
 - Question 에 `decision-criterion` 이 있다. 무엇이 나오면 닫는지를 적지 않으면 검증을 마쳐도 열려 있다.
 - 여섯 종류를 억지로 채우지 않아도 된다. 여기서 다섯이 다 있는 까닭은 실제로 다섯이 있었기
  때문이고, 여섯 번째인 `setup` 은 비어 있다 — 이 프로젝트에는 남이 따라 할 절차가 없었다.
@@ -0,0 +1,188 @@
 ---
 name: publishing-tech-log-to-studio
 description: Use when a finished Tech Log record .md must be put into Tech Log Studio through the browser with Playwright MCP — creating or opening the working copy, uploading assets, filling the per-kind fields, and saving. Save only; this skill never publishes.
 metadata:
  version: "1.0.1"
  language: "ko-KR"
 ---
 # Studio 반입 — 저장까지만
 ## 이 스킬의 경계
 기록 `.md` 하나를 Studio 편집 화면에 넣고 **저장**한다. 거기서 끝난다.
 **게시하지 않는다.** 게시는 공개 사이트에 올리는 일이고, 되돌리려면 `unpublish` 를 해야 하며
 그 사이에 누구나 본다. 더 중요한 것은 **한 번이라도 게시한 문서는 게시를 취소해도 지워지지
 않는다는 것이다** — 삭제가 409 로 거절되고 「공개된 기록은 삭제할 수 없습니다」가 뜬다. 그래서
 시험 삼아 게시하지 않는다. 게시는 사람이 미리보기를 읽고 판단한다.
 편집 화면 오른쪽 `aside` 에 버튼이 `저장`·`게시` 둘뿐이다. **`게시` 를 누르면 저장·검증·
 미리보기·게시가 한 번에 돈다.** 이 스킬은 `저장` 만 누른다.
 ## 들어가기 전 조건
 | 조건 | 확인 |
 |---|---|
 | 기록 `.md` 가 파서를 통과했다 | `studio-body.py` 로 바꾼 파일에 `check_body.mjs`, error 0 |
 | 문장 검사를 지났다 | `check_prose.mjs` error 0 |
 | 인용이 SSOT 에 실재한다 | `check_evidence.mjs <프로젝트> --repo` |
 | 브라우저가 이미 로그인돼 있다 | 아래 「인증」 |
 **검사를 안 지난 초안을 넣지 않는다.** 저장은 빈 칸도 받아 주기 때문에(Studio 는 한 번에 다
 쓰지 않아도 저장되게 만들어져 있다) 넣는 것 자체는 성공한다. 그래서 파서·문장 검사를 여기서
 대신 잡아 주지 않는다.
 ## 인증
 Studio 는 조회에도 권한을 요구한다. 읽는 것이 게시 전 초안이기 때문이다.
 **이 저장소에 자격증명을 두지 않는다.** 이미 로그인된 브라우저 세션을 쓴다. 편집 화면을 열었을
 때 상태 `aside` 가 25초 안에 안 뜨면 **인증이 안 된 것으로 보고 멈춘다.** 로그인 화면을
 자동으로 통과하려 들지 않는다 — 사용자에게 로그인해 달라고 말하고 기다린다.
 ```
 aside[class*="studio-document-status"]   ← 이것이 안 보이면 인증 실패
 ```
 ## 주소
 | 무엇 | 주소 |
 |---|---|
 | Studio | `https://hyeonworks.com/studio` |
 | 편집 화면 | `https://hyeonworks.com/studio/documents/<id>/edit` |
 | 새 문서 | Studio 에서 `새 문서` → 종류 선택 → `작업본 만들기` |
 기록 frontmatter 의 `id` 와 `studio:` 가 이미 차 있으면 **새로 만들지 않는다.** 그 주소로 바로
 간다. 비어 있으면 새로 만들고, 받은 uuid 와 편집 주소를 기록 frontmatter 에 적는다.
 ## 절차
 ### 1. 기록을 읽고 무엇을 넣을지 정한다
 `kind` 로 칸 목록이 정해진다. 어떤 `##` 제목이 Studio 의 어느 칸인지는
 [references/studio-form-map.md](references/studio-form-map.md), 그 칸이 서버에서 어떤 이름과
 자료형인지는 [references/studio-api.md](references/studio-api.md).
 **frontmatter 는 메타데이터고, 본문의 `##` 가 Studio 의 칸이며, 제목 아래 첫 문단이 `요약`
 이다.** 계약에 없는 `##` 는 화면에 자리가 없어 통째로 사라진다.
 **본문은 이제 화면으로 넣지 않는다.** 편집 화면의 본문이 블록 편집기로 바뀌어 블록 하나가
 `<textarea>` 하나다 — 기록 한 편이 블록 171개인 것을 실제로 봤다. 그런데 저장이 서버로 보내는
 것은 여전히 `bodyMarkdown` 이라는 마크다운 문자열 하나다. 그래서 **옮기는 일은 화면이 아니라
 `PUT /api/v1/studio/documents/{id}` 로 한다** — 로그인된 그 페이지 안에서 `fetch` 로 부르므로
 세션과 CSRF 가 그대로 실린다. 화면은 읽고 대조하는 데 쓴다.
 ### 2. 그림이 있으면 Asset 을 먼저 올린다
 frontmatter `assets:` 의 `file:` 이 올릴 파일이고 `key:` 는 저장소 쪽 이름이다. 올리면 서버가
 `<이름>-<해시8>` 형태의 키를 준다.
 **본문을 넣기 전에 올린다.** 순서를 뒤집으면 미리보기가 본문 전체를 막는다 —
 `1:1 supported local evidence key not found: <asset-key>`. 다른 경로로 올렸으면 편집 화면을
 한 번 새로 고쳐야 목록을 다시 받는다. 본문 문법 문제로 오해하기 쉽다.
 본문은 서버가 준 키로 바꿔서 넣는다.
 ```bash
 python3 scripts/studio-body.py <기록.md> --key <저장소 key>=<서버가 준 key> --body-only
 ```
 저장소의 `.md` 는 마크다운 이미지로 두고 고치지 않는다. `:::evidence` 는 Studio 렌더러의
 구문이라 저장소에 쓰면 편집기에서 그림이 안 보인다.
 ### 3. 칸을 채운다
 되풀이되는 칸(`영향`·`선택지`·`사실`처럼 여러 줄인 것)은 **줄 수를 먼저 맞추고** 값을 넣는다.
 줄이 모자란 채로 채우면 뒤엣것이 조용히 버려진다. 셀렉터와 배치 실행 방법은
 [references/playwright-recipes.md](references/playwright-recipes.md).
 **본문이 없는 세 종류(Reference·Question·Decision)의 칸은 마크다운 블록 파서를 안 거친다.**
 그래도 전부 글자로 나오지는 않는다 — 렌더러(`tech-log-frontend` 의
 `presentation/shared/public-render/prose-text.tsx`)가 **백틱 쌍은 인라인 `<code>` 로** 살리고,
 빈 줄은 문단으로, 한 줄 바꿈은 `<br>` 로 남긴다. **글자 그대로 나오는 것은 별표·파이프·`#`·
 코드펜스·인용 표지 `>` 다.** 백틱을 빼지 않는다 — 빼면 식별자가 민무늬로 나온다.
 **환경 구성에도 되풀이 칸이 하나 있다.** `고정한 버전` 은 줄마다 `이름`·`버전` 입력 둘이고
 「버전 추가」 버튼으로 늘린다. 여기도 줄 수를 먼저 맞추고 값을 넣는다.
 ### 4. 저장한다
 API 로 넣었으면 `PUT` 이 200 을 내는 것이 저장이다. **`expectedVersion` 은 저장 직전에 `GET`
 으로 읽은 `document.version` 이다** — 지어내지 않는다. 보내지 않은 칸은 비워지므로 그 종류의
 칸을 전부 담는다.
 화면으로 고쳤으면 버튼을 누른다.
 ```
 aside[class*="studio-document-status"] 안의 `저장` 버튼
 → 같은 aside 의 글자가 `저장됨` 으로 바뀔 때까지 기다린다 (최대 30초)
 ```
 `저장됨` 을 못 보면 실패다. 그 `aside` 의 글자를 그대로 읽어서 보고한다. **버튼을 다시 누르지
 않는다** — 검증 오류로 막힌 것을 연타로 뚫으려다 `게시` 를 누르게 된다.
 버전은 같은 `aside` 의 첫 `dd` 에 있다. 저장 전후로 읽어 두면 실제로 올라갔는지 보인다.
 ### 5. 미리보기로 읽는다
 `즉시 미리보기` 탭은 저장한 값이 아니라 **화면에 입력한 값**을 렌더링한다. 그래서 게시 없이도
 공개 화면과 같은 블록 렌더러로 본문을 볼 수 있다.
 읽을 항목은 `../writing-tech-log-records/references/studio-draft-review.md` 의 목록을 쓴다.
 고칠 것이 있으면 `편집` 탭으로 돌아가 고치고 다시 저장한다.
 ### 6. 기록에 되적는다
 새로 만들었으면 frontmatter 의 `id` 와 `studio:` 를 채우고 색인을 다시 만든다.
 ```bash
 python3 scripts/build-tech-log-tree.py <프로젝트>
 python3 scripts/verify-tech-log-tree.py <프로젝트>
 ```
 `build-tech-log-tree.py` 는 frontmatter 의 `id` 가 있으면 `publication` 을 `게시됨` 으로
 적는다. **이 칸은 「Studio 에 있다」는 뜻이지 「공개돼 있다」가 아니다.** 공개 여부는 기록의
 `status` 와 `public:` 이 말한다.
 ## 시험용 초안을 남기지 않는다
 확인하려고 만든 작업본은 지운다. **여섯 종류 전부 삭제 경로가 있다.** 앞의 다섯은
 `tech-log-backend` @ `a000f87` 의 `ManagementDocumentController` 에서 셌고, 환경 구성은
 `tech-log-frontend` @ `9e5642c` 의 `management-api.openapi.yaml:606-628`(`deleteSetupDraft`)
 에서 읽었다. 경로 앞머리가 줄마다 다른 것은 두 문서가 각자 적는 대로 옮겼기 때문이다.
 | 종류 | 경로 | 본문 |
 |---|---|---|
 | Case | `DELETE /api/v1/studio/cases/{id}` (`:72`) | `{"expectedVersion": <저장 버전>}` |
 | Reference | `DELETE /api/v1/studio/references/{id}` (`:81`) | `{"expectedVersion": <저장 버전>}` |
 | Concept | `DELETE /api/v1/studio/concepts/{id}` (`:95`) | `{"expectedVersion": <저장 버전>}` |
 | Setup | `DELETE /api/v1/studio/setups/{id}` | `{"expectedVersion": <저장 버전>}` |
 | Question | `DELETE /api/v1/studio/questions/{id}` (`:114`) | `{"expectedVersion": <저장 버전>}` |
 | Decision | `DELETE /api/v1/studio/projects/{id}/decisions/{decisionId}` (`:123`) | `{"expectedVersion": <저장 버전>}` |
 **본문 없이 부르면 204 가 아니라 422 다.** `ExpectedVersionRequest` 가 없으면
 `REQUEST_VALIDATION_FAILED` / `Request body is malformed` 로 거절된다. 헤더에는
 `X-CSRF-TOKEN` 이 있어야 한다. 여섯 줄 다 같고, 전에 이 표는 경로만 적고 본문을 적지 않았다.
 환경 구성 줄은 2026-09-12 에 시험 작업본 하나를 만들고 이 경로로 지워 204 를 받아 확인했다
 (계약 `9e5642c`).
 **전에 이 자리에 「Decision 은 계약에 삭제 경로가 없다」고 적혀 있었고 그것은 틀렸다.**
 확인 없이 적힌 문장이 옮겨 다녔다 — 이 배치에서 그 문장을 코드 주석과 보고서로 다시 옮긴
 일이 있었다. **서버를 서술할 때는 확인한 리비전을 함께 적는다.** 리비전이 없으면 서버가
 바뀌어도 아무도 모른다.
 **지워지지 않는 것은 따로 있다.** 게시한 적이 있으면 `DOCUMENT_PUBLISHED` 로 409 가 나고
 (「공개된 기록은 삭제할 수 없습니다」), 관계로 참조된 문서는 `DOCUMENT_IN_USE` 로 막힌다
 (「이 기록을 참조하는 곳이 있어 삭제할 수 없습니다」). 참조하는 쪽의 관계를 먼저 끊는다.
 ## 실패했을 때
 | 증상 | 원인 |
 |---|---|
 | `aside` 가 안 뜬다 | 인증. 로그인 화면을 자동으로 넘기지 않는다 |
 | 미리보기가 본문 전체를 막는다 | Asset 을 올리기 전에 본문을 넣었다. 화면을 새로 고친다 |
 | 칸을 못 찾는다 (`label` 매치 0) | 그 종류에 없는 칸이다. `studio-form-map.md` 를 다시 본다 |
 | 값이 잘렸다 | 되풀이 칸의 줄 수를 안 맞추고 채웠다 |
 | `저장됨` 이 안 뜬다 | 검증이 막은 것이다. `aside` 글자를 읽어 보고한다 |
@@ -0,0 +1,252 @@
 # Playwright MCP 로 편집 화면을 다루는 법
 여기 적은 셀렉터는 지어낸 것이 아니라 이 저장소가 실제로 돌린 것이다. 원문은
 `.playwright-mcp/_p1.mjs`·`_p2.mjs`·`_p3.mjs` 에 남아 있다.
 ## 두 가지 방식
 | 방식 | 언제 |
 |---|---|
 | MCP 도구를 하나씩 (`browser_navigate` · `browser_snapshot` · `browser_fill_form` · `browser_click`) | 기록 한 건. 화면을 보면서 한다 |
 | `browser_run_code_unsafe` 로 한 번에 | 여러 건을 같은 모양으로 채운다 |
 **처음 넣는 기록은 하나씩 한다.** 배치는 이미 한 번 성공한 모양을 반복할 때만 쓴다. 화면을
 안 보고 배치를 돌리면 못 찾은 칸이 조용히 버려진다.
 ## 새로 만들 때 — `/studio/documents/new`
 종류를 라디오로 고르고 `작업본 만들기` 를 누른다. 라디오의 이름은 화면에 보이는 그대로다.
 | 계약 `kind` | 라디오 이름 | 화면이 적어 놓은 칸 |
 |---|---|---|
 | `CASE` | `검증 기록` | 문제 · 결론 · 환경 · 재현 · 본문 |
 | `REFERENCE` | `적용 기준` | 목적 · 규칙 · 적용 조건 · 예외 · 예시 |
 | `CONCEPT` | `동작 원리` | 기준 버전 · 본문 |
 | `SETUP` | `환경 구성` | 버전 · 본문 |
 | `QUESTION` | `열린 질문` | 상태 · 사실 · 가정 · 미지수 · 선택지 |
 | `PROJECT_DECISION` | `설계 결정` | 상태 · 결정일 · 결정문 · 판단 이유 · 영향 · 근거 |
 **여섯 다 한글이다.** 이 표는 전에 「Concept 만 라디오 이름이 한글(`개념`)이다. 나머지 넷은
 영어다」라고 적고 있었고 그것은 낡았다 — 2026-09-12 에 `/studio/documents/new` 를 열어 여섯
 라디오의 이름을 그대로 읽었다. **화면 문구는 이렇게 조용히 바뀐다.** 표를 외워서 넣지 말고
 스냅샷으로 읽은 이름을 쓴다.
 ```js
 await page.goto('https://hyeonworks.com/studio/documents/new');
 await page.getByRole('radio', { name: /^환경 구성/ }).check();
 await page.getByRole('button', { name: '작업본 만들기' }).click();
 // 주소가 /studio/documents/<uuid>/edit 로 바뀐다. 그 uuid 를 기록 frontmatter 에 적는다
 ```
 화면에 이렇게 적혀 있다 — 「이 화면의 작업본은 현재 Studio 세션에서만 유지됩니다.」
 **만들었으면 그 자리에서 칸을 채우고 저장한다.** 만들어 두고 나중에 돌아오지 않는다.
 ## 화면의 기준점
 ```js
 const RAIL = 'aside[class*="studio-document-status"]';
 ```
 이 `aside` 가 상태 레일이다. 여기에 버전(`dd` 첫 번째)과 저장 상태(`저장됨`)와 버튼
 (`저장`·`게시`)이 있다.
 **이것이 25초 안에 안 뜨면 인증이 안 된 것이다.** 로그인 화면을 자동으로 넘기려 들지 않는다.
 ```js
 await page.goto('https://hyeonworks.com/studio/documents/' + id + '/edit');
 try { await page.waitForSelector(RAIL, { timeout: 25000 }); }
 catch { return { error: 'AUTH? ' + page.url() }; }
 ```
 ## 버전 읽기
 ```js
 const version = await page.locator(RAIL + ' dd').first().innerText();
 ```
 저장 전후로 읽는다. 안 올라갔으면 저장이 안 된 것이다.
 ## 칸 채우기
 칸은 `label` 안의 `span` 이 이름을 들고 있다.
 ```js
 const loc = page.locator('xpath=//label[./span[normalize-space(.)="' + label + '"]]')
                .locator('textarea, input').first();
 if (await loc.count() !== 1) { /* 그 종류에 없는 칸이다 — 채우지 말고 기록한다 */ }
 if (await loc.inputValue() === value) { /* 이미 같다 — 건드리지 않는다 */ }
 await loc.fill(value);
 ```
 **매치가 1이 아니면 채우지 않고 못 찾았다고 적는다.** 비슷한 이름의 다른 칸에 넣는 것보다
 안 넣는 쪽이 낫다.
 **이미 같은 값이면 건드리지 않는다.** 안 그러면 바뀐 것이 없는데 버전만 올라간다.
 ## 되풀이되는 칸은 줄 수를 먼저 맞춘다
 `영향`·`선택지`·`사실`처럼 여러 줄인 칸은 `fieldset` 의 `legend` 가 이름이고 줄이
 `.studio-ordered-item` 이다.
 ```js
 const fs = page.locator('xpath=//fieldset[./legend[normalize-space(.)="' + legend + '"]]').first();
 let cur = await fs.locator('.studio-ordered-item').count();
 while (cur > want) {                       // 줄이 남으면 뒤에서 지운다
  await fs.locator('.studio-ordered-item').last().getByRole('button', { name: '삭제' }).click();
  await page.waitForTimeout(60); cur--;
 }
 while (cur < want) {                       // 모자라면 더한다
  await fs.getByRole('button', { name: legend + ' 추가' }).click();
  await page.waitForTimeout(60); cur++;
 }
 ```
 **값을 넣기 전에 한다.** 줄이 모자란 채로 채우면 뒤엣것이 조용히 버려진다.
 **행 클래스가 칸마다 다르다.** `관계` 는 `.studio-relation-item` 이고 나머지가
 `.studio-ordered-item` 이다. 하나로 세면 관계는 늘 0으로 읽힌다.
 **더한 뒤에는 카운트가 아니라 라벨 목록으로 검산한다.** 실제로 「판단 기준 추가」를 7번
 눌렀는데 행이 9개 생겼다. 카운트만 믿으면 못 잡는다.
 ```js
 // 채우기 전에 그 fieldset 안의 라벨을 전부 읽어 몇 줄인지 다시 센다
 const labels = await fs.locator('label span').allInnerTexts();
 ```
 ## 칸은 `aria-label` 로 찾는다 (2026-09-17 에 다시 잼)
 **위의 `label` 두 모양 이야기는 낡았다.** 지금 `label.studio-field` 가 감싸는 것은 제목과 요약
 둘뿐이고, 나머지 칸은 전부 `aria-label` 을 갖는다. xpath 로 `span` 을 뒤질 일이 없다.
 ```js
 document.querySelector('input[aria-label="제목"]')
 document.querySelector('textarea[aria-label="요약"]')
 document.querySelector('input[aria-label="slug"]')
 document.querySelector('input[aria-label="판단 기준 1 제목"]')
 document.querySelector('textarea[aria-label="적용할 때 3"]')
 ```
 되풀이 칸을 늘리는 버튼은 `+ 판단 기준` · `+ 적용할 때` · `+ 예외와 주의` · `+ 예시` ·
 `+ 버전 추가` 다. 줄 수를 먼저 맞추고 값을 넣는 규칙은 그대로다.
 ## 본문 칸이 사라졌다 — 블록 편집기다
 **`본문 Markdown` 이라는 textarea 는 더 없다.** 본문은 `.studio-block-editor` 이고 블록 하나가
 `<textarea>` 하나다. 기록 한 편이 블록 171개인 것을 실제로 봤다.
 ```
 .studio-block-editor
 ├ textarea.studio-markdown-source     본문 전체의 거울. display:none · aria-hidden · readonly
 ├ .studio-block-editor__blocks
 │  └ .studio-authoring-block[data-kind]   heading · paragraph · code · bullet · raw
 └ button  + 블록 추가
 ```
 **코드 블록의 `input.studio-code-language` 에 울타리 뒤 정보 문자열 전체가 들어간다** —
 `bash label="[kc-lab-1] ① 기동 로그에서 쿠키 설정을 찾는다"` 가 그 입력의 값이었다. 라벨을
 넣을 별도 칸은 없다.
 합성한 `ClipboardEvent` 로 붙여넣는 것은 **안 먹는다.** 그래서 쓰인 기록을 화면으로 옮기지
 않는다 — [studio-api.md](studio-api.md) 의 `PUT` 으로 `bodyMarkdown` 을 통째로 보낸다.
 `.studio-markdown-source` 는 `readonly` 라 입력 자리가 아니지만, 화면이 지금 무엇을 직렬화할지를
 그대로 보여 주므로 **저장 전에 눈으로 대조하기에 좋다.**
 ## 저장 다음은 게시가 아니라 검증이다
 편집 화면의 `aside` 에는 `저장` 과 `게시` 둘뿐인데, 저장만 된 기록은 서버가 `nextAction` 을
 **`VALIDATE`** 로 준다. 검증 화면은 `/studio/documents/{id}/validation` 이다. 이 스킬은 저장까지라
 거기까지 가지 않는다 — 다만 「저장했는데 왜 게시가 안 되나」의 답이 이것이다.
 ## Asset 을 올릴 때
 `Asset 업로드` 는 모달을 띄우고 **`filechooser` 이벤트를 내지 않는다.** 기다리면 타임아웃이다.
 모달 안의 `input[type=file]` 에 직접 넣는다.
 ```js
 await page.getByRole('button', { name: 'Asset 업로드' }).click();
 await page.locator('input[type=file]').setInputFiles(svgPath);
 // 대체 텍스트 칸에 기록 본문의 alt 를 그대로 넣는다
 ```
 **올린 직후 목록이 갱신되지 않는다.** 화면의 `Asset 검색` 을 다시 눌러야 새 키가 나온다.
 새로 올리면 서버가 새 키를 준다(`<이름>-<해시8>`) — 옛 키는 목록에 남는다. 다른 문서가
 참조할 수 있으니 지우지 않는다.
 ## 값을 읽을 때는 `getByLabel` 을 쓰지 않는다
 칸이 `<label><span>이름</span><textarea></label>` 모양이라 `getByLabel(...).inputValue()` 가
 30초 타임아웃으로 실패한다. `fill` 은 되는데 읽기만 안 된다. 읽기는 `evaluate` 로 한다.
 ```js
 const got = await page.evaluate((name) => {
  const el = [...document.querySelectorAll('label')]
    .find(l => l.querySelector('span')?.textContent.trim() === name);
  return el?.querySelector('textarea, input')?.value ?? null;
 }, '판단 기준');
 ```
 **넣은 값을 다시 읽어 원문과 대조한다.** 넣었다는 것과 들어갔다는 것은 다르다.
 ## 저장
 ```js
 await page.locator(RAIL).getByRole('button', { name: '저장' }).first().click();
 await page.waitForFunction(() => {
  const el = document.querySelector('aside[class*="studio-document-status"]');
  return el && /저장됨/.test(el.innerText);
 }, null, { timeout: 30000 });
 ```
 **버튼을 이름으로 고른다.** `aside button` 의 첫 번째로 고르면 화면이 바뀌었을 때 `게시` 를
 누르게 된다.
 `저장됨` 을 못 보면 실패다. 다시 누르지 말고 레일의 글자를 읽어서 보고한다.
 ```js
 const why = (await page.locator(RAIL).innerText()).replace(/\s+/g, ' ').slice(0, 140);
 ```
 ## 바뀐 것이 없으면 저장하지 않는다
 ```js
 if (filled.length === 0 && rowsChanged.length === 0) { /* CLEAN — 저장 버튼을 누르지 않는다 */ }
 ```
 누를 때마다 `version` 이 올라가고, 버전이 올라가면 앞서 만든 검증·미리보기 산출물이 무효가
 된다(`validatedVersion == document.version` 이 깨진다).
 ## 미리보기
 **`즉시 미리보기` 는 탭이 아니다.** 편집 화면 오른쪽에 나란히 놓인 `region` 이라
 `getByRole('tab', ...)` 은 0개를 찾는다. 화면에 `[role="tab"]` 자체가 없다.
 ```js
 await page.getByRole('region', { name: /즉시 미리보기/ }).scrollIntoViewIfNeeded();
 ```
 저장한 값이 아니라 화면에 입력한 값을 렌더링한다. **Asset 을 방금 올렸으면 편집 화면을 한 번
 새로 고친다** — 안 그러면 편집 화면이 들고 있는 옛 asset 목록에서 키를 못 찾아 본문 전체가
 막힌다.
 ```text
 초안을 미리 볼 수 없습니다
 1:1 supported local evidence key not found: <asset-key>
 ```
 ## 배치로 돌릴 때 돌려받을 것
 한 건마다 이만큼은 남긴다. 무엇이 채워졌고 무엇을 못 찾았는지 없이 「성공」만 돌려받으면
 못 찾은 칸이 묻힌다.
 ```js
 { name, version, saved: 'OK v13' | 'CLEAN' | 'FAIL <레일 글자>',
  filled: ['문제','결론'], skipped: 2, miss: ['적용 조건'], rows: ['영향 2→3'] }
 ```
 ## 절대로 하지 않는 것
 - `게시` 버튼을 누르지 않는다
 - 로그인 화면에 자격증명을 입력하지 않는다
 - `저장됨` 이 안 뜬다고 연타하지 않는다
 - 시험 삼아 문서를 만들지 않는다 — 한 번 게시한 문서는 취소해도 삭제가 409 로 거절된다
@@ -0,0 +1,180 @@
 # Studio 가 실제로 주고받는 것
 여기 적은 것은 **2026-09-17 에 로그인한 브라우저에서 직접 불러 확인한 것**이다. 문서를 보고
 적은 것이 아니라 요청을 보내고 돌아온 것을 옮겼다. 확인한 판이 바뀌면 이 파일도 낡는다.
 ## 왜 이 파일이 필요해졌나
 **편집 화면의 본문이 블록 편집기로 바뀌었다.** 전에는 본문이 `본문 Markdown` 이라는 textarea
 하나였고 거기에 통째로 붙여넣으면 됐다. 지금은 블록 하나가 `<textarea>` 하나다 — 기록 한 편이
 블록 171개인 것을 실제로 봤다. 화면으로 그것을 채우는 것은 사람이 한 편을 쓸 때의 방식이지
 쓰인 기록을 옮기는 방식이 아니다.
 그런데 **저장이 서버로 보내는 것은 블록이 아니라 마크다운 문자열 하나**다. 화면은 그 문자열
 위의 편집기이고, 저장 요청은 `bodyMarkdown` 한 칸을 보낸다. 그래서 옮기는 일은 화면이 아니라
 이 API 로 한다.
 ## 인증
 **자격증명을 이 저장소에 두지 않는다.** 이미 로그인된 브라우저 세션을 쓰고, 요청은 그 페이지
 안에서(`fetch`) 보낸다. 쿠키가 그대로 실린다.
 CSRF 토큰은 `XSRF-TOKEN` 쿠키에 있고 `x-csrf-token` 헤더로 되돌려 준다.
 ```js
 document.cookie.match(/(?:^|;\s*)XSRF-TOKEN=([^;]+)/)?.[1]
 ```
 로그인이 안 돼 있으면 `/studio` 가 「기록을 쓰려면 로그인이 필요합니다」를 낸다.
 **로그인 화면을 자동으로 통과하려 들지 않는다** — 사람에게 로그인해 달라고 말하고 멈춘다.
 ## 응답 껍데기
 성공이든 실패든 같은 모양이다.
 ```json
 { "success": true, "data": { … }, "error": null,
  "meta": { "requestId": "…", "traceId": "…", "correlationId": "…", "page": null } }
 ```
 실패하면 `data` 가 `null` 이고 `error` 에 `{code, category, message, retryable, details}` 가 온다.
 `details.supportedMethods` 처럼 고칠 방법을 담아 주는 경우가 있다.
 ## 경로
 | 무엇 | 요청 |
 |---|---|
 | 목록 | `GET /api/v1/studio/documents?limit=100` |
 | 한 편 | `GET /api/v1/studio/documents/{id}` |
 | 새로 만들기 | `POST /api/v1/studio/documents` → 201 |
 | **저장** | `PUT /api/v1/studio/documents/{id}` → 200 |
 | 지우기 | `DELETE /api/v1/studio/{종류}/{id}` → 204 |
 **`limit` 은 100 이 상한이다.** 200 을 주면 422 `REQUEST_VALIDATION_FAILED` 다. 더 받으려면
 `data.nextCursor` 를 `cursor` 로 넘긴다.
 **`/documents/{id}` 는 `PUT` 과 `GET` 만 받는다.** 거기에 `DELETE` 를 보내면 405 이고
 `details.supportedMethods` 가 `["PUT","GET"]` 을 준다. 삭제는 종류별 경로다 —
 `cases` · `references` · `concepts` · `setups` · `questions`, 그리고 Decision 은
 `projects/{projectId}/decisions/{decisionId}`.
 ## 한 편 읽기
 ```
 GET /api/v1/studio/documents/{id}
 → data: { document, currentValidation, latestPreview, currentPublication,
          dependencyRevision, nextAction }
 ```
 `nextAction` 이 다음에 할 일을 말한다 — 저장만 된 기록은 `VALIDATE` 다. 검증 화면은
 `/studio/documents/{id}/validation` 이고 편집 화면의 `aside` 에는 **`저장` 과 `게시` 둘뿐**이라
 검증은 그 화면에서 따로 한다.
 ## 저장
 ```
 PUT /api/v1/studio/documents/{id}
 headers: content-type: application/json
         accept: application/json
         x-csrf-token: <XSRF-TOKEN 쿠키>
         idempotency-key: <요청마다 새로>
 body:    { "expectedVersion": <읽어 온 document.version>, "document": { … } }
 ```
 **`expectedVersion` 은 방금 읽은 `document.version` 이다.** 저장이 끝나면 1 올라간다. 지어내지
 말고 저장 직전에 `GET` 으로 읽는다.
 `document` 는 **그 종류의 칸을 전부** 담는다. 빠뜨린 칸은 비는 것으로 저장된다 — 부분 갱신이
 아니다.
 **다만 `GET` 으로 받은 것을 그대로 되보내면 400 이다.** `id` · `version` · `updatedAt` 은 서버가
 주기만 하고 받지는 않아서, 그 셋이 들어 있으면 `VALIDATION_FAILED` 와
 `UnrecognizedPropertyException` 으로 거절된다(2026-09-17 에 두 번 겪었다). 서버 상태는 안
 바뀌니 셋을 빼고 다시 보내면 된다. 어느 칸을 보내고 어느 칸을 빼는지는 바로 아래 표에 있다.
 ## 종류마다의 칸
 여섯이 함께 갖는 것: `kind` · `title` · `slug` · `summary` · `relations` · `projectId` ·
 `topicId` · `variantIds`. 서버가 주지만 보내지 않는 것: `id` · `version` · `updatedAt`.
 | kind | 그 종류만의 칸 |
 |---|---|
 | `CASE` | `problem` · `conclusion` · `environment` · `reproduction` · `bodyMarkdown` · `lastVerifiedOn` |
 | `CONCEPT` | `bodyMarkdown` · `basisVersion` |
 | `SETUP` | `bodyMarkdown` · `pinnedVersions` |
 | `REFERENCE` | `purpose` · `rules` · `applyWhen` · `exceptions` · `examples` · `verifiedOn` |
 | `QUESTION` | `facts` · `assumptions` · `unknowns` · `constraints` · `options` · `nextValidation` · `resolution` · `questionStatus` |
 되풀이되는 칸의 모양이다. `id` 는 서버가 붙이므로 새로 넣을 때는 빼고 `order` 만 0 부터 센다.
 | 칸 | 항목 |
 |---|---|
 | `relations` | `{ targetId, reason, order }` |
 | `facts` · `assumptions` · `unknowns` · `constraints` · `applyWhen` · `exceptions` · `examples` | `{ text, order }` |
 | `options` | `{ title, description, order }` |
 | `rules` | `{ title, body, order }` — **제목과 본문이 따로다** |
 | `pinnedVersions` | `{ name, version }` — `order` 가 없다 |
 ## `bodyMarkdown` 은 바이트 그대로 돌아온다
 넣은 것과 읽어 온 것이 같은지 확인했다. **코드 울타리의 정보 문자열이 그대로 살아남는다.**
 ```
 ```bash label="[host] ① 친다"
 ```
 넣고 다시 읽었을 때 `label="…"` 까지 한 글자도 안 바뀌었다. 그래서 `studio-body.py` 가 만든
 본문을 그대로 실어 보내면 된다.
 ## 화면에서 블록이 어떻게 생겼나
 옮기는 일은 API 로 하지만, 사람이 화면을 읽을 때와 무엇이 어긋났는지 볼 때 필요하다.
 ```
 .studio-block-editor
 ├ textarea.studio-markdown-source     본문 전체의 거울. display:none · aria-hidden · readonly
 ├ .studio-block-editor__blocks
 │  └ .studio-authoring-block[data-kind]   블록 하나
 └ button  + 블록 추가
 ```
 `data-kind` 는 `heading` · `paragraph` · `code` · `bullet` · `raw` 다. `raw`(화면 이름
 **고급 블록**)가 표처럼 블록으로 안 갈리는 것을 그대로 담는다.
 **코드 블록의 `input.studio-code-language` 는 언어 이름만 담지 않는다.** 울타리 뒤의 정보
 문자열 **전체**가 거기 들어간다 — `bash label="[kc-lab-1] ① 기동 로그에서 쿠키 설정을 찾는다"`
 가 그 입력의 값이었다. 라벨을 넣을 별도 칸은 없다.
 **`.studio-markdown-source` 는 읽는 데만 쓴다.** `readonly` 이고 `display:none` 이라 입력
 자리가 아니다. 다만 화면이 지금 무엇을 직렬화할지를 그대로 보여 주므로, 저장 전에 눈으로
 대조하기에 좋다.
 합성한 `ClipboardEvent` 로 붙여넣는 것은 **안 먹는다.** 화면으로 본문을 채우려면 블록을 하나씩
 만들어야 한다.
 ## 화면의 칸 셀렉터
 칸은 이제 `aria-label` 로 찾는다. `label.studio-field` 는 제목과 요약 둘만 감싼다.
 ```js
 document.querySelector('input[aria-label="제목"]')
 document.querySelector('textarea[aria-label="요약"]')
 document.querySelector('input[aria-label="slug"]')
 document.querySelector('input[aria-label="판단 기준 1 제목"]')
 document.querySelector('textarea[aria-label="적용할 때 3"]')
 ```
 되풀이 칸을 늘리는 버튼은 `+ 판단 기준` · `+ 적용할 때` · `+ 예외와 주의` · `+ 예시` ·
 `+ 버전 추가` 다.
 상태 레일은 그대로다 — `aside[class*="studio-document-status"]`(실제 class 는
 `studio-document-status-bar`). 그 안에 **`저장` 과 `게시` 둘뿐**이고, 저장된 상태에서는
 `저장` 이 `disabled` 이며 글자가 `저장됨` 이다.
 ## 하지 않는 것
 - **게시하지 않는다.** 이 스킬은 저장까지다. 한 번이라도 게시한 문서는 게시를 취소해도 삭제가
  409 로 거절된다
 - **`expectedVersion` 을 지어내지 않는다.** 저장 직전에 읽는다
 - **부분 갱신이라고 생각하지 않는다.** 보내지 않은 칸은 비워진다
 - **로그인 화면을 자동으로 넘기지 않는다**
@@ -0,0 +1,137 @@
 # 기록 `.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:` 이 말한다.
@@ -0,0 +1,37 @@
 ---
 name: refactoring-from-analysis
 description: Use when a completed codebase analysis should be turned into one bounded, evidence-backed refactoring WorkItem and implemented in isolation.
 metadata:
  version: "1.0.0"
  language: "ko-KR"
 ---
 # Refactoring From Analysis
 ## Goal
 Use `docs/<프로젝트>` as high-value context for a bounded refactor while treating the current `<분석 대상 저장소>` as source truth. One execution handles at most one WorkItem.
 ## Required sequence
 1. Read `<분석 대상 저장소>/refactor-queue.yaml` and the selected `docs/<프로젝트>/refactor/<project>/<item>/work-item.json`.
 2. Read the project's completed `document-detail` analysis and source anchors cited by the WorkItem.
 3. Confirm the analysis queue entry is `COMPLETE`, its completed source revision equals current repository HEAD, and the source working tree is clean. Otherwise do not refactor.
 4. Re-check the finding against current code. If it no longer exists, mark the item `REJECTED` with evidence; do not force a change.
 5. Read `references/refactor-queue-contract.md`, `references/work-item-contract.md`, `references/type-strategies.md`, and `references/evidence-contract.md`. For `PERFORMANCE`, also read `references/performance-evidence-contract.md`.
 6. Create/use an isolated Git worktree/branch for the WorkItem. Never implement directly in the analysis source checkout.
 7. Follow the strategy selected by `type` and `scope`.
 8. Preserve raw verification evidence under `docs/<프로젝트>/refactor/<project>/<item>/`.
 9. Run `scripts/verify-refactor-work-item.py <item-dir>` before moving to `WAITING_APPROVAL`.
 ## Performance ordering rule
 For `PERFORMANCE`, the state/operation sequence is mandatory:
 `READY → BASELINING → baseline capture at analysisRevision → IN_PROGRESS → source change → VERIFYING → after capture under the same measurement contract → comparison → functional regression checks → WAITING_APPROVAL`.
 `IN_PROGRESS` means source-changing work is now allowed, so a performance item may not enter it until baseline raw evidence and baseline metadata exist. No source-changing refactor begins before that baseline exists. If comparable measurement conditions cannot be maintained, mark the item `BLOCKED` or the comparison `INCOMPARABLE`; never claim improvement.
 ## Bounded change rule
 If a WorkItem expands beyond its declared scope or uncovers an independent problem, stop expanding the diff. Create another candidate WorkItem instead. A large project or module is not permission for a large refactor item.
@@ -0,0 +1,20 @@
 # Refactoring Evidence Contract
 Every WorkItem retains enough evidence for another reviewer or later Tech Log reanalysis to answer:
 1. What source revision was analyzed?
 2. What exact problem was confirmed in current code?
 3. What changed?
 4. What commands/tests/measurements were run?
 5. What raw outputs support the result?
 6. What conditions or limitations apply?
 Store:
 - execution/measurement environment;
 - raw baseline and after output when the type requires comparison;
 - functional/architecture/integration verification output;
 - changed-file/diff summary;
 - explicit acceptance result and limitations.
 Evidence is append-only for a completed cycle where practical. Do not replace a failed raw run with only the successful run; retain material failed attempts when they explain the final result. Never store secrets.
@@ -0,0 +1,37 @@
 # Performance Evidence Contract
 A performance refactor is not complete because code looks faster. It needs a comparable before/after experiment.
 ## Lifecycle
 A performance item uses `READY → BASELINING → IN_PROGRESS → VERIFYING → WAITING_APPROVAL`. `BASELINING` is measurement-only. Source changes are forbidden until the baseline at `analysisRevision` has been retained and the item moves to `IN_PROGRESS`.
 ## Before code changes
 Freeze the measurement contract in `work-item.json`:
 - exact command or reproducible procedure;
 - cwd;
 - environment record;
 - dataset/fixture/load profile;
 - warmup and iteration policy when relevant;
 - metrics and units;
 - acceptance criteria.
 Capture baseline raw output under `evidence/baseline/raw/` and fill `evidence/baseline/metadata.json` with source revision, command, cwd, exit code, dataset, metrics, and raw file references.
 ## After code changes
 Use the same measurement contract. Capture raw output under `evidence/after/raw/` and the matching metadata file.
 ## Comparison
 `evidence/comparison.md` must state whether conditions are materially equivalent and list baseline, after, delta, acceptance result, functional regression checks, conclusion, and limitations.
 Allowed conclusions: `IMPROVED`, `NEUTRAL`, `REGRESSED`, `INCOMPARABLE`.
 If command/procedure, metric definition, dataset/load profile, or material environment differs enough to invalidate comparison, use `INCOMPARABLE`. Do not convert incomparable measurements into an improvement claim.
 ## Evidence quality
 Retain raw output. A hand-written summary alone is insufficient. Do not fabricate missing runs. Avoid secrets at command construction time rather than relying on later redaction.
@@ -0,0 +1,28 @@
 # Refactor Queue Contract
 `<분석 대상 저장소>/refactor-queue.yaml` is the ordering SSOT for bounded refactoring work.
 ## Responsibility split
 - Queue: order, active item, summary state.
 - `docs/<프로젝트>/refactor/<project>/<item>/work-item.json`: detailed problem, goal, type, scope, acceptance criteria, evidence references.
 ## Selection
 1. Ignore items whose analysis snapshot is no longer `COMPLETE`, revision-current, and clean.
 2. Among actionable `READY` items, lower priority number wins: `P0` → `P1` → `P2` → `P3`.
 3. For equal priority, file order wins.
 4. At most one WorkItem is active. Do not start another while the active item is baselining, changing source, verifying, or waiting for approval.
 5. One scheduled execution works on at most one bounded item.
 ## Summary entry shape
 ```yaml
 - project: backend-clean-architecture
  id: RF-001
  priority: P1
  status: READY
  detail: docs/<프로젝트>/refactor/backend-clean-architecture/RF-001/work-item.json
 ```
 The queue does not duplicate detailed analysis or evidence. If queue summary and `work-item.json` disagree, stop and reconcile instead of guessing.
@@ -0,0 +1,28 @@
 # Refactoring Type Strategies
 Type selects mandatory work and verification. Scope controls how broadly dependencies and regressions must be checked.
 | Type | Mandatory strategy / evidence |
 |---|---|
 | PERFORMANCE | Baseline first, same-contract after measurement, before/after comparison, functional regression checks |
 | BUILD | Baseline/after build measurement when speed/size improvement is claimed; build correctness and task/configuration evidence |
 | ARCHITECTURE | Boundary/dependency evidence, architecture rules, build and affected integration paths |
 | MODULE_STRUCTURE | Module/package dependency graph or rule evidence plus affected build/integration tests |
 | DEPENDENCY | Before/after dependency graph, conflict/API impact, build/test evidence |
 | DATA_ACCESS | Query/SQL/row/query-count/plan evidence as relevant plus real DB integration when vendor behavior matters |
 | TRANSACTION | Transaction boundary, commit/rollback/failure contract tests; real provider/DB where semantics depend on it |
 | CONCURRENCY | Deterministic concurrency/contention tests and failure evidence; do not infer safety from sequential tests |
 | RELIABILITY | Failure-path/recovery/retry/timeout evidence and regression tests |
 | SECURITY | Positive and negative-path security tests/config evidence; never retain credentials in evidence |
 | CODE_STRUCTURE | Behavior-preserving tests, reference scan, build; public contract impact explicitly checked |
 | CLEANUP | Reference/usage scan proving removal is safe plus build/tests |
 | TESTABILITY | Demonstrate the targeted behavior is now directly verifiable; preserve production behavior |
 | CONFIGURATION | Binding/default/conditional-loading tests and affected runtime startup/config evidence |
 | OPERABILITY | Logs/metrics/health/runtime behavior evidence appropriate to the operational claim |
 ## Scope expansion
 - `LOCAL`: verify immediate callers/contract plus relevant tests.
 - `MODULE`: verify module API, internal dependency edges, module tests/build.
 - `CROSS_MODULE`: verify all touched module contracts/dependency direction and integration paths.
 - `PROJECT`: exceptional; requires project-wide impact inventory and broad verification. Prefer decomposition when possible.
@@ -0,0 +1,35 @@
 # Refactoring WorkItem Contract
 `<분석 대상 저장소>/refactor-queue.yaml` determines execution order. `docs/<프로젝트>/refactor/<project>/<item>/work-item.json` owns detail.
 ## Required fields
 - `id`, `project`, `analysisRevision`
 - `priority`: P0, P1, P2, P3
 - `type`: one supported strategy type
 - `scope`: LOCAL, MODULE, CROSS_MODULE, PROJECT
 - `target`, `problem`, `goal`
 - `acceptanceCriteria`
 - `status`
 - evidence references
 Priority decides order. Type and scope decide how work is executed and verified.
 ## Statuses
 Allowed statuses are `CANDIDATE`, `READY`, `BASELINING`, `IN_PROGRESS`, `VERIFYING`, `WAITING_APPROVAL`, `APPROVED`, `MERGED`, `REJECTED`, `BLOCKED`, and `COMPLETE`.
 `BASELINING` is used by performance work before source modification. Other types normally move from `READY` directly to `IN_PROGRESS`.
 ## Eligibility
 Before changing code:
 - analysis queue status is `COMPLETE`;
 - `analysisRevision` equals the completed analysis source revision;
 - current repository HEAD equals that revision;
 - source checkout is clean;
 - the finding still exists in current code;
 - item is bounded enough to review independently.
 If any source revision differs, the refactor is not eligible; reanalysis is required first.
@@ -1,6 +1,9 @@
 ---
 name: rewriting-technical-prose-naturally
 description: Use when an existing Korean technical document, section, or heading already contains grounded facts but sounds AI-written, slogan-like, overly polished, abstract, compressed, or mechanically contrasted and must be rewritten without changing its technical meaning.
 metadata:
  version: "1.0.0"
  language: "ko-KR"
 ---
 # Rewriting Technical Prose Naturally
@@ -22,17 +25,75 @@ keep the meaning — but fix the sentence by *adding a short clause that states
 twisting a word into a shape no one uses. A sentence that is technically exact and unspeakable is a
 sentence that still needs work.
-Before the first rewrite in a task, read both references:
+Before the first rewrite in a task, read all three references:
 - [references/document-skeleton.md](references/document-skeleton.md) — how a Korean tech blog article
  is ordered: opener, audience bar, definition section, case template, closing.
 - [references/article-shape.md](references/article-shape.md) — **how much explanation goes inside a
  section.** Ordering can be right while the piece still reads thin. This is the one that fails most often.
 - [references/korean-tech-blog-register.md](references/korean-tech-blog-register.md) — what Korean
  tech blogs actually do with definitions, verbs, particles, subjects, headings, and numbers.
 ## Unpacking is not inventing
 A compressed source and a thin source look the same on the page, and they are not. Four moves recover
 what the source already holds. None of them adds a fact.
 | Move | Where the material comes from |
 |---|---|
 | **Restore a number the prose rounded off** | The record's own fields — `검증 환경`, `재현 조건`, the evidence file, the `확인한 것` table. A body that says 「세 곳에서 막는다」 while `검증 환경` lists ports 8088 · 8081 · 4180 dropped those numbers on the way in. Put them back. |
 | **Define a term at its first use** | The standard, public definition of a term the source already uses. `MessageDigest.isEqual`, `auth_request`, `forward-auth` — one clause each, where the reader first needs it. |
 | **Turn a table row into a sentence** | The table already in the source. A row like `host port 닫힘 \| 외부 직접 경로` becomes the sentence that says which ports, closed how, and what still gets through. The table stays as the summary. |
 | **Show the code the source only named** | The repository, at the revision the record pins. `EdgeIdentityController.currentUser` named in prose becomes the method body — trimmed to what the section is about, cut marked `// …`. |
 What is still off limits: a measurement nobody took, a cause the source did not establish, a benefit or
 drawback the source did not claim, a failure story that did not happen. If a section needs a number that
 was never measured, write that it was not measured and leave the slot open — `article-shape.md` shows the
 six articles doing exactly that.
 **The test:** point at the sentence you added and name the field, file, or line it came from. If you
 cannot, it is invention, not unpacking.
 - [references/regression-examples.md](references/regression-examples.md) — rewrites that failed and why.
 Read the complete source and the nearby context needed to interpret pronouns, comparisons, and causes.
 Do not rewrite an isolated paragraph when its protected meaning depends on the surrounding section.
 ## Required sequence
 This is an **editorial** pass. The source's facts, evidence, causal chain, uncertainty, decision status,
 and technical depth are the contract. Work in this order — the steps that have their own section are
 named here so the spine stays visible.
 1. **Read the whole record once without editing.** A paragraph fixed before you know how the piece ends
   is fixed against the wrong context.
 2. **Mark the protected literals and the sentences that carry technical weight** — `Establish the meaning
   contract` below, and `references/protected-content.md`.
 3. **Name the stylistic problems, and only those.** Repeated sentence frames, forced conversational tone,
   abstract filler, too many headings, translated constructions, a conclusion restated in three places,
   paragraphs of identical length, bolding that has stopped meaning anything.
 4. **Edit diction, sentence order inside a paragraph, paragraph boundaries, and headings.** Do not move a
   fact between sections while doing it.
 5. **Re-read against the original** and restore every technical fact, limitation, condition, and evidence
   detail that fell out. This step finds more than it seems it should.
 6. **Close with `Mechanical pass` then `Final check`.** The checkers read surface patterns; the read-aloud
   test and the preservation questions decide.
 ### Hard rules for this pass
 - Do not shorten merely to look more human.
 - **Do not remove implementation detail because the paragraph feels dense.** Density is not a style defect.
 - **A section is a claim plus its evidence.** Evidence is code, output, a number, or a table — at least
  one. A section that is two paragraphs of prose with neither was cut at the wrong place; merge it with
  its neighbour. `references/article-shape.md`.
 - **Do not let a table carry an explanation that was never written.** Tables summarise prose that already
  ran. If the table is the first place a distinction appears, write the prose first and keep the table.
 - Do not create `처음에는`, `해보니`, `놀랍게도`, `저희는` or other experience language unless the source
  records that experience.
 - **Do not imitate one company's or one author's voice.** `style_profile.mjs` measures against five
  Woowahan articles because they are a *sample of engineering writing*, not a target to sound like. Apply
  the cross-source patterns in `references/editorial-rules.md`; do not adopt a house style.
 - Do not make every section equally polished, equally long, or structurally symmetric.
 ## Establish the meaning contract
 Make an internal claim ledger before editing. Do not print it unless asked. Record:
@@ -428,6 +489,20 @@ where the source really contrasts, `관계` is right inside `연관 관계`, and
 rule, re-run it against them — a rule those articles fail is a rule that is stricter than the standard,
 and it will push you into contorting prose to satisfy a check no human writer meets.
 Then measure depth. `check_prose.mjs` reads sentences; this reads how much is in them.
 ```bash
 node .agents/skills/rewriting-technical-prose-naturally/scripts/density.mjs [--구조] <파일.md>
 ```
 Default thresholds are for a piece that reports something measured — a Case. Pass `--구조` for one that
 explains how something works — a Concept — where two to five figures is normal and thirteen is not.
 Ranges come from the six articles in [examples/](examples/).
 **These are not targets to hit.** A low count names a place where explanation is missing; adding
 paragraphs to move the number produces a worse document that passes. Read the flagged line, find the
 section it points at, and decide whether the source actually holds what belongs there.
 Then take the style profile:
 ```bash
@@ -444,6 +519,22 @@ remove.
 Clean output does not mean the rewrite is good. Both tools read surface patterns and cannot see meaning;
 every rule above still applies, and the read-aloud test below is the one that decides.
 ## 참조
 - `examples/` — **통과 기준이 되는 글 여섯 편.** 이 정도로 읽히면 통과다
 - `references/article-shape.md` — 한 절 안을 무엇으로 채우는가. 잰 값과 그 값을 만드는 것
 - `references/regression-examples.md` — 고친 예와 실패 이유
 - `references/protected-content.md` — 옮길 때 한 글자도 바꾸면 안 되는 것
 - `references/editorial-rules.md` — 편집 규칙
 - `references/research-method.md` — 문체 기준값을 다시 재는 방법
 - `references/corpus/` — 한국어 기술 글 코퍼스 조사 노트
 문장 규칙 두 개는 `writing-tech-log-records` 스킬에 있다. 두 스킬이 같은 규칙을 쓰므로 사본을
 만들지 않는다.
 - `../writing-tech-log-records/references/explaining.md` — 설명하는 법
 - `../writing-tech-log-records/references/ai-tells.md` — 문서군 전체의 리듬
 ## Final check
 First, read every rewritten sentence aloud and ask: **would a Korean-speaking developer say this to a
@@ -0,0 +1,310 @@
 <!-- 출처: https://techblog.woowahan.com/13569/ · 우아한형제들 기술블로그 · 참고용 원문 사본 -->
 # 누구나 할 수 있는 10배 더 빠른 배치 만들기
 ## 비운영 시간 데이터
 셀러시스템에서는 가게와 업주에 대한 다양한 데이터를 관리합니다.
 배달의민족에 입점한 사장님들이 가게의 요일별 휴무일, 임시 휴무일, 공휴일 휴무 여부, 임시 운영 중지 등 다양한 휴무 설정할 수 있는데요.
 실제 가게가 노출되고 음식을 주문하는 과정에서는 '가게가 운영하는지 안하는지'만 중요하기 때문에
 셀러시스템팀에서는 이러한 정보를 조합하여 계산된 결과만을 유관부서에 전달하기도 합니다.
 이것이 바로 '비운영시간 데이터'입니다.
 셀러시스템은 다양한 채널에서 입력되는 각종 운영과 휴무 데이터를 취합하고 비운영시간 데이터를 계산합니다.
 그 후 이러한 데이터가 클라이언트까지 잘 전달될 수 있도록 각 지면에 적절한 형태로 가공하여 제공하는 역할을 합니다.
 현재 연동 구조에서는 실시간으로 수정되는 정보를 반영하는 것뿐만 아니라
 매일 새벽에 전체 데이터를 계산하고 그 결과를 미리 갱신해둔 후 유관부서에 전파하는 작업 또한 하고 있습니다.
 ## 문제 상황
 새벽에 배치 작업을 할 때, 배달의민족에 등록된 수많은 가게의 데이터를 매일 갱신하기 때문에 배치 수행 시간이 상당히 오래 걸립니다.
 이른 새벽에 배치가 실행되는 덕분에 일과 시간 이전에 배치가 모두 끝나고 DB 부하도 큰 수준은 아니어서 여태까지는 큰 문제없이 운영되고 있었습니다.
 하지만 최근 배포를 새벽에 진행할 일이 여러 번 있었는데요.
 배포를 할 때마다 배포 예정 시간과 배치 실행 시간이 겹치는 바람에, 배치가 없었다면 매끄럽게 진행될 배포가 여러 번 복잡한 절차를 밟아 진행할 필요가 생겼습니다.
 팀에서는 이렇듯 새벽 시간까지 오래 실행되는 배치가 배포 및 운영에 영향을 끼치는 것은 잠재적인 리스크라고 판단하였습니다.
 셀러시스템팀에서는 이러한 리스크가 발견되었을 때 당장 조치가 필요한 것이 아니라면 우선 백로그(개발을 기다리는 과제 목록)에 등록합니다.
 배치 성능 개선 과제 또한 우선 백로그에 등록하였고 이후 정기적인 백로그 그루밍(백로그 항목을 살펴보고 유지 관리하는 프로세스) 회의에서 우선순위를 재평가하고, 팀원 사이에서 의견을 취합하였습니다.
 그루밍 회의에서 배치 성능 개선이 필요하다는 것에 공감대가 있었고 우선순위를 높여 스프린트에서 과제를 진행하게 되었습니다.
 ## I/O 최적화
 배치 수행시간 개선을 위해 우선적으로 살펴본 부분은 I/O 병목이었습니다.
 > ##### I/O (Input / Output) 병목이란?
 >
 > 컴퓨팅에서 부하를 설명할 때에는 크게 CPU 부하와 I/O 부하로 나뉩니다.
 >
 > 데이터를 계산하고 처리하는 과정인 CPU 부하와 달리, I/O 부하는 디스크에 파일을 읽고 쓰거나 DB 및 외부 컴포넌트와 통신하는 과정에서 발생합니다.
 >
 > I/O 병목은 이러한 I/O 부하가 시스템의 전체적인 효율성을 떨어뜨리는 부분을 말합니다.
 배치에서 사용하는 I/O 부하 중 가장 핵심은 DB 쿼리였기 때문에
 코드 및 로컬 환경에서 실제 호출하는 DB 쿼리를 살펴보면서 I/O 병목 지점을 살펴보았는데요.
 JPA 지연 로딩으로 설정된 연관 관계 엔티티를 가져오는 과정에서 N+1 문제가 발생하는 것을 확인하였습니다.
 위에서 언급하였듯 비운영시간 데이터 계산을 위해서는 다양한 종류의 데이터를 가져와야 하는데요.
 이러한 데이터가 모두 1 : N 구조의 연관관계로 설정되어 있어서 관련 데이터를 가져오는 데에 오랜 시간이 걸리는 것을 확인할 수 있었습니다.
 N+1 문제의 해결방식은 다양한데요.
 연관관계로 설정된 엔티티의 종류가 많고 실제 연관관계 데이터의 수정은 불필요하다는 점 등을 고려하여
 각 엔티티 정보를 연관관계를 통해 가져오는 것이 아닌 별도 쿼리 호출을 통해 명시적으로 한 번에 읽어오게끔 수정했습니다.
 ##### 수정 전
 ```java
 public List<LiveShopClose> generateLiveShopClose(Shop shop, LocalDate startDate, LocalDate endDate) {
    final List<ShopCalendar> shopCalendars = shopCalendarRepository.findAllByCalendarDateBetween(startDate, endDate);
    final List<ShopTemporaryClosed> shopTemporaryCloses = shop.getActiveShopTemporaryClosed();
    final List<ShopClosed> shopCloses = shop.getActiveShopClosed();
    final List<ShopOperationHour> operationHours = shop.getShopOperationHourIsType(OperationHourType.OPERATION);
    return /* LiveShopClose 데이터 생성 */
 }
 ```
 ##### 수정 후
 ```java
 List<LiveShopClose> generateLiveShopCloses(List<Long> shopNos, LocalDate startDate, LocalDate endDate) {
    List<ShopNo> shopNoEntities = shopNos.stream().map(ShopNo::new).collect(Collectors.toList());
    List<ShopCalendar> shopCalendars = shopCalendarRepository.findAllByCalendarDateBetween(startDate, endDate);
    Map<Long, List<ShopTemporaryClosed>> activeShopTemporaryClosedMap =
            shopTemporaryClosedRepository.findActiveByShopNos(shopNoEntities).stream()
                    .collect(groupingBy(ShopTemporaryClosed::getShopNo, Collectors.toList()));
    Map<Long, List<ShopClosed>> activeShopClosedMap =
            shopClosedRepository.findActiveByShopNos(shopNoEntities).stream()
                    .collect(groupingBy(ShopClosed::getShopNo, Collectors.toList()));
    Map<Long, List<ShopOperationHour>> operationHoursMap =
            shopOperationHoursRepository.findOperationHoursByShopNos(shopNoEntities).stream()
                    .collect(groupingBy(ShopOperationHour::getShopNo, Collectors.toList()));
    return shopNos.stream()
            .flatMap(shopNo -> generateLiveShopClose(
                    shopNo,
                    shopCalendars,
                    ListUtils.emptyIfNull(activeShopTemporaryClosedMap.get(shopNo)),
                    ListUtils.emptyIfNull(activeShopClosedMap.get(shopNo)),
                    ListUtils.emptyIfNull(operationHoursMap.get(shopNo))
            ).stream())
            .collect(Collectors.toList());
 }
 List<LiveShopClose> generateLiveShopClose(Long shopNo, List<ShopCalendar> shopCalendars,
                                          List<ShopTemporaryClosed> activeShopTemporaryCloses,
                                          List<ShopClosed> activeShopCloses,
                                          List<ShopOperationHour> operationHours) {
    return /* LiveShopClose 데이터 생성 */
 }
 ```
 ## 도메인 로직 및 기타 최적화
 그 다음으로는 도메인 로직을 고려해 더 최적화할 수 있는 부분이 있을지 살펴보았습니다.
 현재 가게의 비운영시간 데이터가 업데이트될 경우, 변경된 가게에 대한 이벤트를 발행하고 있는데요.
 기존 로직에서는 실제 데이터의 변경 여부와는 관계없이 D-1~D+2 데이터를 무조건 재생성하기 때문에,
 실제로는 데이터가 변경되지 않을 테지만 다시 데이터가 생성되어 변경 이벤트가 전송되는 케이스가 있었습니다.
 이러한 케이스에 대응하여 데이터가 바뀌었는지 여부를 확인한 후 실제로 바뀐 경우에만 변경 사항을 적용하도록 개선하였습니다.
 이를 통해 불필요한 DB 부하를 줄여 배치 수행시간을 줄일 수 있을 뿐만 아니라 변경 이벤트로 인한 간접적인 부하 또한 개선할 수 있었습니다.
 ## 최적화 검토
 잠시 다른 얘기를 해보겠습니다.
 유명한 개발 서적인 "Effective Java"(3rd ed, Joshua Bloch, 2017)에서는 아래와 같은 격언을 소개하고 있습니다.
 > "성능 효율을 높이기 위해 컴퓨팅 업계에서는 많은 죄악이 저질러지는데(심지어 효율적이지조차 않을 때도 있다)"
 >
 > William A. Wulf (1972)
 > "우리는 세세한 성능 효율에 대해서는 무시할 필요가 있다. 말하자면 97%가 이 경우에 해당한다. 섣부른 최적화는 만악의 근원이다."
 >
 > Donald E. Knuth (1974)
 > "우리는 최적화에 대해서 다음 두가지 규칙을 따른다. 첫째. 하지 마라. 둘째. (전문가 한정) 아직은 하지 마라."
 >
 > M. A. Jackson (1975)
 Java(1995년)는 물론이고 SQL(1978년)과 C++(1980년)이 등장하기도 전에 프로그래밍 대선배들은 위와 같은 발언들을 쏟아냈습니다.
 최적화 얘기를 한참 하다가 최적화가 죄악이란 격언을 가져오다니 뜬금이 없으실 텐데요.
 사실 이는 무작정 최적화하지 말란 것은 아니고 효율만 좇다가 득보다 실이 큰 경우를 경계하라는 뜻에 가깝다고 생각합니다.
 최적화를 하기 전에 항상 아래 두가지를 검토해보면 좋을 것 같습니다.
 > ##### 최적화 이전에 먼저 좋은 코드를 작성하기
 >
 > 코드를 작성하는 데 있어서 성능을 염두에 두는 것은 물론 중요합니다.
 >
 > 하지만 많은 경우 대부분의 코드는 성능상 영향이 크지 않고 실제로 병목이 되는 부분은 극히 일부분입니다.
 >
 > 좋은 코드를 최적화하기는 쉽지만, 섣부르게 최적화된 코드를 좋은 코드로 만드는 건 어렵습니다.
 >
 > 빠른 코드보다는 좋은 코드를 짜는 데에 먼저 집중하고 최적화는 그 다음에 생각해야 합니다.
 >
 > ##### 정량적으로 성능을 측정하면서 병목을 파악하기
 >
 > 정량화된 지표를 통해 실제로 병목이 되는 부분을 파악해야 합니다.
 >
 > 지엽적인 부분을 일일히 개선하는 마이크로 최적화는 많은 경우 100ms 를 99ms로 줄이는 것에 그칩니다.
 >
 > 마이크로 최적화 보다는 거시적인 관점에서 중요한 병목을 찾고 이를 구조적으로 해결하는 것이 중요합니다.
 >
 > 그리고 실질적으로 얼마나 빨라졌는지 정량적인 성과로 나타낼 수 있어야 합니다.
 이번에 진행한 최적화는 유의미한 최적화였을까요?
 우선 기존에 안정적으로 동작하며 비즈니스 로직이 명확한 코드가 있었습니다.
 하지만 이러한 안정적인 코드의 수행시간이 오래 걸려 운영 및 유지보수에 있어서 잠재적인 큰 리스크라는 공감대가 있었습니다.
 최적화를 위해 구조적인 병목을 찾았고 성능 테스트 결과 5배 이상 더 빨리 실행되는 것을 확인하였습니다.
 > 베타 환경 테스트 결과, 특정 조건에서는 20배 이상 빨라지기도 하였습니다.
 이 정도의 성능 개선이라면 최초 문제가 되었던 상황을 깔끔하게 해결함과 동시에
 다소 복잡해진 코드를 고려해도 유의미한 최적화라는 결론을 내렸습니다.
 ## 빨라도 문제
 근데 이거 빨라도 너무 빨라진 것 같습니다.
 개발 환경에서의 지표를 통해 운영 환경 소요시간을 유추해 보면 6시간 걸리던 것이 1시간 조금 넘게 걸리는 것으로 나오는데요.
 '내가 뭘 놓친 게 있나?' 아니면 '코드를 잘못 짰나?' 생각이 들었지만…
 설령 정상 동작하더라도 무작정 빠른 게 능사가 아니기 때문에 안정적인 서비스 제공이 가능한지 다시 검토해보았습니다.
 MSA 구조에서는 애플리케이션과 직접적으로 연동되는 DB와 로드밸런서 등 뿐만 아니라
 많은 모듈 및 유관부서들이 유기적으로 연결되어 있기 때문에 영향 범위를 면밀히 검토해야 합니다.
 특히 위에서 한 번 간단하게 언급한 것처럼 현재는 다음과 같은 형태이기 때문에 이 부분에 문제가 없을지 주로 검토했습니다.
 *   데이터 변경이 발생하면
 *   변경 사항이 큐를 통해서 유관부서에 전달되고
 *   필요에 따라 유관부서가 추가적인 API 호출을 하는
 구체적으로는 아래와 같은 사항들을 확인해보았습니다.
 *   개발 환경에서 테스트 당시 애플리케이션이 실행되는 서버의 CPU 및 I/O 지표
 *   개발 환경에서 테스트 당시 DB CPU, 쿼리 지연 시간 등 지표
 *   예상 트래픽을 산출, 현재 운영 환경에서의 피크 트래픽과 비교하여 문제가 없을지 검토
 *   변경 사항을 전달하는 큐에서 지연이 발생해도 문제가 없을지 검토
 예상 트래픽 비교 및 도메인 로직 최적화 과정에서 변경이벤트 또한 상당히 많이 줄어든 점을 감안하여서
 문제가 없을 것으로 확인하고 운영 환경에 배포하였습니다.
 ## 배포 이후
 문제가 없을 것으로 예상하였지만 일들이 항상 마음처럼 굴러가던가요?
 운영환경에서 추정했던 속도보다 더 빠르게 동작을 하는 바람에
 유관 부서 트래픽 또한 예상 이상으로 인입되어 DB CPU가 다소 높아지는 문제가 있었습니다.
 그렇지만 너무 빨라서 발생하는 문제에 대해서 사전에 미리 검토를 해보았던 덕분에
 당황하지 않고 빠르게 문제 원인을 좁히고 대응 방안을 도출할 수 있었습니다.
 근본적으로는 실행 속도가 너무 빨라진 것이 문제이기 때문에
 모순적이지만 우선 단기적인 대응 방안으로 의도적으로 지연 시간을 설정해 천천히 실행하도록 수정하였습니다.
 ```java
@Bean(STEP_NAME)
@JobScope
 public Step liveShopCloseCreateStep() {
    return stepBuilderFactory.get(STEP_NAME)
            .<Long, Long>chunk(CHUNK_SIZE)
            .reader(shopCloseScheduleReader(null))
            .writer(liveShopCloseWriter(null, null, null))
            .transactionManager(storeTransactionManager)
            .listener(new AfterChunkSleepListener(200))
            .build();
 }
@Slf4j
 public class AfterChunkSleepListener implements ChunkListener {
    private final long sleepMillis;
    public AfterChunkSleepListener(long sleepMillis) {
        this.sleepMillis = sleepMillis;
    }
    @Override
    public void afterChunk(ChunkContext context) {
        try {
            log.info("Chunk 실행 후 sleep {} millis. 현재 read Count : {}",
                    sleepMillis,
                    context.getStepContext().getStepExecution().getReadCount());
            TimeUnit.MILLISECONDS.sleep(sleepMillis);
        } catch (InterruptedException e) {
            log.error("Thread sleep interrupted.", e);
        }
    }
    @Override
    public void afterChunkError(ChunkContext context) {
        // 사용안함.
    }
    @Override
    public void beforeChunk(ChunkContext context) {
        // 사용안함.
    }
 }
 ```
 그리고 위와 같이 지연 시간을 설정해도 **기존 390분이 소요되던 배치가 30분 소요되는 결과**를 얻을 수 있었습니다.
 마지막으로 이러한 변경이벤트를 유관부서에 전달하고 유관부서가 다시 우리 API를 호출하는 방식에 대해서
 좀 더 효율적인 해결책은 없을지 고민하게 되는 계기가 되었습니다.
 ## 결론
 이번 최적화 작업을 요약하면 다음과 같습니다.
 *   리스크를 확인하고 과제에 대한 우선순위를 조정하기
 *   문제 상황을 분석하고 병목을 확인하기
 *   I/O의 경우 최대한 한번에 여러건을 읽고 쓰도록 하여 효율성 높이기
 *   도메인 로직을 검토하여 개선할 수 있는 부분이 있는지 살피기
 *   유의미한 최적화인가? 정량적인 지표로 다시 검토하기
 *   빨라도 문제일 수 있으니 최적화에 의한 영향 범위를 검토하고 운영 환경에서도 문제가 없을지 확인하기
 대단한 알고리즘을 작성하지도, 유행하는 신규 프레임워크를 사용한 것도 아니지만
 생각보다 좋은 결과를 얻었고 그 과정도 좋은 사례라고 생각되어 공유드립니다.
 당연하게 생각되는 부분이라도 돌다리를 한 번 더 두드려보듯이
 항상 한 번 더 고민해 본다면 누구라도 저보다 더 잘하실 수 있으리라고 생각합니다.
@@ -0,0 +1,167 @@
 <!-- 출처: https://techblog.woowahan.com/17386/ · 우아한형제들 기술블로그 · 참고용 원문 사본 -->
 # 우리 팀은 카프카를 어떻게 사용하고 있을까
 ## 누가 읽으면 좋을까
 카프카(Kafka)가 무엇인지 알고 있는 독자를 대상으로 합니다. 기술적 구현방식을 다루기보단 카프카를 기반으로 한 다양한 기술적 개념에 대해서 얇고 넓게 소개하고, 우리팀에서 어떻게 적용하는지 사례를 공유합니다. 기술적 내용에 대해 자세히 알고 싶다면 공식문서나 다른 기술블로그를 참고해 주세요. 글 하단 "참고 자료"에 관련 링크도 첨부하였습니다.
 아래와 같은 키워드가 등장합니다. 각 문단에서 개념을 간단하게 설명하며 진행할 예정이나 관련 배경지식이 있다면 더 쉽게 이해할 수 있을 것으로 예상됩니다.
 * Kafka
 * Transactional Outbox Pattern
 * Event Bus
 * Kafka Streams
 ## 카프카, 한 섹션 요약
 먼저 카프카를 매우 간단하게 알아보겠습니다. 카프카는 분산 스트리밍 플랫폼으로, 대량의 데이터를 처리하고 실시간으로 전송하는 데 사용됩니다. 모든 데이터는 로그 형식으로 파일 시스템에 기록됩니다. 여기서 말하는 로그는 추가만 가능하며, 시간순으로 완전히 정렬된 데이터의 흐름(레코드 시퀀스)을 의미합니다. 로그를 한곳에 모아 처리할 수 있도록 중앙집중화되어 있으며, 대용량 데이터를 수집하고 실시간 스트리밍으로 소비가 가능합니다.
 메시지(레코드)는 발행처(프로듀서)가 보낸 순서로 기록되어 순서가 보장되며, 메시지의 위치 값(offset)으로 소비자(컨슈머)가 소비한 메시지의 위치를 표시합니다. 각 컨슈머 그룹마다 메시지의 위치 값을 가지고 있기 때문에 같은 소스에서 서로 다른 여러 개의 컨슈머 그룹이 개별적으로 소비가 가능합니다. 한 소스(Single Origin)에서 여러 소비자가 손실이나 변형 없이 메시지를 소비할 수 있으며, 원천 데이터를 기반으로 데이터 분석도 가능합니다.
 아래는 이 글을 이해하는 데 필요한 카프카의 기본적인 용어와 개념입니다.
 * **토픽(Topic)**: 데이터의 주제를 나타내며, 이름으로 분리된 로그입니다. 메시지를 보낼 때는 특정 토픽을 지정합니다.
 * **파티션(Partition)**: 토픽은 하나 이상의 파티션으로 나누어질 수 있으며, 각 파티션은 순서가 있는 연속된 메시지의 로그입니다. 파티션은 병렬 처리를 지원하고, 데이터의 분산 및 복제를 관리합니다.
 * **레코드(Record)**: 레코드는 데이터의 기본 단위로 키와 값(key-value pair) 구성입니다.
 * **오프셋(Offset)**: 특정 파티션 내의 레코드 위치를 식별하는 값입니다.
 * **프로듀서(Producer)**: 데이터를 토픽에 보내는 역할을 하며, 메시지를 생성하고 특정 토픽으로 보냅니다.
 * **컨슈머(Consumer)**: 토픽에서 데이터를 읽는 역할을 하며, 특정 토픽의 메시지를 가져와서(poll) 처리합니다. 컨슈머 그룹은 여러 개의 컨슈머 인스턴스를 그룹화하여 특정 토픽의 파티션을 공유하도록 구성합니다. 이를 통해 데이터를 병렬로 처리하고 처리량을 증가시킬 수 있습니다.
 * **카프카 커넥터(Connector)**: 카프카와 외부 시스템을 연동 시 쉽게 연동 가능하도록 하는 프레임워크로 MySQL, S3 등 다양한 프로토콜과 연동을 지원합니다.
  * **소스커넥터(source connector)**: 메시지 발행과 관련 있는 커넥터
  * **싱크커넥터(sink connector)**: 메시지 소비와 관련 있는 커넥터
 ## 우리팀에서 활용하는 방식
 딜리버리서비스팀은 하루 100만 건 이상 생성되는 배민배달(배달의 민족에서 관리하는 자체 배달)을 중계하는 역할을 합니다. 배달의 민족에서 제공하는 여러 주문서비스(배민배달, B마트, 배민스토어)의 배민배달을 받아 여러 배달서비스 중 하나로 분배하고, 배달과정을 중계하고 관리하는 역할을 합니다. 주문과 배달을 처리하는 방식으로 분산시스템 이벤트 기반 아키텍처를 사용하고 있으며, 카프카를 팀에서 주요 기술 중 하나로 사용하고 있습니다. 팀의 분산시스템이 어떻게 나뉘어 있는지 간략하게 설명하고, 카프카를 팀에서 활용하는 방식을 소개하겠습니다.
 딜리버리서비스팀의 분산서버 구조에 대해 간략하게 설명하면 아래 그림과 같습니다.
 주문이벤트를 받아 배달 프로세스를 관리하는 주문/배달서버, 발행한 이벤트를 기반으로 분석하는 분석서버로 구성되어 있습니다. 처리량을 높이고 성능을 향상시키기 위해 많은 서비스에서 그러하듯 각 서버그룹은 N개의 여러 서버로 구성됩니다.
 ## [1] 주문-배달을 안전하게 처리하자
 ### 미리보기
 – 도메인 이벤트에 대해 카프카를 이벤트 브로커로 사용하여 이벤트 순서를 보장한다.
 – MySQL source connector를 이용한 Transactional Outbox Pattern을 사용하여 분산시스템에서 데이터와 메시지 전송을 하나의 트랜잭션으로 관리하여 데이터 정합성을 확보한다.
 주문이 발생하면 고객에게 배달이 완료될 때까지 안전하게 처리하는 것이 가장 큰 목표입니다. 그 과정을 혼란스럽지 않게 처리하기 위해서는 주문과 배달의 이벤트 순서가 중요하며, 이벤트가 누락되지 않도록 관리해야 합니다. 카프카를 이벤트 브로커로 사용하고, 이벤트 발생 순서를 보장하고 있습니다. 배달을 놓치지 않고 처리하기 위해서 Transactional Outbox Pattern을 사용하여 순서를 보장한 재시도를 통해 이벤트 누락이 없도록 처리하고 있습니다.
 ### 순서보장
 배달프로세스를 간략하게 나타내면 아래 그림과 같습니다. 배달이 진행되면서 여러 이벤트가 발행되고, 몇 가지 이벤트는 배달상태를 변경시킵니다. 배달상태는 순서가 있기 때문에 순서대로 진행되며, 특정 이벤트들은 거의 동시에 발생하기도 하고, 배달상태를 변경시기키도 합니다. 혼란스럽지 않은 배달프로세스를 관리하기 위해서는 이벤트 발행과 관련하여 순서를 보장하는 것이 중요합니다.
 예를 들어, 배차완료와 거의 동시에 픽업준비요청이 발생할 수 있습니다. 프로듀서는 배차완료 이후 픽업준비요청을 발행하였으나 네트워크 등의 이슈로 컨슈머는 픽업준비요청 이후, 배차완료를 수신할 수도 있습니다. 이런 경우, 순서가 보장되지 않는다면 컨슈머 측에서는 거의 동시에 발생한 이벤트에 대해서 어떤 이벤트가 먼저 발생한 것인지 혼란스러워 비즈니스 로직 처리에 문제가 발생할 수 있습니다.
 카프카는 메시지 발행 순서에 따라 소비할 수 있도록 순서를 보장합니다. 같은 카프카 클러스터에서 주문, 배달, 분석 토픽 등 목적에 따라 토픽을 구성할 수 있으며, 하나의 토픽은 병렬처리로 처리량을 높이기 위해 여러 개의 파티션으로 구성됩니다. 카프카에서는 같은 파티션에 대해서 프로듀서가 보낸 데이터의 순서를 보장합니다. 같은 키를 가진다면 같은 파티션으로 할당되고, 하나의 파티션에 하나의 컨슈머가 할당됩니다. 따라서 같은 키에 대해서는 분산시스템에서도 같은 서버가 소비하게 되어 이벤트 순서가 보장될 수 있습니다. 주문식별자, 배달식별자 등과 같이 순서관리가 필요한 식별자를 키로 관리하여 순서를 보장합니다. 메시지 공급자가 발행 순서를 보장하기에 거의 비슷한 시점에 발행되는 메시지 동시성 이슈 발생 상황을 줄일 수 있습니다.
 ### 데이터 정합성
 비즈니스 로직을 처리하기 위한 데이터를 MySQL 데이터베이스에 저장하고, 카프카로 이벤트를 발행하는 방식으로 데이터와 이벤트를 관리하고 있습니다. 카프카에 문제가 발생할 경우, 데이터베이스에는 변경된 배달상태가 저장되었으나 이벤트는 발행되지 않을 수도 있습니다. 예를 들어 주문취소가 발생한 경우를 생각해 봅시다. 주문취소로 배달취소가 발생하게 되면 데이터베이스에는 해당 배달은 취소된 상태로 저장될 것입니다. 하지만 이벤트 발행에 실패하게 된다면 컨슈머는 메시지를 수신하지 못해 여전히 배달을 진행할 수 있습니다. 취소된 배달이 진행되는 문제가 발생할 수 있습니다. 데이터와 메시지 발행의 트랜잭션을 하나로 관리하여 데이터 정합성을 확보할 필요가 있었습니다.
 인프라와 커넥션 이슈, 타임아웃 등의 문제로 토픽에 메시지를 넣는 과정에서 실패할 수도 있습니다. 메시지 발행에 실패하는 경우, 메시지가 누락되어 정합성이 보장되지 않기에 누락 방지를 위해서 재시도가 필요했습니다. 재시도 과정에서도 메시지의 순서는 보장되기를 바랐습니다. 하지만, 다른 비즈니스 이벤트 처리에 미치는 영향은 최소화하며 재시도를 하고 싶었습니다. 이벤트 발행에 실패하는 경우, 순서와 영향도를 고려하여 재시도를 시도하는 방법으로 [Transactional Outbox Pattern](https://microservices.io/patterns/data/transactional-outbox.html)을 이용하였습니다.
 Transactional Outbox Pattern은 분산 시스템에서 데이터베이스 트랜잭션과 메시지 큐를 조합하여 데이터 일관성과 메시지 전송의 원자성을 보장하는 패턴입니다. 분산시스템에서 트랜잭션 완료 후, 이벤트를 보내야 하는 경우에 트랜잭션에 실패할 경우 데이터는 롤백되지만, 이벤트는 발송될 수 있고, 메시지 전송 중 문제가 발생하는 경우 메시지 전송 원자성이 보장되지 않을 수 있습니다. 문제를 해결하기 위한 이 패턴의 핵심 아이디어는 다음과 같은 흐름으로 진행됩니다.
 1. 트랜잭션 데이터베이스에 Outbox 테이블을 도입하여, 트랜잭션 완료 시 변경 사항을 기록합니다.
 2. Outbox 테이블에 새로운 레코드가 추가될 때마다 변경 사항을 메시지로 전송합니다.
 설명한 패턴을 구현하기 위해 [Debezium](https://debezium.io/)이라는 라이브러리에서 지원하는 MySQL 카프카 커넥터를 이용하고 있습니다. Debezium은 데이터베이스의 변경 사항을 감지하고 이벤트 스트림으로 변환하는 오픈 소스 라이브러리입니다. 데이터베이스의 기록인 binlog의 변경 사항을 감지(Change Data Capture)하여 읽는 로그 테일링 기법을 사용되어 있습니다. 변경사항을 읽어 설정한 토픽으로 보내주는 방식으로 동작합니다. 트랜잭션의 성공 내역을 binlog 기록하고, 기록을 순서대로 읽어가도록 동작합니다. 메시지 발행에 실패하면 아웃박스테이블의 데이터도 롤백되기 때문에 하나의 트랜잭션으로 데이터 정합성을 관리하고 있습니다. Debezium에서 메시지 발행에 사용되는 MySQL source connector는 태스크를 하나만 사용하도록 강제하기 때문에, 단일 커넥터에서 메시지 전송 순서를 보장할 수 있습니다.
 하나의 태스크로 동작하면 테이블에 데이터가 쌓이는 속도보다 커넥터가 처리하는 속도가 느릴 경우 메시지 지연이 발생할 수 있습니다. 처리량을 높이기 위해 토픽별로 outbox 테이블을 분리하여 만들고, 각 outbox 테이블은 식별자 기반으로 N개의 테이블로 구성하였습니다. delivery-outbox1, delivery-outbox2, delivery-outbox3과 같이 여러 개의 outbox 테이블을 구성하고, 각 테이블에 커넥터를 연결하여 한 커넥터가 처리하는 양을 분산하여 처리량을 확보하였습니다. outbox 테이블은 쓰기(insert)만 동작하는 테이블로 저장된 순서대로 이벤트 메시지 발행을 보장하도록 설정되어 있습니다. 같은 키는 같은 테이블에 저장되며, 한 테이블에서는 하나의 커넥터를 사용하기 때문에 같은 키에 대해서는 순서를 보장됩니다.
 ## [2] 카프카를 이벤트 버스로도 활용해보자
 ### 미리보기
 – 카프카를 이벤트 버스로 활용하여 분산시스템에 알린다.
 분산 시스템에서는 서버 여러 대로 서버군을 이룹니다. 한 서버에서 값을 변경하면 서버군에 속한 모든 서버의 변경된 값을 관리해야 할 때가 있습니다. 배달서버에서 어떤 배달서비스로 분배할지 결정하며, 분배 규칙은 인메모리로 관리합니다. 이 경우, 분배 규칙 이벤트를 소비한 배달서버만 분배규칙이 변경되고 다른 배달서버들은 기존 분배 규칙을 유지할 수 있습니다. 운영자가 필요에 의해 분배 규칙을 변경하면, 모든 배달서버는 해당 변경 값을 알아야 합니다. 카프카를 이벤트버스로 활용하여 값 관리가 필요한 서버군에 변경된 값을 알리고, 변경된 내용을 반영하도록 관리하고 있습니다.
 스프링 클라우드에서 제공하는 RemoteApplicationEvent를 사용하여 [이벤트 버스](https://cloud.spring.io/spring-cloud-bus/reference/html/index.html)로 카프카를 사용하고 있습니다. 이벤트 버스 토픽(예: event-bus)을 설정하고, id는 고유해야 하기에 `${서버명}:${식별자}` 형식으로 설정합니다. RemoteApplicationEvent를 상속한 이벤트를 정의하고, 원하는 목적지(서버군)를 명시하여 발행하면 이벤트 버스는 목적 서버군에 이벤트를 전달합니다. 스프링 클라우드에서 id 서버명의 인스턴스에 애플리케이션 이벤트를 발행하기 때문에, 목적 서버에서 발행한 팀에서 정의한 이벤트를 구독하여 처리한다면, 정의한 이벤트를 수신하여 변경된 값을 반영할 수 있게 됩니다. 이렇게 되면 분산시스템에서 인메모리로 관리되는 값도 변경되어 같은 기준으로 비즈니스 로직을 처리할 수 있습니다.
 RemoteApplicationEvent를 상속한 DeliveryServiceRemoteApplicationEvent를 추상클래스로 설정하고, 각 특성에 맞게 구현체를 구성하여 이벤트를 발행하여 필요한 곳에서 활용하고 있습니다. 서버군에 속한 서버들이 각자 인메모리로 저장하고 있는 값을 모두 초기화나 변경이 필요한 경우에 사용됩니다. 아래는 분배규칙 변경에 대해 RemoteApplicationEvent를 정의한 예시 코드입니다.
 ```java
 public abstract class DeliveryServiceRemoteApplicationEvent extends RemoteApplicationEvent {
    protected DeliveryServiceRemoteApplicationEvent(String destination) {
        super(SOURCE, ORIGIN, DESTINATION_FACTORY.getDestination(destination));
    }
 }
 // 분배규칙 CustomRemoteEvent
 public class RouteRuleRemoteEvent extends DeliveryServiceRemoteApplicationEvent {
    public RouteRuleRemoteEvent() {
        super("delivery"); // destination: 배달서버
    }
 }
 ```
 아래는 분배규칙이 변경되어 새롭게 내려받아야 하는 경우, 서버에서 메서드를 수행하고 배달서버군 전체에도 변경된 규칙이 반영될 수 있도록 RemoteApplicationEvent를 발행하고, 소비하는 예시 코드입니다.
 ```java
 public void load() {
    routeRuleSetStore.load();
    remoteApplicationEventPublisher.publishEvent(new RouteRuleRemoteEvent());
 }
@EventListener
 public void handle(RouteRuleRemoteEvent event) {
    routeRuleSetStore.load();
 }
 ```
 딜리버리서비스팀에서 이벤트 버스 토픽은 하나의 파티션으로 관리하고 있습니다. 설정값을 변경하는 데 높은 처리량이 필요하지 않고, 같은 서버군은 같은 변경사항을 수신해야 하기 때문입니다. 파티션에서 같은 컨슈머 그룹은 오프셋을 공유하므로 모든 서버는 다른 컨슈머 그룹 아이디(consumer group id)를 가져야 합니다. 여러 컨슈머에게 개별적으로 소비될 수 있기 때문에 각 서버가 다른 컨슈머 그룹 아이디를 사용한다면 한 번의 이벤트 발행으로도 여러 서버군의 설정을 바꾸는 것이 가능합니다. 특수하게 컨슈머의 이름을 정하지 않으면, 스프링 클라우드에서는 anomymous라는 프리픽스를 붙여 랜덤하게 컨슈머 그룹 아이디를 설정합니다. 즉, 연결된 서버만큼 `anonymous.{식별자}` 형식의 컨슈머 그룹 아이디가 생성되고 있고, 시스템 모니터링 시에는 anomymous 컨슈머는 필터링하고 있습니다.
 ## [3] 더 나은 배달을 위해 분석하자
 ### 미리보기
 – 분석에 적합하게 가공된 형태로 데이터를 제공한다.
 – 카프카 스트림즈를 활용하여 실시간 배달 정보를 집계하여 배달 상황을 파악할 수 있도록 한다.
 배치 등을 사용하여 분석을 위한 데이터를 제공할 수도 있지만, 일정 주기로 배치를 수행하기 때문에 실시간 데이터를 반영하기 어려운 문제가 있습니다. 우리 팀에서는 실시간 혹은 준실시간에 해당하는 데이터를 조회하여 배달현황을 파악하고 서비스에 반영하기를 원했습니다. 요구사항을 만족시킬 기술로 카프카 스트림즈를 활용하고 있습니다.
 카프카 스트림즈는 카프카에서 실행하는 이벤트별 데이터(레코드) 처리를 수행할 수 있게 하는 라이브러리입니다. 간단히 말하자면, 카프카 스트림즈는 메시지를 활용한 실시간 집계, 분석 시스템으로 실시간 데이터 스트리밍 및 분석 시스템에 적합한 플랫폼으로 폭넓게 활용되는 도구입니다. 카프카 스트림즈 애플리케이션이 처리하는 것은 데이터의 흐름입니다. 전처리 단계와 스트림 연결로 데이터 스트림을 입력받아 필요한 처리를 수행 후, 새로운 스트림을 생성하여 데이터를 처리하고 결과를 산출하는 방식으로 동작합니다.
 ### 분석용으로 가공한 데이터 제공
 분석 서버에서는 배달 이벤트를 수신한 후 전처리 과정을 거쳐, 조회하기 편한 형태로 가공하여 분석 토픽으로 이벤트를 재발행합니다. 원본 이벤트를 가공하여 분석할 수 있도록 또 다른 토픽과 스트림으로 생성합니다. 목적이 다르기에 원본 토픽과 분석용 토픽을 분리하여 사용합니다. 서비스 토픽과 분석용 토픽은 서로 다른 데이터 처리량과 리소스가 필요하기에 토픽과 서버를 분리하여 특성에 맞는 리소스를 사용하고 조정할 수 있도록 구성하였습니다. 주요한 서비스 로직에 사용되는 토픽과 분석에 사용되는 토픽은 문제가 발행하더라도 영향범위를 분리하여 관리할 수 있습니다.
 배달은 생성, 배차, 픽업, 완료 등 순서를 가지고 진행되며, 특정 행위마다 배달이벤트를 발행합니다. 분석이 필요한 경우, 배달의 이벤트를 하나하나 보는 것이 아닌 배달 건별로 정리된 정보를 확인하고 싶은 경우가 많습니다. 주요 정보는 어떻게 되는지, 언제 생성되어 배차, 완료가 되었는지 등 배달 한 건에 주요 정보를 집계해 확인하고자 하는 수요가 있었습니다. 분석하기 편하도록 전처리 과정을 거쳐 한 배달건에 대해 발생한 여러 이벤트를 하나로 모아 완료된 배달 건의 요약된 종합 정보를 제공하고 있습니다. 이때 Redis를 임시저장소로 활용하여 종합데이터를 관리합니다. 원본 배달 토픽에서 배달생성 이벤트를 수신하면 Redis에 주요한 주문과 배달 정보를 저장합니다. 이후, 배달 진행에 따라 발행된 이벤트를 수신하면 각 배달이벤트 시점 등 주요한 정보를 업데이트합니다. 완료된 배달은 Redis에서 삭제하고, 의미 있는 정보로 구성한 새로운 배달통합이벤트를 분석 토픽에 발행하여 배달 건별 종합데이터를 제공합니다.
 S3 싱크 커넥터를 사용하여 분석토픽에 들어간 이벤트는 AWS S3 객체저장소에 보내 영구 저장하고 있습니다. 이벤트 영구 저장소와 비즈니스 로직을 처리하기 위한 저장소를 분리하여, 분석용 서비스와 비즈니스 서비스의 상호 영향을 최소화합니다. S3 객체저장소에 저장된 데이터는 [AWS Athena](https://aws.amazon.com/ko/athena/)를 사용해 비즈니스 서비스 저장소에 부하를 주지 않고 오래된 기록까지 조회할 수 있습니다. 데이터를 분석할 수 있는 도구를 연동하여 사업이나 운영 부서에서 지난 배달 건을 월단위로 분석하기도 하고, 정산에 활용하기도 합니다.
 ### 실시간 데이터 제공
 배차 대기로 남아있는 배달 건이 얼마나 되는지, 현재 배차에 시간이 얼마나 걸리는지, 주문서비스별 유입량은 어떻게 되는지 등 실시간 배달 데이터를 알고 싶었기에 스트림즈 애플리케이션을 활용하여 실시간 배달데이터를 집계하고 있습니다. 실시간 집계된 내용은 그라파나 대시보드로 시각화하여 운영 상황에 대응할 수 있도록 제공하고 있고, 배달인프라 상황을 파악하여 분석하는 데도 사용됩니다.
 각 배달상태에 따른 배달 건수가 얼마나 되는지 실시간 집계하는 한 가지 예시를 들어보겠습니다. 분석용 배달토픽에 들어온 레코드 흐름(Stream)을 기반으로 최신 배달 상태저장소(latest-delivery)를 구축합니다. 상태저장소(statestore)는 키-값 임시저장소입니다. 최신 배달 상태저장소에는 레코드의 시간을 기준값으로 최신 배달을 판단하며, 키를 배달식별자로 하고 값을 배달데이터로 합니다. 최신 배달을 기준으로 배달 상태별 개수를 집계할 수 있습니다. 키는 배달상태, 값은 집계된 배달 상태별 개수로 배달상태별 상태저장소(count-per-status)를 구성합니다. 그 결과로 배달상태별 상태저장소에서 실시간으로 배달상태별로 집계된 결과를 빠르게 조회할 수 있습니다. 배달 상태별 개수를 조회하는 그라파나 게이지를 등록하여 조회한 결과를 대시보드로 시각화하여 나타내고 있습니다. 대시보드를 통해 하나의 배달 상태에 몰려있진 않은 지, 배달진행에 문제가 있는 건 아닐지 대시보드를 보며 추이를 실시간으로 파악할 수 있습니다.
 이외에도 다양하게 집계되는 실시간 현황은 현재 배달상황을 파악하고 대응하는 데 도움이 됩니다. 다양하게 집계되는 데이터를 활용하여 다른 유용한 기능을 제공할 수도 있습니다. 실시간으로 이상 상황으로 감지되는 판단을 자동화하여 알람으로 빠르게 장애인지를 할 수도 있고, 큰 장애로 번지기 전에 주문유입을 최소화하여 장애 범위를 최소화하는 데 활용될 수도 있습니다.
 ## 끗!
 지금까지 카프카의 개념과 특성을 간략하게 설명하고, 팀에서 카프카를 어떻게 활용하고 있는지 소개했습니다. 저는 개발자로 일한 지 갓 2년이 넘었고, 팀에서 사용하는 시스템 설계나 구현을 주도해본 경험은 아직 없습니다. 그래서 각 기술의 자세한 설명은 더 전문가들이 작성한 자료나 공식 문서를 참고하실 수 있게 마지막에 정리해 두었습니다.
 이 글에서는 카프카와 관련된 기술을 상세히 다루기보다는 우리팀에서 카프카를 어떻게 사용하는지 전반적으로 소개하는 데 중점을 두었습니다. 스스로도 더 잘 이해하고 기술을 사용하고 싶었고, 사례를 공유하며 함께 더 알아가고 싶은 마음이었습니다. 이 글의 내용과 연관된 분들이 발표한 우아콘 영상이 있어 마지막 참고 자료 부분에 링크를 넣어두었으니 더 자세한 내용이 궁금하신 분들은 영상도 참고해 주시면 좋겠습니다.
 ### 참고 자료
 #### 책
 * [아파치 카프카 애플리케이션 프로그래밍 with 자바](https://product.kyobobook.co.kr/detail/S000001842177)
 * [Kafka Streams in action](https://product.kyobobook.co.kr/detail/S000001804837)
 #### 링크
 * [이벤트 소싱 패턴](https://learn.microsoft.com/ko-kr/azure/architecture/patterns/event-sourcing)
 * [Pattern: Transactional Outbox](https://microservices.io/patterns/data/transactional-outbox.html)
 * [Pattern: Transaction log tailing](https://microservices.io/patterns/data/transaction-log-tailing.html)
 * [Debezium](https://debezium.io/)
 * [Spring Cloud Bus](https://cloud.spring.io/spring-cloud-bus/reference/html/index.html)
 #### WOOWACON 2023 영상
 * [Kafka를 활용한 이벤트 기반 아키텍처 구축](https://woowacon.com/presentations?presentationId=621)
 * [Kafka Streams를 활용한 이벤트 스트림 처리 삽질기](https://woowacon.com/presentations?presentationId=607)
@@ -0,0 +1,603 @@
 <!-- 출처: https://techblog.woowahan.com/20161/ · 우아한형제들 기술블로그 · 참고용 원문 사본 -->
 # 검색 성능 개선을 위한 Elasticsearch 인덱스 구조와 쿼리 최적화
 2024. 11. 28. 이승효, 김민규, 김범수
 ## 배경
 2023년 12월, 배달의민족 앱 상단 **검색** 기능에 **장보기•쇼핑** 탭이 추가되었습니다. **검색** 창에 검색어를 입력하고 **장보기•쇼핑** 탭을 누르면 비마트와 배민스토어 상품만 검색할 수 있는 기능입니다.
 커머스검색개발파트에서는 Elasticsearch(이하 ES)를 활용해 커머스 검색과 상품 목록 페이지를 제공하는 리스팅 API를 개발하고 운영하고 있으며, ES를 보다 효율적으로 활용하기 위해 다양한 최적화 작업을 진행하고 있습니다.
 비마트와 배민스토어 상품만 검색할 수 있는 서비스를 오픈한 이후, GS25, GS the Fresh, 이마트에브리데이, CU 등 대형 셀러의 지속적인 추가로 색인 문서의 양이 약 3배 증가했습니다. 또한, 검색 API에 다양한 필터와 검색어 매칭 필드가 추가되었고, 리스팅 API를 새롭게 제공하면서 검색 및 리스팅 API 호출 수는 약 1.5배 증가했습니다. 특히 새로운 영역에서도 리스팅 API 호출이 계속 확대되고 있는 상황입니다.
 이처럼 서버가 처리해야 할 기능과 요청량이 급격히 증가하면서 성능 최적화의 중요성이 대두되었습니다. 올해 초부터 커머스 검색 API의 레이턴시 개선을 목표로 다양한 작업을 진행했으며, 특히 ES 인덱스 구조와 쿼리 최적화를 통해 성능을 크게 개선할 수 있었습니다. 이번 글에서는 이러한 성능 개선 과정과 쿼리 최적화에 적용한 주요 방법들을 자세히 공유드리려 합니다.
 ## 성능개선을 돕는 도구
 ### API 응답값 비교 스크립트
 API 서버는 Nginx가 리버스 프록시 역할을 하여 Spring Boot Web Server로 요청을 전달하고 있습니다.
 API 응답값 비교 스크립트는 Nginx의 access log를 기반으로 운영버전 API와 변경버전 API를 호출하여, 응답값의 차이를 검증하는 데 사용됩니다. 이 스크립트는 성능 개선, 대규모 리팩토링, 마이그레이션 작업 등에서 기존 API와 변경된 API의 응답값이 동일한지 확인하기 위해 개발되었습니다.
 여러 차례의 검색 API의 성능개선 과정에서 이 스크립트를 이용하여 변경 코드가 응답값에 영향을 주는지 검증하도록 하여 서비스 장애가 발생하지 않고 안전하게 성능 개선을 진행했습니다.
 #### 참고 자료
 *   [Migrating Critical Traffic At Scale with No Downtime — Part 1](https://netflixtechblog.com/migrating-critical-traffic-at-scale-with-no-downtime-part-1-ba1c7a1c7835)
 *   [Migrating Netflix to GraphQL Safely](https://netflixtechblog.com/migrating-netflix-to-graphql-safely-8e1e4d4f1e72)
 ### 슬로우 쿼리 수집기
 [Nginx의 access.log](https://nginx.org/en/docs/http/ngx_http_log_module.html)에는 요청의 응답 시간(request_time)이 기록됩니다. 검색 API에서는 응답 시간이 0.7초 이상 소요되는 요청을 슬로우 쿼리로 간주하며, 이를 모니터링하여 개선점을 도출했습니다.
 > $request_time
 > request processing time in seconds with a milliseconds resolution; time elapsed between the first bytes were read from the client and the log write after the last bytes were sent to the client
 이제 검색 성능 개선을 위한 5가지 과정들을 공유드리도록 하겠습니다.
 *   카테고리 필터 적용 시 레이턴시 지연현상 개선
 *   포켓몬 키워드로 인한 레이턴시 지연현상 개선
 *   Painless 스크립트를 활용한 정렬 제거
 *   track_scores: true → false 로 변경, 분석되는 term 개수에 따른 쿼리 최적화
 *   analyzer 라이브러리화
 ## 카테고리 필터 적용 시 레이턴시 지연현상
 ### 현상
 대부분의 커머스 검색에서 제공하는 '카테고리 필터링'기능으로, 검색 결과를 특정 카테고리로 좁혀 볼 수 있게 하는 요청에 레이턴시 지연 현상이 발생했습니다.
 특정 카테고리를 필터링하는 경우 검색 API의 요청 파라미터로는 categoryId 값이 들어갑니다. (예. categoryId=1000) 검색 API에서는 ES 상품 인덱스에 아래 쿼리를 포함하여 이 카테고리에 대한 상품만을 필터링합니다.
 ```
 {
  "query": {
    "bool": {
      "filter": [
      ...
        {
          "term": {
            "categoryId": 1000
          }
        }
        ...
      ]
    }
  }
 }
 ```
 겉으로 보기에는 문제가 없어 보이는 쿼리였지만, 카테고리 필터가 있을 때와 없을 때 검색 API의 응답 속도 차이는 매우 큰 편이었습니다.
 카테고리 필터 유무에 따른 API 응답 속도 비교
 *   카테고리 필터가 없는 경우 : 115ms
 *   카테고리 필터가 있는 경우 : 980ms
 ### 문제 원인 분석 및 해결
 원인을 파악해 보니 카테고리ID의 필드 타입 설정에 문제가 있었습니다. 카테고리ID 필드는 숫자이기 때문에 integer로 색인을 하였는데요. 카테고리ID 는 범위 검색을 하는 필드가 아니고 정확하게 일치하는 값을 찾아내는 용도로만 쓰고 있기 때문에 keyword로 타입을 변경하고, term필드로 쿼리가 수행될 수 있도록 변경하였습니다.
 ### 개선 결과
 *   카테고리 필터로 인한 슬로우 쿼리는 더 이상 발생하지 않게 되었습니다. 아래는 개선 전후 달라진 내용입니다.
 | 구분 | 개선 전 | 개선 후 |
 |------|--------|--------|
 | categoryId 필드 타입 | `{"categoryId": {"type": "integer"}}` | `{"categoryId": {"type": "integer", "fields": {"keyword": {"type": "keyword"}}}}` |
 | 쿼리 예시 | `{"term": {"categoryId": 1000}}` | `{"term": {"categoryId.keyword": 1000}}` |
 | API 응답시간 | 980ms | 104ms |
 *   이 문제를 해결하고 나니 특정 키워드에 대한 슬로우 쿼리를 확인할 수 있었습니다.
 ### numeric, keyword 타입 색인/쿼리 비교
 numeric, keyword 타입이 내부적으로 어떻게 색인이 되고 term쿼리를 수행했을 때 어떻게 데이터를 찾아오게 되는지 조금 더 조사해보았습니다.
 #### 색인
 *   numeric (숫자) 타입 : Lucene 내부적으로는 [PointValues](https://lucene.apache.org/core/8_11_1/core/org/apache/lucene/index/PointValues.html)로 색인하게 되는데 이는 KD-Tree 자료구조를 사용하여 저장이 되어있다고 합니다.
 > Points represent numeric values and are indexed differently than ordinary text. Instead of an inverted index, points are indexed with data structures such as [KD-trees](https://en.wikipedia.org/wiki/K-d_tree). These structures are optimized for operations such as _range_, _distance_, _nearest-neighbor_, and _point-in-polygon_ queries.
 *   keyword 타입 : 역인덱스타입으로 저장되어 있습니다. 정확하게 일치하는 값으로만 쿼리가 가능합니다.
 #### 쿼리
 kibana로 아래 쿼리를 프로파일링해 보면, 내부적으로 수행되는 Lucene 쿼리가 다른 것을 확인할 수 있었습니다.
 쿼리를 수행한 인덱스의 문서 수는 4천만 건입니다.
 ```
 {
  "query": {
    "term": {
      "$content.catalogPath0.catalogId": {
        "value": 100001
      }
    }
  }
 }
 ```
 *   integer 타입을 term 쿼리했을 때: [PointRangeQuery](https://lucene.apache.org/core/8_11_1/core/org/apache/lucene/search/PointRangeQuery.html)가 수행됨.
    *   숫자,날짜 등의 범위 검색에 적합한 쿼리라고 할 수 있습니다.
    *   [KD-trees](https://en.wikipedia.org/wiki/K-d_tree)를 기반으로 범위 검색을 수행합니다.
 *   keyword 타입을 term 쿼리했을 때: [TermQuery](https://lucene.apache.org/core/8_11_1/core/org/apache/lucene/search/TermQuery.html)가 수행됨.
    *   말그대로 매칭된 term 이 있는지를 찾는 쿼리입니다. keyword 타입은 역색인으로 저장되어 있기에 바로 접근하여 가져옵니다.
    *   단일 값에 대한 검색은 빠르지만 범위 검색은 불가능합니다.
 ## 포켓몬 키워드로 인한 레이턴시 지연현상
 ### 현상
 카테고리 필터 문제를 해결하고 나니 대부분의 슬로우쿼리를 유발하는 키워드는 "포켓몬" 키워드로 검색하는 경우인 것을 확인할 수 있었습니다.
 ### 문제 원인 분석 및 해결
 ES 쿼리의 성능 문제를 분석한 결과, 특정 카테고리에 속한 키워드 점수를 부스팅하기 위해 사용한 function_score 쿼리에서 원인을 발견했습니다.
 당시 쿼리는 다음과 같은 구조로 작성되어 있었습니다.
 ```
 {
  "from": 0,
  "size": N,
  "query": {
    "bool": {
      "filter": [
         1️⃣ 상품상태와 관련된 매칭 조건, 키워드 매칭 조건 필터링
      ]
      "must": [
        {
          "bool": {
            "must": [
              {
                "function_score": {
                  "query": {
                    "match_all": { }      2️⃣
                  },
                  "functions": [
                    부스팅 조건을 만족할때의 점수부여하는 쿼리들
                  ],
                  "score_mode": "",
                  "boost_mode": ""
                }
              }
            ],
            "should": [
              필드별 매칭 조건에 따른 점수부여
            ]
          }
        }
      ]
    }
  },
  "aggregation": {
    각종 aggregation 쿼리
  }
 }
 ```
 #### 문제점
 *   1️⃣에서 필터링된 결과에 function_score 쿼리가 적용될 것으로 예상했으나, 실제로는 2️⃣ (`"query": { "match_all": {} }`)에 의해 모든 문서에 대해 부스팅 조건을 실행하고 있었습니다.
 *   이로 인해 특정 키워드(예: "포켓몬")가 최상위 카테고리에 속하고 대부분의 문서에 색인된 상황에서, 불필요하게 functions 내의 부스팅 연산을 수행하고 있었습니다.
 #### 해결 방안
 function_score 쿼리의 "filter" 조건에 1️⃣ (기존 bool – filter의 쿼리)를 포함하도록 수정했습니다. 이를 통해 부스팅 조건이 사전에 필터링된 결과에만 적용되도록 변경했으며, 그 결과 쿼리 속도가 크게 개선된 것을 확인했습니다.
 개선 후 쿼리
 ```
 {
  "from": 0,
  "size": N,
  "query": {
    "bool": {
       "filter": [
         1️⃣ 상품상태와 관련된 매칭 조건, 키워드 매칭 조건 필터링
      ],
      "must": [
        {
          "bool": {
            "must": [
              {
                "function_score": {
                  "query": {
                    "bool": {
                      "filter": [
                         1️⃣ 상품상태와 관련된 매칭 조건,  키워드 매칭 조건 필터링
                      ]
                    }
                  },
                  "functions": [
                    부스팅 조건을 만족할때의 점수 부여하는 쿼리들
                  ],
                  "score_mode": "",
                  "boost_mode": ""
                }
              }
            ],
            "should": [
              필드별 매칭 조건에 따른 점수부여
            ],
          }
        }
      ]
  },
  "aggregation": {
    각종 aggregation 쿼리
  }
 }
 ```
 ### 개선 결과
 포켓몬 키워드로 인해 발생한 슬로우쿼리가 모두 사라지게 되었습니다.
 이 작업 이후, function_score 쿼리에서 1️⃣ 블록이 두 군데에 중복으로 filter가 있게 되었는데, 중복 쿼리 및 의미없는 depth가 생긴 쿼리들을 최적화하는 작업을 진행해 쿼리 가독성을 높이도록 했습니다. 이러한 개선 작업으로 쿼리 구조가 더 명확해지고, 쿼리 분석 및 변경 작업이 더욱 효율적으로 이루어질 수 있게 되었습니다.
 ## Painless 스크립트를 활용한 정렬 제거하기
 ### 현상
 배민의 커머스 상품은 대형 셀러(GS25, GS the Fresh, 이마트에브리데이, CU 등)의 입점으로 셀러 * 지점수에 비례하여 상품 수가 증가합니다. 서비스 초기에는 약 1천만 건이었던 상품 수가 현재는 5천만 건을 넘어섰으며, 앞으로도 대형 셀러의 지속적인 입점으로 상품 수는 계속 증가할 전망입니다. 또한, 커머스검색개발파트에서 지원하는 API는 키워드 검색뿐만 아니라 상품 리스팅을 위한 API, 상품 목록 화면의 카테고리별 상품 수를 반환하는 aggregation API 등 다양한 기능을 제공하며, 이에 따라 성능 개선 작업도 꾸준히 진행되고 있습니다.
 키워드 검색 API에서는 여전히 무거운 쿼리로 인해 레이턴시 지연 현상이 발생하고 있었습니다. 위에서 특정 사례를 중심으로 쿼리를 개선하는 작업을 진행했으나, 근본적인 원인을 파악하고 이를 해결하기 위한 추가적인 개선이 필요했습니다.
 ### 문제 원인 분석 및 해결
 원인을 분석한 결과, 검색에서 셀러별로 [aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html)을 수행하고, 이를 그룹화된 형태로 정렬을 하기 위해 [top_hits aggregation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-top-hits-aggregation.html)을 사용하는 과정에서 성능 차이가 발생하는 것을 확인했습니다. 특히, 정렬 과정에서 사용된 [Painless script](https://www.elastic.co/guide/en/elasticsearch/painless/current/painless-sort-context.html)가 근본적인 부하의 원인임을 알게 되었습니다. 이 스크립트는 ES 쿼리로 반환된 `_score` 값을 기반으로 점수를 역산하여 스케일링하고, 입력된 키워드와 매칭되는 점수를 계산하는 작업을 수행했습니다.
 추가로, 스크립트 내에서 계산하던 `keywordMatchingScore`, `ctrScore`, `recommendScore`와 같은 로직을 제거하고, 이를 쿼리 단계에서 처리할 수 있도록 수정하여 성능 개선을 이루었습니다.
 ```
 {
  "_script": {
    "script": {
      "source": """
        _score 역산하여 추출 후 점수 보정 연산한 키워드 매칭 점수
        def keywordMatchingScore = ...
        검색 키워드에 대한 ctrFeature가 반영된 점수
        def ctrScore = ...
        상품의 점수 필드를 위해 여러 값들의 수식을 적용하여 합산한 점수
        def recommendScore = ...
        return keywordMatchingScore + ctrScore + recommendScore;
      """,
      "lang": "painless",
      "params": {
        "keyword": "우유"
      }
    },
    "type": "number",
    "order": "desc"
  }
 },
 ```
 #### keywordMatchingScore
 검색한 키워드에 문서 필드가 매칭되었을때 가중치를 부여하는 부분입니다. 이 점수를 전체 점수를 보정하기 위해서 `_score` 내에서 keywordMatchingScore를 추출해서 값을 역산하게 되었는데요. 아주 간단한 원리를 이용해서 분리했습니다.
 필드 productName, sellerName, shopName에 매칭될 점수가 productName = 10 , sellerName = 20, shopName = 30이라면 **점수보정연산**을 미리 적용한 뒤 쿼리에 적용하여 해결했습니다.
 *   개선 전: (10 + 20 + 30) * 점수보정연산
 *   개선 후: 10 * 점수보정연산 + 20 * 점수보정연산 + 30 * 점수보정연산
 ```
 {
  "bool": {
    "should": [
      {
        "constant_score": {
          "filter": {
            필드 productName에 대한 조건 쿼리
          }
        },
        "boost": 10 * 점수보정연산
      },
      {
        "constant_score": {
          "filter": {
            필드 sellerName에 대한 조건 쿼리
          }
        },
        "boost": 20 * 점수보정연산
      },
      {
        "constant_score": {
          "filter": {
            필드 shopName에 대한 조건 쿼리
          }
        },
        "boost": 30 * 점수보정연산
      }
    ]
  }
 }
 ```
 #### CTR Score
 검색한 키워드가 특정 키워드에 매칭되었을때 가산점을 부여하는 부분입니다. Painless 스크립트를 사용해 반복문으로 질의 키워드와 일치하는 키워드를 찾고 점수를 부여하는 방식으로 구현되었습니다. 의도한 대로 동작하긴 했지만, 반복문 처리로 조회 속도에 부정적인 영향을 미치는 문제가 있었습니다.
 ```
 샘플 데이터
 {
  "ctrFeatures":[
    {
      "ctrKeyword":"배추",
      "ctrScore":0.0127
    },
    {
      "ctrKeyword":"종가집",
      "ctrScore":0.7036
    },
    {
      "ctrKeyword":"김치",
      "ctrScore":0.4284
    }
  ]
 }
 검색한 키워드와 일치하는 키워드에 ctrScore 를 반환하는 함수
 def getCtrScore(def ctrFeatures, def keyword) {
  if (ctrFeatures == null) {
    return 0.0;
  }
  return ctrFeatures.stream()
    .filter(feature -> feature.ctrKeyword.equals(keyword))
    .map(feature -> feature.ctrScore)
    .mapToDouble(Double::doubleValue)
    .max()
    .orElse(0.0);
 }
 ```
 위 문제를 해결하기 위해 Lucene에서 제공하는 Payload 값을 활용하는 방식을 도입했습니다. Payload는 특정 term에 추가로 저장할 수 있는 메타데이터를 의미합니다. ES는 Payload 값을 색인할 수 있도록 [Delimited payload token filter](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-delimited-payload-tokenfilter.html)를 제공합니다.
 > Payloads
 > A payload is user-defined binary data associated with a token position and stored as base64-encoded bytes.
 아래와 같은 형태로 데이터를 색인하면서 Payload 값을 점수로 저장해두고, 검색한 키워드가 매칭될 경우 해당 점수를 부여하도록 구현했습니다. 다만, ES는 기본적으로 검색 시 Payload 값을 활용한 스코어링 기능을 제공하지 않습니다. 이를 해결하기 위해 커스텀 쿼리 플러그인을 구현하여 검색 시 Payload 값을 점수에 반영할 수 있도록 처리했습니다.
 ```
 "ctrScore": "배추|0.0127 종가집|0.7036 김치|0.4284"
 ctrScore 점수 연산 쿼리
 {
  커스텀 쿼리 플러그인으로 정의한 쿼리 이름
  "woowa_payload_score": {
    "query": {
      Lucene의 PayloadScoreQuery는 SpanQuery를 파라미터로 전달받게 되어 있어 span_term 을 사용
      "span_term": {
        "ctrScore": {
          "value": "검색키워드"
        }
     }
   },
   "score_mode": "max",
   "decode_type": "float",
   "include_span_score": false
  }
 }
 ```
 #### Recommend Score
 이 점수는 상품에 대한 정적인 데이터로, 추천팀에서 생성한 다양한 상품 랭킹 피처 값을 기반으로 합니다. 기존 스크립트 코드에서는 여러 필드의 값을 합산하거나 특정 수식을 적용했지만, 이를 색인 시점에 미리 계산하여 저장하도록 변경했습니다. 이후 검색 시에는 **function_score** 쿼리의 `field_value_factor`를 활용해 해당 점수를 반영하도록 구현했습니다.
 쿼리 예시
 ```
 {
  "bool": {
    "should": [
      {
        "function_score": {
          "query": {
            "term": {
              "recommendScore.enable": {
                "value": true
              }
            }
          },
          "functions": [
            {
              "filter": {
                "match_all": {}
              },
              "field_value_factor": {
                "field": "recommendScore 필드",
                "factor": 1,
                "missing": 0
              }
            }
          ],
          "score_mode": "sum",
          "boost_mode": "replace"
        }
      }
    ]
  }
 }
 ```
 여기서도 마찬가지로, function_score 쿼리에 별도의 조건을 지정하지 않으면 match_all 쿼리가 적용됩니다. 이에 따라, 스코어가 있는 문서들만 대상으로 필터링을 수행하도록 설정했습니다.
 이 과정을 통해 Painless 스크립트 쿼리를 제거하였으며, 최종 쿼리는 다음과 같은 형태가 되었습니다.
 ```
 {
  "from": 0,
  "size": N,
  "query": {
    "bool": {
      "must": [
        {
          "bool": {
            "must": [
              {
                "function_score": {
                  "query": {
                    "bool": {
                      "filter": [
                        상품상태와 관련된 매칭 조건, 키워드 매칭 조건 필터링
                      ]
                    }
                  },
                  "functions": [
                    부스팅 조건을 만족할때의 점수부여하는 쿼리들
                  ],
                  "score_mode": "",
                  "boost_mode": ""
                }
              }
            ],
            필드별 매칭 조건에 따른 점수부여
            "should": [
              keywordMatchingScore 점수 연산 쿼리
              {
                "constant_score": {
                  "filter": {
                    필드 A 에 대한 조건 쿼리
                  }
                },
                "boost": 10 * 점수보정연산
              },
              ctrScore 점수 연산 쿼리
              {
                "woowa_payload_score": {
                  "query": {
                    "span_term": {
                      "ctrScore: {
                        "value": "검색키워드"
                      }
                   }
                 },
                 "score_mode": "max",
                 "decode_type": "float",
                 "include_span_score": false
                }
              },
              recommendScore 점수 연산 쿼리
              {
                "function_score": {
                  "query": {
                    "term": {
                      "recommendScore.enable": {
                        "value": true
                      }
                    }
                  },
                  "functions": [
                    {
                      "filter": {
                        "match_all": {}
                      },
                      "field_value_factor": {
                        "field": "recommendScore 필드",
                        "factor": 1,
                        "missing": 0
                      }
                    }
                  ],
                  "score_mode": "sum",
                  "boost_mode": "replace"
                }
              }
            ],
          }
        },
      ],
 (이하 생략)
 ```
 ### 개선 결과
 *   aggregation 수행 속도가 2배 이상 향상되었습니다.
 *   배포 전후 API의 평균 레이턴시 비교한 결과, p99.9와 p99.99의 응답 속도가 20% 개선되었습니다.
 *   API 응답 시간이 0.7초 이상인 슬로우 쿼리 횟수가 절반으로 감소했습니다.
 ## track_scores: true → false 로 변경, 분석되는 term 개수에 따른 쿼리 최적화
 ### 현상
 Painless 정렬 스크립트를 제거한 이후, 레이턴시가 크게 개선된 것을 확인한 뒤 ES 데이터 노드의 스펙을 기존의 절반 수준으로 낮춰보았습니다. 그러나 트래픽이 집중되는 시간대에는 줄어든 코어 개수로 인해 데이터 노드의 CPU 사용률이 85%까지 치솟는 문제가 발생했습니다. 안정성을 확보하기 위해 데이터 노드 스펙을 다시 이전 스펙으로 되돌렸고, 슬로우 쿼리가 완전히 제거되지 않아 추가적인 쿼리 개선 포인트를 찾아내야만 했습니다.
 ### 문제 원인 분석 및 해결
 #### track_scores: true → false 로 변경
 기존 Painless 정렬 스크립트에서는 `_score` 값을 사용하여 스코어를 역산하여 추가적인 점수를 부여하는 형태로 구성되어 있었습니다. Painless 스크립트에서 `_score`를 참조하려면 `track_scores` 값을 `true`로 설정해야만 참조가 가능합니다. 이 track_scores 값은 검색 성능에 아주 큰 영향을 주는 부분이었습니다.
 *   track_scores : ES 검색 쿼리에서 각 문서의 관련성 점수(`_score`)를 계산하고 저장할지 여부를 결정하는 설정
 *   true / false 차이
    *   true: 모든 문서에 대해 점수를 계산하고 저장
    *   false: 점수를 계산할 필요가 있는 경우에만 계산, 상위 N개에 대한 문서를 찾기 위해 ES에서는 효율적인 알고리즘을 사용하여 필요한 문서만을 선별하여 계산함.
 Painless 정렬 스크립트는 이제 더 이상 사용하지 않고 있기에 `track_scores` 값을 `false` 로 변경하였습니다.
 #### 분석되는 term 개수에 따른 쿼리 최적화
 슬로우 쿼리를 계속해서 분석하다보니, 특정 일부 키워드들에 대해서 오래 걸리는 현상이 발견되었습니다. 쿼리를 분석하다보니 성능에 영향을 주는 부분은 키워드의 부스팅 조건을 만족할때 추가점수를 부여하도록 하는 쿼리에서 발생하는 것을 확인했습니다. 부스팅 조건을 확인할 때 입력한 검색어와 매칭되는 필드의 순서 보정을 위하여 [match_phrase](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query-phrase.html)쿼리를 사용하고 있는데요.
 예) `피자치즈` 키워드로 검색시, 피자 / 치즈로 형태소분석되지만 문서에는 피자 – 치즈 순서로 색인되어 있는 문서만 적용되어야 함. 치즈 – 피자에는 적용되면 안 됨
 단일 term일 경우 match_phrase 쿼리가 아니라 match 쿼리로도 요구사항을 만족할 수 있기 때문에 분석된 term에 따라 쿼리를 변경하도록 쿼리를 분기하였습니다. 커머스 검색 API 는 API 호출 흐름상 검색 쿼리를 수행하기 전 검색어에 대해 `_analyze` 를 수행하고 있기에 term 개수를 미리 확인할 수 있었습니다.
 ```
 if (tokens.size() == 1) {
  return QueryBuilders.matchQuery(fieldName, keyword);
 } else {
  return QueryBuilders.matchPhraseQuery(fieldName, keyword)
    .slop(0);
 }
 ```
 ### 개선 결과
 *   검색 API 레이턴시 2배 개선되었고, 연초부터 모니터링하던 응답시간 0.7초 이상 슬로우쿼리가 모두 제거되었습니다.
 *   피크 시간대 기준으로 ES 데이터노드 CPU 사용량이 10% 감소하였습니다.
 ## analyzer 라이브러리화
 ### 현상
 커머스검색 시스템 내에서 검색 API, admin, batch 동작 중 키워드 분석에 대한 형태소 분석 과정이 존재합니다. 이를 ES의 analyze API로 이용하고 있었는데 admin, batch에서는 큰 문제가 발생하진 않지만 검색 API의 경우 아래와 같은 현상이 있었습니다.
 *   검색 API 수행 중 1회 요청에 총 2회의 analyze API 요청이 발생하게 되는데, 이때의 네트워크 통신 비용과 ES 부하가 생기게 됩니다. 또한, 짧은 timeout으로 인한 실패하는 경우도 발생했습니다.
 *   색인이 다량 발생하는 시점에 ES 내부에서 segment merge가 발생할 경우 analyze 요청이 reject되는 상황이 생겼습니다.
 ### 문제 원인 분석 및 해결
 형태소분석기는 ES의 plugin 형태로 적용이 되어있습니다. plugin의 내용을 라이브러리화하고, 이를 사내 nexus에 업로드하여 application(검색 API , admin, batch)에서 분석하도록 코드를 심었습니다. ES 인덱스의 분석기에 적용된 char filter, tokenizer, filter 등 모든 정보를 analyzer 라이브러리에서도 동일하게 적용되도록 하여 `_analyzer` API와 analyzer 라이브러리의 동작이 일치하도록 구현했습니다.
 ### 개선 결과
 *   ES analyze API 호출 없이(네트워크 호출 없이) 내부 라이브러리로 analyze를 할 수 있게 되었습니다.
    *   ES 에서 analyze 요청이 다량 발생했을 때 rejected 현상이 더 이상 발생하지 않도록 개선했습니다.
    *   ES coordinate node (searcher) CPU 사용률이 max 기준 20% → 13%으로 개선되었습니다.
 *   analyze rejected 현상이 사라졌습니다.
 *   analyze timeout 현상 제거 : timeout 발생시 error 로그로 남던 케이스들이 배포 이후 완전히 사라졌습니다.
 ## 개선 후 결과
 위 5가지 작업을 통해 커머스 검색 API의 레이턴시 매트릭이 개선되었습니다. 특히, p99.9와 p99.99 지표가 눈에 띄게 향상되었습니다.
 *   개선 전(2024년 1월)
 *   개선 후(2024년 10월)
 ## 맺으며
 소개한 다섯 가지 API 성능 개선 사례는 Elasticsearch 공식 문서에서 제공하는 기본적인 원칙과 내용을 바탕으로 이루어졌습니다. 단순히 "쿼리는 ES가 알아서 최적화해 주겠지"라는 생각에서 벗어나, 원리를 이해하고 직접 개선한 결과였습니다. 이번 글에서는 검색 쿼리와 관련된 성능 개선 작업에 초점을 맞췄지만, 색인 구조와 관련한 성능 최적화 작업도 병행하고 있습니다.
 커머스검색개발파트에서는 배달의민족 커머스의 성장에 발맞추어 색인량과 검색량의 증가에 따른 다양한 개선 포인트를 찾아내고 해결하는 과정에서 즐거움을 느끼고 있습니다. 앞으로도 커머스에서 더 편리한 검색 경험을 제공하도록 노력하겠습니다.
@@ -0,0 +1,290 @@
 <!-- 출처: https://techblog.woowahan.com/22396/ · 우아한형제들 기술블로그 · 참고용 원문 사본 -->
 # 배차 정확도를 높이는 실거리 시스템 구축하기: OSRM, Kafka, 그리고 Redis
 ## 들어가며
 배민커넥트 배차시스템에서는, 배차에 활용되는 거리를 단순한 직선거리에서 실제 경로 기반의 실거리로 고도화하는 작업을 진행했습니다. 고도화 과정에서 이벤트 드리븐 아키텍처를 도입하고 대량의 트래픽을 효율적으로 처리하기 위해 Redis를 다방면으로 활용했습니다. 이 글은 배차시스템팀에서 얻은 경험과 지식을 정리한 것으로, 유사한 서비스를 개발하시는 분들께 많은 도움이 되는 글이 되었으면 좋겠습니다.
 ## 배차시스템이란?
 ### 배차시스템 소개
 배차시스템은 배달을 고객에게 전달할 수 있도록 적합한 라이더를 찾아 배정하는 시스템입니다. 따라서 주문과 라이더의 상태, 그리고 특성을 잘 고려해 빠르고 효율적으로 배차하는 것이 중요합니다.
 5만 개의 배달이 존재하고 5만 명의 라이더가 활동 중이라고 가정했을 때, 단순히 경우의 수를 계산하면 배차시스템은 25억 건의 계산을 수행해야 합니다. 그러나 현실적으로 매 배차 사이클마다 25억 건을 모두 계산하는 것은 불가능하므로, 이를 최적화하는 과정을 거치게 됩니다. 따라서 배차시스템은 다음과 같은 과정을 통해 배차를 최적화합니다.
 ### 라이더의 상태를 수치화하는 방법
 앞서 소개드린 배차 과정에서는 '비용 계산'이라는 용어가 등장합니다. 배차 최적화 과정은 배달과 라이더의 매칭 문제를 수리 최적화로 해결하기 때문에, 현재 라이더의 상태와 신규 배차를 반영한 상태 변화를 수치적으로 모델링해야 합니다. 배달과 라이더의 특성에는 다양한 속성이 있지만, 그중 가장 중요한 속성은 다음과 같습니다:
 - 라이더의 속도
 - 라이더가 이미 수행 중인 배달들의 거리 및 소요 시간
 - 라이더가 새로 배차받을 배달들의 예상 거리 및 소요 시간
 이 세 가지 속성을 종합해보면, 결국 라이더가 배달을 어떤 순서로, 얼마나 빠르게 수행하는지가 배차에서 매우 중요한 요소가 됩니다.
 다음은 오토바이 라이더와 자전거 라이더가 동일한 경로를 수행하는 예시입니다.
 A와 B 두 개의 배달 건을 위와 같은 순서로 평균 시속 30km로 주행하는 오토바이 라이더가 수행한다면, 주행 시간만 약 4분 36초가 걸립니다. 같은 상황에서 평균 시속 5km인 자전거 라이더가 수행한다면 약 13분 48초가 걸립니다. 그러나 오토바이 라이더가 더 빠르게 배달을 수행할 수 있다고 해서 무조건 오토바이 라이더에게 배차하는 것이 좋은 것은 아닙니다. 배달이 많은 상황에서는 오토바이 라이더와 자전거 라이더를 모두 활용해, 시스템 입장에서 최대한 효율적인 조합을 찾아 배차해야 합니다. 따라서 최적화 알고리즘의 입력으로 활용하기 위해, 라이더가 수행할 것으로 예상되는 배달의 진행 순서를 시퀀스화해 수치화 작업을 진행하게 됩니다.
 이 글의 주제가 되는 `실거리`는, 이러한 수치화 작업의 성능과 정확도를 좌우하는 중요한 요소입니다. 이어서 배차시스템의 경로 문제를 설명하면서, 실거리의 중요성에 대해 자세히 이야기해보겠습니다.
 ## 왜 실거리가 중요할까?
 ### 배차시스템의 경로 문제
 배달 진행 순서의 시퀀스, 다시 말해 라이더가 배달을 수행하기 위한 위치들의 순서를 `경로`라고 부릅니다.
 여기서 '배달을 수행하기 위한 위치'란 배달의 픽업지와 전달지를 의미합니다. 그렇다면, 한 명의 라이더가 배달을 수행하는 과정에서 가능한 경로의 경우의 수는 몇이나 될까요? 배달의 진행 상태와 배달 개수에 따라 가능한 경로는 매우 다양하게 달라집니다.
 경로를 계산하기 위해 그래프를 한 번 그려보면, 꽤 많은 간선이 만들어집니다. 라이더에게 할당된 신규 배달이 N개라고 했을 때, 정점과 간선의 수는 다음과 같습니다.
 - 정점: 픽업지와 전달지를 모두 거쳐야 하므로 2N개
 - 간선: C(2N, 2)개
 이때 그려본 것은 하나의 조합(라이더:매칭=1:1)에 대한 그래프에 불과합니다. 실제 최적화 과정에서는 한 명의 라이더가 수행할 수 있는 여러 배달 조합(라이더:매칭=1:N)에 대해서도 모두 수치화를 해보아야 합니다. 즉, 라이더당 배차 가능한 모든 배달 조합에 대해 경로를 계산하고 수치화하여 최적화 알고리즘에 전달해야 합니다. 그리고 이 수치화를 위해서는 각 간선에 대한 거리값을 반드시 알아야 합니다.
 ### 거리는 예민한 문제이다
 배달 도메인에서 거리는 예민한 문제입니다. 라이더분들은 짧은 시간과 짧은 이동 거리로 최대한 많은 배달을 수행해야 하기 때문입니다. 다만 한 가지 강조할 것은, 배차 경로에서의 거리는 실제 배달료를 책정하는 데 사용되는 수행 거리는 아니라는 점입니다.
 > **참고: 배달료 책정이나 배민커넥트 앱상에서 활용되는 거리 계산에는 상용 내비게이션이 사용됩니다.**
 그럼에도 거리는 중요합니다. 배차 최적화를 하려면, 거리값이 정확하고 일관돼야 합니다. 거리를 기반으로 효율적인 경로를 만들어보고, 그 경로를 기반으로 한 수치들이 최적화에 사용됩니다. 그러므로 단순히 직선거리로 셈하기보다는 가능한 현실 세계에 가까운 거리를 사용할 수 있어야 합니다.
 ### 작은 변화가 배차시스템 전체의 성능을 좌우한다
 두 지점 간의 거리를 계산하는 일은 얼핏 단순해 보일 수 있습니다. 하지만 수많은 경우의 수에 따른 경로를 고려해야 하기 때문에, 작은 변화도 배차시스템 성능에 큰 영향을 미칠 수 있습니다. 마치 나비효과와도 같죠. 배차해야 할 배달이 많아질수록 이러한 영향은 더욱 커집니다. 이처럼 직선거리에서 실거리로의 전환은 단순한 변화가 아니라, 배차 전반의 효율성과 정확도에 영향을 미치는 중요한 변화가 될 수 있습니다.
 지금까지 배차시스템에서 실거리가 왜 중요한지 설명드렸습니다. 배차시스템은 한 번의 배차 과정에서 필요한 모든 간선의 실거리를 계산합니다. 이 실거리는 배차의 정확도를 결정짓는 중요한 요소입니다. 하지만 작은 변화만으로도 시스템 성능이 쉽게 저하될 수 있는 민감한 부분이기도 합니다. 따라서 배차의 정확도와 성능을 모두 고려하기 위해 실거리 시스템을 도입했던 과정을 소개합니다.
 ## 배차시스템에서 실거리를 계산하는 방법
 ### 한 번의 배차에는 몇 번의 실거리 계산이 필요할까?
 배차시스템은 라이더분들에게 배차 요청을 하기 위해 주말 피크 시간 기준 분당 약 15만~20만 건의 경로를 계산합니다. 만약 모든 라이더가 무배차 상태이고, 1건의 배달을 배차한다면 각 경로마다 1건의 배달 위치 간 실거리가 필요합니다.
 - n=1, C(2, 2) = 1
 알뜰배달 서비스가 론칭된 이후부터는 라이더가 1개 이상의 배달을 한 번에 수행할 수 있게 되었습니다. 예를 들어, 라이더가 이미 1건의 배달을 수행 중인 상태에서 시스템이 1건을 추가 배차하는 상황이나, 한 번에 2건을 배차하는 상황이라면 6건의 실거리가 필요하고, 한 번에 3건을 배차하는 상황이라면 15건의 실거리가 필요합니다.
 - n=2, C(4, 2) = 6
 - n=3, C(6, 2) = 15
 물론, 반대 방향의 경우도 고려하면 계산해야 하는 거리는 2배가 됩니다. 실제로 A-B 거리와 B-A 거리는 다르지만, 이 포스팅에서는 동일하다고 가정하고 해당 내용은 다루지 않겠습니다.
 만약 시스템이 모든 라이더를 대상으로 2건의 배달 경로를 계산해야 하고 주말 피크 기준 분당 20만 건의 경로를 계산해야 한다면, 시스템은 분당 120만 건의 실거리 계산을 수행해야 합니다. 이는 초당 약 2만 건으로 시스템 성능의 중요 지표인 TPS(Transaction Per Second) 기준으로도 매우 높은 수준입니다.
 배달들의 위치 사이의 거리를 직선거리가 아닌 실제 거리로 반영하려면 내비게이션이 필요합니다. 실거리 계산이 분당 수백만 건에 이르는 만큼, 이를 뒷받침할 수 있는 내비게이션 시스템이 필요했습니다.
 ### 어떤 내비게이션을 사용할까?
 배달의민족의 딜리버리플랫폼은 여러 기능에서 상용 내비게이션을 활용합니다. 예를 들어, 배달료 계산이나 배달 수행 중 이동 경로 추천 기능 등이 있습니다. 하지만 초당 2만 건에 달하는 경로 계산을 위해 API 호출마다 비용이 발생하는 상용 내비게이션을 사용하는 것은 현실적으로 어렵습니다. 게다가 배차를 추천받은 라이더분이 바로 수락하는 경우, 한 번 계산한 거리를 오랜 시간 재활용하기도 쉽지 않습니다.
 이번 배차 실거리 프로젝트는 배차 정확도와 시스템 성능을 동시에 높이기 위해 기획되었습니다. 단순히 직선거리를 사용하는 대신, 실제 경로를 고려한 실존 거리를 활용하면 기존보다 더욱 현실적인 수행 거리와 시간을 기반으로 배차 최적화를 할 수 있다는 가정에서 시작되었습니다.
 비용 문제를 고려하여 상용 내비게이션 대신, 우리나라 지리 정보가 잘 반영되고 최신화와 업데이트가 빈번하고, 오픈소스 지도 API 중 가장 성능이 좋다고 알려진(Open Source Routing Machine, [Project OSRM](https://project-osrm.org/))을 선택하게 되었습니다. OSRM은 공개된 지도 데이터 정보를 기반으로 경로를 제공하는 엔진입니다. 공통시스템팀에서 여러 지도 서비스를 필요에 따라 제공하기 위해 운영하는 지도 미디에이터 서비스 덕분에, 안전하고 편리하게 API 방식으로 OSRM 실거리를 받아올 수 있었습니다.
 > 앞서 언급했지만 중요한 내용이기에 다시 한번 강조드립니다.
 > **배달료 책정이나 배민커넥트 앱상에서 활용되는 거리 계산에는 상용 내비게이션이 사용됩니다.**
 ### 거리를 저장해서 활용해야만 하는 이유?
 오픈소스 지도를 활용하더라도 여전히 초당 2만 TPS 수준의 부하는 신중히 고민해야 합니다. 현실적인 배차 상황에서는 여러 라이더에게 다양한 배달 조합이 고려되어 경로가 계산됩니다.
 또한, 한 번의 배차로 라이더분이 바로 수락하여 배달이 수행되는 경우가 드물어, 한 번 경로가 계산된 배달도 평균 3~5회 정도 다른 조합으로 재계산되는 경우가 많습니다. 이처럼 매번 거리를 재계산하면 중복된 요청이 다수 발생하고, 중복 요청까지 포함된 초당 2만 건의 TPS를 OSRM 서버가 모두 처리해야 하므로 OSRM 서버에 과도한 부하가 발생하게 됩니다.
 앞서 살펴본 배차 예시에서 활용된 모든 배달 간 실거리를 미리 구하면 효율적인 구조로 표현할 수 있습니다. 실제 배차 환경에서는 가까운 거리의 배달들이 짧은 시간 내에 여러 번 반복되기 때문에, 유사한 조합의 배차가 자연스럽게 여러 차례 발생할 수밖에 없습니다. 그리고 유사한 조합의 배차가 반복된다면, 동일한 거리를 재사용할 가능성이 높아집니다. 따라서 매번 필요한 실거리를 실시간으로 모두 계산하는 데 리소스를 쏟기보다는, 보다 효율적인 방식으로 미리 계산한 거리 데이터를 저장하고 재활용하는 방안을 고민하게 되었습니다.
 이러한 이유로 시스템 아키텍처를 설계할 때, 거리 데이터의 재활용을 적극 고려하여 진행했습니다.
 ## 이벤트 드리븐 아키텍처 기반 실거리 데이터 관리
 ### 배달의 라이프 사이클에 따라 거리를 저장해보자
 배달의민족의 딜리버리플랫폼에서 수행되는 배달의 라이프 사이클은 다음과 같습니다.
 또한 배달의 상태와 직접적으로 연관되지는 않지만, 전달 위치 변경이나 조리 완료 등 배달 수행에 중요한 정보가 변경되는 상황에서도 이벤트가 발행됩니다. 배달 처리 시스템은 이러한 다양한 상태 변경 사항을 Kafka를 통해 이벤트로 발행합니다.
 하지만 거리 계산을 위해 모든 배달 상태 변경 이벤트를 수신할 필요는 없습니다. 따라서 거리 계산에 필요한 배달 생성, 위치 변경, 배달 완료, 배달 취소 이벤트만을 수신하여 도메인 로직을 처리합니다.
 각 이벤트에서 처리해야 할 내용을 간단히 정리하면 다음과 같습니다:
 | 배달이벤트 | 거리 계산 |
 |-----------|---------|
 | 배달 생성 (DeliveryCreated) | • 픽업지 → 전달지 거리 계산<br>• 픽업지 → 지역 내 모든 픽업지, 전달지 거리 계산<br>• 전달지 → 지역 내 모든 픽업지, 전달지 거리 계산 |
 | 픽업지 변경 (PickupLocationChanged) | • 변경된 픽업지 → 전달지 거리 계산<br>• 변경된 픽업지 → 지역 내 모든 픽업지, 전달지 거리 계산 |
 | 전달지 변경 (DeliveryLocationChanged) | • 변경된 전달지 → 픽업지 거리 계산<br>• 전달지 → 지역 내 모든 픽업지, 전달지 거리 계산 |
 | 배달 완료 (DeliveryDelivered) / 배달취소 (DeliveryCanceled) | • 지역 내 동일 위치가 더이상 존재하지 않는 경우<br> • 픽업지 → 지역 내 모든 픽업지, 전달지 거리 제거<br> • 전달지 → 지역 내 모든 픽업지, 전달지 거리 제거 |
 위 표에 정리한 내용을 각 이벤트 프로세서를 나누어 수행하도록 `EventProcessorFactory`를 정의합니다.
 ```java
 public class EventProcessorFactory {
    public EventProcessor create(Event<?> event) {
        switch (event.getEventType()) {
            case DeliveryCreated.EVENT_TYPE:
                return new DeliveryCreatedProcessor(DeliveryCreatedSpec.from(event), ...);
            case PickupLocationChanged.EVENT_TYPE:
                return new PickupLocationChangedProcessor(PickupLocationChangedSpec.from(event), ...);
            case DeliveryLocationChanged.EVENT_TYPE:
                return new DeliveryLocationChangedProcessor(DeliveryLocationChangedSpec.from(event), ...);
            case DeliveryDelivered.EVENT_TYPE:
                return new CompletedDeliveryProcessor(DeliveryStatusChangedSpec.from(event), ...);
            case DeliveryCanceled.EVENT_TYPE:
                return new CanceledDeliveryProcessor(DeliveryStatusChangedSpec.from(event), ...);
            default:
                throw new IllegalArgumentException("...");
        }
    }
 }
 ```
 이벤트는 Kafka를 통해 발행되므로, Kafka 컨슈머가 각 이벤트를 수신하여 처리합니다. 다음은 각 이벤트에 따라 `EventProcessorFactory`를 사용해 적절한 이벤트 프로세서를 반환하고, 로직을 수행하는 예제 코드입니다.
 ```java
 public class EventConsumer {
    private static final List<String> SUPPORTED_EVENT_TYPES = List.of(...);
    @KafkaListener(topics = "...", groupId = "...", containerFactory = ...)
    public void consume(Message<Event<?>> message, Acknowledgment acknowledgment) {
        if (!SUPPORTED_EVENT_TYPES.contains(event.getEventType())) {
            acknowledgment.acknowledge();
            return;
        }
        EventProcessor processor = processorFactory.create(event);
        processor.execute();
        acknowledgment.acknowledge();
    }
 }
 ```
 이와 같이 발행되는 모든 이벤트를 무작정 수신하지 않고, 프로세서가 정의된 이벤트 타입, 즉 컨슈머 도메인의 관심사에 해당하는 이벤트만 처리하도록 명확히 구분할 수 있습니다. 또한, 관심 없는 이벤트는 조기에 리턴하여 처리하지 않음으로써 성능 향상에도 기여할 수 있습니다.
 ### Kafka 스트림 리파티션
 배달 처리 후에는 배달 ID가 키로 구성된 이벤트가 발행됩니다. 만약 배달 이벤트를 실거리 컨슈머가 그대로 받아 처리한다면 어떤 문제가 발생할까요?
 예를 들어, 하나의 지역에서 여러 배달이 동시에 생성된다면, 어떤 이벤트는 처리가 완료되었음에도 결과가 저장되지 못할 수도 있습니다. 즉, 나중에 들어온 배달 이벤트로 트리거된 작업이 직전에 들어온 배달 데이터를 포함하지 못하는 상황이 발생할 수 있는 것입니다.
 Kafka는 기본적으로 각 파티션에 들어오는 이벤트를 오프셋 기반으로 처리하기 때문에, 동일 파티션 내 이벤트는 순차로 처리됩니다. 배달 이벤트를 지역별로 순차 처리하려면, 이벤트 키를 배달 ID가 아닌 배달이 속한 지역 ID로 변경해야 합니다. 이에 따라 이벤트 처리 기준을 변경하는 리파티션 작업을 자체적으로 수행하여, 지역별 배달 이벤트가 순서를 유지하며 처리되도록 재발행했습니다.
 리파티션된 이벤트를 처리하면, 배달 생성, 픽업 완료, 배달 취소와 같은 이벤트들이 순서가 꼬이지 않고 처리됩니다. 이를 통해 배달의 라이프사이클에 맞춰 지역별 거리 계산과 데이터 제거가 정확하게 이루어질 수 있습니다.
 ## 실거리는 어떻게 효율적으로 저장할까
 ### 실거리 저장소에서의 제약 사항
 실거리는 배달의 라이프사이클에 따라 단기간 활용되는 데이터이기 때문에, 빠른 읽기/쓰기가 가능한 인메모리 저장소인 Redis(AWS ElastiCache Redis)를 저장소로 사용하고 있습니다. 거대한 트래픽의 실거리 문제를 해결할 때 큰 제약 사항은 Redis의 저장 용량과 네트워크 대역폭이었습니다. 이를 극복하기 위해 자료 구조와 데이터 형식 등을 다양하게 변경하며 여러 시행착오를 겪었습니다.
 ### 지역별로 실거리 그래프를 관리한다면
 배차시스템에서는 동일한 지역에 속한 배달들끼리 묶어 배차를 수행합니다. 따라서 서로 묶일 수 있는 배달들 간의 실거리만 모아 관리하는 것이 효율적입니다. 예를 들어, 종로구에 있는 가게와 송파구에 있는 가게 간의 거리를 계산할 필요는 없습니다. 그렇다면 아래와 같이, 각 지역별로 실거리 그래프를 저장하는 방법은 어떨까요?
 위 방식은 인터페이스가 간단하고 직관적이라는 장점이 있습니다. 다만, 한 지역 내 모든 실거리를 하나의 데이터로 저장하려면 다음 세 가지 정보를 모두 포함할 수 있는 구조화된 형식이 필요합니다.
 1. 첫 번째 지점의 좌표 (위도, 경도)
 2. 두 번째 지점의 좌표 (위도, 경도)
 3. 두 지점 간의 실거리 값
 위 정보를 하나의 JSON 데이터로 표현해보면 아래와 같습니다. 단순한 인터페이스를 위하여 Redis String에 지역 ID를 key로, 아래 실거리 JSON 데이터를 value로 저장하는 것이 초기의 계획이었습니다.
 ```
 Key: "region:1234567"
 Value:
 {
  "distanceGraph": {
    "37.479482,127.135229-37.511794,127.101274": 5612,
    "37.479482,127.135229-37.496764,127.133687": 2311,
    "37.496764,127.133687-37.511794,127.101274": 3973,
    "37.479482,127.135229-37.480794,127.144663": 1014,
    "37.480794,127.144663-37.490578,127.113274": 3570,
    "37.480794,127.144663-37.511794,127.101274": 6180,
    "37.490578,127.113274-37.511794,127.101274": 3102,
    "37.490578,127.113274-37.496764,127.133687": 2312,
    "37.479482,127.135229-37.490578,127.113274": 2755,
    "37.480794,127.144663-37.496764,127.133687": 2426
  }
 }
 ```
 ### 실거리 그래프의 단점과 네트워크 대역폭의 관계
 다만, 이 구조는 데이터가 커질수록 치명적인 단점이 드러납니다. 특정 실거리 하나만 조회하거나 갱신하더라도, 해당 지역에 저장된 모든 데이터를 한꺼번에 가져와 수정한 뒤 다시 저장해야 하기 때문입니다.
 매번 전체 데이터를 주고받다 보니, 데이터가 클수록 네트워크 대역폭 초과 위험이 커집니다. 네트워크 대역폭이 초과되면 커넥션 장애와 부하가 발생해 시스템 다운으로 이어질 수 있습니다.
 여기서 이야기하는 네트워크 대역폭은, ElastiCache 노드가 네트워크를 통해 초당 전송할 수 있는 최대 데이터 용량을 의미합니다. [AWS ElastiCache 사용자 가이드 문서](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/CacheNodes.SupportedTypes.html)에서 다음과 같이 노드 타입별 네트워크 대역폭 정보를 확인할 수 있습니다. Baseline bandwidth은 항상 보장되는 최소 처리량을, Burst bandwidth은 순간적으로 사용할 수 있는 최대 처리량을 의미합니다.
 | Instance type | Baseline bandwidth (Gbps) | Burst bandwidth (Gbps) |
 |---------------|---------------------------|----------------------|
 | cache.r6g.large | 0.75 | 10.0 |
 | cache.r6g.xlarge | 1.25 | 10.0 |
 | cache.r6g.2xlarge | 2.5 | 10.0 |
 대역폭 사용량은 CloudWatch에서 제공하는 아래 지표로 모니터링이 가능합니다.
 - NetworkBandwidthInAllowanceExceeded
 - NetworkBandwidthOutAllowanceExceeded
 ### 실거리 그래프 관리를 효율화하기 위한 시도 1. 데이터 압축
 실거리 그래프의 비효율 문제를 해결하고자 가장 먼저 데이터 압축을 시도했습니다.
 Spring Data Redis에서는 `RedisSerializer`를 직접 구현하여 원하는 압축 알고리즘을 사용할 수 있습니다. 이를 활용해 `ZstdRedisSerializer`를 주입한 `RedisTemplate`을 생성하면 됩니다. 압축 알고리즘으로는 높은 압축률과 빠른 처리 속도를 제공하는 효율적인 알고리즘인 Zstd(Zstandard)를 사용했습니다.
 ```java
 public static <T> RedisTemplate<String, T> zstdRedisTemplate(RedisConnectionFactory connectionFactory, Class<T> clazz) {
    RedisSerializer<T> serializer = new ZstdRedisSerializer<>(jackson2JsonRedisSerializer(clazz));
    return objectRedisTemplate(connectionFactory, serializer);
 }
 ```
 하나의 지역에 1000개의 서로 다른 좌표 간 모든 실거리를 저장할 경우, JSON 데이터 원본 크기는 약 24MB였으며, 압축한 크기는 3MB였습니다. 만약 최대 대역폭이 10Gbps라고 했을 때, 3MB 크기로는 초당 3400회의 조회도 버티기 어렵습니다. 압축률이 높더라도 원본 데이터가 워낙 커서 압축만으로는 대역폭 문제를 해결할 수 없었습니다.
 또한, 문자열은 숫자에 비해 메모리 사용량이 많아 소수점 생략이나 구분자 축소 등 형식 변경을 시도했으나 효과는 미미했습니다. 데이터 대부분이 숫자임에도 불구하고, 결국 Redis에 String 타입으로 저장되기 때문입니다. 따라서, 실거리 그래프를 하나의 문자열로 표현하는 구조에서는 더 이상의 개선이 어렵다고 판단했습니다.
 ### 실거리 그래프 관리를 효율화하기 위한 시도 2. Redis 자료구조 활용
 데이터 타입이나 압축보다도 자료구조 자체의 변경이 필요했습니다. 지역별로 실거리 데이터를 관리하는 콘셉트는 유지하되, 데이터를 단일 String으로 압축해 사용하는 방식 대신 Redis Hash 자료구조를 활용했습니다. Redis Hash 자료구조로 지역별 실거리 관리 인터페이스를 어느 정도 유지하면서도 읽기와 쓰기 성능을 크게 개선할 수 있었습니다.
 구체적으로는 지역 ID를 Key로 하고, 각 Hash의 필드에는 실거리를 이루는 두 좌표를, 값에는 실거리를 저장하도록 설계했습니다. 이 구조에서는 매번 모든 데이터를 읽고 쓸 필요 없이 필요한 Hash 필드에만 접근할 수 있어, 네트워크 송수신 데이터량을 크게 줄일 수 있었습니다. 또한, 거리 값 자체를 Integer로 저장함으로써 메모리 사용도 더욱 효율적으로 관리할 수 있었습니다.
 더 나아가 해시 필드 접근 시 단일 커맨드를 여러 번 호출하는 대신, 다중 인자를 한 번에 전달해 여러 필드에 동시에 접근하도록 하여 네트워크 오버헤드를 줄였습니다. 다만 다중 인자를 받는 커맨드의 시간 복잡도는 O(N)이므로 호출 횟수와 인자 수에 주의가 필요합니다. 또, [AWS ElastiCache 사용자 가이드](https://docs.aws.amazon.com/ko_kr/AmazonElastiCache/latest/dg/RedisConfiguration.html)를 보면 요청당 최대 인자 수를 3,999개로 제한하는 것을 확인할 수 있습니다. 이를 감안해 인자 개수를 적절한 크기로 청크 처리하여 슬로우 쿼리 없이 적용할 수 있었습니다.
 ## Redis 성능 최적화
 ### EXPIRE 커맨드 줄이기
 TTL은 Redis가 제공하는 매우 유용한 기능이지만, 지나치게 많이 사용될 경우 네트워크 오버헤드가 증가할 수 있습니다. 또한 만료 시간이 긴 경우 내부적으로 CPU와 메모리 리소스도 불필요하게 소모될 수 있습니다.
 실거리 관리 시스템 초기 배포 시에는 버그나 롤백 상황에 대비해 일정 시점마다 메모리를 반드시 비워야 한다는 판단 하에, 모든 HMSET 요청에 6시간 EXPIRE 명령을 함께 실행하도록 설계했습니다. 하지만 배달이 N시간 안에 모두 완료된다는 가정은 현실적이지 못하고 비효율적이었습니다. TTL을 너무 짧게 설정하면 캐시 히트율이 떨어지고, 너무 길면 리소스 낭비로 이어집니다.
 특히 실거리 시스템은 Redis Hash 구조를 사용해 지역 ID별로 거리 데이터를 관리하기 때문에, HMSET 요청 시마다 EXPIRE 명령을 함께 실행하면 Hash key의 TTL이 불필요하게 자주 갱신됩니다. 이로 인해 네트워크 비용이 낭비되는 문제가 발생합니다.
 위 단점을 극복하기 위해, 일정 시간 TTL을 설정하는 대신 배달이 완료 또는 취소되는 시점에 해당 배달과 동일한 위치가 더 이상 사용되지 않는 경우에만 실거리 데이터를 명시적으로 삭제하는 방식을 선택했습니다.
 이 방식은 별도의 삭제 로직이 필요하다는 단점이 있지만, 불필요한 가정을 하지 않아도 되고 CPU와 메모리 자원을 보다 효율적으로 관리할 수 있습니다. 또한 HMSET 수행 시마다 EXPIRE 명령을 함께 실행하지 않아도 되므로 네트워크 비용이 줄어듭니다. 더 나아가, 레플리카 복제 과정에서 발생하는 쓰기 트래픽 역시 감소하여 네트워크 송수신 데이터 양을 효과적으로 줄일 수 있습니다.
 | 구분 | TTL로 삭제 (expire) | 명시적 삭제 (delete) |
 |-----|------------------|------------------|
 | 장점 | • 배달 주기 신경 쓸 필요 없음<br>• 별도 로직 구현 불필요 | • 배달 주기에 맞춰 실거리 그래프 관리 가능<br>• TTL 대비 단순하고 명확한 처리 가능 |
 | 단점 | • 배달마다 완료 시간이 달라 TTL 설정 모호<br>• 해시 필드별 TTL은 저수준 직접 구현 필요 (Spring Data Redis 미지원)<br>• 지역별 해시 TTL은 매번 expire 연장 발생<br>• TTL 만료 시 콜드 스타트 이슈 발생 가능<br>• 대량 만료 시 CPU 사용량 증가 | • 명시적 삭제 로직 구현 필요 |
 ### 쓰기 분산을 위한 Redis 클러스터 모드 적용
 TTL과 명시적 삭제 방식을 비교해보며, 실거리 그래프는 쓰기 트래픽이 많다는 점을 확인했습니다. 따라서 이를 위한 분산 전략이 매우 중요합니다.
 Redis는 고가용성을 위해 마스터-레플리카 모드와 클러스터 모드를 지원합니다. 마스터-레플리카 모드에서는 모든 쓰기 작업이 Primary 노드에 집중되고, Primary 노드는 변경사항을 Replica 노드에 전송해야 합니다. 이 과정에서 Primary 노드의 네트워크 병목과 대역폭 초과가 발생할 수 있습니다. 반면 클러스터 모드는 쓰기 작업도 여러 노드에 분산할 수 있습니다.
 Redis 클러스터 모드의 샤딩은 키 공간을 해시 슬롯으로 나누어 동작합니다. 실거리 그래프는 지역 ID를 키로 관리하므로, 서로 다른 지역에 대한 HMGET, HMSET 요청을 각기 다른 샤드가 분산 처리할 수 있어 성능 향상에 유리합니다.
 멀티 키 연산이 필요한 경우 클러스터 모드 적용 시 해시 태그 등의 추가 고려가 필요하지만, 실거리 그래프는 동일 키에 대해서만 멀티 연산(HMGET, HMSET, HDEL)이 발생하므로 서비스 코드 수정 없이 적용할 수 있었습니다. 따라서 클러스터 모드로의 전환만으로도 쓰기 트래픽 분산이 가능했습니다. 물론 트래픽 급증 시 네트워크 부하 문제는 여전히 발생할 수 있으나, 클러스터 모드는 노드를 수평 확장하기 쉬워 새로운 노드 추가로 유연한 대응이 가능합니다.
 이처럼 클러스터 모드 적용을 통해 네트워크 용량 확장과 분산 처리, 성능 최적화를 통해 보다 안정적인 실거리 관리 시스템을 구축할 수 있었습니다. 실거리 관리 시스템 도입 후 Redis 지표 모니터링과 최적화 시도를 병행하며 지역별 점진 배포를 진행했고, 클러스터 모드 적용 후에는 전 지역으로 안정적 확장을 빠르게 마칠 수 있었습니다.
 ## 마무리
 지금까지 배차시스템에서 OSRM 지도, Kafka, Redis를 활용한 이벤트 기반 실거리 시스템 개발 사례와 과정을 공유드렸습니다. 배차시스템팀은 배달에서 발생하는 대량 트래픽을 처리하기 위해 다양한 고민과 개발을 이어가고 있으며, 이번 실거리 시스템은 그중에서도 가장 많은 트래픽을 다루는 핵심 도메인 중 하나입니다.
 이번 프로젝트를 통해 Kafka 기반 이벤트 드리븐 아키텍처(EDA)를 경험하고, Redis를 활용한 대규모 트래픽 처리 기술을 적용할 수 있었습니다. 또한 라이더분들의 효율적인 배달 수행을 지원하여 배차 효율 향상에 기여할 수 있었습니다. 저희의 경험과 사례가 글을 읽으시는 분들의 서비스 개선에 도움이 되길 기대합니다.
@@ -0,0 +1,73 @@
 <!-- 출처: https://techblog.woowahan.com/23625/ · 우아한형제들 기술블로그 · 참고용 원문 사본 -->
 <!-- 이 페이지는 자바스크립트로 본문을 그려서 전문을 받지 못했다. 아래는 받아낸 부분이다.
     인용부호가 붙은 문장만 원문 그대로이고, 나머지는 원문을 줄인 것이다. 문장 표본으로 쓰지 말고
     글의 골격(요구사항 목록 → 표 설계 → 트레이드오프)을 보는 데만 쓴다. -->
 # 장시간 비동기 작업, Kafka 대신 RDB 기반 Task Queue로 해결하기
 박민규 · Backend · 2025년 11월 25일
 ## 문제 상황
 전자계약서 시스템에서 대용량 엑셀 파일 생성 작업은 Kafka를 통해 비동기로 처리되고 있었습니다. 초기에는 대부분의 작업이 10분 이내에 완료되었지만, 신규 엑셀 타입 추가로 인해 각 행마다 여러 외부 API를 호출해야 하면서 처리 시간이 30분 이상으로 증가했습니다.
 심각한 문제는 사용자가 "같은 엑셀 파일을 여러 번 받았다"는 문의였습니다. 조사 결과, Kafka의 5분 타임아웃(`max.poll.interval.ms`)을 초과하면서 리밸런싱이 발생하여 Worker가 비동기 처리한 뒤 즉시 ACK하도록 변경했지만, 이는 작업 유실 위험을 초래했습니다.
 ## 근본 원인
 "5분 동안 `poll()`이 호출되지 않으면 Consumer가 죽은 것으로 판단하고" 리밸런싱이 일어납니다. 장시간 작업 중 리밸런싱이 발생하면서 동일 메시지가 다른 Consumer에게 재할당되었습니다. 타임아웃을 증가시키는 임시 해결책은 실제 Worker 장애 감지를 지연시키는 부작용을 초래했습니다.
 ## 기존 Kafka 방식의 한계
 팀은 엑셀 생성에 Kafka가 정말 필요한지 검토했습니다. Kafka는 대량 트래픽과 다중 consumer group에 유리하지만, 실제로는 트래픽이 일정하고 생산자/소비자가 모두 내부 서비스였습니다. 장시간 작업 특성상 타임아웃 문제가 지속적으로 발생했고, 타임아웃을 늘리면 실제 장애 감지가 1시간 이상 지연되는 딜레마가 생겼습니다.
 ## RDB 기반 Task Queue 아키텍처로 전환
 새로운 구조는 다음과 같은 요구사항을 반영했습니다:
 - **시간 제한 없음**: 1~2시간 걸리는 작업도 안정적 완료
 - **배포 영향 없음**: 서버 배포 시 즉시 중단되어야 함
 - **작업 유실 방지**: 서버 다운 시에도 작업 재처리
 - **자동 재시도**: 일시적 오류 시 최대 3회 재시도
 - **병렬 처리**: 여러 Worker의 분산 처리
 - **중복 방지**: 동일 작업의 중복 처리 차단
 ### 핵심 구조
 **테이블 설계**:
 ```sql
 CREATE TABLE excel_download_request (
    id BIGINT PRIMARY KEY,
    status VARCHAR(20),           -- PENDING, IN_PROGRESS, DONE, FAILED
    last_heartbeat_at DATETIME,   -- Worker 생존 신호 마지막 수신 시각
    retry_count INT DEFAULT 0,    -- 재시도 횟수 (최대 3회)
    created_at DATETIME,
    updated_at DATETIME
 );
 ```
 **작업 선점 및 처리**: Worker는 3초마다 PENDING 작업을 조회하고 Redis 분산 락으로 선점합니다. 동시에 최대 2개 작업을 병렬 처리합니다(10대 서버 × 2 = 20개의 시스템 처리 용량).
 **Heartbeat 메커니즘**: 작업 중인 Worker는 1분마다 마지막 활동 시각을 갱신합니다. 2분 이상 갱신이 없으면 Fallback 스케줄러가 작업을 PENDING으로 되돌려 다른 Worker가 복구하도록 합니다. 복구 스케줄러는 ShedLock 으로 한 인스턴스만 수행합니다.
 **재시도 처리**: 실패한 작업은 retryCount를 증가시킨 뒤 PENDING으로 되돌립니다. 3회 이상 실패하면 최종적으로 FAILED 상태로 처리됩니다.
 ## 개선 효과
 **강점**:
 - Kafka 메시지 플로우 제거로 디버깅 용이
 - 단일 데이터 소스(RDB)로 상태 관리 단순화
 - 메시지 재발행/유실 문제 원천 차단
 - Worker 수평 확장이 단순함
 - 단순 쿼리로 실시간 모니터링 가능
 **트레이드오프**:
 - 지속적인 폴링 쿼리로 DB 부하 증가(커버링 인덱스로 최적화, 분당 20~30회 정도)
 - 폴링 주기(3초)만큼 처리 시작 지연 발생(엑셀 다운로드에서는 허용 가능)
 ## 핵심 인사이트
 "작업 트랜잭션 특성에 따라 메시징 시스템 선택이 달라져야 한다"는 결론에 도달했습니다. 짧고 빠른 작업은 Kafka 같은 이벤트 스트리밍에 적합하지만, 수십 분 소요되는 복잡한 작업은 상태 관리와 재시도가 용이한 RDB 기반 Task Queue가 더 안정적입니다.
@@ -0,0 +1,417 @@
 <!-- 출처: https://techblog.woowahan.com/7835/ · 우아한형제들 기술블로그 · 참고용 원문 사본 -->
 # 회원시스템 이벤트기반 아키텍처 구축하기
 ## 배달의민족의 마이크로서비스 여정
 최초의 배달의민족은 하나의 프로젝트로 만들어졌습니다. 배달의민족의 주문수는 J 커브를 그리는 빠른 속도로 성장했고, 주문수가 커지면서 자연스럽게 트래픽 또한 매우 커졌습니다.
 하나의 시스템, 하나의 데이터베이스로 폭발적으로 늘어가는 트래픽을 감당하지 못하고, 결국 배달의민족은 대장애 시대를 맞이했습니다. 이에 배달의민족은 마이크로서비스로 전환을 시도하였고, 2019년 11월 1일 모든 시스템이 분리되며 마이크로서비스를 완성하였고 시스템의 안정화를 찾을 수 있었습니다.
 배달의민족은 마이크로서비스로 전환을 하게 되었고, 이벤트 기반 아키텍처의 시대를 맞이했습니다.
 ## 회원 시스템 이벤트 기반 아키텍처 구축하기
 ### 무엇을 이벤트로 발행할 것인가?
 MicroService Architecture (이하 MSA) 에서 Event Driven 이 함께 언급되는 이유는 MSA 핵심 키워드 중 `느슨한 결합`과 연관이 있습니다. 각 마이크로서비스는 서로 간 느슨한 결합을 가져감으로써 타 시스템에 대한 의존과 영향도를 줄이고 각 시스템의 목적에 집중함으로써 강한 응집을 갖는 시스템을 만들 수 있습니다. Event Driven 은 이를 돕습니다.
 이해를 돕기 위하여 배달의민족의 회원과 가족계정이라는 두 가지 도메인의 관계를 예시로 들겠습니다.
 "회원의 본인인증이 초기화되는 경우 가족계정 서비스에서 탈퇴되어야 한다" 라는 정책이 있습니다.
 이를 코드로 작성하면 가족계정 서비스 탈퇴 로직은 회원의 본인인증 해제 로직에 깊게 관여되어 강한 결합을 가지고 있습니다.
 마이크로서비스를 구성 함에 따라 두 도메인은 서로 다른 시스템으로 분리되어 회원 시스템, 가족계정 시스템이 되었습니다. 이 때 하나의 시스템에 존재하던 두 도메인의 물리적인 분리가 이루어집니다.
 물리적인 시스템의 분리로 인해 코드 레벨의 호출이 동기적인 HTTP 통신으로 변했습니다. 그러나 여전히 대상 도메인을 호출해야한다는 의도가 남아있기 때문에 물리적인 시스템 분리만으로는 결합이 느슨해졌다고 볼 수는 없습니다.
 물리적인 의존을 제거하는 방법으로 쉽게 떠올릴 수 있는 것은 비동기 방식입니다. 대표적인 비동기 방식으로는 별도 스레드를 통한 HTTP 방식과 메시징 시스템을 이용한 방식이 있습니다.
 주 흐름에서 분리된 별도 스레드를 통해 HTTP 요청을 합니다. 별도 스레드에서 진행되기 때문에 주 흐름과 직접적인 결합이 제거될 수 있습니다. 그러나 시스템 관점에서는 여전히 별도 스레드에서 대상 도메인을 호출한다는 의도가 남아있기 때문에 이 또한 결합이 느슨해졌다고 볼 수 없습니다.
 메시징 시스템을 이용하여 메시지를 전송합니다. 메시징 시스템을 사용하면서 느슨한 결합을 가져갈 수 있을 것이라고 기대하겠지만 메시징시스템을 사용하는 아키텍처가 항상 느슨한 결합을 보장하지는 않습니다.
 회원의 본인인증 해제가 발생할 때 가족계정 탈퇴 메시지를 발송하였습니다. 메시지를 발송하는 것으로 물리적인 의존이 제거되었습니다. 그러나 결합은 느슨해지지 않습니다.
 가족계정 탈퇴를 기대하는 메시지를 발행했기 때문에 가족계정 시스템의 정책이 변경될 때 회원 시스템의 메시지도 함께 변경되어야 합니다. 어떤 일을 해야 하는 지를 메시지 발행자가 알려주는 경우(Command), 해야하는 일이 변경될 때 메시지 발행자와 수신자 양쪽 모두의 코드가 변경돼야 하기 때문에 높은 결합도가 존재하게 됩니다. 또한 회원시스템은 여전히 가족계정의 비지니스를 알고 있는 논리적인 의존관계가 남아있기 때문에 결합이 느슨해졌다고 볼 수 없습니다. 물리적으로는 결합도가 높지 않지만 개념적으로는 결합도가 높은 상태인 것 입니다.
 메시지를 발행하였음에도 의존관계가 남아있는 이유는 대상 도메인에게 기대하는 목적을 담은 메시지를 발행하였기 때문입니다. 메시징 시스템으로 보낸 메시지가 대상 도메인에게 기대하는 목적을 담았다면, 이것은 이벤트라 부르지 않습니다. 이것은 메시징 시스템을 이용한 비동기 요청일 뿐 입니다.
 회원의 본인인증 해제가 발생할 때 본인인증 해제 이벤트를 발송하였습니다. 회원시스템은 더 이상 가족계정 시스템의 정책을 알지 못합니다. 가족계정 시스템은 본인인증 해제 이벤트를 구독하여 가족계정 시스템의 비지니스를 구현합니다. 회원시스템은 가족계정 시스템의 비지니스 변경에 더 이상 영향을 받지 않습니다. 이로써 두 시스템 간의 결합이 느슨해졌습니다.
 물리적인 시스템 분리부터 비동기 HTTP 통신, 이벤트 방식까지 살펴보며 의존 관계의 흐름을 살펴보았습니다.
 메시징 시스템을 사용해 물리적인 의존을 제거할 수 있었지만, **메시지가 담는 의도에 따라 전혀 다른 결과**를 얻는다는 것을 알 수 있습니다.
 **우리가 발행해야할 이벤트는 `도메인 이벤트로 인해 달성하려는 목적`이 아닌 `도메인 이벤트` 그 자체입니다.**
 > `도메인`이란 해결하고자 하는 문제 영역이며, `도메인 이벤트` 는 문제 영역에서 발생할 수 있는 핵심 가치나 행위입니다. `도메인` 이라는 용어로 Domain-Driven Design(이하 DDD) 과 관계를 지어 글을 보시는 분들이 계실 것 같아 DDD 와 큰 관련이 없음을 미리 명시합니다.
 도메인의 핵심 가치나 행위를 정의하기 어렵다면 `이벤트 스토밍` 을 추천드립니다. `이벤트 스토밍` 은 DDD 의 전략적 설계 도구 중 하나이지만, 도메인 주도 설계를 위해서가 아니더라도 문제 영역 식별과 해결에 좋은 도구입니다.
 ### 이벤트 발행과 구독
 회원시스템에서는 다양한 고민을 해결하기 위하여 3가지의 이벤트 종류와 3가지의 이벤트 구독자 계층을 정의하였습니다. 각 계층과 이벤트가 왜 만들어졌는지, 무엇을 해결해주는지 살펴보겠습니다.
 #### 어플리케이션 이벤트 & 첫번째 구독자 계층
 메시징 시스템을 사용하기 전 `Spring Framework` 의 `Application Event` 를 먼저 다루었습니다.
 어플리케이션 이벤트를 먼저 다루는 이유는 이벤트를 통해 느슨한 결합을 만들어야 하는 일이 외부 세상에만 존재하는게 아니기 때문입니다.
 스프링의 어플리케이션 이벤트는 분산-비동기를 다룰 수 있는 이벤트 버스를 제공하며, 트랜잭션을 제어할 수 있도록 지원합니다.
 어플리케이션 이벤트를 구독하는 첫번째 구독자 계층은 스프링의 어플리케이션 이벤트가 제공하는 기능으로 한 어플리케이션 내에서 도메인 내부의 비관심사를 효율적으로 처리할 수 있습니다.
 어플리케이션 내에서 반드시 해결해야만 하는 대표적인 도메인의 비관심사는 메시징 시스템으로 이벤트를 발행하는 것 입니다. 이벤트 구독은 발행 시스템에 영향 없이 자유롭게 확장이나 변경이 가능하므로, 우리는 도메인에 영향 없이 메시징 시스템에 대한 연결을 쉽게 작성하고 확장하고 변경할 수 있습니다.
 또한 스프링 어플리케이션 이벤트를 통해 트랜잭션을 제어할 수 있습니다. 도메인에서 정의된 트랜잭션의 범위가 외부로부터 제어 될 수 있다는 것을 도메인에 대한 침해로 볼 수 있지만, 이 침해를 감수하는 대신 강력한 구독자를 만들 수 있습니다.
 상태 변경을 야기하는 모든 도메인 행위는 메시징 시스템으로 전달해야한다는 시스템 정책을 세웠습니다. 이벤트를 메시징 시스템으로 전달하는 것은 도메인에게는 관심사가 아니지만 시스템에서는 중요한 정책입니다. 이런 경우 도메인 정책에 변경없이 트랜잭션을 확장하여 구독자의 행위를 트랜잭션 내에서 처리되도록 변경할 수 있습니다.
 회원시스템은 메시징 시스템으로 `AWS SNS` 를 사용하고 있으므로, 첫번째 구독자 계층의 `SNS` 발행을 책임지는 이벤트 구독자가 만들어졌습니다.
 ```java
@Async(EVENT_HANDLER_TASK_EXECUTOR)
@TransactionalEventListener(phase = TransactionPhase.BEFORE_COMMIT)
 public void handleJoinEvent(MemberJoinApplicationEvent event) {
    MemberJoinEventPayload payload = MemberJoinEventPayload.from(event);
    notificationMessagingTemplate.sendNotification(clientNameProperties.getSns().getJoin(), payload, null);
 }
 ```
 그리고 이 구독자를 통해 발행되는 이벤트는 `내부 이벤트` 입니다.
 #### 내부 이벤트 & 두번째 구독자 계층
 어플리케이션 이벤트로 내부 이벤트를 처리할 수 있지만, 어플리케이션 이벤트 처리기는 어플리케이션의 리소스를 사용하기 때문에 도메인의 주요 기능 처리 성능에 영향을 미치게 됩니다. 또한 `Application Event` 가 잘 구현되어 있다지만, 메시지 유실과 장애 복구를 최소화해주는 메시징 시스템의 장점을 가져갈 수 없습니다.
 첫번째 구독자 계층이 어플리케이션 내에서 해결해야하는 비관심사를 처리했다면, 내부 이벤트를 구독하는 두번째 구독자 계층은 이 외의 모든 도메인 내의 비관심사를 처리합니다.
 ##### 비관심사 분리
 도메인 행위가 수행될 때 함께 수행되어야 하는 정책들이 있을 수 있습니다. 이러한 부가 정책들이 도메인의 주 행위인 것으로 착각될 수 있으며, 의존성 관계를 확장시키고 도메인의 주 행위에 대한 응집을 방해하게 됩니다.
 도메인 내의 비관심사 분리의 예시로 로그인 프로세스를 살펴보겠습니다.
 회원이 로그인을 할 때
 - 회원을 로그인 상태로 변경
 - "동일 계정 로그인 수 제한" 규칙에 따라 동일 계정이 로그인된 타 디바이스 로그아웃 처리
 - 회원이 어느 디바이스에서 로그인되었는지 기록
 - 동일 디바이스의 다른 계정 로그아웃 기록
 을 해야 합니다.
 ```java
@Transactional
 public void login(MemberNumber memberNumber, DeviceNumber deviceNumber) {
    devices.login(memberNumber, deviceNumber);
    devices.logoutMemberOtherDevices(memberNumber, deviceNumber);
    devices.logoutOtherMemberDevices(memberNumber, deviceNumber);
    member.login(memberNumber);
    applicationEventPublisher.publishEvent(MemberLoginApplicationEvent.from(memberNumber, deviceNumber));
 }
 ```
 이 코드를 살펴보았을 때 도메인의 주 행위가 무엇인지 알기 어렵습니다. 부가 정책들이 도메인 로직에 함께 작성되어 있기 때문입니다. 주요 기능을 찾고 비관심사를 분리하여 도메인 행위의 응집을 높이고 비관심사에 대한 결합을 느슨하게 만들어야 합니다. 도메인의 주요행위는 정책을 살펴보았을 때 알 수 있을 것 입니다. 정책마저 모호하다면 즉시 처리되어야 하는 것과 언젠가 처리되어야 하는 것을 분리함으로써 도메인의 주요 기능을 찾을 수 있습니다.
 로그인 기능의 주 행위는 **"회원을 로그인 상태로 변경"** 하는 것 입니다. 이 외의 행위들은 로그인 행위에 부가적으로 붙어있는 정책들입니다. 부가적인 정책들을 도메인 로직에서 분리시킵니다.
 ```java
@Transactional
 public void login(MemberNumber memberNumber, DeviceNumber deviceNumber) {
    member.login(memberNumber);
    applicationEventPublisher.publishEvent(MemberLoginApplicationEvent.from(memberNumber, deviceNumber));
 }
 ```
 또한 3가지 비관심사 작업이 서로 간의 의존이 없음을 알 수 있습니다. 우리는 `AWS SNS-SQS` 메시징 시스템을 통해 하나의 이벤트를 여러 구독으로 나누어서 처리할 수 있습니다.
 ```java
@SqsListener(value = "${sqs.login-device-login}", deletionPolicy = SqsMessageDeletionPolicy.ON_SUCCESS)
 public void loginDevice(@Payload MemberLoginApplicationEvent payload) {
    devices.login(payload.getMemberNumber(), payload.getDeviceNumber());
 }
@SqsListener(value = "${sqs.login-member-other-device-logout}", deletionPolicy = SqsMessageDeletionPolicy.ON_SUCCESS)
 public void logoutMemberOtherDevices(@Payload MemberLoginApplicationEvent payload) {
    devices.logoutMemberOtherDevices(payload.getMemberNumber(), payload.getDeviceNumber());
 }
@SqsListener(value = "${sqs.login-other-member-device-logout}", deletionPolicy = SqsMessageDeletionPolicy.ON_SUCCESS)
 public void logoutOtherMemberDevices(@Payload MemberLoginApplicationEvent payload) {
    devices.logoutOtherMemberDevices(payload.getMemberNumber(), payload.getDeviceNumber());
 }
 ```
 이렇게 도메인 내의 비관심사를 분리함으로써 도메인 행위의 응집을 높이고, 비관심사에 대한 결합을 느슨하게 만들 수 있습니다. 또한 분리된 비관심사는 각자 구현이 되어 강한 응집과 높은 재사용성을 확보할 수 있습니다.
 ##### 외부 이벤트 발행
 시스템 내의 비관심사를 분리했지만, MSA 를 위한 외부 시스템과의 관심사 분리를 위한 외부 이벤트 발행이 필요합니다. 외부 시스템에 이벤트를 전파하는 행위 또한 도메인 내에 존재하던 비관심사로 볼 수 있습니다.
 ```java
@SqsListener(value = "${sqs-join-broadcast}", deletionPolicy = SqsMessageDeletionPolicy.ON_SUCCESS)
 public void handleBroadcast(@Payload MemberJoinApplicationEvent payload) {
    messageBroadcastExecutor.broadcast(MemberBroadcastMessage.from(payload));
 }
 ```
 다른 내부 이벤트 처리와 동일하게 두번째 구독자 계층의 `SNS 발행` 을 책임지는 이벤트 구독자로부터 `외부 이벤트` 가 발행되게 됩니다.
 #### 외부 이벤트 & 세번째 구독자 계층
 내부이벤트를 외부에서 구독하도록 할 수 있지만, 내부 이벤트와 외부 이벤트를 분리함으로써 내부에는 열린, 외부에는 닫힌 이벤트를 제공할 수 있다는 장점이 있습니다.
 동일한 이벤트를 수신하더라도 각 구독자마다 서로 다른 목적을 가지고 있습니다. 이로인해 각 구독자는 이벤트를 인지하는 것 이상으로 데이터가 더 필요하게 될 수 있습니다.
 ##### 열린 내부이벤트, 닫힌 외부이벤트
 **내부이벤트** 에는 구독자가 필요한 데이터를 페이로드에 제공하여 이벤트 처리의 효율을 챙길 수 있습니다. 이런 페이로드의 확장을 열어둘 수 있는 것은 이 이벤트가 내부 이벤트이기 때문입니다. **내부 이벤트는 시스템 내에 존재하기 때문에 이벤트의 발행이 구독자에게 미치는 영향을 파악하고 관리할 수 있습니다.** 또한 외부에 알릴 필요없는 내부의 개념을 이벤트에 녹일 수도 있습니다. 이러한 확장이 가능한 것 또한 내부 이벤트는 시스템 내에 존재하는 이벤트이기 때문입니다.
 반면 외부 시스템 으로 전파되는 **외부이벤트**는 내부이벤트와는 다릅니다. 내부 이벤트는 도메인에 존재하는 비관심사를 분리하여 도메인의 응집도를 높이고 비관심사를 효율적으로 처리하는 것을 목적으로 하며, 외부 이벤트는 시스템과 시스템의 결합을 줄이는 것을 목적으로 합니다. 시스템 간의 결합을 느슨하게 만들기 위해 발행되는 **외부 이벤트는 이벤트 발행처에서 이벤트 구독자가 어떤 행위를 하는지 관심을 가지면 안되며, 관리할 수 없습니다**. 이벤트 발행처가 이벤트 구독자의 행위에 관심을 갖게 된다면 이는 또 다시 논리적인 의존 관계를 형성하게 되는 것 입니다.
 외부시스템에서도 이벤트를 처리하기 위해 더 많은 정보가 필요할 것 입니다. 그러나 외부시스템의 비지니스에서 필요한 데이터를 페이로드에 추가하게 되면, 외부시스템의 비지니스 변화에 직접적인 의존 관계를 형성하게 될 것 입니다. 외부시스템과의 의존을 갖지 않는 이벤트를 만들기 위해 하나의 형태로 이벤트를 전달할 수 있는 **이벤트에 대한 일반화**가 필요합니다.
 ##### 이벤트 일반화
 외부 시스템이 이벤트로 수행하려는 행위는 광범위하겠지만, 이벤트를 인지하는 과정은 쉽게 일반화할 수 있습니다.
 **"언제, 어떤 회원이(식별자) 무엇을(행위) 하여 어떤 변화(변화 속성)가 발생했는가"**
 `식별자`와 `행위`, `속성`, `이벤트 시간` 이 있다면 어떠한 시스템에서도 필요한 이벤트를 인지할 수 있음을 알 수 있습니다. 이를 페이로드로 구현하면 이벤트를 수신하는 측에서 필요한 이벤트를 분류하여 각 시스템에서 필요한 행위를 수행할 수 있습니다.
 ```java
 public class ExternalEvent {
    private final String memberNumber;
    private final MemberEventType eventType;
    private final List<MemberEventAttributeType> attributeTypes;
    private final LocalDateTime eventDateTime;
 }
 ```
 외부 시스템들은 정해진 이벤트 형식 내에서 필요한 행위를 수행하면 되므로, 이벤트를 발행하는 시스템은 외부 시스템의 변화에 영향을 받지 않을 수 있습니다.
 > TIP. **SNS 속성을 이용하여 구독자들이 원하는 이벤트만 구독하기**
 >
 > "AWS SNS" 의 속성을 기반으로 구독자마다 이벤트를 필터링할 수 있는 기능을 사용할 수 있습니다.
 >
 > 각 구독자는 필요한 이벤트 형식 혹은 속성 종류를 필터로 정의하여 어플리케이션에 필요한 이벤트만 유입되도록 만들 수도 있습니다. 필터링 기능을 통해 어플리케이션이 직접 이벤트를 분류해야하는 리소스 낭비를 줄일 수 있습니다.
 ##### ZERO-PAYLOAD 방식
 닫혀있는 외부이벤트의 부가 데이터를 전달하는 방식으로는 `ZERO-PAYLOAD` 방식을 선택했습니다.
 `ZERO-PAYLOAD` 방식은 이벤트의 순서에 대한 보장 문제를 해소하는 방식으로 주로 소개되곤 하지만, 페이로드에 외부시스템에 대한 의존을 제거하여 느슨한 결합을 만들 수 있는 장점 또한 있습니다.
 외부시스템은 일반화된 이벤트를 필터링하여 필요한 이벤트를 구독하고, 필요한 부가 정보는 API 를 통해 보장된 최신상태의 데이터를 사용할 수 있습니다.
 ---
 **어플리케이션 이벤트를 통해 이벤트의 트랜잭션 제어를 할 수 있었으며, 내부 이벤트를 통해 내부의 비관심사를 효율적으로 분리할 수 있었으며, 외부 이벤트를 통해 외부시스템과 의존없는 이벤트를 발행하게 되었습니다.**
 **이렇게 회원 시스템에 이벤트 기반의 아키텍처가 구축되었습니다.**
 ## 이벤트 저장소 구축
 이벤트의 계층을 분리하고, 메시징 시스템을 통해 안정적인 이벤트를 처리할 수 있게 되었지만 여전히 문제점들이 존재하고 있습니다.
 ### 첫번째 문제. 이벤트 발행에 대한 보장 유실
 `SNS-SQS-어플리케이션` 구간에서는 SQS의 정책을 통해 안정적인 실패 처리, 재시도 처리가 가능하지만 `어플리케이션-SNS` 구간에서는 HTTP 통신을 사용하므로 이벤트를 발행하는 과정에 문제가 발생할 수 있습니다.
 내부 이벤트를 발행하는 과정을 트랜잭션 내부로 정의하면서, 메시징 시스템의 장애가 곧 시스템의 장애로 이어질 수 있습니다. 메시징 시스템의 장애가 시스템 장애로 이어지는 문제는 굉장히 큰 문제이므로 반드시 해결이 필요합니다.
 ```java
@Async(EVENT_HANDLER_TASK_EXECUTOR)
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
 public void handleJoinEvent(MemberJoinApplicationEvent event) {
    MemberJoinEventPayload payload = MemberJoinEventPayload.from(event);
    notificationMessagingTemplate.sendNotification(clientNameProperties.getSns().getJoin(), payload, null);
 }
 ```
 이 문제는 내부 이벤트 발행을 트랜잭션 이후로 정의를 하면서 해결할 수 있습니다.
 그러나 트랜잭션 외부에서 처리되기 때문에 이벤트 발행에 대한 보장이 사라지게 되었습니다. `어플리케이션-SNS` 구간에서는 HTTP 통신을 사용하므로 네트워크 구간에서는 다양한 문제로 충분히 실패가 발생할 수 있습니다.
 ### 두번째 문제. 이벤트 재발행
 구독자들이 이벤트를 정상적으로 처리하더라도, 이벤트 처리를 잘못할 수 있기 때문에 언제든 이벤트를 재발행 해줄 수 있어야 합니다.
 이 때 구독자들이 원하는 이벤트들의 형태는 자유롭습니다. 특정 이벤트, 특정 기간, 특정 회원이나, 특정 타입, 특정 속성 의 이벤트 발행을 원할 수 있습니다. 일부 메시징 시스템은 재발행에 대한 기능을 제공하지만, 모든 메시징 시스템이 이 기능을 제공하지 않으며 모든 요구사항을 수용하기도 힘듭니다.
 대부분의 데이터는 최종 상태만을 보관하여 특정 시점의 상태를 복원하기 어려우며, 변경 내역을 가지고 있다고 하더라도 이벤트를 고려하지 않고 저장된 데이터로 이벤트를 복원하기는 쉽지 않습니다.
 **이 두 가지 문제점을 해결하기 위해 우리는 이벤트 저장소를 구축하기로 하였습니다.**
 ### 이벤트 저장 시점
 메시징 시스템의 장애가 시스템의 장애로 이어지지 않도록 메시징 시스템으로 이벤트 발행을 별도 트랜잭션으로 정의를 하였습니다. 이는 "메시징 시스템으로 이벤트 발행을 도메인의 중요한 행위로 본다"는 정의를 깨버리는 것이었고, 이것이 이벤트 발행에 대한 보장을 사라지게 만들었습니다.
 이 정의를 이벤트 저장소로 다시 복구를 하기 위해 우리는 "이벤트 저장소에 이벤트 저장하는 것을 도메인의 중요한 행위로 본다" 고 정의를 하였습니다. 모든 도메인 이벤트는 반드시 저장소에 저장되어야 하며, 저장소에 저장이 실패하게 되었을 때 도메인 행위도 실패했다고 간주한다는 리스크가 있지만, 어딘가에서는 반드시 데이터를 보장을 해야하기 때문에 이런 정의가 필요합니다.
 ```java
@EventListener
@Transactional
 public void handleEvent(MemberJoinApplicationEvent event) {
    memberEventRecorder.record(event.toEventCommand());
 }
 ```
 이 정의를 통해 이벤트 저장소에 대한 저장을 트랜잭션 범위 내에서 처리하는 구독자를 만들었습니다.
 ### 저장소의 종류
 이벤트는 작은 단위로 저장이 되고, 고속 처리되어야하기 때문에 RDBMS 가 아닌 다른 데이터베이스를 선택해야한다고 생각할 수 있습니다.
 도메인 저장소와 다른 종류의 데이터베이스를 사용할 경우 두 저장소에 대한 트랜잭션 처리를 할 수 있어야 합니다. 그러나 다종 데이터베이스의 분산 트랜잭션을 구현 하는 것은 굉장히 어려운 일 입니다.
 이벤트 저장소를 도메인 저장소와 동일한 저장소로 선택을 했을 경우 트랜잭션에 대한 처리는 DBMS 를 믿고 맡길 수 있으며, 인프라에 장애가 발생해도 트랜잭션을 통해 데이터 일관성을 보장할 수 있습니다.
 동일 저장소를 통해 데이터베이스를 저장하고 이벤트를 발행함에 안정적인 정합성을 보장하는 방식은 [Transactional outbox Pattern](https://microservices.io/patterns/data/transactional-outbox.html) 이라고 소개되기도 합니다. 이 패턴의 핵심은 로컬 트랜잭션(동일 저장소를 사용한 트랜잭션)을 사용하여 데이터베이스를 저장하고 이벤트를 발행함에 정합성을 보장하는 내용입니다. 이벤트 저장소를 사용하기로 한 것이 이벤트 발행에 대한 보장 문제를 해결하기 위함이니 이 구현은 `Transactional outbox Pattern` 의 또다른 구현이라고 볼 수도 있습니다.
 단일 저장소의 쓰기량 및 읽기량에 대한 성능적 리스크를 동반할 수 있겠지만, 이는 스케일업/아웃 혹은 샤딩을 하는 등 충분히 확장하여 대응 가능합니다.
 그래서 이벤트 저장소로는 도메인 저장소와 동일한 저장소인 RDBMS 를 선택하게 되었습니다.
 ### 데이터의 형태
 #### 이벤트 발행을 보장하기 위해 이벤트가 발행되었는지 확인할 수 있어야 한다.
 이벤트 발행에 대한 여부를 확인할 수 있도록 발행 여부 플래그가 필요했으며, 이벤트 자체에 대한 식별자가 필요했습니다.
 ```sql
 create table member_event
 (
    id            varchar(128) not null primary key,
    published     tinyint      not null,
    published_at  datetime     null,
    created_at    datetime     not null
 );
 create index ix_member_event_created_at_published
    on member_event (created_at, published);
 ```
 #### 특정 회원, 특정 행위, 특정 속성 변화, 특정 기간을 조회하여 재발행할 수 있어야 한다.
 다행히 이벤트 조회를 해결할 수 있는 일반화는 이미 진행되었었습니다. 바로 외부 이벤트 발행에서 입니다. "식별자"와 "행위", "속성", "이벤트 시간" 이 있다면 어떠한 시스템에서도 필요한 이벤트를 인지할 수 있다는 것을 알고 있습니다.
 "식별자"와 "행위", "속성", "이벤트 시간" 를 정의하여 이벤트 조회를 해결합니다.
 ```sql
 alter table member_event add member_number varchar(12) not null;
 alter table member_event add event_type varchar(255) not null;
 alter table member_event add attributes text not null;
 create index ix_member_event_event_type_created_at
    on member_event (event_type, created_at);
 create index ix_member_event_member_number
    on member_event (member_number);
 ```
 하나의 행위에서 여러 속성이 변화될 수 있습니다. 속성을 풀어서 외래키를 갖는 별도 테이블로 작성할 수 있겠지만, 이벤트-속성에 대한 카디널러티는 다소 작기 때문에 속성을 JSON 형태로 보관하고 어플리케이션에서 필터링하도록 설계하였습니다.
 - 회원 시스템은 이벤트 타입과 속성 타입의 N-M 관계를 정의하여 스팩 문서로 제공하고 있습니다.
 #### 사용자 활동 추적
 정의된 이벤트를 다시 살펴보았을 때 이벤트 저장소가 회원에 대한 모든 활동과 변화를 추적할 수 있는 데이터가될 수 있다는 것을 알게 되었습니다. **우리가 정의한 이벤트는 구독자의 필요로 의해 만들어진 이벤트가 아닌, 이벤트 스토밍을 통해 회원에게 발생할 수 있는 모든 이벤트를 정의하였기 때문입니다.**
 활동과 변화를 추적할 수 있는 데이터가 될 수 있도록 "수행 시스템", "수행 주체", "수행 사유" 를 추가로 기록하기로 했습니다. 또한 도메인의 상태 변화까지 추적할 수 있도록, 속성 타입 뿐만 아니라 속성 자체도 기록을 하기로 하였습니다.
 ```sql
 alter table member_event add reason text not null;
 alter table member_event add event_channel varchar(36) not null;
 alter table member_event add requested_by varchar(36) not null;
 ```
 **이렇게 문제 해결을 위한 저장소 스키마가 구성되었습니다.**
 ### 문제해결
 #### 이벤트 발행 보장
 이벤트 발행에 대한 보장이 필요한 지점은 **내부 이벤트를 발행하는 과정** 이었습니다. 최초 이벤트를 기록할 때는 발행 여부를 `false`로 저장하고, 두번째 구독자 계층에 이벤트 발행 여부를 기록하는 구독자를 추가하여 데이터를 업데이트 처리하였습니다.
 이 때 이벤트 발행 여부를 기록하는 구독자는 이벤트의 ID만 있다면 처리할 수 있습니다. 모든 이벤트의 `super class`를 정의하여 모든 이벤트가 이벤트 ID를 가지도록 만들었습니다.
 ```java
 public abstract class EventPayload {
    private final String eventId;
 }
 ```
 구독자는 이벤트의 공통 페이로드를 사용하므로, 모든 `SNS`의 이벤트를 하나의 `Queue`를 통해 구독하여 처리할 수 있습니다.
 ```java
@SqsListener(value = "${sqs.event-publish-record}", deletionPolicy = SqsMessageDeletionPolicy.ON_SUCCESS)
 public void recordEventPublish(@Payload EventPayload eventPayload) {
    eventPublishRecordCommand.record(eventPayload.getEventId());
 }
 ```
 **1) 도메인 이벤트가 발생할 때 `첫번째 계층의 이벤트 저장 구독자` 는 트랜잭션을 확장하여 도메인 행위와 함께 이벤트가 저장소에 저장되게 됩니다.**
 **2) `첫번째 계층의 SNS 발행 구독자`는 `AFTER_COMMIT` 옵션으로 인해 도메인의 트랜잭션이 정상 처리되었을 때 SNS로 내부이벤트를 발행하게 됩니다.**
 **3) `두번째 계층의 이벤트 발행 기록 구독자`는 내부이벤트를 수신하여 이벤트가 정상 발행되었음을 기록합니다.**
 이제 내부 이벤트가 메시징 시스템으로 정상 발행되었다면 반드시 이벤트의 발행여부가 업데이트될 것 입니다.
 우리는 이벤트 발행이 누락된 케이스를 사람이 감지하는 것이 아닌 시스템이 감지하여 자동으로 재발행할 수 있도록 배치 프로그램을 구성했습니다.
 이 배치 프로그램은 이벤트 저장 시간을 기준으로 5분이 지나도 발행처리 되지 않은 이벤트를 SNS 에 재발행 합니다.
 - 5분을 기준으로 한 이유는 `AWS SQS`의 재시도 처리가 최대 5분까지 진행될 수 있도록 설정을 해두었기 때문입니다.
 - 이 배치 프로그램은 직접 이벤트의 상태를 변경하지 않습니다. 이벤트를 재발행하여 메시징 시스템에 정상적으로 전달이 된다면 이벤트 발행 처리 구독자에 의해 구독 처리가 될 것이기 때문입니다.
 **4) 정상 발행되지 않은 이벤트는 `이벤트 발행 감지 배치` 를 통해 자동 재발행 처리됩니다.**
 **이렇게 이벤트 저장소와 발행 처리 구독자, 배치 프로그램을 통해 메시지 발행이 보장되는 이벤트 시스템을 구축하였습니다.**
 #### 이벤트 재발행
 이벤트 저장소에 모든 이벤트가 남아있기 때문에 이벤트 저장소를 통해 모든 이벤트를 재발행할 수 있습니다.
 이를 쉽게 처리할 수 있는 배치 프로그램을 구성했습니다.
 `기간` `특정 행위` `특정 속성` `특정 회원` `특정 이벤트` 의 조건을 통해 `내부 이벤트` `외부 이벤트`를 선택하여 이벤트를 발행할 수 있도록 하였습니다.
 > TIP. **SNS 속성을 이용하여 특정 구독자 계층으로 이벤트 전송하기**
 >
 > `AWS SNS` 의 속성을 기반으로 구독자마다 이벤트를 필터링할 수 있는 기능을 사용할 수 있습니다.
 >
 > 모든 SNS 속성에 "target" 이라는 속성을 정의하였습니다.
 >
 > 각 구독자에게 고유 ID 를 발급하고, `target` 에 대한 조건으로 `고유 ID`, `ALL` 을 정의합니다.
 >
 > `ALL` 은 모든 구독자에게 대한 공통 속성으로 모든 이벤트를 구독받게 하기 위함입니다.
 >
 > 평상시에는 `target` 속성에 `ALL` 타입을 사용하여 모든 구독자가 이벤트를 사용할 수 있도록 발급을 하며, 특정 구독자로 발행이 필요한 이벤트는 배치시스템에서 `고유 ID` 를 `target` 속성에 작성하여 발행하도록 합니다.
 >
 > 이 방법을 통해 특정 구독자로만 이벤트를 발행하는 메커니즘을 만들 수 있습니다.
 #### 기록 테이블 통합
 회원시스템은 개인정보를 처리하는 시스템으로 데이터 조회에 대한 많은 요구사항을 가지고 있습니다.
 고객센터 인입 문제를 해결을 위해, 부정 사용자를 추적하기 위하여, 수사 기관의 협조를 하기 위하는 등 회원의 활동을 추적할 수 있어야 합니다. 그래서 회원시스템에는 이 요구사항을 수행하기 위한 수십개의 기록 테이블이 존재하였습니다.
 이벤트 저장소를 구축함으로써 회원에 대한 모든 활동이 일관성있는 방식으로 저장되었고, 이로 인해 더 이상 별도 기록 테이블들이 필요하지 않게 되었습니다.
 ---
 이벤트 저장소까지 구축하며 회원시스템의 이벤트기반 아키텍처 만들기는 완료되었습니다.
 ## 마무리
 회원은 대부분의 시스템에 존재하는 도메인입니다. 어떤 시스템에나 존재하는 가장 평범한 도메인이기도 하지만, 동시에 모든 도메인이 회원을 의존하지 않을 수 없는 가장 중심적인 도메인이기도 합니다. 또한 개인정보를 집중적으로 다루고 있는 가장 치명적인 도메인이기도 합니다.
 MSA 의 가장 중심에 위치한 회원 도메인이 외부 시스템에 의한 영향이 없기 위한, 외부 시스템에 영향을 주지 않기 위한, 회원의 개인정보를 안전하게 다루기 위한 고민 끝에 이러한 이벤트 기반의 아키텍처가 만들어졌습니다.
 MSA 중심에서 가장 안정적인 시스템이기 위한 회원시스템의 고민은 계속되고 있습니다.
@@ -0,0 +1,31 @@
 # 통과 기준이 되는 글 여섯 편
 우아한형제들 기술블로그에서 가져왔다. **이 저장소의 글이 이 정도로 읽히면 통과다.**
 | 파일 | 원문 | 무엇을 보나 |
 |---|---|---|
 | `17386-kafka-in-our-team.md` | [17386](https://techblog.woowahan.com/17386/) | 개념을 모르는 독자를 데리고 가는 법. 용어 정의 → 우리 사례 |
 | `20161-elasticsearch-query-optimization.md` | [20161](https://techblog.woowahan.com/20161/) | 현상 → 원인 분석 → 해결 → 개선 결과를 다섯 번 반복 |
 | `22396-real-distance-system.md` | [22396](https://techblog.woowahan.com/22396/) | 왜 이 문제가 어려운지를 수로 먼저 세운다. 시도 1 실패 → 시도 2 |
 | `7835-member-event-architecture.md` | [7835](https://techblog.woowahan.com/7835/) | 같은 코드를 네 번 고쳐 보이며 「왜 아직 부족한가」를 쌓는다 |
 | `13569-10x-faster-batch.md` | [13569](https://techblog.woowahan.com/13569/) | 수정 전/후 코드를 나란히. 빨라져서 생긴 문제까지 |
 | `23625-rdb-task-queue.md` | [23625](https://techblog.woowahan.com/23625/) | 요구사항 목록 → 표 설계 → 트레이드오프 (본문 일부) |
 `23625` 는 페이지가 자바스크립트로 그려져 본문 일부만 받았다. 나머지 다섯은 전문이다.
 ## 이 여섯 편의 공통 골격
 여섯 편이 서로 다른 주제인데도 같은 뼈대를 쓴다. `../references/article-shape.md` 가 그 뼈대를
 규칙으로 적은 것이다.
 1. **누가 읽으면 좋은지, 무엇을 알아야 하는지 먼저 말한다** — 17386 의 「누가 읽으면 좋을까」
 2. **문제를 수로 세운다** — 22396 의 「분당 20만 건 × 6 = 120만 건, 초당 2만 TPS」
 3. **코드를 보여 준다. 이름과 줄 번호로 대신하지 않는다** — 13569 의 수정 전/수정 후 전문
 4. **틀린 시도를 지우지 않는다** — 22396 의 「시도 1. 데이터 압축」이 실패한 채로 남아 있다
 5. **결과를 수로 닫는다** — 20161 의 「980ms → 104ms」, 13569 의 「390분 → 30분」
 6. **감수한 것을 적는다** — 23625 의 「트레이드오프」, 22396 의 TTL 대 명시적 삭제 표
 ## 쓰지 않는 방법
 이 글들을 흉내 내지 않는다. 문체를 베끼면 남의 목소리가 된다. 보는 것은 **골격과 밀도**다 —
 독자가 모르는 것을 어디서 채워 주는가, 주장 하나에 근거를 몇 개 대는가, 코드를 언제 꺼내는가.
@@ -0,0 +1,139 @@
 # 밀도 — 설명을 어디까지 하는가
 순서는 [document-skeleton.md](document-skeleton.md)가 맡는다. 이 문서는 **한 절 안을 무엇으로
 채우는가**를 맡는다. 순서가 맞는데도 얇게 읽히는 글이 있고, 그것이 이 저장소가 실제로 겪은 문제다.
 기준이 되는 글은 [`../examples/`](../examples/) 여섯 편이다.
 ## 잰 값
 `scripts/density.mjs`로 잰 것이다. **글 한 편과 기록 본문은 다른 잣대로 본다.** 기록은 문제·결론·
 검증 환경·재현 조건을 Studio 칸이 따로 들고 있고, 본문의 `##`는 「본문」 칸 아래라 층이 한 단
 낮다. 그래서 본문은 절대값이 아니라 밀도로 잰다 — 절 하나가 몇 낱말인가, 1,000 낱말에 수치가
 몇 개인가.
 | | 여섯 편 (글 한 편) | 기록 본문 기준 |
 |---|---|---|
 | 낱말 | 1,277 ~ 2,871 | — |
 | 문장 평균 낱말 | 14.2 ~ 18.3 | 14.2 ~ 18.3 |
 | 코드블록 | 1 ~ 13 | 1 ~ 13 |
 | 표 줄 | 0 ~ 15 | 0 ~ 15 |
 | 절당 낱말 | 160 ~ 718 | 160 ~ 718 |
 | 1,000 낱말당 수치 | 측정 글 10.2 ~ 13.8 · 구조 글 0.9 ~ 1.7 | 측정 9 ~ 45 · 구조 0.8 ~ 8 |
 고치기 전 AP4 본문은 절 하나가 68 낱말, 수치는 본문 전체에 1개, 표 37줄이었다. 손대지 않은
 `clean-architecture-backend-template` 기록들은 지금도 **절 하나가 31 낱말**이다. 갈리는 것은 셋이다.
 ## 1. 수치 — 크기를 말하지 않으면 독자는 판단할 수 없다
 여섯 편은 문단마다 잰 값을 댄다. 구조만 말하고 크기를 말하지 않는 문단이 거의 없다.
 > 라이더에게 할당된 신규 배달이 N개라고 했을 때 … 간선: C(2N, 2)개
 > n=2, C(4, 2) = 6 … 분당 20만 건의 경로를 계산해야 한다면, 시스템은 분당 120만 건의
 > 실거리 계산을 수행해야 합니다. 이는 초당 약 2만 건으로 … (22396)
 세는 과정을 보여 준다. 결과만 적지 않는다. 이 절이 없으면 뒤에 나오는 Redis 자료구조 선택이
 과한 짓처럼 읽힌다.
 **무엇을 세는가.** 자료에 있는 것 중에서 고른다 — 몇 개인가, 몇 번 도는가, 몇 바이트인가,
 몇 밀리초인가, 몇 곳에서 부르는가, 그중 몇이 프로덕션인가, 전과 후가 각각 얼마인가.
 **없으면 만들지 않는다.** 재지 않았으면 「재지 않았다」로 적고 그 자리를 비운다. 다만 자료에
 숫자가 있는데 「여러 곳」·「대부분」·「크게」로 뭉갠 자리는 되돌린다. 그것이 이 저장소가 가장
 자주 하는 실수다.
 ## 2. 절 — 잘게 자르면 설명이 자리를 못 잡는다
 여섯 편의 `##` 절은 4~9개다. 절 하나가 600~900 낱말인 것도 있다.
 한 절은 **주장 하나 + 그 근거**다. 근거는 코드·출력·수치·표 중 하나 이상이다. 절이 문단
 두 개로 끝나면 자른 자리가 틀린 것이므로 앞뒤와 합친다.
 절 제목은 그 절이 무엇을 하는지 말한다. 「현상」·「문제 원인 분석 및 해결」·「개선 결과」처럼
 일하는 이름이 낫다. 「같은 이름의 헤더」처럼 명사구만 두면 무엇을 할 절인지 알 수 없다.
 ## 3. 표 — 산문을 대신하지 못한다
 표는 **이미 산문으로 말한 것을 대조할 때** 쓴다. 22396의 TTL 표는 앞 세 문단이 설명한 것을 두
 열로 정리한 것이고, 20161의 개선 전/후 표도 마찬가지다.
 표로 설명을 시작하면 독자가 각 칸을 스스로 풀어야 한다. 표 줄이 산문 문단보다 많으면 그 글은
 명세서다.
 ## 코드는 이름과 줄 번호로 대신하지 않는다
 읽는 사람은 그 파일을 열 수 없다. `InboxCleanupJob:56`이라고만 적으면 독자에게는 아무 일도
 일어나지 않는다.
 13569는 「수정 전」과 「수정 후」 메서드를 통째로 싣는다. 7835는 같은 `login` 메서드를 두 번
 싣는다 — 비관심사가 섞인 판과 분리한 판. 20161은 문제의 ES 쿼리 전문을 싣고 `1️⃣` `2️⃣`로 어디가
 문제인지 표시한다.
 코드블록 앞이나 뒤에 **무엇을 보라는 한 줄**을 붙인다. 코드만 던지지 않는다.
 인용할 코드가 길면 그 절에 필요한 부분만 자른다. 자른 자리는 `// …`로 표시한다. 자르는 것과
 이름만 대는 것은 다르다.
 ## 틀린 시도를 지우지 않는다
 22396은 「시도 1. 데이터 압축」을 실패한 채로 남긴다.
 > 하나의 지역에 1000개의 서로 다른 좌표 간 모든 실거리를 저장할 경우, JSON 데이터 원본
 > 크기는 약 24MB였으며, 압축한 크기는 3MB였습니다. 만약 최대 대역폭이 10Gbps라고 했을 때,
 > 3MB 크기로는 초당 3400회의 조회도 버티기 어렵습니다.
 실패도 수로 닫는다. 24MB → 3MB는 성공한 압축률인데, 그것으로도 모자란다는 것을 3400회로 보인다.
 자료에 실패한 시도가 있으면 살린다. 없는 실패를 지어내지 않는다.
 ## 감수한 것을 적고 닫는다
 좋아진 것만 적고 닫는 글은 여섯 편에 없다. 23625는 「트레이드오프」를 목록으로 적고, 22396은
 TTL 삭제와 명시적 삭제를 장단점 표로 나란히 놓고 **왜 단점이 있는 쪽을 골랐는지** 적는다.
 13569는 빨라져서 생긴 문제와 그 대응 코드까지 싣는다.
 ## 독자를 어디서 채워 주나
 **쓰기 직전에** 채운다. 앞에 몰아 두지 않고 뒤로 미루지도 않는다.
 > 여기서 이야기하는 네트워크 대역폭은, ElastiCache 노드가 네트워크를 통해 초당 전송할 수
 > 있는 최대 데이터 용량을 의미합니다. (22396 — 대역폭 이야기를 시작하는 자리)
 > track_scores : ES 검색 쿼리에서 각 문서의 관련성 점수(`_score`)를 계산하고 저장할지 여부를
 > 결정하는 설정 (20161 — 그 설정을 바꾼 절의 첫머리)
 기준은 하나다. **이 낱말을 모르면 다음 문단을 못 읽는가.** 그러면 한 줄로 편다.
 용어 절을 따로 두는 것은 그 글의 중심 개념일 때다(17386의 카프카 용어 일곱 개). 한두 개면
 쓰는 자리에서 푼다.
 ## 검사기를 만족시키려고 문장을 넣지 않는다
 이것은 겪은 일이다. `check_prose.mjs`의 `monotone-endings`가 「물음(~할까요?)·권유(~봅시다)를
 섞으라」고 안내했고, 그 글을 고친 사람이 절 제목을 물음으로 바꾸고 문단 가운데 수사 의문을 끼워
 넣었다. 수치는 통과했고 글에는 없던 화자가 생겼다.
 **종결어미 변화는 문장이 하는 일에서 나온다.** 한다체 안에도 어미는 여럿이다.
 | 문장이 하는 일 | 어미 |
 |---|---|
 | 확인한 것 | ~였다 · ~했다 · ~됐다 |
 | 지금 그러한 것 | ~한다 · ~된다 · ~넘긴다 |
 | 아닌 것 | ~아니다 · ~없다 · ~않는다 |
 | 이유 | ~때문이다 · ~뿐이다 · ~까지다 |
 | 값·이름으로 끝나는 문장 | 명사 종결 |
 물음은 그 절이 실제로 답할 때만 쓴다. 22396의 「왜 실거리가 중요할까?」·「어떤 내비게이션을
 사용할까?」는 그 절이 답하는 물음이라 제목으로 맞다. 답이 예·아니오뿐인 물음
 (「~인 걸까?」·「~되지 않을까?」)은 답하지 않고 분위기만 만든다. `rhetorical-question`이 잡는다.
 마무리도 같다. 「지금까지 ~를 살펴봤다」로 끝나면 앞 내용을 한 번 더 읽힌 것뿐이다. 17386은 그
 문장으로 마무리를 **열고** 회고와 참고 자료로 닫는다. 되풀이 뒤에 남은 일이 오면 두고, 되풀이가
 마무리의 전부면 지운다. `closing-recap`이 경고로 알린다.
 ## 낱말 수는 목표가 아니다
 설명을 다 하면 따라오는 값이다. 늘리려고 문단을 넣으면 검사기는 통과하고 글은 나빠진다.
 반대로 1,700 낱말짜리 글이 코드도 수치도 없이 표만 서른 줄이라면, 그것은 짧아서가 아니라
 **설명을 안 해서** 얇은 것이다.
@@ -0,0 +1,78 @@
 # 2026-08-28 Korean Engineering Blog Corpus Notes
 ## 조사 범위
 공개된 한국 기술 블로그 중 실제 서비스/시스템 개발 경험을 다루는 글을 중심으로 보았다.
 - NAVER D2 — 「네이버 통합 검색의 웹 성능 - 모니터링과 성능 개선」, 「생성형 AI 기반 실시간 검색 결과 재순위화 1편」, 검색 SRE 관련 글
 - 토스 기술 블로그 — 토스증권 실시간 데이터 파이프라인/Observability 시리즈, Gateway 관련 글
 - 우아한형제들 기술블로그 — 장시간 비동기 작업을 Kafka에서 RDB Task Queue로 재설계한 글, Kafka/분산락/개발환경 관련 글
 - 카카오테크 — 서버 개발자를 위한 운영툴 개발 등 실제 개발/운영 경험 글
 이 문서는 표현을 복사하는 자료가 아니라 공통 구조를 추출한 메모다.
 ## 반복해서 보인 서술 관행
 ### 1. 기술 이름보다 서비스 상황과 제약이 먼저 나온다
 글이 곧바로 프레임워크 장점을 나열하기보다 현재 시스템 규모, 기존 구조, 실제 운영 요구나 실패 상황을 먼저 설명한다. 기술 선택은 그 뒤의 문제 해결 수단으로 등장한다.
 편집 기준: 초안이 `X는 무엇인가`로 길게 시작하지만 실제 사건이 뒤에 있다면, 필요한 개념 설명만 남기고 사건/제약을 앞쪽으로 이동한다.
 ### 2. 해결책 전에 요구조건을 명시한다
 토스의 Observability 글과 우아한형제들의 장시간 작업 재설계 글처럼 해결안이 만족해야 할 조건을 목록/표로 먼저 고정하는 패턴이 자주 보인다. 이러면 선택 이유가 일반론이 아니라 제약과 연결된다.
 편집 기준: 선택을 설명할 때 자료에 있는 `제약 → 요구조건 → 선택` 연결을 살린다. 자료에 없는 요구조건을 새로 만들지는 않는다.
 ### 3. 문제는 관측된 현상과 원인 추적으로 이어진다
 NAVER D2의 웹 성능 글은 배포 시점의 변화, 지표, 원인 후보를 실제 관측 흐름에 연결한다. 우아한형제들의 Kafka 작업 글도 처리시간 증가 → poll 공백 → rebalance → 중복 처리로 사건을 이어 간다.
 편집 기준: `문제가 있었다` 뒤에 추상 평가를 늘리지 말고, 입력/상태 변화/관측 결과/원인 근거를 이어 쓴다.
 ### 4. 수치는 주장 장식이 아니라 비교 축이다
 성능 수치나 규모가 나오면 무엇과 무엇을 비교하는지, 어느 시점/조건에서 측정했는지가 같이 나온다. 숫자만 굵게 강조해 결론을 대신하지 않는다.
 편집 기준: 수치 근처에 측정 조건과 비교 대상을 유지한다. 근거 없는 정량 표현은 삭제한다.
 ### 5. 표와 그림은 산문을 대신할 축이 있을 때 쓴다
 요구사항, 전/후 비교, 구성요소, 여러 후보의 동일한 비교축처럼 행/열이 자연스러운 경우 표를 쓴다. 그림은 구조나 흐름을 보여주고, 본문은 그림에서 읽어야 할 변화나 의미를 설명한다.
 ### 6. 실제 글은 모든 절의 길이와 문형이 같지 않다
 배경은 짧고 핵심 실패 원인은 길 수 있으며, 자명한 결과는 한두 문장으로 끝난다. 모든 절을 `문제 → 원인 → 해결 → 장점` 네 문장으로 맞추지 않는다.
 ### 7. 1인칭은 실제 경험을 담을 때만 자연스럽다
 기업 기술 블로그는 `저희는`, `우리는`을 자주 쓰지만 이는 실제 작성자가 겪은 프로젝트 경험이 있기 때문이다. 코드 분석에서 그런 기록이 없는데 같은 장치를 흉내 내면 오히려 가짜 경험이 된다.
 편집 기준: source에 1인칭 경험이 없으면 객관적 관측 문장으로 쓴다.
 ### 8. 한계를 숨기지 않는다
 새 구조가 해결한 범위와 아직 남은 문제를 분리하는 글이 많다. 이것이 기술 선택을 과장하지 않게 만든다.
 편집 기준: 상세 분석의 `확인하지 않은 것`, `남은 질문`, `운영에서 별도 검증할 것`을 삭제하지 않는다.
 ### 9. 개념 설명은 현재 문제를 읽는 데 필요한 만큼만 끼워 넣는다
 Kafka, Gateway, LCP 같은 용어를 설명하더라도 백과사전식 장문이 아니라 이후 구조/문제를 이해하는 데 필요한 수준으로 제한한다.
 ### 10. 제목은 읽을 이유를 주되 본문보다 앞서 결론을 과장하지 않는다
 문제/구조/변화를 드러내는 제목은 많지만, 모든 절을 질문형이나 자극적인 카피로 만들지는 않는다. 핵심 기술 문단은 비교적 직접적이다.
 ## 조사한 공개 글
 - NAVER D2 — 네이버 통합 검색의 웹 성능 - 모니터링과 성능 개선: https://d2.naver.com/helloworld/8113611
 - NAVER D2 — 생성형 AI 기반 실시간 검색 결과 재순위화 1편: https://d2.naver.com/helloworld/2380720
 - 토스 기술 블로그 — 토스증권의 수 천개 실시간 데이터 파이프라인 운영방법 #2: https://toss.tech/article/MSA-observability
 - 토스 기술 블로그 — 토스는 Gateway 이렇게 씁니다: https://toss.tech/article/22910
 - 우아한형제들 기술블로그 — 장시간 비동기 작업, Kafka 대신 RDB 기반 Task Queue로 해결하기: https://techblog.woowahan.com/23625/
 - 우아한형제들 기술블로그 — 표준 개발 환경 개선 되돌아보기: https://techblog.woowahan.com/15572/
 - 카카오테크 — 서버 개발자를 위한 운영툴 개발: https://tech.kakao.com/posts/528
 URL은 조사 provenance를 남기기 위한 것이다. 특정 문장을 복사하거나 특정 필자의 어조를 목표로 삼지 않는다.
@@ -0,0 +1,7 @@
 # Korean Technical Writing Research
 한국어 엔지니어링 글의 편집 기준을 만들기 위한 공개 자료 조사 기록을 둔다.
 목적은 특정 회사나 필자의 문체를 복제하는 것이 아니다. 여러 기술 블로그에서 반복되는 **문제 제시, 근거 전개, 요구사항 명시, 측정 결과 연결, 한계 표기, 표/그림 사용 방식**을 추출해 `humanizing-korean-tech-writing` Skill에 반영한다.
 새 조사 결과는 날짜별 corpus note에 먼저 기록하고, 여러 출처에서 반복되는 패턴만 Skill의 durable rule로 승격한다.
@@ -19,7 +19,7 @@
 - [검색 성능 개선을 위한 Elasticsearch 인덱스 구조와 쿼리 최적화](https://techblog.woowahan.com/20161/) — `20161`
 - [나 4년 차 서버개발자, 배달의민족의 지리 체계를 뒤흔들다](https://techblog.woowahan.com/11238/) — `11238`
-이 다섯 편은 `scripts/style_profile.mjs`가 쓰는 기준선이기도 하다. 원문을 다시 받으려면
+이 다섯 편은 `scripts/style_profile.mjs`가 문체 수치를 재는 기준값이기도 하다. 원문을 다시 받으려면
 `node scripts/fetch_reference.mjs <디렉터리>`를 쓴다. 사이트가 curl과 리더 프록시를 403으로 막으므로
 실제 브라우저가 필요하고, `playwright-core`가 있어야 한다. 받은 뒤
 `node scripts/style_profile.mjs --baseline <디렉터리>/*.md`로 값을 다시 잰다.
@@ -0,0 +1,72 @@
 # Editorial Rules From Korean Engineering Writing
 These rules were distilled from multiple public Korean engineering blogs. They describe broad technical-writing habits, not a target author's style.
 ## Lead with the engineering situation
 When a draft spends several paragraphs defining a technology before stating why it appears, move the concrete service/code situation, constraint, failure, or measurement earlier. Keep only the concept explanation needed to follow that situation.
 Do not fabricate a `background story` merely to create an opening.
 ## Keep constraint → requirement → choice connected
 A credible choice is usually readable from its constraints. When the source contains requirements, put them close to the solution they rule in/out. Do not add generic benefits such as maintainability, scalability, security, or performance unless the source demonstrates that they mattered here.
 ## Write the observed chain, not a summary slogan
 Prefer:
 ```text
 input/condition → state change → observable result → evidence-backed cause
 ```
 over a paragraph that repeatedly says the architecture has a problem or responsibility.
 ## Make metrics carry context
 Keep the dataset, request shape, time window, before/after condition, or comparison axis next to a number. Do not turn a measurement into an adjective such as `크게`, `압도적으로`, `획기적으로` unless the source justifies that interpretation.
 ## Use tables only when there is a real axis
 Good table candidates:
 - requirement → reason;
 - before → after;
 - option → same comparison dimensions;
 - environment → observed result;
 - defined → not defined verification coverage.
 If every row needs a paragraph of caveats, prose may be clearer.
 ## Let section lengths differ
 Human engineering reports spend space where the difficult reasoning occurred. A two-line setup next to a long failure analysis is fine. Do not normalize all sections to the same number of paragraphs or bullets.
 ## Do not manufacture first person
 Public engineering blogs often use first person because their authors participated in the project. A code-derived document has no such license. Use `코드에서는`, `실행 결과에서는`, `이 구성에서는`, or the concrete component name unless source material contains a real first-person account.
 ## Preserve limitations
 Do not polish away `확인하지 않은 것`, `운영에서는 별도 검증`, failed attempts, excluded scope, or competing explanations. Those boundaries make the technical claim credible.
 ## Explain concepts at the point of use
 Introduce PKCE, LCP, Kafka rebalance, keyset pagination, etc. only to the depth needed for the next piece of reasoning. Avoid detached encyclopedia sections unless the record itself is a Reference that requires them.
 ## Prefer direct headings over forced questions
 Use headings that name the actual event, boundary, measurement, or change. Do not convert every heading to `왜 ...일까?`, `...해보자`, or rhetorical copy. A question heading is appropriate only when the section genuinely resolves that question.
 ## Vary rhythm by content, not by randomization
 Do not mechanically alternate short and long sentences. Instead:
 - keep a consequence close to its cause;
 - split a sentence when it contains two independently important actions;
 - keep a short sentence when a measured fact can stand alone;
 - combine fragments that only make sense together.
 ## Remove AI scaffolding
 Review expressions such as `중요한 점은`, `핵심은`, `결국`, `즉`, `다시 말해`, `이 지점에서`, `한편`, `정리하면`. They are not forbidden, but repeated use often means the previous sentence already said the same thing. Delete the scaffold before rewriting the substance.
@@ -0,0 +1,33 @@
 # Protected Content
 Editorial work must preserve these exactly unless the source itself is being corrected with new evidence:
 - numeric values and signs;
 - dates and times;
 - versions;
 - units;
 - commands and command arguments;
 - code and configuration;
 - file/module/class/method names when used as identifiers;
 - URLs and paths;
 - HTTP status/error codes;
 - test names and assertions;
 - observed terminal/browser output;
 - direct quotations;
 - decision/question status;
 - distinctions between observed fact, inference, assumption, unknown, and recommendation.
 ## Meaning-preservation checks
 After editing, compare original and revised record and ask:
 1. Did any condition (`when`, `only if`, environment, topology, dataset) disappear?
 2. Did `can/may` become `does/will`?
 3. Did a local/test observation become a production/general claim?
 4. Did an unresolved question sound answered?
 5. Did a proposed decision sound adopted?
 6. Did a measured value lose its measurement context?
 7. Did a failure/limitation disappear because it made the paragraph less tidy?
 8. Did the rewrite invent a motivation or personal history?
 If yes, restore the lost distinction before further stylistic changes.
@@ -0,0 +1,10 @@
 # Research Method
 Use this when updating the editorial skill from public Korean engineering writing.
 1. Sample several companies and several technical domains; do not build rules from one writer.
 2. Prefer implementation/incident/performance/operations articles over recruiting or marketing posts.
 3. Record structural observations: how the problem is introduced, where constraints appear, how measurements are tied to claims, how alternatives and limitations are handled, and when tables/diagrams replace prose.
 4. Do not copy distinctive phrases, jokes, metaphors, or signature expressions.
 5. Promote a pattern into `editorial-rules.md` only when it appears useful across multiple sources and is compatible with evidence-preserving Tech Log writing.
 6. Keep source notes under `./research/korean-tech-writing/`; runtime editing must work even if the websites are unavailable later.
@@ -13,6 +13,16 @@ import { readFileSync } from 'node:fs';
 const ERR = 'error', WARN = 'warn';
 // 관형형 어미 `-ㄴ`·`-ㄹ` 이 붙은 음절. 「적힌」·「만들」처럼 받침이 ㄴ 이나 ㄹ 인 글자를
 // 코드포인트로 만든다. 「두 자리」·「세 자리」 같은 자릿수는 앞 글자에 받침이 없어 빠진다.
 const ADNOMINAL = (() => {
  const out = [];
  for (let cho = 0; cho < 19; cho++)
    for (let jung = 0; jung < 21; jung++)
      for (const jong of [4, 8]) out.push(String.fromCharCode(0xAC00 + cho * 588 + jung * 28 + jong));
  return out.join('');
 })();
 const RULES = [
  { id: 'idiom-follow', sev: ERR, re: /[를을]\s*(따라갔|따라\s*늘|따라\s*증가|좇았|좇아)/g,
    msg: '개수에 `따라가다/좇다`를 붙였습니다. `~에 비례해`, `~가 커지는 만큼`, `~와 같은 수로`, 또는 값을 그대로 적으세요.' },
@@ -28,6 +38,40 @@ const RULES = [
  { id: 'wrap-up', sev: ERR, re: /(이\s*(관찰|결과|측정)은[^.\n]{0,40}(보여준|드러낸|말해\s*준)|이는[^.\n]{0,30}보여준다)/g,
    msg: '방금 보여 준 것을 다시 선언합니다. 지우세요.' },
  // 마무리가 되풀이로 끝나는 것을 본다. 17386 은 「지금까지 ~ 소개했습니다」로 열고 회고로
  // 닫으므로 그 자체는 defect 가 아니다. 뒤에 남은 일이 오는지는 사람이 본다 — 그래서 경고다.
  { id: 'closing-recap', sev: WARN,
    re: /(지금까지|여기까지)[^.\n]{0,80}(살펴봤|살펴보았|알아봤|알아보았|소개했|정리했|다뤘|다루었)/g,
    msg: '앞 내용을 다시 늘어놓았습니다. 이 뒤에 남은 일이나 감수한 것이 오면 두고, 이것으로 끝나면 지우세요.' },
  // 검사기의 종결어미 수를 채우려고 끼워 넣는 물음. 「왜 ~할까?」·「어떤 ~할까?」처럼 그 절이
  // 실제로 답하는 물음은 참고 글도 쓴다(22396). 잡는 것은 답이 예·아니오뿐인 수사 의문이다.
  { id: 'rhetorical-question', sev: ERR,
    re: /[^\n?]{4,60}([가-힣]\s*걸까\?|지\s*않을까\?|[가-힣]\s*게\s*아닐까\?|[가-힣]\s*것일까\?)/g,
    msg: '답이 예·아니오뿐인 물음을 끼워 넣었습니다. 종결어미 수를 채우려고 넣은 문장이면 지우고, 답할 물음이면 무엇을 묻는지 적으세요.' },
  // 역할을 세어 대칭을 만들고 닫는 문장. 「하나가 나머지 둘을 대신하지 못한다」·「각각 다른 구간을
  // 맡는다」·「그 자리를 메우지 못한다」. 참고 여섯 편에 한 건도 없다. 무엇이 실제로 통과하는지를
  // 말하지 않고 구조가 정연하다는 인상만 남긴다.
  { id: 'role-symmetry', sev: ERR,
    re: /(나머지\s*(둘|셋|하나)[^.\n]{0,20}(대신|자리|메우)|어느\s*하나도[^.\n]{0,25}(대신|자리)|각각\s*다른\s*[가-힣]{1,8}(을|를|에서|에)\s*(맡|쓰이|담당)|그\s*자리를\s*(대신|메우)|서로\s*독립된\s*[가-힣\d]{1,6}\s*곳|만으로는[^.\n]{0,40}(속성|성질)을\s*대신)/g,
    msg: '역할을 세어 대칭을 만들었습니다. 그것 하나만 있을 때 무엇이 실제로 통과하는지 적으세요.' },
  // 무엇이 어디서 일어나는지를 「자리」로 대신한다. 「적힌 자리가 없다」·「그 자리에서 푼다」·
  // 「검사기가 자리다」. 참고 여섯 편에 한 건도 없다(자리 0 · 옆 0 · 칸 0). 곳·부분으로 바꾸거나,
  // 애초에 장소가 아니라 순서·동작이면 그것을 적는다.
  // 관형형 어미와 지시어 뒤만 본다. 「앞 두 자리」 같은 자릿수는 걸리지 않는다.
  { id: 'spatial-metaphor', sev: ERR,
    re: new RegExp(`(?:[${ADNOMINAL}]|는|던|[그이저])\\s*자리`, 'g'),
    msg: '`자리`로 설명했습니다. 장소를 뜻하면 `곳`·`부분`으로 바꾸고, 장소가 아니면 거기서 무엇이 일어나는지 동사로 적으세요.' },
  // 할 일이나 노출을 「그대로 남아 있다」로 닫는다. 누가 무엇을 해야 하는지 말하지 않고 상태만
  // 보고한다. 참고 여섯 편에 한 건도 없다 — 그 글들의 「남아있다」 3건은 의존관계가 실제로 남는
  // 것이라 형태가 다르다. 값·쿠키가 진짜 남는 문장은 걸리지 않는다.
  { id: 'leftover-state', sev: ERR,
    re: /(그대로\s*남[아는])|((일|것|부분|점|과제|몫)(은|이|도)\s*(아직\s*)?남[아는])|(아직\s*남아\s*있)/g,
    msg: '무엇이 「남아 있다」로 닫았습니다. 누가 무엇을 해야 하는지, 또는 무엇을 아직 막지 못하는지로 적으세요.' },
  { id: 'nominalized', sev: ERR, re: /(채워진\s*목록\s*수|준비한\s*SQL\s*문장|획득한[^.\n]{0,10}객체\s*수|[가-힣]+에\s*대한\s*(측정|비교|확인|분석))/g,
    msg: '사건을 명사구로 바꿨습니다. 동사로 적으세요.' },
@@ -59,10 +103,25 @@ const ACRONYM_OK = new Set([
  'CANCEL','GREEN','RED','TODO','NOTE','CODE','BLOCK','AND','OR','NOT','NULL','TRUE','FALSE',
 ]);
 // YAML frontmatter 는 글쓴이가 고르는 문장이 아니라 **계약에서 옮겨 온 메타데이터**다.
 // 여기에 문장 규칙을 걸면 고칠 수 없는 error 가 나고, 글쓴이는 통과하려고 **칸을 지운다** —
 // 실제로 `topicName: 측정이 거짓말하는 자리` 가 spatial-metaphor 로 잡혀 그 주제의 기록들이
 // 그 칸 없이 저장됐다. 줄 번호는 유지한 채 비운다.
 function stripFrontMatter(src) {
  const m = /^---\r?\n[\s\S]*?\r?\n---(\r?\n|$)/.exec(src);
  if (!m) return src;
  return m[0].replace(/[^\n]/g, ' ') + src.slice(m[0].length);
 }
 function strip(src) {
-  return src
+  return stripFrontMatter(src)
    .replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, ' '))
-    .replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
+    .replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length))
    // 표와 인용은 「쓰지 않는다」 예시가 사는 자리다. 규칙을 적은 문서가 그 규칙을 어긴 것으로
    // 잡히지 않게 줄을 통째로 비운다. 줄 번호는 유지한다.
    .split('\n')
    .map((line) => (/^\s*(\||>)/.test(line) ? ' '.repeat(line.length) : line))
    .join('\n');
 }
 function positiveChecks(text, lines, docMode, rulesMode) {
@@ -94,32 +153,82 @@ function positiveChecks(text, lines, docMode, rulesMode) {
    // 문서 어디에든 `약어(...)` 형태가 있으면 푼 것으로 본다
    if (!new RegExp(a + '\\s*\\(').test(text)) {
      out.push({ id: 'unexpanded-acronym', sev: WARN,
-        msg: `약어 \`${a}\`을(를) 글 어디에서도 풀지 않았습니다. 처음 나오는 자리에 \`${a}(전체 이름, 우리말 뜻)\`으로 폅니다.` });
+        msg: `약어 \`${a}\`을(를) 글 어디에서도 풀지 않았습니다. 처음 나오는 곳에 \`${a}(전체 이름, 우리말 뜻)\`으로 폅니다.` });
    }
  }
  // 3. 종결어미가 한 가지뿐인가
  //
  // 한다체 문서는 `한다`·`였다`·`아니다`·`없다`·명사 종결이 전부 다른 어미다. 이것을 한 덩어리로
  // 세면 잘 쓴 한다체 글이 단조롭다고 잡히고, 고치려는 사람은 물음표 문장을 끼워 넣게 된다.
  // 실제로 그렇게 됐다. 그래서 어미를 잘게 센다.
  const kinds = new Set();
  for (const st of sentences) {
    if (/(습니다|았습니다|었습니다)[.!]?$/.test(st)) kinds.add('습니다');
    if (/입니다[.!]?$/.test(st)) kinds.add('입니다');
    if (/(했다|이다|였다|된다|한다)[.!]?$/.test(st)) kinds.add('한다');
    if (/(겠습니다|하겠습니다|보겠습니다)[.!]?$/.test(st)) kinds.add('겠습니다');
    if (/(한다|된다|만든다|넘긴다|받는다)[.!]?$/.test(st)) kinds.add('한다');
    if (/(했다|였다|됐다|되었다|았다|었다)[.!]?$/.test(st)) kinds.add('했다');
    if (/(아니다|없다|같다|다르다|이다)[.!]?$/.test(st)) kinds.add('이다');
    if (/(못한다|않는다|않았다|못했다)[.!]?$/.test(st)) kinds.add('부정');
    if (/(뿐이다|때문이다|까지다|것이다)[.!]?$/.test(st)) kinds.add('설명');
    if (/[가-힣A-Za-z0-9`)\]]$/.test(st.replace(/[.!]$/, ''))) kinds.add('명사');
    if (/까요\??$/.test(st) || /\?$/.test(st)) kinds.add('물음');
    if (/(봅시다|보자|맙시다|주세요)[.!]?$/.test(st)) kinds.add('청유');
  }
  // 3-1. 문장을 「~것이 ~이다」로 닫는 버릇
  //
  // 사건을 서술하는 대신 그것이 무엇인지 이름 붙이고 끝낸다. 「확인한 자리다」·「~하는 실례다」·
  // 「~라는 점이다」. 참고 여섯 편은 이 어미를 통틀어 세 번 쓴다(17386 1 · 22396 2). 한 문서에
  // 이것이 몰려 있으면 사건을 적지 않고 분류만 한 것이다.
  // 「자리다」·「실례다」·「경우다」는 받침이 없어 `이`가 붙지 않는다. `이다` 만 찾으면 정작
  // 가장 나쁜 세 개를 놓친다 — 처음 이 규칙을 넣었을 때 그렇게 됐다.
  const namingEnd = [
    ...text.matchAll(/[가-힣)\]`]\s*(사실|이유|점|것|뿐|셈)(이다|입니다)[.!]?(?=\s|$)/g),
    ...text.matchAll(/[가-힣)\]`]\s*(자리|실례|경우|출발점|사례|대목)(다|이다|입니다)[.!]?(?=\s|$)/g),
  ];
  const alwaysBad = namingEnd.filter((m) => /(자리|실례|출발점|대목)/.test(m[1]));
  for (const m of alwaysBad) {
    out.push({ id: 'naming-instead-of-telling', sev: ERR, index: m.index,
      excerpt: text.slice(Math.max(0, m.index - 30), m.index + m[0].length),
      msg: '무슨 일이 있었는지 적는 대신 그것이 무엇인지 이름 붙이고 닫았습니다. 거기서 실제로 일어나는 일을 동사로 적으세요.' });
  }
  if (!rulesMode && namingEnd.length >= 4) {
    out.push({ id: 'naming-instead-of-telling', sev: ERR,
      msg: `문장을 「~것이 ~이다」로 닫은 곳이 ${namingEnd.length}군데입니다(참고 여섯 편은 글 하나에 0~2회). `
         + `분류하지 말고 거기서 무엇이 일어나는지 적으세요.` });
  }
  if (!rulesMode && sentences.length >= 8 && kinds.size <= 1) {
    out.push({ id: 'monotone-endings', sev: ERR,
-      msg: `문장 ${sentences.length}개가 모두 같은 종결어미입니다. 예고(~살펴보겠습니다)·물음(~할까요?)·권유(~봅시다)를 섞습니다.` });
+      msg: `문장 ${sentences.length}개가 모두 같은 종결어미입니다. 문장이 하는 일이 다르면 어미도 달라집니다 — `
         + `확인한 것은 ~였다, 지금 그러한 것은 ~한다, 아닌 것은 ~아니다, 이유는 ~때문이다. `
         + `물음이나 권유를 끼워 넣어 수를 채우지 마세요.` });
  }
  // 4. 독자를 데리고 다니는 문장
  const steer = /(살펴보|알아보|파보|확인해\s*봅|정리해\s*보|소개해\s*보|다뤄\s*보|짚어\s*보|나중에\s*살펴|딴 길로|먼저[^\n]{0,25}부터|이번에는|공유합니다|공유하고자|다루겠습니다|보겠습니다|하겠습니다)/;
-  // 강제하지 않는다. 강제했더니 `먼저 ~를 구분해야 합니다` 같은 지도형 문장이 절마다 붙어서
+  // 안내 문장이 없다고 경고하지 않는다. 그 경고가 「필요하면 하나 두라」로 읽혀 평가·안내 문장을
-  // 문장이 아니라 구조가 기계처럼 읽히게 됐다.
+  // 보태는 쪽으로 작용했다. 문서는 대상을 설명하지 독자의 읽기를 지시하지 않는다.
-  if (!rulesMode && !steer.test(text)) {
+
-    out.push({ id: 'no-reader-steering', sev: WARN,
+  // 문장이 끝나지 않은 채 문단이 끝나는 줄 — 지우다 남은 조각이거나 마침표가 빠진 것.
-      msg: '독자를 안내하는 문장이 없습니다. 필요하면 하나 두되, 없어도 됩니다.' });
+  // 연결어미·조사로 끝나고 다음 줄이 비어 있을 때만 잡는다. 문단 안에서 줄을 바꾼 것은
  // 다음 줄이 이어지므로 걸리지 않는다. 줄 끝에 인라인 코드가 있었으면(strip 이 공백으로
  // 바꿔 둔 자리) 판단할 수 없으니 건너뛴다. 「이름 : 값」 줄도 문장이 아니라 건너뛴다.
  const DANGLING = /(때|고|며|면|를|을|는|은|이|가|에서|으로|에|와|과|도|서|아|어|지|니|라서|라|의)$/;
  let inFront = lines[0] === '---';
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (inFront) { if (i > 0 && line === '---') inFront = false; continue; }
    const t = line.trimEnd();
    if (!t.trim() || t !== line) continue;                       // 빈 줄 · 끝에 공백(인라인 코드 자리)
    if (/^\s*(#|-|\*|\d+\.|:::|<!--|\||>)/.test(t) || t.includes(' : ')) continue;
    const next = (lines[i + 1] ?? '').trim();
    if (next !== '') continue;                                    // 문단이 이어진다
    if (DANGLING.test(t)) {
      out.push({ id: 'dangling-sentence', sev: ERR, line: i + 1,
        msg: `문장이 끝나지 않은 채 문단이 끝납니다("…${t.slice(-24)}"). 지우다 남은 조각이거나 마침표가 빠졌습니다.` });
    }
  }
  // 독자에게 사고를 지시하는 문장 — 사건으로 바로 들어가면 될 자리
@@ -0,0 +1,105 @@
 #!/usr/bin/env node
 // 글이 얼마나 채워져 있는지 잰다. 문체가 아니라 밀도를 본다.
 //
 //   node density.mjs 초안.md [...]      기준값과 나란히 보여 준다
 //   node density.mjs --baseline dir/*.md  기준값을 다시 잰다
 //
 // 기준값은 ../examples 의 여섯 편에서 잰 것이다. 맞히려고 문단을 넣지 않는다 —
 // 낮게 나오면 설명이 빠진 자리를 찾으라는 뜻이지 분량을 늘리라는 뜻이 아니다.
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 // examples 의 여섯 편에서 잰 값. 23625 는 본문 일부만 받아서 낱말 수 기준에서 뺐다.
 const BASE = {
  words: [1277, 2871], sentWords: [14.2, 18.3], code: [1, 13],
  sections: [4, 9], tableLines: [0, 15],
 };
 // Tech Log 기록의 본문은 글 한 편이 아니라 그 가운데 토막이다. 문제·결론·검증 환경·재현 조건은
 // Studio 칸이 따로 들고 있고, 본문의 `##` 는 「본문」 칸 아래라 층이 한 단 낮다. 그래서 절 수와
 // 낱말 수를 절대값으로 재면 잘 쓴 본문이 「절이 모자람」으로 잡힌다.
 // 대신 밀도로 본다 — 절 하나가 몇 낱말인가, 1,000 낱말에 수치가 몇 개인가.
 //   여섯 편: 절당 160 ~ 718 낱말 · 측정 글은 1,000 낱말에 10.2 ~ 13.8 개
 const BODY = {
  sentWords: [14.2, 18.3], code: [1, 13], tableLines: [0, 15],
  wordsPerSection: [160, 718],
 };
 const BODY_NUM_RATE = { 측정: [9, 45], 구조: [0.8, 8] };
 // 수치 개수는 장르가 가른다. 잰 것을 쓰는 글과 구조를 쓰는 글의 기준이 다르다.
 //   측정 글 13569(13) · 23625(18) · 20161(24) · 22396(36)
 //   구조 글 17386(2) · 7835(5)
 const NUMBERS = { 측정: [13, 36], 구조: [2, 12] };
 const NUM = /\d[\d,.]*\s*(?:ms|초|분|시간|일|년|개월|주|배|%|건|개|줄|번|회|명|자|KB|MB|GB|TB|Gbps|TPS|QPS|만|천|억)/g;
 function measure(text) {
  // 본문 마커부터 찾는다. 주석을 먼저 지우면 마커도 같이 지워진다 — 그러면 Studio 칸까지
  // 세게 되고, 기록 하나가 절 아홉 개인 것처럼 보인다.
  const marked = text.match(/<!-- body:start -->([\s\S]*?)<!-- body:end -->/);
  let t = marked ? marked[1] : text.replace(/^---\n.*?\n---\n/s, "");
  t = t.replace(/<!--.*?-->/gs, "");
  const code = (t.match(/^```/gm) || []).length / 2;
  const tableLines = (t.match(/^\s*\|/gm) || []).length;
  const sections = (t.match(/^## /gm) || []).length;
  const prose = t.replace(/```[\s\S]*?```/g, "").replace(/^\s*\|.*$/gm, "");
  const words = prose.split(/\s+/).filter(Boolean).length;
  const sentences = prose.split(/(?<=[.!?다])\s+/).filter((s) => s.trim().length > 10);
  const numbers = (t.match(NUM) || []).length;
  const proseParas = prose.split(/\n\s*\n/).filter((p) => p.trim().length > 40).length;
  return { isBody: Boolean(marked), words,
           sentWords: +(words / Math.max(sentences.length, 1)).toFixed(1),
           code, numbers, sections, tableLines, proseParas,
           wordsPerSection: Math.round(words / Math.max(sections, 1)),
           numberRate: +((numbers / Math.max(words, 1)) * 1000).toFixed(1) };
 }
 const args = process.argv.slice(2);
 // 잰 것을 쓴 글인가 구조를 쓴 글인가. Case 는 측정, Concept 은 `--구조` 로 부른다.
 const genre = args.includes("--구조") ? "구조" : "측정";
 const files = args.filter((a) => !a.startsWith("--"));
 if (args.includes("--baseline")) {
  const all = files.map((f) => measure(readFileSync(f, "utf8")));
  const range = (k) => [Math.min(...all.map((m) => m[k])), Math.max(...all.map((m) => m[k]))];
  for (const k of [...Object.keys(BASE), "numbers"]) console.log(`  ${k}: [${range(k)}]`);
  process.exit(0);
 }
 if (!files.length) {
  console.error("쓰는 법: node density.mjs [--구조] 초안.md");
  process.exit(2);
 }
 const LABEL = { words: "낱말", sentWords: "문장 평균 낱말", code: "코드블록",
                numbers: "수치", sections: "## 절", tableLines: "표 줄",
                wordsPerSection: "절당 낱말", numberRate: "1,000 낱말당 수치" };
 let bad = 0;
 for (const file of files) {
  const m = measure(readFileSync(file, "utf8"));
  const where = m.isBody ? "기록 본문" : "글 한 편";
  console.log(`\n${basename(file)}   (${where} · ${genre} 글 기준)`);
  const bands = m.isBody
    ? { ...BODY, numberRate: BODY_NUM_RATE[genre] }
    : { ...BASE, numbers: NUMBERS[genre] };
  for (const [k, [lo, hi]] of Object.entries(bands)) {
    const v = m[k];
    const ok = v >= lo && v <= hi;
    const note = ok ? "" : v < lo ? "  ← 모자람" : "  ← 넘침";
    if (!ok && k !== "words" && k !== "code") bad++;
    console.log(`  ${LABEL[k].padEnd(16)} ${String(v).padStart(6)}   기준 ${lo}~${hi}${note}`);
  }
  if (m.tableLines > m.proseParas)
    console.log(`  ! 표 ${m.tableLines}줄이 산문 ${m.proseParas}문단보다 많다 — 표가 설명을 대신하고 있다`);
  const rateLo = m.isBody ? BODY_NUM_RATE[genre][0] : null;
  if (rateLo !== null && m.numberRate < rateLo)
    console.log(`  ! 1,000 낱말에 수치가 ${m.numberRate}개다 — 자료에 있는 크기를 「여러」·「대부분」으로 뭉갠 자리를 찾는다`);
  if (!m.isBody && m.numbers < NUMBERS[genre][0])
    console.log(`  ! 수치가 ${m.numbers}개다 — 자료에 있는 크기를 「여러」·「대부분」으로 뭉갠 자리를 찾는다`);
  if (m.wordsPerSection < 160)
    console.log(`  ! 절 하나가 ${m.wordsPerSection} 낱말이다 — 문단 두세 개짜리 절을 앞뒤와 합친다`);
 }
 process.exit(bad ? 1 : 0);
@@ -22,7 +22,9 @@ const BASE = {
 // 산문만 남긴다. 코드블록·표·제목·목록·링크주소·인라인코드는 문장이 아니다.
 function strip(src) {
-  let t = src;
+  // frontmatter 는 산문이 아니다. 빼지 않으면 그 블록 하나가 길이 398자짜리
  // 「문장」으로 세어져 avgLen · longRatio 를 통째로 흔든다 (실측)
  let t = src.replace(/^---\n[\s\S]*?\n---\n/, '');
  // 짝이 맞는 코드펜스 제거
  t = t.replace(/```[\s\S]*?```/g, '\n');
  // 짝이 안 맞는 펜스(구획을 중간에서 잘랐을 때): 남은 펜스부터 끝까지 버린다
@@ -53,7 +55,13 @@ export function profile(raw) {
  for (const s of sents) {
    if (/(습니다|았습니다|었습니다)[.!]?$/.test(s)) kinds.add('습니다');
    if (/입니다[.!]?$/.test(s)) kinds.add('입니다');
-    if (/(했다|이다|였다|된다|한다)[.!]?$/.test(s)) kinds.add('한다');
+    // 한다체 안에도 어미는 여럿이다. 한 덩어리로 세면 잘 쓴 한다체 글이 1점을 받고,
    // 점수를 올릴 길이 물음·청유밖에 남지 않아 없던 화자가 생긴다. 실제로 그렇게 됐다.
    if (/(한다|된다|만든다|넘긴다|받는다)[.!]?$/.test(s)) kinds.add('한다');
    if (/(했다|였다|됐다|되었다|았다|었다)[.!]?$/.test(s)) kinds.add('했다');
    if (/(아니다|없다|같다|다르다|이다)[.!]?$/.test(s)) kinds.add('이다');
    if (/(못한다|않는다|않았다|못했다)[.!]?$/.test(s)) kinds.add('부정');
    if (/(뿐이다|때문이다|까지다|것이다)[.!]?$/.test(s)) kinds.add('설명');
    if (/(겠습니다|보겠습니다)[.!]?$/.test(s)) kinds.add('겠습니다');
    if (/\?$/.test(s)) kinds.add('물음');
    if (/(봅시다|보자|맙시다|주세요)[.!]?$/.test(s)) kinds.add('청유');
@@ -65,6 +73,7 @@ export function profile(raw) {
  // 백틱 안(식별자)은 빼고, 맨몸으로 쓰인 영문만 센다
  const bare = raw
    .replace(/^---\n[\s\S]*?\n---\n/, ' ')   // frontmatter 는 산문이 아니다
    .replace(/```[\s\S]*?```/g, ' ')
    .replace(/<!--[\s\S]*?-->/g, ' ')      // HTML 주석(techviz 등)은 산문이 아니다
    .replace(/<\/?[a-zA-Z][^>]*>/g, ' ')   // <details>, <summary> 같은 태그
@@ -72,7 +81,10 @@ export function profile(raw) {
    .replace(/`[^`\n]*`/g, ' ')
    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1');
  const PROPER = /^(Redis|Nginx|Hibernate|Spring|Actuator|Keycloak|PostgreSQL|Java|Gradle|Lettuce|Kubernetes|Docker|OAuth|Sentinel|Lua|SQL|API|TTL|ACL|TLS|HTTP|JSON|YAML|CI|AI|DB|ID|URL)$/i;
-  const engWords = (bare.match(/[A-Za-z][A-Za-z0-9_.-]{1,}/g) || []).filter(w => !PROPER.test(w));
+  // 분자와 분모가 같은 글을 봐야 「문장당」이 뜻을 갖는다. 문장 수는 strip() 이 목록을
  // 걷어낸 `text` 에서 세는데 영문은 `bare`(목록 포함)에서 세고 있었다 — 본문이 거의
  // 목록인 Question 기록에서 이 비율이 구조적으로 부풀었다 (실측 11.94)
  const engWords = (text.match(/[A-Za-z][A-Za-z0-9_.-]{1,}/g) || []).filter(w => !PROPER.test(w));
  // 한글 비율은 글쓴이가 고를 수 있는 산문만 본다. 백틱 안 식별자는 보호 구간이라 제외한다.
  const hangul = (bare.match(/[가-힣]/g) || []).length;
  const letters = (bare.match(/[가-힣A-Za-z]/g) || []).length || 1;
@@ -0,0 +1,208 @@
 ---
 name: running-tech-log-pipeline
 description: Use when a codebase must go all the way to a saved Tech Log Studio draft — running the seven stages (SSOT, tree, record, diagram, prose, voice, Studio save) as separate subagents, one skill per stage, with a run ledger that records which skill each stage actually used and which gate it passed.
 metadata:
  version: "1.0.0"
  language: "ko-KR"
 ---
 # Tech Log 파이프라인 실행
 ## 이 스킬이 하는 일
 스킬 일곱 개를 **한 줄기로 잇는다.** 각 스킬은 자기 단계만 알고 앞뒤를 모른다. 이 스킬이
 단계 사이의 인계물과 순서와 관문을 정하고, 단계마다 **서브에이전트를 하나씩 띄운다.**
 한 실행이 남기는 것은 산출물과 **런 원장**(`runs/<프로젝트>/<runId>/run.json`) 둘이다.
 원장은 단계마다 어떤 스킬을 실제로 읽었고 어떤 관문을 어떤 종료 코드로 지났는지를 적는다.
 `python3 scripts/verify-pipeline-run.py <원장>` 이 그 원장을 검사한다.
 **원장이 이 스킬의 존재 이유다.** 스킬을 안 읽고 쓴 글과 읽고 쓴 글은 결과물만 봐서는
 구분되지 않는다. 원장은 그것을 기계가 구분할 수 있게 만든다.
 ## 왜 단계마다 서브에이전트인가
 한 세션이 일곱 단계를 이어서 하면 앞 단계의 문맥이 뒤 단계로 새어 든다. 그러면 세 가지가
 망가진다.
 - **스킬을 안 읽고도 그럴듯하게 쓴다.** 3단계에서 본문 규칙을 읽었으니 5단계에서
  `rewriting-technical-prose-naturally` 를 열지 않아도 문장이 나온다. 스킬이 적용됐는지
  확인할 방법이 사라진다.
 - **관문이 형식이 된다.** 자기가 쓴 글을 자기가 검사하면 실패를 「이건 예외」로 넘긴다.
 - **어디서 어긋났는지 못 찾는다.** 결과가 이상할 때 일곱 단계 중 어디가 원인인지 가릴 수 없다.
 서브에이전트는 **자기 단계의 입력 파일과 자기 스킬만** 받는다. 다른 단계가 무엇을 했는지
 모른다. 그래서 스킬을 안 읽으면 못 쓰고, 못 쓰면 원장에 남는다.
 ## 일곱 단계
 | # | 단계 | 스킬 | 에이전트 | 산출물 |
 |---|---|---|---|---|
 | S1 | 코드베이스 → SSOT | `analyzing-codebase-for-tech-log` | `ssot-analyst` | `docs/<프로젝트>/final/document.md` |
 | S2 | SSOT → 분해 계약 | `deriving-tech-log-root-tree` | `tree-deriver` | `docs/<프로젝트>/tech-log-studio/tech-log-tree.json` |
 | S3 | 글감 → 기록 | `writing-tech-log-records` | `record-writer` | `.../<주제>/<종류>/<기록>.md` |
 | S4 | 기록 → 그림 | `technical-visualizer` | `diagram-maker` | `final/assets/<이름>/` · `final/.techviz/<이름>/` |
 | S5 | AI 티 제거 | `rewriting-technical-prose-naturally` | `prose-rewriter` | 같은 기록 파일 (제자리 수정) |
 | S6 | 일한 사람의 목소리 | `writing-as-the-person-who-did-it` | `voice-writer` | 같은 기록 파일 (제자리 수정) |
 | S7 | Studio 저장 | `publishing-tech-log-to-studio` | `studio-validator` | Studio 작업본 + `studio:` URL. **게시하지 않는다** |
 단계마다의 입력·관문·원장 칸은 [references/stage-contracts.md](references/stage-contracts.md).
 서브에이전트에 그대로 넣는 프롬프트는 [references/subagent-prompts.md](references/subagent-prompts.md).
 ## 에이전트를 그때그때 만들지 않는다
 단계마다 맡을 에이전트가 `.claude/agents/` 에 있다. `Agent` 도구의 `subagent_type` 에 위 표의
 이름을 준다.
 ```
 Agent(subagent_type="record-writer", prompt=<references/subagent-prompts.md 의 S3>)
 ```
 프롬프트만 새로 써서 일반 에이전트를 띄우면 **어떤 규칙으로 일했는지가 어디에도 안 남는다.**
 `skillEcho` 는 「스킬을 열었다」를 증명하지만 **누가 열었는지는 증명하지 않는다** — 매번 새로
 띄운 에이전트도 SKILL.md 를 읽고 한 줄을 옮겨 적을 수 있다. 그래서 원장의 `runBy` 가 이름을
 담고, 검사기가 계약과 대조한 뒤 그 `.md` 가 실재하는지까지 본다.
 **배정의 정본은 `scripts/verify-pipeline-run.py` 의 `STAGES` 다.** 틀(`templates/run.json`)에도
 같은 값이 적혀 있고, 둘이 갈리면 시험이 잡는다.
 에이전트 정의는 그 단계의 「하는 일 · **안 하는 일** · 관문 · 보고」를 적는다. 프롬프트가
 그것을 되풀이하지 않아도 되는 것이 이 방식의 값이다 — 프롬프트는 **이번 런의 입력 경로와
 글감**만 준다.
 **단계가 아닌 에이전트가 넷 더 있다.** 기록 한 편을 놓고 역할을 가른 것이라 아무 단계에도
 붙지 않는다. 부를지는 사람이 정하고, 원장의 단계 칸에는 안 들어간다.
 | 에이전트 | 언제 | 안 하는 일 |
 |---|---|---|
 | `source-auditor` | S3 앞. 원본의 주장을 `관측`·`추론`·`미검증`으로 가른 표를 만든다 | 기록을 안 쓴다 |
 | `fact-reviewer` | 쓴 뒤. 결과 문장을 원문과 한 글자씩 역대조한다 | 파일을 안 고친다 |
 | `reader-reviewer` | 쓴 뒤. 제목·요약·목차만 보고 30초 안에 읽히는지 본다 | 본문을 안 연다 |
 | `setup-runner` | Setup 을 쓴 뒤. 손으로 끝까지 칠 수 있는지 읽는다 | 실제로 치지는 않는다 |
 ## 순서가 고정된 곳
 세 자리는 바꾸면 결과가 틀어진다.
 **S3 → S4.** 그림은 기록을 쓴 다음에 만든다. 무엇을 그릴지는 기록 본문이 정하고
 (`writing-tech-log-records/references/choosing-a-diagram.md` 의 세 관문), 그림의 근거는 그
 기록의 `source` 앵커가 가리키는 SSOT 절이다. **기록 본문이 그림의 소재를 고르고, SSOT 절이
 그림의 사실을 댄다.** 기록 `.md` 를 `techviz prepare` 에 넣지 않는다 — 기록은 SSOT 의 인용이라
 줄 번호가 근거가 되지 못한다.
 **S4 → S5 → S6.** 문장 손질은 본문이 다 찬 뒤에 한다. 그림을 붙이면 본문에 그림을 읽는 문단이
 한둘 늘고, 그 문단도 같은 손질을 받아야 한다. S5 가 먼저다 — 번역투와 반복 문형을 걷어낸 뒤라야
 S6 이 채울 자리(선택·비교·어긋남)가 보인다. 순서를 뒤집으면 S5 가 S6 이 넣은 목소리를
 「과한 대구」로 다시 깎는다.
 **S6 → S7.** Studio 에는 문장 손질이 끝난 것만 넣는다. 저장한 뒤에 고치면 Studio 쪽 `version`
 이 올라가고 검증 산출물이 무효가 된다.
 ## S5·S6 뒤에는 S3 관문을 다시 돌린다
 문장을 고치면 본문 문법과 인용이 함께 움직인다. `check_prose` 가 error 0 이어도 `check_body`
 가 깨지거나, 고쳐 쓴 코드블록 한 줄이 SSOT 와 달라져 `check_evidence` 가 걸린다.
 ```bash
 python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
 node --experimental-transform-types \
  .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
 node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
 ```
 원장에서는 이것이 S5·S6 의 관문이지 S3 의 재실행이 아니다.
 ## 건너뛰어도 되는 단계
 이미 있는 것을 다시 만들지 않는다. 건너뛴 단계도 **원장에 `SKIPPED` 와 사유를 적는다.**
 적지 않고 빠뜨린 것과 판단해서 건너뛴 것을 구분해야 한다.
 | 단계 | 건너뛰는 조건 |
 |---|---|
 | S1 | `final/document.md` 가 있고 그 안에서 이 글감의 근거를 찾을 수 있다 |
 | S2 | `tech-log-tree.json` 에 이 글감이 `PROMOTE` · `CONFIRMED` 로 이미 있다 |
 | S4 | 그림이 필요 없다(세 관문에 걸린다) 또는 `ssot-assets` 가 배정한 그림이 이미 있다 |
 | S7 | 사용자가 Studio 반입을 요청하지 않았다 |
 **S3·S5·S6 은 건너뛰지 않는다.** 기록을 쓰는 단계와 문장을 고치는 두 단계는 이 파이프라인의
 산출물 자체다.
 ## 실행 절차
 ### 0. 런을 연다
 ```bash
 python3 scripts/verify-pipeline-run.py --init runs/<프로젝트>/<runId>/run.json \
  --project <프로젝트> --record <기록 경로>
 ```
 `runId` 는 `YYYY-MM-DD-HHMM` 이다. 원장의 틀은
 [templates/run.json](templates/run.json) 이고, `--init` 이 그 틀을 채워 놓는다.
 `--init` 은 단계마다 `skillRevision` 도 적는다 — 그 시점 그 스킬의 커밋이다. 스킬은
 나중에 고쳐지고, 그러면 이 런의 영수증(`skillEcho`)이 현재 SKILL.md 에서 사라진다.
 그 커밋이 적혀 있으면 검사기가 이력을 훑지 않고 그것 하나로 대조한다. 작업 트리가 그
 커밋과 다르면 `null` 이다 — 모르는 리비전을 지어내지 않는다. 칸이 없는 옛 원장은
 이력 훑기로 떨어지고, 그것도 정상이다.
 ### 1. 단계마다 서브에이전트를 띄운다
 에이전트는 위 표의 것을 쓴다 — `Agent(subagent_type="<이름>", ...)`. 새로 만들지 않는다.
 프롬프트는 [references/subagent-prompts.md](references/subagent-prompts.md) 의 것을 쓴다.
 프롬프트에 **반드시** 들어가야 하는 넷이 있다.
 1. **스킬 이름과 「먼저 그 SKILL.md 를 끝까지 읽어라」** — 요약을 주지 않는다. 요약을 주면
   에이전트가 스킬을 안 연다.
 2. **자기 단계의 입력 파일 경로만.** 앞 단계가 무엇을 했는지 설명하지 않는다.
 3. **관문 명령 원문과 「error 0 까지 고쳐라」.**
 4. **스킬 영수증** — 그 SKILL.md 에서 자기 단계에 해당하는 규칙 한 줄을 **원문 그대로**
   인용해 돌려보내게 한다. 이것이 스킬을 열었다는 기계 검증 가능한 증거다
   (`verify-pipeline-run.py` 가 그 문자열이 실제 SKILL.md 안에 있는지 대조한다).
 한 단계가 끝나면 그 결과를 원장에 적고 다음 단계를 띄운다. **단계를 병렬로 띄우지 않는다** —
 S1~S7 은 앞 단계의 산출물이 뒤 단계의 입력이다. 병렬이 되는 것은 같은 단계 안에서
 **서로 다른 기록 여러 건**을 처리할 때뿐이다.
 ### 2. 원장을 검사한다
 ```bash
 python3 scripts/verify-pipeline-run.py runs/<프로젝트>/<runId>/run.json
 ```
 error 0 이어야 런이 끝난 것이다. 이 검사기가 보는 것은 결과물의 품질이 아니라 **절차의
 준수**다 — 단계가 빠졌는지, 스킬 영수증이 그 스킬의 실제 문장인지, 관문이 돌았고 종료 코드가
 0 이었는지, 적어 낸 산출물이 디스크에 있는지.
 영수증은 셋이 아니라 **넷으로 갈린다.** 지금 SKILL.md 에 있으면 통과, 그 스킬의 과거
 커밋에만 있으면 warn(그 뒤에 스킬이 고쳐졌다 — 어느 커밋에 있었는지 함께 적는다), 어느
 판에도 없으면 error, 과거를 볼 수 없었으면(git 이 없다 · 이력 상한에 걸렸다) 또 다른
 warn 이다. **warn 은 통과가 아니다** — 요약 줄이 「대조 못 한 영수증」을 따로 센다.
 지난 런의 영수증이 warn 으로 바뀌었다고 원장을 고쳐 쓰지 않는다. 그것은 영수증이다.
 ### 3. 프로젝트 검사기를 돌린다
 ```bash
 python3 scripts/verify-tech-log-tree.py <프로젝트>
 python3 scripts/verify-project-layout.py <프로젝트>
 python3 scripts/audit-records.py <프로젝트>
 python3 scripts/check-figure-text.py <프로젝트>
 ```
 ## 이 스킬이 하지 않는 것
 - **판단을 대신하지 않는다.** 어떤 후보를 `PROMOTE` 할지, 그림이 필요한지, 어떤 종류인지는
  각 단계의 스킬이 정한다. 이 스킬은 그 스킬이 실제로 불렸는지만 본다.
 - **관문을 완화하지 않는다.** 관문이 error 를 내면 그 단계는 끝나지 않은 것이다. 원장에
  `FAILED` 로 적고 멈춘다. 다음 단계로 넘기지 않는다.
 - **게시하지 않는다.** S7 은 저장까지다. 게시는 사람이 공개 화면을 보고 판단한다.
 ## 자주 어긋나는 자리
 | 증상 | 원인 | 원장에 남는 모습 |
 |---|---|---|
 | 문장이 여전히 AI 같다 | S5 를 같은 세션이 겸했다 | `skillEcho` 가 비었거나 SKILL.md 에 없는 문장 |
 | 그림 안에 문장이 있다 | S4 가 `check-figure-text.py` 를 안 돌렸다 | 관문 목록에 그 명령이 없다 |
 | SSOT 에 없는 인용이 있다 | S3 이 앞 기록에서 코드를 옮겨 적었다 | `check_evidence` 종료 코드 ≠ 0 |
 | 기록이 색인에 없다 | S2 를 건너뛰고 S3 을 했다 | S2 가 `SKIPPED` 인데 사유가 없다 |
 | Studio 에서 그림이 안 보인다 | S7 이 Asset 을 올리기 전에 본문을 넣었다 | S7 관문에 미리보기 확인이 없다 |
 | 스킬은 열었는데 결과가 그 역할 같지 않다 | 일반 에이전트를 띄웠다 | `runBy` 가 계약 이름이 아니다 |
@@ -0,0 +1,267 @@
 # 단계 계약
 단계마다 다섯을 정한다 — **입력 · 스킬 · 에이전트 · 관문 · 산출물.** 원장에 적히는 것도
 이 다섯이다.
 **에이전트는 그때그때 만들지 않는다.** `.claude/agents/<이름>.md` 가 그 단계의 「하는 일 ·
 안 하는 일 · 관문 · 보고」를 적고 있고, `Agent` 도구의 `subagent_type` 에 그 이름을 준다.
 배정의 정본은 `scripts/verify-pipeline-run.py` 의 `STAGES` 이고, 원장의 `runBy` 가 그 이름을
 담는다 — 검사기가 계약과 대조한 뒤 그 `.md` 가 실재하는지까지 본다.
 관문은 종료 코드가 0 이어야 지난 것이다. 0 이 아니면 그 단계는 `FAILED` 이고 다음 단계로
 넘어가지 않는다.
 ---
 ## S1 — 코드베이스 → SSOT
 | | |
 |---|---|
 | 스킬 | `analyzing-codebase-for-tech-log` |
 | 에이전트 | `ssot-analyst` — `.claude/agents/ssot-analyst.md` |
 | 입력 | 분석 대상 저장소 경로(사용자가 준다) · 그 저장소의 `AGENTS.md`(있으면) |
 | 산출물 | `docs/<프로젝트>/final/document.md` |
 | 관문 | `python3 scripts/verify-project-layout.py <프로젝트>` |
 **분석 대상 저장소는 이 저장소 밖이다.** `docs/<프로젝트>` 는 이 저장소 기준이고, 분석 대상은
 사용자가 준 절대 경로다. 두 저장소를 섞지 않는다 — 대상 저장소를 고치지 않는다.
 **`analysis-queue.yaml` 은 여러 프로젝트를 줄 세울 때만 쓴다.** 사용자가 저장소 하나를
 지목했으면 큐 없이 그 하나를 분석한다. 큐가 있으면 큐가 정한 활성 프로젝트를 따른다.
 작업 재료(`analysis/` · `notes/` · `checkpoints/` · `state.json` · `source-index.md`)는 분석
 중에만 있고, 끝나면 `final/document.md` 로 합치고 지운다.
 ```bash
 python3 scripts/fold-analysis-into-final.py <프로젝트>
 ```
 **S2 가 무엇을 기대하는지 알고 쓴다.** S2 는 `final/document.md` 를 절 단위로 훑어 후보를
 찾는다. 절 제목이 무엇을 다루는지 말하지 않으면 후보가 안 잡힌다. 접어 넣은 문서라면
 제1부(통합 분석)가 후보 범위이고 제2·3부는 근거다.
 산출물이 이미 있고 이 글감의 근거가 그 안에 있으면 `SKIPPED` 로 적고 사유를 남긴다.
 ### 이미 접어 넣은 프로젝트를 다시 볼 때 — 대조 모드
 `final/document.md` 가 이미 있는 프로젝트에 S1 을 다시 돌리는 것은 **분석이 아니라 대조**다.
 스킬의 절차(작업 재료를 만들고 → 분석하고 → 접어 넣는다)를 그대로 밟으면 두 곳이 깨진다.
 - `docs/<프로젝트>/` 에 `state.json`·`analysis/` 를 만들면 배치 검사기가 error 로 센다.
  완료된 프로젝트의 폴더는 `final/` 과 `tech-log-studio/` 뿐이다.
 - `final/document.md` 를 고치면 `ssotSha256` 이 어긋나 분해 계약이 통째로 무효가 된다.
 그래서 대조 모드는 이렇게 돈다.
 | | 분석 모드 | 대조 모드 |
 |---|---|---|
 | 작업 재료 | `docs/<프로젝트>/analysis/` | `runs/<프로젝트>/<runId>/stage/S1/` |
 | SSOT | 만들거나 접어 넣는다 | **고치지 않는다.** 보강 후보만 적는다 |
 | 끝 조건 | fold 하고 재료를 지운다 | 어긋난 것·빠진 것을 목록으로 남긴다 |
 SSOT 가 코드와 **어긋나는** 것을 찾으면 그것은 보강 후보가 아니다. 크게 적고 사람에게
 올린다 — 이미 그 SSOT 를 근거로 쓴 기록이 있기 때문이다.
 ---
 ## S2 — SSOT → 분해 계약
 | | |
 |---|---|
 | 스킬 | `deriving-tech-log-root-tree` |
 | 에이전트 | `tree-deriver` — `.claude/agents/tree-deriver.md` |
 | 입력 | `docs/<프로젝트>/final/document.md` **하나** |
 | 산출물 | `docs/<프로젝트>/tech-log-studio/tech-log-tree.json` |
 | 관문 | `python3 scripts/build-tech-log-tree.py <프로젝트>` → `python3 scripts/verify-tech-log-tree.py <프로젝트>` (error 0) |
 `analysis/**` 를 후보를 찾으려고 열지 않는다. 분석에만 있는 자료를 발견하면 `final/document.md`
 를 먼저 보강한다.
 **검사기나 계약이 요구하는데 스킬의 절차가 안 적는 칸이 있다.** 손으로 채운다.
 | 칸 | 무엇 |
 |---|---|
 | `candidateScope` | 후보를 찾은 범위. 적지 않으면 모듈 분석 절 제목이 전부 글감이 된다 |
 | `sourceRepository` | 분석한 저장소의 경로·리비전·그렇게 판단한 근거. 모르면 `null`, 지어내지 않는다 |
 | `ssotSha256` | `build-tech-log-tree.py` 가 채운다. 그래서 build 를 먼저 돌리고 verify 를 돌린다 |
 | `ssot-assets` · `ssot-evidence` | SSOT 가 이미 그린 그림과 이미 돌린 측정을 글감에 배정한다. 계약 문서에만 있고 절차에는 이 단계가 없다 |
 | `candidateScope.excludedAnchorPattern` | 「범위 밖 글감」 검사가 이 칸으로 판정한다. 없으면 그 검사가 통째로 꺼진다 |
 `assetLedger` 는 계약이 요구하지만 스크립트 어느 것도 읽지 않는다. 사람이 보는 칸이다.
 **`source` 앵커의 형식이 어디에도 적혀 있지 않다.** keycloak 은 「h2 슬러그 + `-ap1`」 같은
 합성 앵커를 쓰고, 제목 슬러그를 쓴 프로젝트도 있다. 검사기는 SSOT 경로를 포함하는지만 보고
 실재하는 heading 으로 풀지 않는다. **한 프로젝트 안에서는 한 형식으로 통일한다** — S4 가
 `--heading` 값을 이 앵커에서 옮기기 때문이다.
 **검사기는 「후보 ↔ 글감」만 본다. 「SSOT ↔ 후보」는 안 본다.** 그래서 SSOT 에 있는 재료를
 후보 대장에 올리지도 않고 지나쳐도 error 가 0 이다. 범위의 절을 끝까지 읽는 것은 사람의 일이다.
 제외가 0 건인 분해는 선별하지 않은 분해다. 후보마다 처분(`PROMOTE`·`MERGE_INTO`·
 `KEEP_IN_SSOT`·`NEEDS_EVIDENCE`·`NEEDS_DECISION`)을 적고, 사람이 다시 읽은 것만
 `dispositionReview: CONFIRMED` 로 둔다.
 ---
 ## S3 — 글감 → 기록
 | | |
 |---|---|
 | 스킬 | `writing-tech-log-records` |
 | 에이전트 | `record-writer` — `.claude/agents/record-writer.md` |
 | 입력 | `tech-log-tree.json` 의 노드 하나 · 그 노드의 `source` 앵커가 가리키는 SSOT 절 |
 | 산출물 | `docs/<프로젝트>/tech-log-studio/<주제>/<종류>/<기록>.md` |
 | 관문 | 아래 셋 |
 ```bash
 python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
 node --experimental-transform-types \
  .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
 node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
 node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
 ```
 **노드가 `PROMOTE` 이고 `CONFIRMED` 인지 먼저 본다.** 아니면 쓰지 않는다.
 **인용한 줄은 SSOT 에서 찾아 대조한다.** 앞선 기록에서 옮겨 적은 것은 확인한 것이 아니다 —
 그렇게 게시된 기록에 SSOT 와 다른 redirect URI 가 네 곳 있었다.
 그림이 필요해 보이면 **`final/assets/` 에 이미 있는지부터 본다.** 계약의 `ssot-assets` 가 이
 글감에 배정한 그림이 있으면 그 파일을 그대로 가리킨다. 없을 때만 S4 로 넘긴다.
 ---
 ## S4 — 기록 → 그림
 | | |
 |---|---|
 | 스킬 | `technical-visualizer` |
 | 에이전트 | `diagram-maker` — `.claude/agents/diagram-maker.md` |
 | 입력 | S3 이 쓴 기록 `.md`(무엇을 그릴지) · 그 기록의 `source` 앵커가 가리키는 SSOT 절(그림의 사실) |
 | 산출물 | `final/.techviz/<이름>/{context.json,prompt.md,spec.json}` · `final/assets/<이름>/` |
 | 관문 | `techviz lint` · `check-figure-text.py` · `check-figure-overlap.py` · `preview-figure.py` 로 눈 확인 |
 **입력이 둘이라는 것이 이 단계의 전부다.**
 - **무엇을 그릴지는 기록 본문이 정한다.** 세 관문(자리가 Case·Concept 인가 · 표가 아닌가 ·
  옆 문단이 이미 말하지 않았는가)을 지나야 그린다. 그리고 **그림이 주장하는 것을 기록 본문이
  말해야 한다.** 본문이 안 적은 단계를 그림만 넣으면 설명 없는 주장이 남는다. 순서는
  본문을 먼저 보강하고 그다음 그림을 붙인다.
 - **그림의 사실은 SSOT 절이 댄다.** 기록은 SSOT 의 인용이라 줄 번호가 근거가 되지 못한다.
  `techviz prepare` 에는 `final/document.md` 를 넣고, 절은 기록의 `source` 앵커로 지목한다.
 ```bash
 ./scripts/techviz prepare docs/<프로젝트>/final/document.md \
  --heading "<기록의 source 앵커가 가리키는 절 제목>" \
  -o docs/<프로젝트>/final/.techviz/<이름>/context.json
 ```
 `--line` 은 쓰지 않는다. context 는 관리 블록을 접은 좌표를 쓰므로 파일 줄 번호와 어긋난다.
 **그림 안에는 이름만 넣는다.** 문장은 `<desc>` 와 옆 문단에 둔다. lint 는 이것을 못 잡는다 —
 `check-figure-text.py` 가 잡는다.
 **lint 는 좌표를 안 본다.** 관계가 이어져 있는지만 본다. 그래서 구역 둘이 겹쳐 그려지거나
 라벨이 상자에 먹혀도 통과한다. `check-figure-overlap.py` 가 그것을 본다.
 ```bash
 python3 scripts/check-figure-overlap.py <프로젝트>
 python3 scripts/check-figure-overlap.py --file 그림.svg
 ```
 **그래도 마지막에는 눈으로 본다.** 검사기가 보는 것은 배경 사각형의 좌표라, 글자가 상자
 밖으로 조금 나가거나 화살표가 라벨을 지나는 것은 못 잡는다.
 기록에 되적는다 — frontmatter `assets:` 에 `key` 와 `file`(=`final/assets/<이름>/<이름>.svg`)
 을 적고, 본문에는 마크다운 이미지로 넣는다. `:::evidence` 는 저장소에 쓰지 않는다. 사본을
 `tech-log-studio/` 쪽에 두지 않는다 — 사본에는 `.techviz/<이름>/` 이 없어 다시 못 만든다.
 ---
 ## S5 — AI 티 제거
 | | |
 |---|---|
 | 스킬 | `rewriting-technical-prose-naturally` |
 | 에이전트 | `prose-rewriter` — `.claude/agents/prose-rewriter.md` |
 | 입력 | S3·S4 를 지난 기록 `.md` (제자리 수정) |
 | 산출물 | 같은 파일 |
 | 관문 | `check_prose.mjs` error 0 · `style_profile.mjs` · S3 관문 재실행 |
 ```bash
 S=.agents/skills/rewriting-technical-prose-naturally/scripts
 node $S/check_prose.mjs --warn <기록.md>      # error 0 까지 고친다
 node $S/style_profile.mjs <기록.md>
 ```
 문서 전체를 다시 쓴 것이 아니면 `--doc` 을 빼고 부른다.
 **`density.mjs` 는 본문이 있는 종류에만 건다.** 그 기준은 글 한 편(낱말 1277+ · 코드블록 1+ ·
 수치 13+)을 잰 값이고, Reference·Question·Decision 은 칸이 평문이라 코드블록을 넣는 것 자체가
 규칙 위반이다. 본문 없는 종류에 걸면 구조적으로 통과할 수 없는 관문이 되고, 통과시키려면
 없는 측정값을 지어내야 한다.
 **문체 수치를 맞추려고 문장을 넣지 않는다.** 검사기는 표면 패턴만 보고 뜻은 못 본다.
 **보호 구간을 건드리지 않는다** — 수치·날짜·버전·단위·코드·명령어·URL·직접 인용·공식 명칭은
 원문과 한 글자도 달라지면 안 된다. 그래서 문장을 고친 뒤 `check_evidence.mjs` 를 다시 돌린다.
 ---
 ## S6 — 일한 사람의 목소리
 | | |
 |---|---|
 | 스킬 | `writing-as-the-person-who-did-it` |
 | 에이전트 | `voice-writer` — `.claude/agents/voice-writer.md` |
 | 입력 | S5 를 지난 기록 `.md` · **그리고 그 기록의 상류 자료** (SSOT · 커밋 메시지 · 주석 · `확인하지 못한 것` 칸) |
 | 산출물 | 같은 파일 |
 | 관문 | `check_voice.mjs` · `check_prose.mjs` 재실행 · S3 관문 재실행 |
 ```bash
 node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <기록.md>
 node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
 ```
 **S5 다음이다.** 번역투와 반복 문형을 걷어낸 뒤라야 채울 자리가 보인다. 그리고 이 스킬이
 넣은 문장을 `check_prose` 가 다시 본다 — 그래서 재실행이 관문이다.
 **자료에 흔적이 없으면 이 단계는 여기서 끝난다.** 없는 사람을 만들지 않는다. 「처음에는」·
 「고민 끝에」·「놀랍게도」를 자료 없이 쓰면 지어낸 것이다. 원장에는 `DONE` 에 「흔적 없음」을
 적는다 — `SKIPPED` 가 아니다. 찾아봤다는 것이 이 단계의 일이다.
 **`check_voice.mjs` 는 목소리가 모자란지 재지 않는다.** 지어낸 목소리를 잡는다. 조용하다고
 목소리가 생긴 것은 아니다.
 ---
 ## S7 — Studio 저장
 | | |
 |---|---|
 | 스킬 | `publishing-tech-log-to-studio` |
 | 에이전트 | `studio-validator` — `.claude/agents/studio-validator.md` |
 | 입력 | S6 을 지난 기록 `.md` · frontmatter `assets:` 가 가리키는 SVG |
 | 산출물 | Studio 작업본. 기록 frontmatter 의 `id`·`studio:` |
 | 관문 | 상태 레일이 `저장됨` · `python3 scripts/build-tech-log-tree.py` → `verify-tech-log-tree.py` |
 **저장까지다. 게시하지 않는다.**
 Asset 을 본문보다 먼저 올린다. 순서를 뒤집으면 미리보기가 본문 전체를 막는다.
 바뀐 것이 없으면 저장 버튼을 누르지 않는다 — 누를 때마다 `version` 이 올라가고 앞서 만든
 검증·미리보기 산출물이 무효가 된다.
 ---
 ## 관문 요약
 | 단계 | 에이전트 | 명령 |
 |---|---|---|
 | S1 | `ssot-analyst` | `verify-project-layout.py <프로젝트>` |
 | S2 | `tree-deriver` | `build-tech-log-tree.py` → `verify-tech-log-tree.py` (error 0) |
 | S3 | `record-writer` | `studio-body.py` → `check_body.mjs` · `check_prose.mjs` · `check_evidence.mjs --repo` |
 | S4 | `diagram-maker` | `techviz lint` · `check-figure-text.py` · `check-figure-overlap.py` · `preview-figure.py` (눈 확인) |
 | S5 | `prose-rewriter` | `check_prose.mjs` (error 0) · `style_profile.mjs` · S3 관문 |
 | S6 | `voice-writer` | `check_voice.mjs` · `check_prose.mjs` · S3 관문 |
 | S7 | `studio-validator` | `저장됨` 확인 · `build-tech-log-tree.py` → `verify-tech-log-tree.py` |
@@ -0,0 +1,305 @@
 # 서브에이전트 프롬프트
 단계마다 에이전트를 하나 띄운다. 아래를 그대로 쓰고 `<...>` 만 바꾼다.
 **에이전트를 새로 만들지 않는다.** 단계마다 맡을 에이전트가 `.claude/agents/` 에 있고,
 `Agent` 도구의 `subagent_type` 에 그 이름을 준다. 절마다 첫 줄에 적혀 있다.
 ```
 Agent(subagent_type="record-writer", prompt=<아래 S3 프롬프트>)
 ```
 에이전트 정의가 그 단계의 「하는 일 · 안 하는 일 · 관문 · 보고」를 이미 적고 있다. 그래서
 프롬프트는 **이번 런의 입력 경로와 글감**을 준다 — 아래 것을 그대로 쓰되, 정의와 어긋나는
 지시를 프롬프트로 덮어쓰지 않는다.
 ## 모든 프롬프트에 들어가는 넷
 1. **스킬 이름과 「SKILL.md 를 끝까지 먼저 읽어라」.** 요약을 주지 않는다. 요약을 주면
   스킬을 안 연다.
 2. **자기 단계의 입력 경로만.** 앞 단계가 무엇을 했는지 설명하지 않는다.
 3. **관문 명령 원문.** 「검사해라」가 아니라 붙여 넣을 수 있는 명령을 준다.
 4. **스킬 영수증** — SKILL.md 에서 한 줄을 **원문 그대로** 인용해 돌려보내게 한다.
   `verify-pipeline-run.py` 가 그 문자열이 실제 파일 안에 있는지 대조한다.
 ## 돌려받는 형식 (모든 단계 공통)
 ```json
 {
  "stage": "S3",
  "skill": "writing-tech-log-records",
  "skillEcho": "<SKILL.md 에서 그대로 옮긴 한 줄>",
  "status": "DONE",
  "outputs": ["docs/keycloak/tech-log-studio/.../case-x.md"],
  "gates": [{"cmd": "node ... check_body.mjs /tmp/studio-body.md", "exit": 0}],
  "notes": "<판단한 것과 못 한 것>"
 }
 ```
 `skillEcho` 를 지어내지 말라고 프롬프트에 적는다. 파일에 없는 문장이면 검사기가 잡는다.
 ## 파일을 쓰라고 할 때는 방법을 함께 준다
 서브에이전트의 `Write` 는 「보고는 파일이 아니라 글로 돌려라」는 기본 정책에 막힐 수 있다.
 S1 처럼 산출물이 `.md` 인 단계는 그래서 한 줄을 더한다.
 ```
 파일을 쓸 때 Write 툴이 막히면 Bash heredoc (`cat > 경로 <<'EOF'`) 을 써라.
 ```
 이것을 안 적으면 에이전트가 산출물을 만들지 못하고 본문에 통째로 붙여 돌려준다.
 ---
 ## S1 — 코드베이스 → SSOT
 **에이전트:** `ssot-analyst` — `subagent_type="ssot-analyst"`
 ```
 너는 Tech Log 파이프라인의 1단계를 맡는다.
 먼저 .agents/skills/analyzing-codebase-for-tech-log/SKILL.md 를 끝까지 읽어라.
 references/ 아래 문서도 그 스킬이 읽으라는 것을 읽어라. 요약본은 주지 않는다.
 대상 저장소: <절대 경로>
 쓸 곳: docs/<프로젝트>/
 analysis-queue.yaml 이 없으면 이 저장소 하나만 분석한다. 큐가 없다는 이유로 멈추지 마라.
 대상 저장소를 고치지 마라. 읽기만 한다.
 끝나면 분석 재료를 SSOT 로 합쳐라:
  python3 scripts/fold-analysis-into-final.py <프로젝트>
 합친 뒤 analysis/ · notes/ · checkpoints/ · state.json · source-index.md 를 지운다.
 관문:
  python3 scripts/verify-project-layout.py <프로젝트>
 error 0 이 될 때까지 고쳐라.
 돌려줄 것 (JSON):
  stage, skill, skillEcho, status, outputs, gates, notes
 skillEcho 는 방금 읽은 SKILL.md 에서 네 작업에 해당하는 규칙 한 줄을 원문 그대로 옮긴 것이다.
 지어내지 마라 — 파일에 그 문자열이 있는지 기계가 대조한다.
 ```
 ---
 ## S2 — SSOT → 분해 계약
 **에이전트:** `tree-deriver` — `subagent_type="tree-deriver"`
 ```
 너는 Tech Log 파이프라인의 2단계를 맡는다.
 먼저 .agents/skills/deriving-tech-log-root-tree/SKILL.md 를 끝까지 읽어라.
 references/candidate-disposition.md 와 references/decomposition-checklist.md 도 읽어라.
 출력 계약은 .agents/skills/writing-tech-log-records/references/tech-log-tree-contract.md 다.
 입력: docs/<프로젝트>/final/document.md — 이것 하나다.
 analysis/** 를 후보를 찾으려고 열지 마라.
 출력: docs/<프로젝트>/tech-log-studio/tech-log-tree.json
 검사기가 error 로 요구하는데 스킬 본문이 안 적는 칸 셋을 손으로 채워라:
  candidateScope   — 후보를 찾은 범위
  sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 모르면 null 로 두고 지어내지 마라
  ssotSha256       — build 가 채운다. 그래서 build 를 먼저 돌린다
 제외가 0 건인 분해는 선별하지 않은 분해다. 후보마다 처분을 적고, 다시 읽은 것만
 dispositionReview: CONFIRMED 로 둬라.
 관문:
  python3 scripts/build-tech-log-tree.py <프로젝트>
  python3 scripts/verify-tech-log-tree.py <프로젝트>
 error 0 까지 고쳐라.
 돌려줄 것: 위 JSON 형식. skillEcho 포함.
 ```
 ---
 ## S3 — 글감 → 기록
 **에이전트:** `record-writer` — `subagent_type="record-writer"`
 ```
 너는 Tech Log 파이프라인의 3단계를 맡는다.
 먼저 .agents/skills/writing-tech-log-records/SKILL.md 를 끝까지 읽어라.
 그 스킬이 가리키는 references/ 중 네 종류에 해당하는 것을 읽어라 —
 record-kinds.md · writing-each-kind.md · body-syntax.md · code-tables-diagrams.md ·
 explaining.md · ai-tells.md · choosing-a-diagram.md.
 **종류가 Setup 이면 본문을 쓰기 전에 `Skill` 도구로 `writing-practitioner-guides` 를 연다.**
 명령을 어떤 형태로 쓸지는 그 스킬이 정한다 — 사람이 직접 치는 실습 가이드이지 에이전트가
 실행하기 편한 명령이 아니다. **그 스킬을 못 열면 Setup 을 쓰지 말고 그 사실을 돌려줘라.**
 안 열고 쓴 Setup 은 검사기를 다 지나면서도 실행이 중간에 끊긴다 — 실제로 그렇게 나갔다.
 글감: docs/<프로젝트>/tech-log-studio/tech-log-tree.json 의 <주제> / <종류> / "<제목>"
 그 노드가 PROMOTE 이고 dispositionReview 가 CONFIRMED 인지 먼저 확인해라. 아니면 쓰지 마라.
 근거: 그 노드의 source 앵커가 가리키는 docs/<프로젝트>/final/document.md 의 절.
 인용하는 줄은 SSOT 에서 찾아 대조해라. 기억이나 다른 기록에서 옮겨 적지 마라.
 쓸 곳: docs/<프로젝트>/tech-log-studio/<주제>/<종류>/<파일>.md
 그림이 필요해 보이면 docs/<프로젝트>/final/assets/ 에 이미 있는지부터 봐라.
 없으면 이 단계에서 만들지 말고 notes 에 "그림 필요: <무엇을>" 이라고 적어라. 4단계가 만든다.
 관문:
  python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
  node --experimental-transform-types \
    .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
  node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
  node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
 error 0 까지 고쳐라.
 돌려줄 것: 위 JSON 형식. skillEcho 포함.
 ```
 ---
 ## S4 — 기록 → 그림
 **에이전트:** `diagram-maker` — `subagent_type="diagram-maker"`
 ```
 너는 Tech Log 파이프라인의 4단계를 맡는다.
 먼저 두 개를 읽어라:
  .agents/skills/technical-visualizer/SKILL.md — 끝까지
  .agents/skills/writing-tech-log-records/references/choosing-a-diagram.md
 기록: <기록.md>
 이 기록을 읽고 무엇을 그릴지 정해라. 세 관문을 지나야 그린다 —
 자리가 Case·Concept 인가 / 표로 될 것이 아닌가 / 옆 문단이 이미 말하지 않았는가.
 그리고 그림이 주장하는 것을 이 기록 본문이 말하고 있어야 한다. 본문이 안 적은 단계를
 그림만으로 넣지 마라.
 그림의 근거는 기록이 아니라 기록의 source 앵커가 가리키는 SSOT 절이다:
  ./scripts/techviz prepare docs/<프로젝트>/final/document.md \
    --heading "<그 절 제목>" \
    -o docs/<프로젝트>/final/.techviz/<이름>/context.json
 --line 은 쓰지 마라.
 그림 안의 <text> 는 전부 이름이어야 한다. 문장은 <desc> 와 옆 문단에 둬라.
 관문:
  ./scripts/techviz lint docs/<프로젝트>/final/.techviz/<이름>/spec.json \
    --context docs/<프로젝트>/final/.techviz/<이름>/context.json
  python3 scripts/check-figure-text.py <프로젝트>
  python3 scripts/check-figure-overlap.py <프로젝트>
  python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs
 마지막 것은 PNG 로 떠서 라벨이 상자를 덮지 않는지 눈으로 봐라. lint 는 그것을 못 잡는다.
 기록에 되적어라 — frontmatter assets: 에 key 와 file, 본문에는 마크다운 이미지.
 :::evidence 를 저장소 .md 에 쓰지 마라.
 돌려줄 것: 위 JSON 형식. skillEcho 포함. 그리지 않기로 했으면 status 를 SKIPPED 로 하고
 어느 관문에 걸렸는지 적어라.
 ```
 ---
 ## S5 — AI 티 제거
 **에이전트:** `prose-rewriter` — `subagent_type="prose-rewriter"`
 ```
 너는 Tech Log 파이프라인의 5단계를 맡는다.
 먼저 .agents/skills/rewriting-technical-prose-naturally/SKILL.md 를 끝까지 읽어라.
 그 스킬이 "첫 rewrite 전에 읽으라"고 지정한 references 세 개도 읽어라 —
 document-skeleton.md · article-shape.md · korean-tech-blog-register.md.
 고칠 파일: <기록.md>  (제자리에서 고친다)
 너의 일은 문체다. 사실을 만들지 마라. 분류가 틀렸거나 근거가 모자란 것은 네 일이 아니다 —
 발견하면 고치지 말고 notes 에 적어라.
 보호 구간을 건드리지 마라: 수치 · 날짜 · 버전 · 단위 · 코드 · 명령어 · URL · 직접 인용 ·
 공식 명칭. 한 글자도 달라지면 안 된다.
 관문:
  S=.agents/skills/rewriting-technical-prose-naturally/scripts
  node $S/check_prose.mjs --warn <기록.md>     # error 0 까지
  node $S/style_profile.mjs <기록.md>
 그리고 문장을 고쳤으니 본문 문법과 인용을 다시 본다:
  python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
  node --experimental-transform-types \
    .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
  node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
 수치를 맞추려고 문장을 넣지 마라. 검사기는 표면 패턴만 본다.
 돌려줄 것: 위 JSON 형식. skillEcho 포함.
 ```
 ---
 ## S6 — 일한 사람의 목소리
 **에이전트:** `voice-writer` — `subagent_type="voice-writer"`
 ```
 너는 Tech Log 파이프라인의 6단계를 맡는다.
 먼저 .agents/skills/writing-as-the-person-who-did-it/SKILL.md 를 끝까지 읽어라.
 references/voice-moves.md 도 읽어라. 그 스킬이 "이것보다 먼저 본다"고 한
 ../rewriting-technical-prose-naturally/references/article-shape.md 를 먼저 읽어라.
 고칠 파일: <기록.md>  (제자리에서 고친다)
 상류 자료: docs/<프로젝트>/final/document.md · <대상 저장소의 커밋 메시지·주석·README>
 찾을 것은 자료에 남아 있는 사람의 흔적이다 — 무엇을 골랐고 무엇과 견주었나,
 확인하지 못한 것이 무엇이고 그것이 어느 주장에 걸리나, 처음 생각과 어긋난 자리가 있나.
 없는 사람을 만들지 마라. 「처음에는」·「고민 끝에」·「놀랍게도」를 자료 없이 쓰면 지어낸 것이다.
 넣은 문장마다 그것이 어느 파일 어느 줄에서 왔는지 댈 수 있어야 한다.
 자료에 흔적이 없으면 아무것도 넣지 말고 그렇게 보고해라. 그것도 이 단계를 한 것이다.
 관문:
  node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <기록.md>
  node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
  python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
  node --experimental-transform-types \
    .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
  node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
 check_voice.mjs 는 목소리가 모자란지 재지 않는다. 지어낸 목소리를 잡는다.
 돌려줄 것: 위 JSON 형식. skillEcho 포함. 흔적이 없었으면 status DONE 에 notes 로 적어라.
 ```
 ---
 ## S7 — Studio 저장
 **에이전트:** `studio-validator` — `subagent_type="studio-validator"`
 ```
 너는 Tech Log 파이프라인의 7단계를 맡는다.
 먼저 .agents/skills/publishing-tech-log-to-studio/SKILL.md 를 끝까지 읽어라.
 references/studio-form-map.md 와 references/playwright-recipes.md 도 읽어라.
 넣을 기록: <기록.md>
 도구: Playwright MCP (mcp__playwright__browser_*)
 저장까지만 한다. 게시 버튼을 누르지 마라. 한 번 게시한 문서는 취소해도 삭제가 409 로 거절된다.
 상태 레일 aside[class*="studio-document-status"] 가 25초 안에 안 뜨면 인증이 안 된 것이다.
 로그인 화면에 자격증명을 입력하지 말고 거기서 멈추고 사용자에게 알려라.
 frontmatter 의 id 와 studio: 가 이미 있으면 그 주소로 가라. 새로 만들지 마라.
 그림이 있으면 Asset 을 본문보다 먼저 올려라. 순서를 뒤집으면 미리보기가 본문을 막는다.
 관문:
  상태 레일의 글자가 저장됨 으로 바뀌는 것을 확인 (최대 30초)
  python3 scripts/build-tech-log-tree.py <프로젝트>
  python3 scripts/verify-tech-log-tree.py <프로젝트>
 저장됨 이 안 뜨면 버튼을 다시 누르지 말고 레일의 글자를 그대로 보고해라.
 돌려줄 것: 위 JSON 형식. skillEcho 포함. gates 에 저장 전후 version 을 적어라.
 ```
@@ -0,0 +1,108 @@
 {
  "schemaVersion": 2,
  "runId": "<YYYY-MM-DD-HHMM>",
  "project": "<프로젝트>",
  "record": "<docs/<프로젝트>/tech-log-studio/<주제>/<종류>/<기록>.md — 이 런이 만드는 기록>",
  "startedAt": "<ISO-8601>",
  "finishedAt": null,
  "stages": [
    {
      "id": "S1",
      "name": "코드베이스 → SSOT",
      "skill": "analyzing-codebase-for-tech-log",
      "runBy": "ssot-analyst",
      "status": "PENDING",
      "skipReason": "",
      "skillEcho": "",
      "skillRevision": null,
      "inputs": [],
      "outputs": [],
      "gates": [],
      "notes": ""
    },
    {
      "id": "S2",
      "name": "SSOT → 분해 계약",
      "skill": "deriving-tech-log-root-tree",
      "runBy": "tree-deriver",
      "status": "PENDING",
      "skipReason": "",
      "skillEcho": "",
      "skillRevision": null,
      "inputs": [],
      "outputs": [],
      "gates": [],
      "notes": ""
    },
    {
      "id": "S3",
      "name": "글감 → 기록",
      "skill": "writing-tech-log-records",
      "runBy": "record-writer",
      "status": "PENDING",
      "skipReason": "",
      "skillEcho": "",
      "skillRevision": null,
      "inputs": [],
      "outputs": [],
      "gates": [],
      "notes": ""
    },
    {
      "id": "S4",
      "name": "기록 → 그림",
      "skill": "technical-visualizer",
      "runBy": "diagram-maker",
      "status": "PENDING",
      "skipReason": "",
      "skillEcho": "",
      "skillRevision": null,
      "inputs": [],
      "outputs": [],
      "gates": [],
      "notes": ""
    },
    {
      "id": "S5",
      "name": "AI 티 제거",
      "skill": "rewriting-technical-prose-naturally",
      "runBy": "prose-rewriter",
      "status": "PENDING",
      "skipReason": "",
      "skillEcho": "",
      "skillRevision": null,
      "inputs": [],
      "outputs": [],
      "gates": [],
      "notes": ""
    },
    {
      "id": "S6",
      "name": "일한 사람의 목소리",
      "skill": "writing-as-the-person-who-did-it",
      "runBy": "voice-writer",
      "status": "PENDING",
      "skipReason": "",
      "skillEcho": "",
      "skillRevision": null,
      "inputs": [],
      "outputs": [],
      "gates": [],
      "notes": ""
    },
    {
      "id": "S7",
      "name": "Studio 저장",
      "skill": "publishing-tech-log-to-studio",
      "runBy": "studio-validator",
      "status": "PENDING",
      "skipReason": "",
      "skillEcho": "",
      "skillRevision": null,
      "inputs": [],
      "outputs": [],
      "gates": [],
      "notes": ""
    }
  ]
 }
@@ -1,6 +1,9 @@
 ---
 name: technical-visualizer
 description: Create source-grounded, diagram-only technical visuals from nearby documentation context. Select a logical composition grammar, compile VizSpec 1.1 into SVG and editable formats, and reject disconnected-card output.
 metadata:
  version: "1.0.0"
  language: "ko-KR"
 ---
 # Technical Visualizer
@@ -192,6 +195,16 @@ Load supporting guidance only as needed:
 `techviz build ... --document docs/<프로젝트>/final/document.md` 가 그 블록을 갱신한다.
 ### Tech Log 파이프라인에서 불릴 때
 `running-tech-log-pipeline` 의 4단계가 이 스킬이다. 입력이 둘이라는 것만 다르다.
 - **무엇을 그릴지는 방금 쓴 기록 본문이 정한다.** 세 관문은
  `../writing-tech-log-records/references/choosing-a-diagram.md` 에 있고, 그림이 주장하는
  것을 기록 본문이 말하고 있어야 한다.
 - **그림의 사실은 SSOT 절이 댄다.** 기록은 SSOT 의 인용이라 줄 번호가 근거가 되지 못한다.
  `prepare` 에는 `final/document.md` 를 넣고 절은 기록의 `source` 앵커로 지목한다.
 ### Tech Log 기록으로 옮길 때
 런의 `document.md` 는 마크다운 이미지로 그림을 싣지만, Studio 기록은 다르다. SVG 를 Studio 에 Asset 으로
@@ -203,10 +216,45 @@ Load supporting guidance only as needed:
 ```
 `references/code-tables-diagrams.md`(writing-tech-log-records)의 규칙이 함께 적용된다. 특히
-**`<text>` 는 이름만 담고 문장은 `<desc>` 와 옆 문단에 둔다.** 이 저장소의 기존 손그림 SVG 는 이 규칙을
+**`<text>` 는 이름만 담고 문장은 `<desc>` 와 옆 문단에 둔다.** `render` 뒤에 반드시 돌린다 —
 `spec.json` 의 `label`·`details`·edge `label` 이 그대로 `<text>` 가 되므로 스펙을 쓸 때부터 이름으로 쓴다.
 ```bash
 python3 scripts/check-figure-text.py <프로젝트>       # <text> 가 전부 이름인가
 python3 scripts/check-figure-overlap.py <프로젝트>    # 상자와 라벨이 서로를 덮지 않는가
 ```
 ### 컴파일한 뒤 반드시 눈으로 본다
 **lint 는 라벨이 상자를 덮는 것을 못 잡는다.** 엣지가 노드를 지나가는 것(`edge-through-node`)은
 보지만 라벨은 앵커 점만 보고 폭을 재지 않는다. 그래서 `PASS` 인 그림에도 라벨이 상자에 먹히거나
 경계선 위에 얹히는 일이 생긴다. SVG 를 PNG 로 떠서 본다.
 ```bash
 python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs
 python3 scripts/preview-figure.py --file 그림.svg
 ```
 지금까지 확인한 것:
 | 증상 | 원인 | 대응 |
 |---|---|---|
 | 엣지 라벨이 옆 상자에 먹힌다 | 라벨이 길다 | 라벨을 짧은 이름으로. 자세한 것은 노드 `details` 로 |
 | 라벨이 group 점선 위에 얹힌다 | `two-zone-pipeline` 은 지역 **안쪽** 엣지 라벨을 캔버스 top 에 고정한다 | 지역 안 엣지를 없애거나 `component-flow` + `groups` 로 바꾼다 |
 | 원기둥이 제목·항목을 덮는다 | `shape: cylinder` 에 `details` 가 많다 | `details` 를 줄이거나 `shape: box` | 이 저장소의 기존 손그림 SVG 는 이 규칙을
 어기고 문단과 각주 번호·커밋 해시를 캔버스 안에 넣어 두었다. 다시 만들 때 그 문장들은 본문으로 내린다.
 ### 그림을 만들기 전에
 `rewriting-technical-prose-naturally` 의 `## Figures` 를 먼저 읽는다. 옆 문단이 이미 말한 것을 상자와
 화살표로 다시 그린 그림은 만들지 않는다. 그림이 담아야 할 것은 순서·구조·측정값·실제 산출물이다.
 **표로 되는 것을 그림으로 그리지 않는다.** `comparison` 프로필은 연결성 검사에서 빠지기 때문에
 항목을 나란히 늘어놓기만 해도 lint 를 통과한다. 그것이 표다 — 표는 값을 비교하고 그림은
 포함·순서·경계처럼 자리로만 보이는 것을 맡는다. 스펙을 쓰기 전에 묻는다.
 > **관계선을 다 지워도 뜻이 남는가.** 남으면 표다. 마크다운 표로 쓴다.
 `verify-project-layout.py` 의 「표로 되는 그림」이 관계선 없이 항목마다 같은 수의 `details` 를
 늘어놓은 spec 을 센다. `comparison` 이 맞는 자리는 비교 자체가 자리로 드러나는 때다 — 겹치는
 범위, 갈라지는 경계처럼.
@@ -0,0 +1,120 @@
 ---
 name: writing-as-the-person-who-did-it
 description: Use when a Korean technical document is accurate, well-ordered and well-evidenced but reads like a report produced by nobody — no one chose anything, nothing surprised anyone, and the limits are an inventory instead of an admission.
 metadata:
  version: "1.0.0"
  language: "ko-KR"
 ---
 # 일한 사람이 쓴 글로 만들기
 ## 무엇을 고치는 스킬인가
 문장도 맞고 순서도 맞고 근거도 붙어 있는데 **아무도 쓰지 않은 글처럼 읽히는** 상태를 고친다.
 증상은 셋이다.
 - 무엇을 골랐다는 말은 있는데 **왜 그것을 골랐는지, 무엇과 견주었는지**가 없다
 - 확인하지 못한 것이 **목록**으로 있고, 그것이 걸리는 대목에는 없다
 - 어긋난 자리가 없다. 처음부터 지금 구조를 알고 있었던 것처럼 읽힌다
 고치는 방법은 하나뿐이다. **자료에 남아 있는 사람의 흔적을 찾아서 제자리에 놓는다.**
 ## 절대 규칙 — 없는 사람을 만들지 않는다
 이 스킬을 잘못 쓰면 지어낸 경험이 붙는다. 그것이 아무 목소리도 없는 글보다 나쁘다.
 **쓸 수 있는 것은 자료가 기록한 사람의 행동과 판단뿐이다.** 넣은 문장마다 그것이 어느 파일,
 어느 칸, 어느 줄에서 왔는지 댈 수 있어야 한다. 못 대면 지어낸 것이다.
 | 이런 말이 떠오르면 | 실제로 벌어지는 일 |
 |---|---|
 | 「처음에는 X를 의심했다」 | 자료에 그런 기록이 없으면 없던 수사 과정을 만든 것이다 |
 | 「놀랍게도」·「당황스럽게도」 | 감정을 지어냈다. 관측이 뜻밖이었다는 근거가 자료에 없다 |
 | 「고민 끝에 Y를 골랐다」 | 대안을 견주었다는 기록이 없으면 고민도 없었다 |
 | 「많은 시행착오를 겪었다」 | 시행착오가 자료에 있으면 그것을 적고, 없으면 이 문장도 없다 |
 | 「이 글이 도움이 되길 바란다」 | 기록에는 독자에게 인사하는 자리가 없다. 참고 글의 습관을 옮겨 온 것이다 |
 | 「~로 읽기 쉽다. 그렇지 않다」 | 자료에 그런 오독 기록이 없으면 독자를 지어낸 것이다. 관측부터 적는다 |
 `../rewriting-technical-prose-naturally/references/protected-content.md`가 함께 걸린다. 수치·버전·
 식별자는 이 스킬에서도 한 글자도 바뀌지 않는다.
 ## 자료 어디에 사람이 남아 있나
 기록을 열기 전에 이것부터 찾는다. 대개 **이미 문서 안에 있고 자리가 틀렸을 뿐**이다.
 | 어디 | 무엇이 있나 |
 |---|---|
 | `확인하지 못한 것` 칸 | 재지 않은 것을 아는 사람이 적어 둔 것이다. 목록이 아니라 그 대목에서 할 말이다 |
 | `재현 조건` 칸 | 누군가 실제로 이 순서로 돌렸다. 그 순서가 왜 그 순서인지가 대개 빠져 있다 |
 | javadoc·README·주석 | 코드를 쓴 사람이 남긴 말. 그대로 옮길 수 있다 |
 | 커밋 메시지 | 왜 지웠는지·왜 바꿨는지가 한 줄로 남아 있다 |
 | `final/document.md` | 기록으로 뽑으면서 잘라낸 판단이 여기 남아 있는 경우가 많다 |
 | 결정 기록의 `판단 이유`·`영향` | 감수한 비용이 적혀 있다 |
 찾은 것이 없으면 **이 스킬은 여기서 끝난다.** 없는 목소리를 채우지 않는다.
 ## 옮길 수 있는 다섯 가지
 참고 여섯 편에서 뽑았고, 각 항목이 어느 글에서 왔는지는
 [references/voice-moves.md](references/voice-moves.md)에 있다. 여섯 편이 다 쓰는 것이 아니다 —
 13569 한 편에 몰려 있고 23625는 거의 쓰지 않는다. **글마다 자료가 허락하는 만큼만 쓴다.**
 1. **고른 이유를 견준 대상과 함께 적는다** — 무엇을 놓고 무엇을 골랐고 무엇을 감수했나
 2. **확인하지 못한 것을 그 대목에서 말한다** — 끝의 목록이 아니라 그 주장 옆에서
 3. **어긋난 자리를 남긴다** — 예상과 결과가 달랐던 지점이 자료에 있으면 지우지 않는다
 4. **남의 말을 그대로 옮긴다** — javadoc·문서·커밋 메시지·사용자 문의. 요약하지 않는다
 5. **자료에 남은 오독을 그 자리에 둔다** — 누군가 실제로 틀리게 읽었다는 기록(버그·정정·문의)이 있을 때만.
   독자가 틀릴 것이라고 가정해서 만든 「~로 읽기 쉽다」는 이 항목이 아니라 지어낸 독자다
 다섯을 다 쓰지 않는다. 한 기록에 둘이면 충분하고 **하나도 없어도 된다.** 이미 충분히 설명된 문단에
 사람의 목소리를 더하려고 문장을 붙이면 그것이 「설명 뒤의 평가」가 된다. 다섯을 채우면 그것이 또 다른 틀이 된다.
 ## 문체는 옮기지 않는다
 참고 글은 합니다체이고 `~는데요`·`~텐데요`·`~거든요`로 말을 부드럽게 한다. 이 저장소의 기록은
 한다체다. **부드러움을 흉내 내면 그 회사 목소리가 되고, 기록의 어조가 무너진다.**
 한다체에서 사람이 드러나는 자리는 어미가 아니라 **무엇을 말하기로 했는가**다.
 ```text
 없는 목소리    컨트롤러가 직접 내부 토큰을 확인한다.
 지어낸 목소리  컨트롤러가 직접 내부 토큰을 확인하는데요, 이게 좀 아쉬운 부분입니다.
 평가만 더한 것 컨트롤러가 직접 내부 토큰을 확인한다. 지금 구조에서 이것을 막는 것은 없다.
 있는 목소리    컨트롤러가 직접 내부 토큰을 확인한다. /edge/** 전체를 보호하는 filter 는 없어서,
              새 엔드포인트가 같은 메서드를 부르지 않으면 그 엔드포인트는 검사를 지나친다.
 ```
 네 번째가 사람이 쓴 글이다. 어미는 그대로이고, 아는 사람만 할 수 있는 말이 하나 붙었다 — 그리고 그
 말이 **사실을 더한다**(filter 가 없다, 어느 경로가 검사를 지나치는가). 세 번째처럼 판정만 더하면
 (「막는 것은 없다」) 그것은 목소리가 아니라 평가다. 그런 문장은 빼는 쪽이 맞다.
 ## 절차
 1. **자료를 먼저 훑는다.** 위 표의 자리를 다 열고, 쓸 수 있는 흔적을 목록으로 적는다
 2. **흔적이 없으면 멈춘다.** 문서에 그렇게 보고한다
 3. **흔적마다 놓일 자리를 정한다.** 대개 그 주장이 나오는 문단 바로 뒤다
 4. **옮긴다.** 문장을 새로 짓지 말고, 자료의 말을 그 자리에 놓는 것으로 시작한다
 5. **검사한다** — `scripts/check_voice.mjs`. 이 검사기는 목소리가 **모자란지** 재지 않는다.
   **지어낸 목소리**를 잡는다
 6. `../rewriting-technical-prose-naturally`의 `check_prose.mjs`를 다시 돌린다
 ## 검사
 ```bash
 node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <파일.md>
 ```
 세 가지를 본다.
 - **지어낸 경험** — 자료가 뒷받침하지 않으면 error인 표현들
 - **참고 글에서 옮겨 온 인사말** — 「도움이 되길 바랍니다」 계열
 - **합니다체 부드러움을 한다체에 섞은 자리**
 검사기가 조용하다고 목소리가 생긴 것은 아니다. **모자란 것은 사람이 읽어야 안다.**
 ## 참조
 - [references/voice-moves.md](references/voice-moves.md) — 다섯 가지가 여섯 편에서 어떻게 쓰였나
 - `../rewriting-technical-prose-naturally/examples/` — 원문 여섯 편
 - `../rewriting-technical-prose-naturally/references/article-shape.md` — 밀도. 이 스킬보다 먼저 본다
 - `../writing-tech-log-records/references/writing-each-kind.md` — 종류마다 어느 칸이 사람의 자리인가
@@ -0,0 +1,160 @@
 # 다섯 가지가 여섯 편에서 어떻게 쓰였나
 원문은 `../../rewriting-technical-prose-naturally/examples/`에 있다. 인용은 그 파일에서 그대로
 옮긴 것이다.
 ## 먼저 — 여섯 편이 고르게 쓰지 않는다
 세어 보면 이렇다.
 | | 1인칭 | 그때 든 생각 | 예상이 빗나감 | 독자에게 말 걸기 | 모순·자조 | 겸양 닫기 |
 |---|---|---|---|---|---|---|
 | 13569 | 12 | 3 | 5 | 3 | 5 | 1 |
 | 17386 | 10 | 5 | 0 | 2 | 1 | 0 |
 | 7835 | 8 | 0 | 0 | 3 | 0 | 0 |
 | 20161 | 5 | 0 | 0 | 2 | 0 | 0 |
 | 22396 | 4 | 0 | 0 | 2 | 0 | 4 |
 | 23625 | 1 | 0 | 0 | 0 | 0 | 0 |
 **13569 한 편에 몰려 있다.** 23625는 거의 쓰지 않는데도 읽힌다. 그러니까 이것은 채워야 할 칸이
 아니라, **자료가 그런 글일 때만 나오는 것**이다.
 13569이 그렇게 쓸 수 있었던 이유는 그 글이 「예상보다 빨라져서 문제가 생겼다」는 사건을 실제로
 겪었기 때문이다. 겪지 않은 글이 같은 어조를 쓰면 그때부터 거짓이 된다.
 ---
 ## 1. 고른 이유를 견준 대상과 함께 적는다
 무엇을 골랐다가 아니라, **무엇을 놓고 무엇을 골랐고 무엇을 감수했나**를 적는다.
 22396은 상용 내비게이션을 쓰지 않은 이유를 돈으로 적는다.
 > 하지만 초당 2만 건에 달하는 경로 계산을 위해 API 호출마다 비용이 발생하는 상용 내비게이션을
 > 사용하는 것은 현실적으로 어렵습니다. 게다가 배차를 추천받은 라이더분이 바로 수락하는 경우,
 > 한 번 계산한 거리를 오랜 시간 재활용하기도 쉽지 않습니다.
 그리고 고르지 **않은** 쪽을 표로 남긴다 — TTL 삭제 대 명시적 삭제. 장점 칸이 채워진 쪽을 버리고
 단점이 하나뿐인 쪽을 골랐다는 것이 표에 그대로 보인다.
 7835는 저장소를 고르는 대목에서 반대 의견을 먼저 적는다.
 > 이벤트는 작은 단위로 저장이 되고, 고속 처리되어야하기 때문에 RDBMS 가 아닌 다른 데이터베이스를
 > 선택해야한다고 생각할 수 있습니다.
 그리고 왜 그럼에도 RDBMS인지로 이어 간다.
 **한다체로 옮길 때** — 어미만 바꾸면 된다. 「~하는 것은 현실적으로 어렵다」·「~라고 생각할 수 있다」.
 **쓸 수 없는 경우** — 자료에 대안이 없으면 이 항목은 건너뛴다. 「여러 방법을 검토했다」는 검토한
 기록이 없으면 지어낸 문장이다.
 ---
 ## 2. 확인하지 못한 것을 그 대목에서 말한다
 이 저장소의 기록은 `확인하지 못한 것`을 끝에 목록으로 모아 둔다. 참고 글은 **그 말이 걸리는 자리**
 에서 한다.
 22396은 압축을 시도한 절 안에서 바로 닫는다.
 > 압축률이 높더라도 원본 데이터가 워낙 커서 압축만으로는 대역폭 문제를 해결할 수 없었습니다.
 13569은 배포 전 검토 항목을 늘어놓은 뒤 그 자리에서 한계를 인정한다.
 > 문제가 없을 것으로 예상하였지만 일들이 항상 마음처럼 굴러가던가요?
 **한다체로 옮길 때** — 끝의 목록을 지우라는 말이 아니다. 목록은 두고, **그중 하나를 그 주장이
 나오는 문단 뒤에 한 번 더** 놓는다. 읽는 사람이 그 주장을 믿을지 정하는 자리가 거기이기 때문이다.
 ```text
 전   (본문 끝)  ## 확인하지 못한 것
                 role 전달은 확인하지 않았다.
 후   (그 대목)  지금 edge 응답은 사용자와 이메일만 전달한다. role을 넘기면 무엇이 달라지는지는
                 확인하지 않았다.
     (본문 끝)  ## 확인하지 못한 것  ← 목록은 그대로 둔다
 ```
 ---
 ## 3. 어긋난 자리를 남긴다
 **자료에 있을 때만 쓴다.** 없으면 이 항목은 통째로 건너뛴다.
 13569의 「빨라도 문제」 절 전체가 이것이다.
 > 근데 이거 빨라도 너무 빨라진 것 같습니다.
 > '내가 뭘 놓친 게 있나?' 아니면 '코드를 잘못 짰나?' 생각이 들었지만…
 그리고 배포 뒤 실제로 문제가 났고, 그 대응이 스스로 모순임을 적는다.
 > 근본적으로는 실행 속도가 너무 빨라진 것이 문제이기 때문에
 > 모순적이지만 우선 단기적인 대응 방안으로 의도적으로 지연 시간을 설정해 천천히 실행하도록
 > 수정하였습니다.
 22396은 실패한 시도를 지우지 않는다 — 「시도 1. 데이터 압축」이 실패한 채로 남아 있고, 24MB → 3MB
 라는 성공한 압축률까지 적은 다음 그것으로도 모자란다고 닫는다.
 **한다체로 옮길 때** — 감탄사와 혼잣말은 옮기지 않는다. 옮기는 것은 **순서**다. 그때 그렇게
 생각했다 → 실제로는 이랬다 → 그래서 이렇게 했다.
 ```text
 지어낸 것   놀랍게도 응답은 200이었다.
 있는 것     세션 자체는 유효하므로 이 요청이 200으로 처리되는 것은 정상이고, 그래서 이 테스트의
            판정 기준은 상태 코드가 아니다.
 ```
 두 번째는 읽는 사람이 200을 보고 「뚫렸다」고 짐작할 것을 알고 쓴 문장이다. 감정을 적지 않고도
 사람이 보인다.
 ---
 ## 4. 남의 말을 그대로 옮긴다
 여섯 편이 가장 자주 쓰는 방법이고, **증거로 뒷받침되므로 지어낼 수 없다.**
 13569은 최적화를 말하다 말고 격언 셋을 통째로 옮긴다.
 > "우리는 최적화에 대해서 다음 두가지 규칙을 따른다. 첫째. 하지 마라. 둘째. (전문가 한정)
 > 아직은 하지 마라."
 > M. A. Jackson (1975)
 23625는 사용자 문의를 그대로 옮긴다.
 > 심각한 문제는 사용자가 "같은 엑셀 파일을 여러 번 받았다"는 문의였습니다.
 20161은 Nginx 문서와 Lucene 문서를 원문 그대로 인용문으로 넣는다.
 **이 저장소에서 쓸 수 있는 것** — javadoc이 가장 많다. 코드를 쓴 사람이 자기 코드의 위험을 적어
 둔 자리가 있으면 그것을 요약하지 말고 그대로 옮긴다.
 > `InboxCleanupJob`의 javadoc이 스스로 적는다 — "A single unbounded DELETE over a table that has
 > been accumulating for weeks holds locks long enough to block the very reservations the inbox
 > exists to serve, so the cleanup would cause the outage it is meant to prevent."
 이 한 줄이 있으면 「이 결함은 알려져 있었다」는 말을 따로 할 필요가 없다.
 ---
 ## 5. 한 번은 독자 쪽을 본다
 읽는 사람이 **틀리게 짐작할 자리**에서 한 문장이다. 인사가 아니다.
 20161은 겉보기에 멀쩡한 쿼리를 보여 주고 나서 짚는다.
 > 겉으로 보기에는 문제가 없어 보이는 쿼리였지만, 카테고리 필터가 있을 때와 없을 때 검색 API의
 > 응답 속도 차이는 매우 큰 편이었습니다.
 22396은 강조를 두 번 한다고 말하고 두 번 한다.
 > 앞서 언급했지만 중요한 내용이기에 다시 한번 강조드립니다.
 > **배달료 책정이나 배민커넥트 앱상에서 활용되는 거리 계산에는 상용 내비게이션이 사용됩니다.**
 17386은 글 첫머리에 「누가 읽으면 좋을까」를 두고 전제 지식을 못 박는다.
 **한다체로 옮길 때** — 「~라고 생각하기 쉽다」·「겉보기에는 ~이지만」·「여기서 확인할 값은
 ~가 아니다」. 한 기록에 **한 번**이다. 두 번 넘으면 독자를 끌고 다니는 글이 된다.
 **옮기지 않는 것** — 「도움이 되길 바랍니다」·「공유드립니다」·「즐거움을 느끼고 있습니다」.
 블로그 글의 맺음말 자리에 있는 인사이고, 기록에는 그 자리가 없다.
@@ -0,0 +1,115 @@
 #!/usr/bin/env node
 // 지어낸 목소리를 잡는다. 모자란 목소리는 재지 않는다 — 그것은 사람이 읽어야 안다.
 //
 //   node check_voice.mjs [--블로그] <파일.md> [...]
 //
 // 왜 세지 않는가: 이 저장소에서 「종결어미 종류 수」를 세는 검사를 넣었더니, 그것을 맞추려고
 // 없던 물음표 문장과 「~해 보자」가 문서에 끼어들었다. 목소리를 개수로 재면 같은 일이 난다.
 // 그래서 이 검사기는 있어야 할 것을 요구하지 않고, 있으면 안 되는 것만 잡는다.
 //
 // 참고 여섯 편을 그냥 돌리면 떨어진다. 그것은 규칙이 과해서가 아니라 장르가 달라서다 —
 // 여섯 편은 합니다체 블로그 글이라 `~는데요`를 쓰고 맺음말에 인사를 둔다. 기록은 한다체이고
 // 인사할 자리가 없다. 여섯 편에 돌려 볼 때는 `--블로그`를 붙인다. 그러면 이 두 규칙만 꺼지고
 // 지어낸 목소리를 잡는 규칙은 그대로 돈다 — 여섯 편은 그쪽에 한 건도 걸리지 않는다.
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 const ERR = "error", WARN = "warn";
 const RULES = [
  // 1. 수사 과정을 말하는 문구.
  //
  // 이것만으로는 지어냈는지 알 수 없다. 22396 의 「여러 시행착오를 겪었습니다」는 바로 뒤에
  // 실패한 시도 1 을 통째로 싣고, 7835 의 「고민 끝에」는 글 전체가 그 고민이다. 둘 다 정당하다.
  // 나쁜 것은 문장만 있고 과정이 없는 경우인데, 그건 문서를 읽어야 안다. 그래서 판단 항목이다.
  { id: "process-claimed", sev: WARN,
    re: /(처음에는[^.\n]{0,30}(의심|생각|짐작)|한참[^.\n]{0,15}(헤매|찾|고민)|여러[^.\n]{0,10}(시행착오|삽질)|고민\s*끝에|우여곡절|검토\s*끝에)/g,
    msg: "겪은 과정을 말했습니다. 이 문서가 그 과정을 실제로 보여 주면 두고, 문장만 있으면 지우세요." },
  { id: "invented-emotion", sev: ERR,
    re: /(놀랍게도|당황스럽|의외로|뜻밖에도|아쉽게도|다행히도|기쁘게도|흥미롭게도|충격적)/g,
    msg: "감정을 지어냈습니다. 관측이 뜻밖이었다는 근거가 자료에 있어야 쓸 수 있습니다." },
  // 2. 참고 글의 맺음말을 옮겨 온 자리. 기록에는 독자에게 인사하는 칸이 없다.
  { id: "borrowed-greeting", sev: ERR,
    re: /(도움이\s*되(길|기를)|되었으면\s*좋겠|공유(드립니다|하고자|합니다)|읽어\s*주셔서|감사합니다|즐거움을\s*느끼|노력하겠습니다|기대합니다)/g,
    msg: "블로그 맺음말의 인사입니다. 기록에는 그 자리가 없습니다. 남은 일이나 감수한 것으로 닫으세요." },
  // 3. 합니다체의 부드러움을 한다체 문서에 섞은 자리
  { id: "register-mix", sev: ERR,
    re: /(는데요|거든요|텐데요|인데요|한데요|잖아요|네요)/g,
    msg: "합니다체의 부드러운 어미를 섞었습니다. 참고 글의 어조이지 이 기록의 어조가 아닙니다." },
  // 4. 겪지 않은 1인칭. 기록의 주어는 대개 코드와 요청이다.
  // 앞 글자가 한글이면 낱말 안이다 — 「브라우저는」의 「저는」을 잡지 않는다
  { id: "unsupported-first-person", sev: WARN,
    re: /(?<![가-힣])(저는|저희(는|가|의|도)|제가|우리는)\s/g,
    msg: "1인칭입니다. 자료가 그 사람의 행동을 기록했으면 두고, 아니면 무엇이 그렇게 했는지로 바꾸세요." },
  // 5. 독자를 끌고 다니는 문장이 여러 번 나오는 것은 참고 글도 하지 않는다 (개수는 아래에서 본다)
  { id: "steering", sev: WARN,
    re: /(라고\s*생각하기\s*쉽|겉보기에는|여기서\s*확인할\s*값은|짐작하기\s*쉽|헷갈리기\s*쉽)/g,
    msg: "독자 쪽을 보는 문장입니다. 한 기록에 한 번이면 충분합니다." },
 ];
 function strip(src) {
  return src
    .replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, " "))
    .replace(/`[^`\n]*`/g, (m) => " ".repeat(m.length))
    .replace(/^---\n[\s\S]*?\n---\n/, (m) => m.replace(/[^\n]/g, " "));
 }
 function lineOf(text, index) {
  return text.slice(0, index).split("\n").length;
 }
 let failed = 0;
 const argv = process.argv.slice(2);
 // 합니다체 블로그 글에 돌릴 때는 어조·인사 규칙을 끈다. 장르가 다르지 글이 나빠서가 아니다.
 const blogMode = argv.includes("--블로그");
 const GENRE = new Set(["register-mix", "borrowed-greeting"]);
 const files = argv.filter((a) => !a.startsWith("--"));
 if (!files.length) {
  console.error("쓰는 법: node check_voice.mjs [--블로그] <파일.md>");
  process.exit(2);
 }
 for (const file of files) {
  const raw = readFileSync(file, "utf8");
  const text = strip(raw);
  const found = [];
  for (const r of RULES) {
    if (blogMode && GENRE.has(r.id)) continue;
    for (const m of text.matchAll(r.re)) {
      found.push({ ...r, line: lineOf(text, m.index), hit: m[0].trim() });
    }
  }
  // 독자 쪽을 보는 문장은 하나까지가 정상이다
  const steering = found.filter((f) => f.id === "steering");
  const rest = found.filter((f) => f.id !== "steering");
  const shown = steering.length > 1 ? rest.concat(steering) : rest;
  const errors = shown.filter((f) => f.sev === ERR).length;
  const warns = shown.length - errors;
  if (errors) failed = 1;
  console.log(
    errors
      ? `FAIL ${basename(file)} — error ${errors}건${warns ? ` · 경고 ${warns}건` : ""}`
      : `OK   ${basename(file)}${warns ? `  (경고 ${warns}건)` : ""}`
  );
  for (const f of shown) {
    const mark = f.sev === ERR ? " " : "·";
    console.log(`  ${mark} ${basename(file)}:${f.line}  [${f.id}] "${f.hit}"`);
    console.log(`       ${f.msg}`);
  }
  if (steering.length > 1) {
    console.log(`  · [steering] 독자 쪽을 보는 문장이 ${steering.length}개입니다 — 하나만 남기세요.`);
  }
 }
 console.log(
  "\n검사기가 조용해도 목소리가 생긴 것은 아닙니다. 모자란 것은 사람이 읽어야 압니다."
 );
 process.exit(failed);
@@ -0,0 +1,580 @@
 ---
 name: writing-practitioner-guides
 description: Use when writing hands-on guides, runbooks, troubleshooting docs, lab walkthroughs, or validation procedures that a human will execute themselves in a terminal over SSH. Symptoms that this applies - the reader is expected to type the commands, the doc teaches how to read a system rather than reporting a result, or a draft contains python -c, embedded JSON parsing, one-liners nobody types by hand, or a config file or YAML authored with printf/echo >>/heredoc instead of an editor.
 ---
 # Writing Practitioner Guides
 ## Overview
 **Optimize for human operation, not command compactness.**
 A guide is not a script. The reader types each command, reads its raw output,
 and decides what to do next. Commands that are efficient for an agent to run
 once are often useless for a human learning to read a system.
 The failure this prevents: an agent writes `curl … | python3 -c 'import json…'`
 because it produces a clean answer in one call. The reader gets the answer and
 learns nothing about the tool they will need at 3am.
 ## The boundary
 Three tiers. Pick the lowest one that fits.
 ```
 interactive command  →  short pipeline  →  saved script file
 ```
 | Tier | When | Form |
 |---|---|---|
 | **interactive** | reading state, one question | `kubectl get pods`, `ss -lntp`, `journalctl -u nginx -n 50` |
 | **short pipeline** | filtering that a person would actually type | `ps aux \| grep java`, `… \| jq .status`, `for p in a b; do … done` |
 | **saved script** | it has become a program | write the file with an editor, then run it |
 **Move to a saved script when any of these is true:**
 - multiple branches (`if`) or nested loops
 - combining several requests and computing across them
 - non-trivial JSON transformation
 - you cannot tell what it does by reading it once
 - it will be run again later
 For a saved script, the guide says to open an editor, shows the code as a
 **separate file listing** (not a terminal command), then shows the run command.
 ```bash
 vim scripts/check_sessions.py
 ```
 ```python
 # file: scripts/check_sessions.py
 ...
 ```
 ```bash
 python3 scripts/check_sessions.py
 ```
 Terminal command ≠ program source. Never blur them with a heredoc.
 ## Files the reader has to understand before changing them
 The tiers above stop at the saved script. The same split reaches further: **any
 file whose content the reader must read and understand to change it is written
 in an editor, not assembled by a shell one-liner.** Config files and YAML are
 that kind of file.
 > **조회·진단·실행은 CLI를 적극 사용하고, 사람이 내용을 이해하면서 작성해야 하는 설정 파일은
 > 에디터를 사용한다.**
 | Reading or acting on the system → CLI | Authoring a file a human must understand → editor |
 |---|---|
 | CPU flags → `grep /proc/cpuinfo`, `lscpu` | cloud-init YAML → `nano kc-lab-1.yaml` |
 | service state → `systemctl status` | systemd unit → `sudo nano /etc/systemd/system/x.service` |
 | VM state → `virsh list --all` | `nginx.conf` → `sudo nano /etc/nginx/nginx.conf` |
 | network → `ip addr`, `virsh net-list --all` | `~/.bashrc` → `nano ~/.bashrc` |
 | logs → `journalctl -u x` | Kubernetes manifest → `nano deploy.yaml` |
 | fetch / copy → `curl`, `cp`, `scp` | a script → `nano x.sh` → `chmod +x x.sh` → `./x.sh` |
 | create a VM → `virt-install` | |
 ### This rule is not "replace sed with nano"
 > 단순히 **「`sed`를 `nano`로 바꿔라」**라고 하면 안 됩니다. 그러면 모든 shell 명령을 기계적으로
 > 에디터 작업으로 바꿀 가능성이 큽니다.
 The trigger is the *file-authoring step*, not the appearance of a shell tool.
 | Kind | Examples | Verdict |
 |---|---|---|
 | what an operator types by hand | `virsh`, `systemctl`, `ssh`, `curl`, `virt-install` | keep |
 | reading / diagnosing | `grep`, `lsmod`, `cat`, `stat`, `groups` | keep |
 | shell tricks that author a file | `printf >`, `echo >>`, `cat <<EOF`, `python3 -c`, `ssh '… cat > …'` | rewrite as an editor step |
 A pipe is not the problem. A 12-line `virt-install` is not the problem —
 creating the VM *is* that command's purpose, so the CLI is the right way to show
 it. `sed` is fine for a query or a throwaway substitution; it is wrong as the
 default interface for editing config, because what the reader will actually do
 during an incident is open the file and read what is in it.
 ### Rewrite: `~/.bashrc`
 ```bash
 # before
 echo 'export LIBVIRT_DEFAULT_URI=qemu:///system' >> ~/.bashrc
 virsh uri
 ```
 ```bash
 # after
 nano ~/.bashrc
 ```
 ```text
 export LIBVIRT_DEFAULT_URI=qemu:///system
 ```
 ```bash
 source ~/.bashrc
 virsh uri
 ```
 Two reasons, and the second is the one that gets forgotten:
 1. The reader sees the chain — file → variable → reload this shell → `virsh`
   now resolves that URI. `echo >>` produces only the end state.
 2. **`echo >>` is not idempotent.** Someone who walks the guide a second time
   appends the same line again. Opening the file shows what is already there.
 ### Rewrite: cloud-init meta-data
 ```bash
 # before
 printf 'instance-id: kc-lab-1-%s\nlocal-hostname: kc-lab-1\n' "$(date +%s)" > meta-kc-lab-1
 ```
 ```bash
 # after
 nano meta-kc-lab-1
 ```
 ```yaml
 instance-id: kc-lab-1-20260912
 local-hostname: kc-lab-1
 ```
 > `instance-id`는 이전 cloud-init 실행과 다른 인스턴스로 인식시키기 위해 이전 값과 겹치지 않게
 > 지정한다.
 The `printf` form makes the reader decode `%s`, `\n`, `$(...)`, `date +%s` and
 `>` before reaching the two keys the page is about. A document teaching
 cloud-init should not be teaching shell `printf`. The editor form also gives the
 one line about `instance-id` a place to sit, right where it is typed.
 ### Rewrite: a file on a remote host
 ```bash
 # before
 ssh donghyeon@192.168.122.11 'umask 077; cat > ~/kc-lab-2.yaml' < kc-lab-2.yaml
 ssh donghyeon@192.168.122.11 'cloud-init schema -c ~/kc-lab-2.yaml; rm -f ~/kc-lab-2.yaml'
 ```
 ```bash
 # after
 scp kc-lab-2.yaml donghyeon@192.168.122.11:~/
 ssh donghyeon@192.168.122.11
 ```
 then, on the guest:
 ```bash
 chmod 600 ~/kc-lab-2.yaml
 cloud-init schema -c ~/kc-lab-2.yaml
 rm ~/kc-lab-2.yaml
 ```
 The first line asked the reader to hold SSH, redirection, `umask`, file creation
 and local stdin at once. The rewrite uses more commands and puts fewer things in
 each: **one action, one command.** In a guide someone is learning from, that
 trade is the right way round.
 One more rewrite belongs to this rule — replacing a `python3 -c` YAML check with
 the format's own validator. It sits in **Command priority** below, where the
 ranking it changes lives.
 ## Command priority
 | Rank | Reach for | Examples |
 |---|---|---|
 | 1 | the system's own CLI | `kubectl`, `systemctl`, `psql`, `redis-cli`, `docker compose` |
 | 2 | standard OS tools | `ps`, `ss`, `lsof`, `free`, `top`, `dmesg` |
 | 3 | network / protocol tools | `curl`, `dig`, `openssl`, `nc`, `tcpdump` |
 | 4 | short Unix combinators | `grep`, `jq`, `awk`, `head`, `tail`, `less`, `watch` |
 | — | **avoid** | python/node heredocs, `python -c` that *processes data*, giant awk programs, pipelines built to produce one tidy answer |
 **The line is doing-the-work vs checking-a-fact, not the language.**
 ```bash
 # not fine — this is data processing the native tool should do
 curl -s "$URL" | python3 -c '
 import json,sys
 for r in json.load(sys.stdin)["data"]["result"]:
    print(r["metric"]["pod"], r["value"][1])'
 ```
 That one iterates, reshapes, and formats. `jq`, or the tool's own
 output flag, does that — and when neither is installed, say so and show the
 raw output instead of writing a parser.
 `grep`, `jq`, `awk`, and a one-line `for` are what practitioners type. Do not
 ban them. Ban the ones written for the *agent's* convenience.
 ### Validate with the format's own checker first
 Checking a fact is allowed — but a hand-rolled syntax check is the *last*
 resort, not the default. If the domain ships a command that validates this file,
 that command is the step. Drop to a one-line syntax check only when nothing
 validates the format.
 ```bash
 # before — checks that it parses as YAML, and nothing else
 python3 -c 'import yaml,sys; yaml.safe_load(open("kc-lab-1.yaml")); print("YAML OK")'
 # after — the domain's own validator: schema, keys, and deprecations too
 cloud-init schema -c ~/kc-lab-2.yaml
 ```
 Same rank elsewhere: `nginx -t`, `sshd -t`, `systemd-analyze verify x.service`,
 `kubectl apply --dry-run=server -f deploy.yaml`, `terraform validate`,
 `docker compose config`. Each one is also the command the reader will reach for
 when the service refuses to start, which a `python3 -c` line never becomes.
 ### Two shapes of the same tool
 Most tools have a *reading* form and a *value-extracting* form. Pick by what
 the reader does next with the output.
 | The reader will… | Form | Example |
 |---|---|---|
 | **look at the response** and judge | reading form | `curl -I <url>` · `curl -v <url>` |
 | **compare or count the value** across runs or hosts | extracting form | `curl -s -o /dev/null -w '%{http_code}\n' <url>` |
 The extracting form hides everything except the field you chose. Use it only
 when that field *is* the answer — a status code you will compare before and
 after an injection, or a number you will repeat 900 times. When the reader is
 still figuring out what is wrong, they need the headers and the TLS handshake,
 not `200`.
 Same split elsewhere: `kubectl get` (read) vs `-o jsonpath=` (extract),
 `systemctl status` (read) vs `systemctl show -p X --value` (extract),
 `psql` interactive (read) vs `psql -tAc` (extract).
 **Show the reading form first at least once per tool.** A reader who has only
 ever seen `-w '%{http_code}'` cannot debug a TLS error.
 ## Progressive narrowing
 Never jump to the precise command. Show the widening-to-narrowing path the
 reader will actually walk.
 ```
 list / status  →  detail / describe  →  logs  →  targeted inspection
 ```
 ```bash
 kubectl get pods                       # what is there
 kubectl get pods -o wide               # where, and on which node
 kubectl describe pod api-7c874-8m2js   # why is this one unhappy
 kubectl logs api-7c874-8m2js           # what did it say
 kubectl logs api-7c874-8m2js --previous  # what did it say before it died
 ```
 **Observe before filtering.** Show the raw output at least once before piping
 it. A reader who has never seen `ss -lntp` output needs to see it whole.
 ## Mutation ordering
 ```
 observe → diagnose → reproduce → mutate
 ```
 `rm`, `kill`, `delete`, `UPDATE`, restart, config change do not appear in the
 diagnosis phase. If a step changes state, say what it changes and how to undo it.
 ## Shape of one step
 Four elements, in this order. A command with no interpretation is not a step.
 ```
 무엇을 확인하는가        one line — the question this answers
 $ command                the command, short
 어디를 봐야 하는가        which field/line in the output matters
 이 결과가 의미하는 것     what it tells you, and what to do next
 ```
 Show the real output. If it was measured, quote it verbatim; if it is
 illustrative, say so.
 ### When the step changes state
 The four elements above are the shape of a step that **reads**. A step that
 **changes state** needs a different one — otherwise the why, the failure
 symptoms and the special cases all pile into the same paragraph:
 > 정보 밀도는 높은데 **처음 따라 하는 사람의 시선 이동이 어렵습니다.**
 ```
 목적 → 행동(번호 매긴 명령) → 예상 결과 → 왜 필요한가 → 문제가 생기면
 ```
 ```text
 ### 4. libvirt 기본 연결을 system으로 설정한다
 목적
 virsh가 사용자 세션이 아니라 시스템 libvirt에 연결되도록 한다.
 1. 설정 파일을 연다.
 $ nano ~/.bashrc
 2. 다음 줄을 추가한다.
 export LIBVIRT_DEFAULT_URI=qemu:///system
 3. 저장한 설정을 현재 셸에 반영한다.
 $ source ~/.bashrc
 4. 확인한다.
 $ virsh uri
 예상 결과
 qemu:///system
 왜 필요한가
 qemu:///session과 qemu:///system은 서로 다른 libvirt 연결이다.
 VM을 system 쪽에 만들고 virsh가 session 쪽을 보고 있으면
 VM을 만들었는데도 목록에서 찾지 못할 수 있다.
 문제가 생기면
 $ virsh uri
 부터 확인한다.
 ```
 **A step that only reads takes the first shape; a step that changes state takes
 this one.** Same headings every time, so the reader's eye lands in the same
 place on step 11 as on step 1.
 ## Verify before publishing
 Every command in a guide must have been run, or be marked as unverified.
 **Check that the tools you reach for are actually installed on the machine
 the reader will be on** — `jq` and `yamllint` are absent more often than you
 expect, and a guide that assumes them sends the reader to install things
 mid-diagnosis.
 Two failures this catches, both real:
 - `kubectl get endpoints` — deprecated since v1.33, prints a warning
 - `kubectl exec keycloak-0 -- curl …` — the image has no curl, exit 127
 A guide that teaches a stale or failing command makes the reader doubt their
 own environment.
 ## No placeholders
 `<token>` puts the value outside the document. Give the command that produces
 it. For secrets, confirm existence or length — never print the value.
 ```bash
 TOKEN=$(ssh node1 'sudo cat /var/lib/rancher/k3s/server/node-token')
 echo "${#TOKEN} chars"
 ```
 One exception: a value an earlier step already printed on screen, which the
 reader carries into a later step in a different shell — a session id, a realm
 UUID. The producing command is already in the document, so the value is not
 outside it. Write that slot as `{{NAME}}` (uppercase, digits, underscore), and
 say in the prose above the block which step printed it.
 Not `${NAME}` — guides use `$TOKEN`, `$SID` and friends as real shell
 variables, and a reader who reads a placeholder as one will paste it unchanged.
 `{{ }}` is not shell syntax, so pasting it fails where the reader can see it.
 ## The reader cannot see what is not on screen
 Everything below came out of reading 35 finished guides in one pass. Each rule
 names the accident that produced it. None of them is a style preference — in
 every case the guide passed every other rule in this file and still handed the
 reader a wrong answer that looked right.
 ### A value copied into a container is a snapshot, not a reference
 `kubectl run --env="K0=$K0"`, `docker run -e`, cloud-init user-data: each bakes
 the string as it was at that moment. From then on two spellings mean different
 things, and they differ by two characters:
 ```bash
 exec pod -- sh -c '...$K0...'          # the value baked into the pod
 exec pod -- sh -c '...'"$K0"'...'      # the value in the shell typing this
 ```
 **They agree until something restarts.** In one guide a `rollout restart` changed
 the pod IP, and a later step still read the baked copy; the request went to an
 address that no longer existed, and the failure it produced was a `500` — which
 was also that step's expected result. The screen looked correct.
 So: when a step replaces the thing a baked value points at — a pod IP, a node
 address, a lease — say in that step which spelling the next commands use.
 Prefer recreating the container. If state inside it forbids that, show the
 live-read form and add one line saying why it differs from the block above.
 **Distance is not the test.** A variable defined 700 lines up can be safe, and
 one defined nine lines up can be stale. Ask what happened in between.
 ### A step that only works inside a window says when, not just what
 The four-part shape above — what / command / where to look / what it means —
 has no *when*. Several steps read correctly only during a restart, only while a
 rule is installed, only within sixty seconds. Read late, they do not error;
 they print a different, plausible number.
 Name the command that opens the window and the one that closes it, and say
 **what the reader sees if they type it after it closed** — that is what most
 readers will actually get.
 ### A check must be able to fail
 For every line that says "이렇게 나오면 통과", state what would print the same
 thing while the condition is false. Three real cases:
 - `virsh list --all` used to prove a group membership took effect — it connects
  to the per-user URI, which works with no group at all
 - a `postmaster.pid` path checked on a fixed node, when the volume may be on the
  other one — "no such file" passes either way
 - `source ~/.bashrc` on a host whose login shell is zsh — true in that shell,
  gone at next login, and the symptom surfaces one guide later
 If the check passes when the step was skipped — because it reads a different
 scope, host or shell than the step wrote to — it is not a check. Put the scope
 in the command, or write one line naming the failure this check cannot see.
 ### Never ship a command the guide knows is wrong
 Three guides printed a command and told the reader, in prose underneath, to
 edit it before typing. Prose is not a guard. The worst of them was a **valid**
 assignment:
 ```bash
 OLDID=980ee9b7-...        # ← copy from the output above
 ```
 Paste it and `OLDID` holds the literal string, and the `delete` two lines later
 runs. Every other hardcoded value in those guides failed loudly — `(0 rows)`,
 `(nil)`. This one succeeded at the wrong thing.
 If prose under a block says "replace X first", the block already says it — or
 says `{{X}}`, which is not shell syntax and fails where the reader can see it.
 ### One block, one machine
 A code block is the reader's copy unit. When the machine changes, the block
 ends, even when the commands form one logical step. Splitting the explanation
 in prose does not help: they copy the block.
 And a machine label tells the reader *where* a block runs — it does not put
 them there. When consecutive blocks carry different labels, the transition is
 its own step with its own command (`ssh host`, `exit`, "open a second
 terminal"). Count them per guide: entries and exits must balance. A
 verification section that runs somewhere else needs both.
 ### A shell function defined mid-guide is worse than all three tiers
 It leaves no file, so the reader cannot re-read it. It dies with the shell, so
 a new window silently breaks every later step. `unset` does not reach it.
 One guide defined `R()` on line 188 and used it through line 617 — a one-letter
 name for `kubectl -n … exec deploy/redis -- redis-cli`. At the point of use
 the reader cannot see what command they are running.
 If something is repeated often enough to want a name, make it a script file
 with that name. If it must be a function, define it in the same block as its
 first use, name it for what it does (`redis`, not `R`), and restate the
 definition at the top of any later section more than a screen away.
 ### Names the reader must already have
 A host alias, a directory, a volume, a file that no earlier step created is not
 a placeholder — it is an assumption, and the placeholder rule above does not
 catch it. Four guides in one set ran entirely on `ssh kc-lab-1` with no stanza
 anywhere that creates it; the second guide hits it on its first command.
 Show the command that creates it, or name the guide that owns it, in the prose
 above the first block that uses it.
 ### Walk the guide twice
 `echo >>` is one case of a larger rule. Anything created under a fixed name — a
 pod, a volume, a DHCP reservation, a namespace — says what the second run
 prints and how to clear it first. `--rm` only removes on clean exit; Ctrl+C
 leaves the pod and the next run dies on `AlreadyExists`.
 And anything that destroys and recreates a host says what identity changes with
 it — SSH host keys, MAC-bound leases, certificates — and what that breaks the
 next time the reader connects.
 ### The output block belongs to the command above it
 If it came from a wider `grep`, an extra `uniq -c`, or a `sed` that rewrote
 names, show that command too or say so on the line before. Readers compare
 their screen to yours character by character; a silent edit makes them hunt for
 a fault that is not there.
 ### Context selectors are read as a set
 `-n`, `--context`, `-h`, `-U`. One guide's `kubectl exec` was missing
 `-n keycloak-lab` while the eight commands around it had it. On its own the
 line looks fine; next to its neighbours it is obviously running somewhere else.
 Read them as a column, not line by line.
 ### When the same action has several forms, one of them is the step
 One guide gave three ways to kill a backend and marked none of them. Show the
 step; put the rest under a heading that says they are alternatives. Leaving the
 reader to choose asks them to weigh a trade-off the guide has not explained yet.
 ### A fixed output path makes a block single-use
 "Change the variable and run it again" is incomplete when the block writes to a
 fixed file: the second run overwrites the first run's baseline, silently, and
 the comparison two sections later has nothing to compare against. Name the
 output path among the things to change.
 ### Run the remedy you prescribe
 A guide diagnosed lexical sorting and prescribed `sort -g`. Every line in that
 file began with the same `200`, so `sort -g` compared equal and fell through to
 byte order — its output was identical to plain `sort`. The fix the guide
 offered did not fix anything, and the sentence "miss this and you misread the
 maximum" stayed true after following it.
 ## Rationalization table
 | Excuse | Reality |
 |---|---|
 | "The pipeline gives a clean answer" | The reader needs to read the raw output, not your summary of it |
 | "python -c is shorter than explaining" | It is shorter for you. The reader learns nothing and cannot adapt it |
 | "jq/awk are also programming" | They are what practitioners type. The line is *program vs command*, not *language* |
 | "I'll show the efficient way" | Efficient for one run. This doc is for someone learning to read the system |
 | "The reader can copy-paste it" | Copy-paste is not the goal. Knowing where to look is |
 | "I verified the logic mentally" | Run it. Two commands in a recent guide were wrong and both looked right |
 | "It's obvious what this output means" | Then write the one line. If it is obvious it costs nothing |
 | "`-w '%{http_code}'` is precise" | Precise about one field. The reader debugging TLS needs `-v`, not `200` |
 | "It's fewer commands" | Fewer for you to type. The reader cannot tell which action they are in the middle of |
 | "The file ends up the same either way" | Only on the first run. `echo >>` appends again every time someone repeats the guide |
 | "So I should use nano for everything" | No. The trigger is authoring a file the reader must understand. `grep`, `virsh`, a long `virt-install` stay as they are |
 | "`python3 -c` only checks syntax" | Then it misses the schema. If the format has a validator — `cloud-init schema`, `nginx -t`, `--dry-run` — that is the step |
 | "The prose right under it says to change that value" | The reader copies the block. Prose is not a guard — put `{{NAME}}` in the block |
 | "The variable is defined earlier in the same shell" | Ask what restarted in between. A pod IP baked at line 877 was stale by line 764 |
 | "The label says which machine it runs on" | A label says where, not how to get there. The transition is its own step |
 | "It's the same command, just shorter" | A one-letter function hides the command at the exact moment the reader needs to read it |
 | "The check passed" | Ask what it would print if the step had been skipped. Three checks in one set passed either way |
 ## Red flags — stop and rewrite
 - `python3 -c` or a `<<'PY'` heredoc inside a guide
 - JSON parsed with a language runtime instead of `jq` or the tool's own `-o`
 - a pipeline whose purpose you cannot state in one clause
 - a command with no "what to look at" line under it
 - `delete`/`kill`/`restart` before any observation step
 - `<placeholder>` with no command that produces it
 - output shown that you never actually ran
 - only the extracting form of a tool appears, never the reading form
 - a config file or YAML built with `printf >`, `echo >>`, or `cat <<EOF`
 - one line stacking connect + redirect + file creation (`ssh host 'cat > f' < f`)
 - `python3 -c` checking syntax when the format has its own validator
 - a step that appends, so walking the guide twice appends the line twice
 - prose under a block telling the reader to edit the command before typing it
 - a block whose machine label differs from the one above, with no command between
 - a one- or two-letter shell function, or any function defined far from its use
 - a host alias, directory or volume that no step in any guide creates
 - `--rm` with no line saying what a Ctrl+C leaves behind
 - a "통과" line that would print the same thing if the step had been skipped
 - a step that reads correctly only during a window, with no word about the window
 - a remedy you have not run against the data that made you prescribe it
 ## References
 Per-technology command vocabulary — what practitioners reach for first, not
 an encyclopedia. Load only the one you need.
 - [kubernetes.md](references/kubernetes.md)
 - [linux-systemd.md](references/linux-systemd.md)
 - [networking-tls.md](references/networking-tls.md)
 - [datastores.md](references/datastores.md)
@@ -0,0 +1,52 @@
 # 데이터 저장소 — what to reach for first
 ## PostgreSQL
 ```bash
 psql -U <user> -d <db>
 ```
 ```
 \conninfo          지금 어디에 붙어 있나
 \dt                테이블 목록
 \d <table>         구조 · 인덱스 · 제약
 \du                롤
 \l                 데이터베이스 목록
 \x                 세로 출력 토글 (넓은 행을 볼 때)
 ```
 ```sql
 SHOW <setting>;                          -- 전역값
 SELECT * FROM pg_stat_activity;          -- 지금 도는 쿼리
 EXPLAIN <query>;                         -- 계획만
 EXPLAIN (ANALYZE, BUFFERS) <query>;      -- 실제 실행. 변경 쿼리에 쓰면 실제로 바뀐다
 ```
 한 줄로 값만 뽑을 때.
 ```bash
 kubectl exec deploy/postgres -- psql -U <user> -d <db> -tAc 'select count(*) from <t>'
 ```
 문장 로깅 — 애플리케이션을 고치지 않고 「무엇이 DB 를 어떻게 쓰는지」 본다.
 ```sql
 ALTER SYSTEM SET log_statement = 'all';
 SELECT pg_reload_conf();
 -- 끝나면 되돌린다
 ALTER SYSTEM RESET log_statement;
 ```
 ## Redis
 ```bash
 redis-cli ping
 redis-cli info server | head
 redis-cli dbsize
 redis-cli --scan --pattern '<prefix>*'    # KEYS 대신. 블로킹하지 않는다
 redis-cli type <key>
 redis-cli ttl <key>
 redis-cli --no-raw get <key>              # 바이너리를 이스케이프해 보여 준다
 redis-cli config get appendonly
 ```
 `\xac\xed` 로 시작하면 Java 네이티브 직렬화라 사람이 읽을 수 없다.
 `/data` 가 볼륨이 아니면 영속화 설정은 컨테이너와 함께 사라진다.
 ```bash
 kubectl get pod -l app=redis -o jsonpath='{.items[0].spec.volumes}'
 ```
@@ -0,0 +1,72 @@
 # Kubernetes — what to reach for first
 Order matters. Widen first, then narrow.
 ## 무엇이 있나
 ```bash
 kubectl get pods                    # 이름 · 상태 · 재시작 횟수
 kubectl get pods -o wide            # + 노드 · 파드 IP
 kubectl get all                     # 워크로드 계열만. Secret·PVC·Ingress 는 안 나온다
 kubectl get secret,configmap,pvc,ingress
 ```
 ## 왜 이 파드가 이런가
 ```bash
 kubectl describe pod <pod>          # 이벤트가 여기 붙는다 — 로그보다 먼저 본다
 kubectl logs <pod>
 kubectl logs <pod> --previous       # CrashLoop 이면 죽은 이유는 여기 있다
 kubectl logs <pod> -c <container>   # 컨테이너가 여럿일 때
 kubectl events --for pod/<pod>
 kubectl get events --sort-by=.lastTimestamp | tail -20
 ```
 ## 사슬을 따라간다
 ```bash
 kubectl get deploy,rs,pod -l app=<label>
 ```
 Deployment 는 파드를 직접 만들지 않는다. ReplicaSet 을 만들고 그것이 파드를
 만든다. RS 가 여러 개 남아 있는 것은 정상이며(배포 이력) 활성인 것만 0 이 아니다.
 StatefulSet 은 RS 를 쓰지 않고 파드를 직접 만든다 — 이름이 고정이라
 `Terminating` 이 안 풀리면 대체 파드가 생기지 않는다.
 ## Service 가 파드를 잡고 있나
 ```bash
 kubectl describe svc <svc> | grep -i endpoints
 kubectl get endpointslice -l kubernetes.io/service-name=<svc>
 ```
 `kubectl get endpoints` 는 v1.33+ 에서 deprecated 다.
 비어 있으면 셀렉터와 라벨이 안 맞거나 readiness 미통과다.
 ```bash
 kubectl get svc <svc> -o jsonpath='{.spec.selector}'
 kubectl get pods --show-labels
 ```
 ## Secret 이 실제로 들어갔나 — 값은 찍지 않는다
 ```bash
 kubectl get secret <s> -o jsonpath='{.data}' | tr ',' '\n' | grep -o '"[A-Z_]*"'   # 키 이름만
 kubectl get secret <s> -o jsonpath='{.data.<KEY>}' | base64 -d | wc -c             # 길이만
 kubectl exec <pod> -- sh -c 'echo ${#MY_ENV}'                                      # 파드 안 주입 확인
 ```
 ## 적용과 대기
 ```bash
 kubectl apply -f <file>
 kubectl rollout status deploy/<name> --timeout=180s      # 끝날 때까지 블록한다
 kubectl rollout undo deploy/<name>
 ```
 ## 안에서 볼 때
 ```bash
 kubectl exec -it <pod> -- sh
 kubectl port-forward svc/<svc> 8080:80
 kubectl debug -it <pod> --image=busybox --target=<container>   # 최소 이미지에 도구가 없을 때
 ```
 **최소 이미지에는 `curl` 도 `wget` 도 없다.** Keycloak 공식 이미지가 그렇다
 (`exit 127`). 밖에서 물어보거나 임시 파드를 띄운다.
 ```bash
 kubectl run tmp --rm -it --restart=Never --image=curlimages/curl:8.11.1 -- \
  curl -s http://<podIP>:9000/metrics
 ```
@@ -0,0 +1,51 @@
 # Linux · systemd — what to reach for first
 ## 서비스 상태
 ```bash
 systemctl status <unit>             # 상태 · Main PID · CGroup · 최근 로그
 systemctl is-active <unit>          # 한 단어. 스크립트용
 systemctl cat <unit>                # 유닛 파일에 적힌 것
 systemctl show <unit>               # 기본값까지 합쳐 실제 적용되는 것
 ```
 `cat` 과 `show` 는 다르다. `Restart=on-failure` 만 적혀 있어도 `show` 는
 `RestartUSec`·`StartLimitBurst` 같은 기본값을 함께 보여 준다.
 ## 로그
 ```bash
 journalctl -u <unit> -n 50          # 최근 50줄
 journalctl -u <unit> -e             # 끝으로 (페이저)
 journalctl -u <unit> -f             # 실시간
 journalctl -u <unit> -p err         # 에러만
 journalctl -u <unit> --since '1 hour ago'
 journalctl -u <unit> -o json        # 메타데이터까지
 ```
 긴 줄이 접히면 `less -S` 로 좌우 스크롤한다.
 **nginx 에러 로그는 2048바이트에서 잘린다**(`NGX_MAX_ERROR_STR`). 저널
 포맷을 바꿔도 안 늘어난다 — 기록 자체가 잘렸기 때문이다. access 로그에는
 제한이 없으므로 그쪽을 본다.
 ## 프로세스 · 포트 · 자원
 ```bash
 ps aux | grep <name>
 ps -eo pid,ppid,etimes,lstart,args | grep <name>   # 얼마나 오래 떠 있나
 ss -lntp                            # 듣고 있는 TCP 포트 + 프로세스
 lsof -i :8080
 free -m
 top / htop
 ```
 ## cgroup
 ```bash
 systemd-cgls /system.slice/<unit>.service
 cat /sys/fs/cgroup/system.slice/<unit>.service/memory.current
 cat /sys/fs/cgroup/system.slice/<unit>.service/pids.current
 ```
 `systemctl status` 의 `Memory:` `Tasks:` `CPU:` 가 여기서 읽은 값이다.
 ## nginx
 ```bash
 nginx -t && systemctl reload nginx   # -t 를 통과할 때만 reload
 ps -eo pid,lstart,args | grep 'nginx: worker'   # reload 판정은 워커 PID 로
 ```
 reload 하면 마스터는 유지되고 워커만 새로 뜬다. 로그 문구가 아니라 이걸 본다.
@@ -0,0 +1,61 @@
 # 네트워크 · TLS — what to reach for first
 ## HTTP
 ```bash
 curl -I <url>                                  # 한 번 볼 때
 curl -v <url>                                  # 헤더 · TLS 협상까지
 curl -s -o /dev/null -w '%{http_code}\n' <url> # 여러 번 재서 비교할 때만
 ```
 `-w` 형태는 측정용이다. 눈으로 한 번 볼 때는 `-I` 나 `-v` 로 충분하다.
 ## 이름 해석
 ```bash
 dig +short <name>
 getent hosts <name>          # /etc/hosts 와 NSS 순서까지 반영된 결과
 ```
 ## TLS
 ```bash
 echo | openssl s_client -connect <host>:443 -servername <host> 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
 echo | openssl s_client -connect <host>:443 -servername <host> 2>/dev/null \
  | grep -E '^ *[0-9]+ s:|^ *i:|Verify return code'
 ```
 체인 단계가 1개면 `cert.pem` 을 쓴 것이다. `fullchain.pem` 이어야 한다.
 발급 시각의 외부 기준이 필요하면 SCT 를 본다.
 ```bash
 … | openssl x509 -noout -ext ct_precert_scts
 ```
 ## 연결 추적
 ```bash
 sudo conntrack -L | grep <port>
 sudo conntrack -C
 cat /proc/sys/net/netfilter/nf_conntrack_tcp_timeout_established   # 보통 86400
 ```
 `ESTABLISHED` 는 대부분의 방화벽 규칙 평가를 건너뛴다. 규칙을 넣었는데
 아무 일도 없으면 여기를 먼저 본다.
 ## 방화벽 규칙
 ```bash
 sudo iptables -S FORWARD             # 순서가 중요하다 — 내 규칙이 몇 번째인가
 sudo iptables -L FORWARD -v -n       # 카운터가 0 이면 도달하지 않았다
 sudo iptables -t raw -S PREROUTING   # conntrack 보다 먼저 잡는 자리
 ```
 ## 패킷
 ```bash
 sudo tcpdump -i <iface> -n port <p> -c 20
 ```
 오버레이 네트워크(flannel VXLAN 등)에서는 물리 인터페이스에 안쪽 IP 가 안
 보인다. `flannel.1` 같은 터널 인터페이스에서 잡는다.
 ## 시계
 ```bash
 timedatectl show -p NTP -p NTPSynchronized
 A=$(date -u +%s.%N); B=$(ssh <host> 'date -u +%s.%N'); C=$(date -u +%s.%N)
 curl -sI https://www.google.com | grep -i '^date:'    # 어느 쪽이 맞는지 외부 기준
 ```
 두 기계의 로그를 나란히 놓기 전에 확인한다.
@@ -1,16 +1,17 @@
 # writing-tech-log-records
-Tech Log Studio에 올릴 기록을 쓰는 스킬. Case · Concept · Reference · Question · Decision 다섯 종류의
+Tech Log Studio에 올릴 기록을 쓰는 스킬. Case · Concept · Setup · Reference · Question · Decision
-종류 선택, 칸 채우기, Case 본문 작성, 게시 전 대조를 다룬다.
+여섯 종류의 종류 선택, 칸 채우기, 본문 작성, 게시 전 대조를 다룬다.
 ## 파일
 | 파일 | 무엇 |
 |---|---|
 | `SKILL.md` | 진입점. 종류 선택과 절차 |
-| `references/record-kinds.md` | 다섯 종류의 칸·상한·게시 조건 |
+| `references/record-kinds.md` | 여섯 종류의 칸·상한·게시 조건 |
 | `references/from-ssot-to-records.md` | 긴 글에서 글감을 뽑는 기준과 `tech-log-tree.json` |
 | `references/writing-each-kind.md` | 종류마다 무엇을 어떤 순서로 쓰나 |
 | `templates/*.md` | 종류별 빈 틀. 복사해서 채운다 |
 | `references/body-syntax.md` | Case 본문의 허용·금지 문법 |
 | `references/code-tables-diagrams.md` | 코드블록·표·SVG·이미지 |
 | `references/explaining.md` | 설명의 깊이와 말투 |
@@ -55,5 +56,5 @@ FAIL  초안.md:3:1  unsupported block syntax: html
 ## 알아둘 제약
-코드·표·다이어그램·이미지는 **본문에만** 들어간다. 본문이 있는 종류는 Case 와 Concept 이다. Reference·Question·Decision의 모든
+코드·표·다이어그램·이미지는 **본문에만** 들어간다. 본문이 있는 종류는 Case·Concept·Setup 셋이고,
-칸은 평문으로 렌더링된다. 설계상 그렇다 — 본문을 가진 종류는 Case뿐이다.
+Reference·Question·Decision의 모든 칸은 평문으로 렌더링된다.
@@ -1,6 +1,6 @@
 ---
 name: writing-tech-log-records
-description: Use when writing or revising a Tech Log Studio record — Case, Concept, Reference, Question, or Decision — including choosing the right kind, filling each kind's fields, authoring body Markdown with code blocks, tables, callouts, diagrams and evidence images, and linking records so a published document renders correctly on the public site.
+description: Use when writing or revising a Tech Log Studio record — Case, Concept, Setup, Reference, Question, or Decision — including choosing the right kind, filling each kind's fields, authoring body Markdown with code blocks, tables, callouts, diagrams and evidence images, and linking records so a published document renders correctly on the public site.
 metadata:
  version: "1.1.0"
  language: "ko-KR"
@@ -12,48 +12,108 @@ metadata:
 ## 개요
-Studio는 다섯 종류를 구분한다. 종류를 잘못 고르면 채울 칸이 맞지 않는다.
+Studio는 여섯 종류를 구분한다. 종류를 잘못 고르면 채울 칸이 맞지 않는다.
 | 종류 | 쓰는 때 | 본문 |
 |---|---|---|
 | **Case** | 내가 재현하고 검증해 결론을 냈다 | 있음 |
 | **Concept** | 남의 것이 어떻게 동작하는지 읽고 정리했다 | 있음 |
 | **Setup** | 남이 자기 손으로 따라 할 절차를 남긴다 (`SETUP`, 화면 이름 「환경 구성」) | 있음 |
 | **Reference** | 반복 적용할 기준을 굳혔다 | 없음 |
 | **Question** | 아직 판단이 안 끝났다 | 없음 |
 | **Decision** | 프로젝트가 방향을 정했다 (`PROJECT_DECISION`) | 없음 |
 **Setup 만 끝난 일을 적지 않는다.** 나머지 다섯은 이미 일어난 일을 적고, Setup 은 읽는 사람이
 자기 기계에서 실행할 순서를 적는다. 그래서 본문에 명령이 들어가고, 버전만 본문 밖의
 `pinnedVersions` 에 남는다. 프로젝트가 필수이고 주제는 비워도 된다.
 ## 절대 규칙
-**코드·표·다이어그램·이미지는 본문에만 들어간다. 본문이 있는 종류는 Case 와 Concept 둘뿐이다.**
+**코드·표·다이어그램·이미지는 본문에만 들어간다. 본문이 있는 종류는 Case·Concept·Setup 셋이다.**
-본문이 없는 세 종류의 칸은 평문으로 렌더링돼 백틱과 파이프가 글자 그대로 보인다. 그런 자료는 Case 나
+본문이 없는 세 종류(Reference·Question·Decision)의 칸은 평문으로 렌더링돼 백틱과 파이프가 글자
-Concept 에 담고 `관계`로 가리킨다. `references/record-kinds.md`
+그대로 보인다. 그런 자료는 본문이 있는 종류에 담고 `관계`로 가리킨다. `references/record-kinds.md`
 ## 필수 절차
-0. **글감 나누기** — 긴 글(SSOT)에서 옮겨 오는 것이면 먼저 나눈다. 기준과 `tech-log-tree.json`
+0. **글감 나누기** — 긴 글(SSOT)에서 옮겨 오는 것이면 먼저 나눈다. 기준은
-   형식은 `references/from-ssot-to-records.md`. 나눈 뒤 글을 쓴다.
+   `references/from-ssot-to-records.md`, 계약은 `references/tech-log-tree-contract.md`.
-1. **종류 선택** — 위 표. 애매하면 "재현했나"를 묻는다.
+   **`tech-log-tree.json` 에 노드가 없는 글은 쓰지 않는다** — 트리에 먼저 올리고, 그 노드의
   후보가 `PROMOTE` 이면서 `dispositionReview: CONFIRMED` 인지 확인한 뒤에 쓴다. `PENDING` 은
   사람이 다시 읽지 않았다는 뜻이라, 그 위에 쓴 글은 과분류를 그대로 물려받는다. 계약 밖에서 쓴
   기록은 색인에 `unlisted` 로 남는다. 그 노드의 `ssot-assets`·`ssot-evidence` 도 함께 본다 —
   SSOT 가 이미 그린 그림과 이미 돌린 측정 가운데 이 글감에 배정된 것이 거기 적혀 있다.
 1. **종류 선택** — 위 표. 애매하면 「끝난 일을 적나, 남이 따라 할 절차를 적나」를 먼저 묻고,
   끝난 일이면 "재현했나"를 묻는다.
 2. **칸 채우기** — 칸과 게시 조건은 `references/record-kinds.md`.
-3. **본문 작성**(Case·Concept) — **종류마다 무엇을 어떤 순서로 쓰는지는
+3. **본문 작성**(Case·Concept·Setup) — **종류마다 무엇을 어떤 순서로 쓰는지는
-   `references/writing-each-kind.md`.** 문법은 `references/body-syntax.md`, 표·코드·그림은
+   `references/writing-each-kind.md`.**
   **Setup 은 본문을 쓰기 전에 `Skill` 도구로 `writing-practitioner-guides` 를 연다.** 명령을
   어떤 형태로 쓸지는 그 스킬이 정한다. 그다음이 `references/writing-each-kind.md` 의 Setup 절이다 —
   단계 하나의 모양과 이 저장소에서만 걸리는 셋이 거기 있다.
   문법은 `references/body-syntax.md`, 표·코드·그림은
   `references/code-tables-diagrams.md`. **문장은 `references/explaining.md`.**
-   **문서군 전체의 리듬은 `references/ai-tells.md`.**
+   **문서군 전체의 리듬은 `references/ai-tells.md`.** 이 둘은 첫 초안부터 적용한다 — AI 티를
-   그림이 필요하면 손으로 그리지 말고 `technical-visualizer` 스킬로 만든다.
+   남겨 두고 나중에 걷어내는 순서가 아니다. **문체를 손보기 전에 문장을 고른다** — 설명이 끝난
-   이미 쓴 문장이 AI가 쓴 것처럼 읽히면 `rewriting-technical-prose-naturally` 로 다시 쓴다.
+   뒤에 붙은 평가·예고·되풀이·독자 오해 가정을 먼저 뺀다(`ai-tells.md` 첫 절). 문체 규칙의
-4. **검사** — 둘 다 돌린다. 파서와 문장은 다른 것을 본다.
+   정본은 `ai-tells.md` 다.
-   - `scripts/check_body.mjs` — Case 본문이 Studio 파서를 통과하는지. 같은 파서를 그대로 부른다.
+   **그림이 필요한지, 필요하면 무엇을 그릴지는 `references/choosing-a-diagram.md`.** 담을 곳
   (Case·Concept·Setup 만) · 표가 아닌지 · 옆 문단이 이미 말하지 않았는지 세 관문을 지나야 그린다.
   순서·경계·상태 전이처럼 문장만으로 따라가기 어려운 관계가 있으면 **`final/assets/` 에 그
   그림이 이미 있는지부터 본다.** SSOT 를 만들 때 그려 둔 것이 있고 계약의 `ssot-assets` 가 이
   글감에 배정해 두었으면 기록의 `assets` 가 **그 파일을 그대로** 가리킨다. 사본을 따로 만들지
   않는다 — 사본에는 `.techviz/<이름>/` 이 없어 다시 만들 수 없다. **없을 때만**
   `technical-visualizer` 로 새로 만든다. 손으로
   SVG 를 그리지 않고, 모든 글에 그림을 만들지도 않는다.
   인용할 측정도 같다. `final/evidence/` 에 있는 원문을 가리키고 같은 것을 다시 돌리지 않는다.
   **그림과 측정을 그 자리에서 만들어 내기 전에 SSOT 가 이미 가진 것을 먼저 찾는다** — keycloak
   에서는 그러지 않아 정본까지 갖춘 그림 13 장이 남고 이름이 다른 그림 5 장이 새로 만들어졌다.
 4. **검사** — 셋 다 돌린다. 파서와 문장과 증빙은 각각 다른 것을 본다.
   - `scripts/check_body.mjs` — 본문이 Studio 파서를 통과하는지. 같은 파서를 그대로 부른다.
     저장소의 그림은 마크다운 이미지이므로 `python3 scripts/studio-body.py <기록> -o /tmp/x.md`
     로 바꾼 파일에 돌린다. 저장소 파일에 그대로 돌리면 `unsafe image URL` 로 실패한다.
   - `rewriting-technical-prose-naturally/scripts/check_prose.mjs` — 문장 규범. **error 0 이 될 때까지 고친다.**
     칸 하나나 한 절만 고쳤으면 `--doc` 없이 부른다. 이어서 `style_profile.mjs` 로 문체 수치를 본다.
   - `scripts/check_evidence.mjs <프로젝트> --repo` — **인용한 것이 실재하는지.** 본문 코드블록의
     각 줄이 SSOT 안에 있는지, `source` 앵커가 SSOT 를 가리키는지, 제목이 계약과 같은지,
     `sourceRepository` 의 리비전이 그 저장소에 있는지를 본다.
 5. **관계 연결** — Decision은 근거가 **1개 이상** 없으면 게시가 거절된다.
 6. **Studio에서 확인** — 넣고 **저장까지만** 한 뒤 미리보기로 읽는다.
   절차는 `references/studio-draft-review.md`. **게시하지 않는다.**
-7. **게시** — 고칠 것이 없을 때만. 못 채운 칸은 그 칸 아래에 표시된다.
+7. **색인 갱신** — 기록을 쓰거나 지웠으면 다시 만들고 검사한다.
   `python3 scripts/build-tech-log-tree.py <프로젝트>` ·
   `python3 scripts/verify-tech-log-tree.py <프로젝트>` — error 0 이어야 한다.
 8. **게시** — 고칠 것이 없을 때만. 못 채운 칸은 그 칸 아래에 표시된다.
 ## 어느 스킬이 무엇을 하나
 이 스킬이 첫 초안을 만든다. `writing-practitioner-guides` 는 Setup 본문을 쓰는 동안 함께 열고,
 나머지는 초안이 나온 뒤에 각각 다른 것을 고친다.
 | 스킬 | 하는 일 | 하지 않는 일 |
 |---|---|---|
 | `deriving-tech-log-root-tree` | 후보에 처분을 매기고 `PROMOTE` 를 글감으로 올린다 | 글을 쓰지 않는다 |
 | `writing-tech-log-records` | 종류를 고르고 칸과 본문을 쓴다. `explaining.md`·`ai-tells.md` 를 처음부터 적용한다 | — |
 | `writing-practitioner-guides` | 사람이 직접 치는 명령의 형태를 정한다 — 한 줄에 담는 계층, 도구 우선순위, 출력을 읽는 형태와 값 하나만 뽑는 형태, 넓은 명령에서 좁은 명령으로 | Tech Log 의 종류와 칸을 모른다. SSOT 대조도 색인 갱신도 하지 않는다 |
 | `technical-visualizer` | 문장으로 따라가기 어려운 관계를 그림으로 만든다 | 무엇을 그릴지 정하지 않는다 — `choosing-a-diagram.md` 가 정한다 |
 | `rewriting-technical-prose-naturally` | 사실과 구조가 이미 맞는 초안의 번역투·반복 문형·과한 대구를 고친다 | 분류가 틀렸거나 근거가 모자란 것은 못 고친다 |
 | `writing-as-the-person-who-did-it` | 자료에 남아 있는 선택·비교·어긋남·확인하지 못한 범위를 제자리에 놓는다 | 자료에 없는 「처음에는」·「고민 끝에」를 만들지 않는다 |
 Reference·Question·Decision 은 그림을 렌더링할 곳이 없다. 그림이 필요한 내용은 짝이 되는
 Case·Concept·Setup 에 담고 `관계`로 가리킨다.
 ## 보호 구간
 수치, 날짜, 버전, 단위, 코드, 명령어, URL, 인용, 공식 명칭은 원문과 한 글자도 달라지면 안 된다.
 측정하지 않은 값을 채우지 않는다 — 검증일은 실제로 확인한 날이다.
 **옮겨 적었다고 확인한 것이 아니다.** 앞선 기록에서 코드를 가져오거나 기억으로 경로를 쓰면
 SSOT 에 없는 인용이 생긴다. 실제로 그렇게 게시된 기록에 잘못된 redirect URI 가 네 곳 남아 있었고,
 realm 설정이 와일드카드라 실행해도 드러나지 않았다. **인용한 줄은 SSOT 에서 찾아 대조한다.**
 `check_evidence.mjs` 가 그 대조를 기계로 한 번 더 한다.
 SSOT 에 없는데 필요한 인용이라면 순서가 반대다 — `final/document.md` 를 먼저 보강하고,
 그것도 저장소에서 확인한 뒤에 한다. `sourceRepository.path` 가 그 저장소를 가리킨다.
 ## 쓰지 않는 것
 - 자료가 뒷받침하지 않는 선택 이유. 썼다는 사실을 왜 골랐는지로 바꾸지 않는다.
@@ -65,7 +125,7 @@ Concept 에 담고 `관계`로 가리킨다. `references/record-kinds.md`
 | 실패 | 대응 |
 |---|---|
 | Reference 규칙에 코드블록 | Case로 옮겨 관계 연결 |
-| 본문 밖 칸에 백틱 | 평문이다. 백틱을 뺀다 |
+| 본문 밖 칸에서 백틱을 뺌 | 이 칸도 백틱은 `<code>` 로 산다. 빼는 것은 별표·파이프·`#` 다 |
 | 평문 칸에 쉼표 나열 | `이름 : 값`으로 줄 나눔. 있음·없음은 `o`·`x` |
 | 표 머리글이 명사뿐 | 질문으로. 비교 축은 `전`·`후` 시점으로 |
 | 그림 안에 문장·숫자 | `<text>`는 이름만. 문장은 `<desc>`·옆 문단에 |
@@ -79,7 +139,17 @@ Concept 에 담고 `관계`로 가리킨다. `references/record-kinds.md`
 | 문서마다 같은 문형·같은 길이 | `references/ai-tells.md` |
 | 표를 `:::table`로 감쌈 | 그냥 파이프로 쓴다 |
 | `![](https://…외부)` | Asset으로 올려 `/api/v1/public/media/…` |
 | SSOT 에 있는 그림을 두고 새로 그림 | `final/assets/` 를 먼저 본다. `ssot-assets` 가 배정한 것을 쓴다 |
 | SSOT 에 있는 측정을 두고 다시 돌림 | `final/evidence/` 의 원문을 가리킨다 |
 | Decision에 근거 없음 | 관계 1개 이상 연결 |
 | Setup에 끝난 일을 적음 | 따라 할 순서가 아니면 Case다 |
 | Setup 본문에 `printf >`·`echo >>`·`python3 -c` | 사람이 치는 형태로 바꾼다. 설정 파일은 에디터로 연다 |
 | Setup 본문의 명령만 고치고 SSOT 를 그대로 둠 | `final/document.md` 를 먼저 고친다. `check_evidence.mjs` 가 막는다 |
 | Setup 본문에 「2026-09-12 기준」 | 검증일 칸이 없다. 버전은 `pinnedVersions` 에 적는다 |
 | Setup에 프로젝트를 안 고름 | 「환경 구성은 프로젝트에 속합니다」로 막힌다 |
 | 측정 안 한 검증일 | 비워 둔다 |
 | 설명 직후에 「~증거다」「~가 아니다」로 평가 | 지운다. 앞 문장이 사실을 말했으면 거기서 끝낸다 |
 | 「~로 읽기 쉽다. 그렇지 않다」 | 오해를 지어내지 않는다. 관측부터 적는다 |
 | 「먼저 ~를 보고 …」 차례 예고 · 「~를 함께 적는다」 | 지운다. 다음 절이 바로 시작한다 |
 작성 후 `references/review-checklist.md`로 대조한다.
@@ -3,6 +3,95 @@
 문장 하나하나는 멀쩡한데 문서군 전체가 같은 리듬으로 굴러갈 때 티가 난다. 개별 문장을 일부러
 어눌하게 만드는 방향은 역효과다. 아래는 실제 리뷰에서 지적된 것들이다.
 **이 문서가 문체 규칙의 정본이다.** `explaining.md` 는 무엇을 더 설명할지를 다루고, 둘이 어긋나면
 이쪽을 따른다.
 ## 설명 뒤에 평가를 붙이지 않는다
 가장 많이 지적된 형태다. 기술 설명은 이미 끝났는데 그 뒤에 **그 설명을 평가하거나, 다음을 예고하거나,
 독자가 오해할 것이라고 가정하거나, 어떻게 읽고 써야 하는지 지시하는 문장**이 하나 더 붙는다.
 문장마다 무엇을 주는지 본다 — 동작, 정의, 근거, 판단에 영향을 주는 조건 가운데 하나여야 한다.
 그 넷 중 어느 것도 주지 않고 판정만 하는 문장은 지운다. 특정 단어를 금지하는 방식은 쓰지 않는다.
 「중요하다」가 나쁜 것이 아니라 그 문장이 아무것도 더하지 않는 것이 문제다.
 **고치는 순서는 내용이 먼저다.** 필요 없는 문장을 남긴 채 표현만 자연스럽게 바꾸면 어색한 문장의
 표현만 달라진다. 평가·예고·되풀이를 걷어낸 뒤에 문장을 다듬는다.
 네 가지가 반복된다. 전부 「다른 표현으로 고치는 사례」가 아니라 **「통째로 지우는 사례」**다.
 ### 설명한 것의 중요성을 다시 평가한다
 ```text
 ✗ 다른 하나는 앞 단계가 어긋났는데도 나머지를 계속 돌려 마지막에 전체 통과를 남기는 일이다.
  그렇게 만든 기록은 경계가 지켜졌다는 근거가 되지 않는다.
 ○ 다른 하나는 앞 단계가 어긋났는데도 나머지를 계속 돌려 마지막에 전체 통과를 남기는 일이다.
 ✗ 발행된 SQL에 Limit 노드가 없다는 것 자체가 DB가 페이징을 하지 않았다는 증거다.
 ○ 발행된 SQL에는 Limit 노드가 없었다.
 ```
 「증거다」「핵심이다」「너무 넓다」「서로를 대신하지 않는다」로 끝나는 꼬리 문장이 이 형태다.
 앞 문장이 사실을 말했으면 거기서 끝낸다.
 ### 독자가 오해할 것이라고 먼저 가정한다
 ```text
 ✗ 훑은 행만 보면 keyset이 결과까지 줄인 것으로 짐작하기 쉽다. 커서로 넘긴 두 번째 페이지는
  OFFSET의 두 번째 페이지와 같은 20개 식별자를 같은 순서로 반환했다.
 ○ 커서로 넘긴 두 번째 페이지는 OFFSET의 두 번째 페이지와 같은 20개 식별자를 같은 순서로 반환했다.
 ✗ Web Storage에 토큰을 쓰지 않으니 JavaScript에서도 토큰이 사라진다고 읽기 쉽다. 그렇지 않다.
  액세스·리프레시·ID 토큰은 실행 중 메모리에 있다.
 ○ 액세스·리프레시·ID 토큰은 실행 중 메모리에 있다.
 ```
 「~로 읽기 쉽다」「~라고 생각하면 안 된다」「~로 보기 쉽다」. 자료에 누군가 실제로 그렇게 읽었다는
 기록(버그·정정·문의)이 없으면 독자를 지어낸 것이다. 관측부터 적으면 오해는 생기지 않는다.
 ### 어떻게 읽고 어떻게 써야 하는지 지시한다
 ```text
 ✗ AP2와 AP3의 쿠키는 서버 쪽 상태를 찾는 열쇠이고, AP4의 쿠키는 최소 상태를 담은 값이다.
  두 쿠키를 같은 문장으로 설명하면 서버 저장소가 있는 쪽과 없는 쪽이 구분되지 않는다.
 ○ AP2와 AP3의 쿠키는 서버 쪽 상태를 찾는 열쇠이고, AP4의 쿠키는 최소 상태를 담은 값이다.
 ✗ 이 두 낱말만 알면 따라올 수 있고, 나머지는 처음 나오는 곳에서 푼다.
 ✗ 먼저 브라우저가 들고 있는 값부터 보고, 그 값이 Bearer 요청이 되기까지를 따라간다.
 ✗ native로 내려갔다는 것과 그 범위를 함께 적는다.
 ```
 「~라고 설명하면 ~가 구분되지 않는다」「~를 함께 적는다」「먼저 ~를 보고 다음에 ~를 본다」. 독자에게
 필요한 것은 각 쿠키가 무엇을 보관하는지이지 그것을 어떻게 설명해야 하는지가 아니다. 이런 문장은
 작성자의 검토 메모다. 차례 예고도 같다 — 다음 절이 바로 시작하면 된다.
 ### 이미 설명한 것을 다시 말한다
 ```text
 ✗ 배치는 SQL 왕복 횟수를 줄이고 프로젝션은 적재할 대상을 줄인다. 두 효과는 서로를 대신하지 않는다.
 ○ 배치는 SQL 왕복 횟수를 줄이고 프로젝션은 적재할 대상을 줄인다.
 ✗ 반복이 사라진 것이 아니라 스트림 뒤로 숨었다.
 ○ 현재 매핑에서는 각 아이템의 getHighlights()에 접근하면서 지연 로딩이 실행된다.
 ```
 같은 대조를 추상어로 한 번 더 하거나, 동작 설명 뒤에 인상적인 문장으로 닫는 것. 동작을 그대로
 적으면 독자가 비유를 코드 동작으로 다시 번역하지 않아도 된다.
 ### SSOT 에 같은 문장이 있어도 옮기지 않는다
 `final/document.md` 는 사실과 근거의 기준이지 문장의 기준이 아니다. 원문에 「너무 넓은 성공 기준입니다」가
 있어도 기록에 옮길 이유는 없다. 옮기는 것은 수치·조건·동작·판단이고, 평가는 옮기지 않는다.
 ### 무엇을 남기나
 - 코드가 그렇게 동작하는 이유, 측정 조건, 결과를 읽는 데 필요한 예외
 - 실제 선택을 바꾼 판단 — 「200 이어도 정상인 이유는 세션이 유효하기 때문이다」처럼 판정에 영향을 주는 것
 - 요약·결론·본문 사이의 반복 — Studio 칸 구조상 필요하다. 걷어낼 것은 **한 칸 안에서** 설명 직후에 붙은 문장이다
 어미 수·절 수·안내 문장 수 같은 수치는 참고 정보다. `style_profile.mjs` 가 「벗어남」을 내도 그것을
 맞추려고 문장을 넣지 않는다. 위 첫 예시는 문장 검사를 error 0 으로 통과한 채로 지적됐다.
 ## 억지 구어체를 만들지 않는다
 AI 티를 지우려고 넣은 질문체와 청유형이 오히려 「AI 문장을 억지로 인간화한 것」으로 읽힌다.
@@ -93,5 +93,24 @@ mailto:…
 | `list items must contain exactly one paragraph` | 목록을 중첩했다 |
 | `unsafe link URL: …` | 허용되지 않는 스킴이나 `//` 주소 |
 | `duplicate explicit ID: …` | 같은 id를 두 번 썼다 |
 | `unknown inline directive: 27` | **문단에 시각을 그냥 썼다** — 아래를 본다 |
 거절 메시지에는 줄·칸 번호가 붙는다. 그 줄을 먼저 본다.
 ## 문단 안의 시각은 백틱으로 감싼다
 `:` 뒤에 글자가 붙으면 파서가 인라인 directive 로 읽는다. 그래서 문단에 `08:20:27` 을
 그냥 쓰면 `:27` 에서 막힌다. `00/12:00:00` 같은 설정값도 같다.
 ```text
 새 인증서가 08:20:27 에 기록됐다.      ← FAIL  unknown inline directive: 27
 새 인증서가 `08:20:27` 에 기록됐다.    ← PASS
 ```
 **이것이 조용한 결함이 되는 경로가 있다.** 막히면 시각을 빼고 넘어가게 되고, 그러면
 검사기는 통과하는데 **기록에서 수치가 사라진다.** 실제로 한 회차에서 두 편이 각각
 시각 둘과 타이머 설정값을 빼고 통과시켰다. 수치·날짜·시각은 보호 구간이다 —
 **빼지 말고 감싼다.**
 표와 코드블록 안은 걸리지 않는다. 그래서 같은 프로젝트의 다른 기록이 통과하는 것이
 「이 문법이 괜찮다」는 뜻이 아니다 — 그쪽은 시각이 전부 표 안에 있었을 뿐이다.
@@ -0,0 +1,88 @@
 # 기록에 어떤 그림이 필요한지 정하는 기준
 `code-tables-diagrams.md` 는 그림을 **어떻게** 그리는지를 말한다. 이 문서는 그 앞 단계 —
 **이 기록에 그림이 필요한가, 필요하다면 무엇을 그리는가** 를 정한다.
 ## 세 관문
 순서대로 통과해야 그림을 만든다. 하나라도 걸리면 그리지 않는다.
 ### 1. 자리가 있는가
 `assets` 는 본문이 있는 세 종류만 갖는다 — **Case·Concept·Setup**. Reference·Question·Decision 의
 칸은 평문으로 렌더링돼 그림이 들어갈 곳이 없다.
 파생 기록에 그림이 필요해 보이면 그 그림은 **짝이 되는 Case·Concept·Setup 의 것**이다. 거기 담고
 `관계`로 가리킨다. 담을 기록이 없으면 그 그림은 아직 집이 없다 — 계약의
 `assetLedger.unassigned` 에 그렇게 적고, 새 글감을 세울지는 따로 판단한다.
 ### 2. 표가 아닌가
 > **관계선을 다 지워도 뜻이 남는가.** 남으면 표다.
 표는 값을 비교하고, 그림은 **포함·순서·경계**처럼 자리로만 보이는 것을 맡는다. 항목을 같은
 속성으로 늘어놓은 것은 마크다운 표로 쓴다. `verify-project-layout.py` 의 「표로 되는 그림」이
 관계선 없이 항목마다 같은 수의 `details` 를 늘어놓은 spec 을 센다.
 ### 3. 옆 문단이 이미 말하지 않았는가
 > **이 그림이 없으면 독자가 무엇을 못 보나.** 한 문장으로 답할 수 없으면 그리지 않는다.
 기록에 이미 그 비교표가 있으면 그림은 중복이다. 실제로 그렇게 만든 그림 셋을 지웠다 —
 `keyset-vs-offset` 을 넣은 기록에는 훑은 행·buffers·exec 까지 있는 플랜 비교표가 이미 있었다.
 ## 종류마다 무엇을 그리나
 세 관문을 통과했을 때, 그 기록이 요구하는 그림은 종류마다 다르다.
 | 종류 | 그림이 답하는 물음 | 흔한 profile |
 |---|---|---|
 | **Case** | 이 요청 한 번이 어떤 순서로 무엇을 지나갔나 | `sequence` · `component-flow` |
 | **Case** (경계가 논지일 때) | 무엇이 어느 경계 안에 있고 무엇이 밖에 있나 | `two-zone-pipeline` |
 | **Concept** | 남의 것이 어떤 순서·구조로 동작하나 | `sequence` · `component-flow` · `ports-adapters` |
 | **Setup** | (아직 못 적는다 — 아래) | — |
 Case 는 **내가 돌려서 본 것**이라 대개 순서가 논지다. Concept 은 **남의 것이 어떻게 동작하는지**라
 구조나 변환 사슬이 논지다. 어느 쪽이든 「무엇이 무엇으로 바뀌는가」를 못 적으면 아직 그릴 것이
 없다는 뜻이다.
 **Setup 은 담을 곳만 있고 본보기가 없다.** 본문 파서가 Case 와 같아서 그림이 렌더링되기는 한다.
 다만 2026-09-12 에 Studio 의 환경 구성 문서가 0건이라, 위 두 줄처럼 「반복된 물음」을 셀 자료가
 없다. 이 줄은 그림을 그리지 말라는 뜻이 아니라 **아직 아무도 안 그려 봤다**는 뜻이다. 그릴 때는
 세 관문만 그대로 지나고, 무엇을 그렸는지 이 표에 적어 둔다.
 **한 절에 그림 하나.** 같은 절에 구조 그림과 흐름 그림을 둘 다 넣으면 독자가 어느 쪽을 먼저
 읽어야 하는지 알 수 없다. 둘 다 필요하면 절을 나눈다.
 ## 어디를 근거로 삼나 — 기록의 `source` 가 앵커다
 `techviz prepare` 는 `final/document.md` 를 받는다. 기록은 `tech-log-studio/` 에 있지만 **그림의
 근거는 기록이 아니라 기록이 가리키는 SSOT 절**이다. 기록의 `source` 앵커를 그대로 쓴다.
 ```bash
 # 기록의 source: final/document.md#선택의-이유와-지킨-경계-ap1  이면
 ./scripts/techviz prepare docs/<프로젝트>/final/document.md \
  --heading "AP1: OAuth와 JWT 계약을 가장 가까이서 관찰한다" \
  -o docs/<프로젝트>/final/.techviz/<id>/context.json
 ```
 `--line` 은 쓰지 않는다. context 는 관리 블록을 접은 좌표를 쓰므로 파일의 줄 번호와 어긋난다.
 `--heading` 이나 `--marker` 로 절을 지목한다.
 **그림이 주장하는 것을 기록 본문이 말해야 한다.** SSOT 에 근거가 있어도 기록이 그 단계를 적지
 않았으면 그림만 넣지 않는다 — 설명 없는 주장이 남는다. 순서는 하나다.
 > 본문을 먼저 보강한다 → 그다음 그림을 붙인다.
 `ap1-browser-bearer-flow` 가 그랬다. 마지막 단계인 `/api/me` 응답 4필드를 기록이 말하지 않아
 붙이지 못하고 있다가, SSOT §474 를 근거로 본문에 한 줄을 더한 뒤에 붙였다.
 ## 만든 뒤
 `code-tables-diagrams.md` 의 규범과 아래 둘을 함께 돌린다. lint 는 라벨이 상자를 덮는 것을
 못 잡는다.
 ```bash
 python3 scripts/check-figure-text.py <프로젝트>            # <text> 가 전부 이름인가
 python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs  # PNG 로 떠서 눈으로 본다
 ```
@@ -1,6 +1,6 @@
 # 코드·표·다이어그램·이미지
-본문(`bodyMarkdown`)에만 해당한다. 본문이 있는 종류는 Case 와 Concept 이다.
+본문(`bodyMarkdown`)에만 해당한다. 본문이 있는 종류는 Case·Concept·Setup 셋이다.
 ## 코드블록
@@ -160,6 +160,28 @@ SVG는 `image/svg+xml`로 올라가고 다른 이미지와 같게 다뤄진다.
 `READY`가 아닌 Asset은 게시 시 거절된다.
 ### 저장소의 `.md` 에는 `:::evidence` 를 쓰지 않는다
 `:::evidence`는 Studio 렌더러의 구문이다. 저장소의 `.md`를 그 형태로 쓰면 편집기에서 그림이
 보이지 않고 구문이 글자로 남는다. **저장소는 읽는 형태로 쓴다.**
 ```markdown
 ![브라우저 SPA, Keycloak, Resource Server 사이에서 …](../../../final/assets/ap1-browser-bearer-flow/ap1-browser-bearer-flow.svg)
 ```
 `alt`는 그림의 `alt`를 그대로 쓰고, 경로는 frontmatter `assets`의 `file`과 같아야 한다.
 Studio 로 보낼 때만 `:::evidence` 로 바꾼다. 손으로 고치지 않는다.
 ```bash
 python3 scripts/studio-body.py <기록.md> -o /tmp/x.md      # check_body 는 이 파일에 돌린다
 python3 scripts/studio-body.py <기록.md> --body-only        # Studio 에 붙여넣을 본문
 python3 scripts/studio-body.py <기록.md> --key a=a-1a2b3c4d # 서버가 준 키로
 ```
 Studio 파서는 상대 경로 이미지를 `unsafe image URL`로 거절하므로 `check_body.mjs`는 **바꾼
 파일**에 돌린다. 저장소 파일에 그대로 돌리면 그림 자리에서 실패한다.
 ## 일반 이미지
 Asset이 아닌 그림은 Markdown으로 쓴다.
@@ -2,6 +2,12 @@
 가장 자주 나오는 지적은 **설명이 짧다**는 것이다. 사실은 맞는데 독자가 따라오지 못한다.
 그 반대도 같은 무게로 지적된다 — 설명이 끝난 뒤에 그 설명을 평가하거나, 다음 절을 예고하거나,
 독자가 오해할 것이라고 가정하는 문장이 붙는 것. 이 문서는 **무엇을 더 설명하는가**를 다루고,
 무엇을 빼는가는 `ai-tells.md` 첫 절이 다룬다. **문체 규칙의 정본은 `ai-tells.md` 다.** 두 문서가
 어긋나면 그쪽을 따른다. 여기 규칙은 전부 「그 설명이 없으면 독자가 막히는 자리」에서만 쓴다.
 이미 설명된 문단에 더하지 않는다.
 ## 이름을 댔으면 왜 있는지도 댄다
 낯선 클래스·기법·설정 이름을 적고 다음 문장으로 넘어가지 않는다. **왜 그것이 존재하는지**를 한
@@ -13,13 +19,13 @@ XorCsrfTokenRequestAttributeHandler가 token을 XOR와 Base64로 가린다.
 쓴다
 XorCsrfTokenRequestAttributeHandler가 token을 XOR와 Base64로 가린다.
-BREACH 공격을 줄이기 위해서다. 여기서 깊게 다루지는 않는다 — HTTP 응답 압축 크기의
+BREACH 공격을 줄이기 위해서다. HTTP 응답 압축 크기의 차이로 응답 안의 비밀값을 조금씩
-차이로 응답 안의 비밀값을 조금씩 추측하는 공격이고, 그래서 응답에 실리는 값을 매번
+추측하는 공격이고, 그래서 응답에 실리는 값을 매번 다르게 만든다.
 다르게 만든다.
 ```
-깊게 안 갈 것이면 **안 간다고 밝히고 한 문장 요약을 준다.** 이름만 던지고 넘어가면 독자는 그
+깊게 안 갈 것이면 **한 문장 요약만 준다.** 「여기서 깊게 다루지는 않는다」 같은 예고는 붙이지 않는다 —
-자리에서 검색하러 나간다.
+요약이 있으면 그것으로 충분하고, 없으면 독자는 그 자리에서 검색하러 나간다. 이 규칙은 **처음
 나오는 낯선 이름**에만 걸린다. 이미 설명한 이름이나 문맥에서 분명한 이름에는 붙이지 않는다.
 ## 「역할이 다르다」로 끝내지 않는다
@@ -87,27 +93,6 @@ sessionStorage에도 accessToken과 refreshToken이 없었다.
 쓴다        identity-header-trust
 ```
 ## 제목은 묻고 본문은 답한다
 절 제목에 `~해보자` `~하지?` `~일까?`를 쓴다. 그리고 **첫 문장에서 그 질문을 다시 던지고**
 답한다.
 | 쓰지 않는다 | 쓴다 |
 |---|---|
 | 브라우저에 남은 것 | 브라우저에 관리 대상 |
 | 위조 요청은 어떻게 생겼나 | 위조 요청은 어떻게 생겼을까? |
 | 세 겹으로 나눠서 막는다 | 세 겹으로 나눠서 막아보자 |
 | 무엇이 서버로 넘어왔나 | 무엇이 서버로 책임이 넘어왔지? |
 | upstream이 JWT를 받지 않는다는 뜻 | upstream이 JWT를 받지 않는다? |
 ```text
 ## 브라우저에 관리 대상
 브라우저에 관리 대상은 그럼 어떤 게 될까?
 | 무엇 | 브라우저에 있나..? | JavaScript가 읽나..? |
 ```
 ## 굵게를 걷어낸다
 `**굵게**`는 거의 쓰지 않는다. 한 절에 하나를 넘기면 강조가 아니라 얼룩이 된다. 강조는
@@ -155,9 +140,6 @@ authorization code와 함께 redirect되고, 그 code를 mediator가 token으로
 이 구조에서는 token 관리와 교환의 위치가 브라우저에서 Spring backend로 옮겨지게 된다.
 ```
 같은 대조를 절 끝에서 한 번 더 쓴다 — 「앞선 구조에서는 브라우저가 OIDC client였다면 이
 구조에서는 mediator가 OIDC client가 된다」처럼.
 ## 결론은 문장 끝에 붙인다
 한 줄짜리 단정문을 따로 떼어 강조하지 않는다. 앞 문장에서 `그래서` · `그렇기 때문에`로
@@ -205,11 +187,6 @@ access token이 필요하고, 그것을 응답 본문으로 받게 된다. 그
 Reference의 규칙 제목과 Decision의 결정문도 `~한다`로 끊는다. 그 자리는 기준이다.
 ## 그림은 한 줄로 예고한다
 `전체적인 구조를 보면 다음과 같다` 같은 한 줄을 두고 그림을 넣는다. 문단 사이에 말없이
 끼우지 않는다.
 ## 번역투를 걷어낸다
 가장 자주 나오는 지적 두 번째다. 어미는 한국어인데 **문장 구조가 영어**여서 읽기 힘들다.
@@ -409,5 +386,4 @@ Reference의 규칙 제목과 Decision의 결정문도 `~한다`로 끊는다.
 - **`~하면 된다`를 쓰지 않는다.** 조언하는 말투이지 기록하는 말투가 아니다.
  `정하면 된다` → `정한다`, `적으면 된다` → `적는다`, `두면 된다` → `둔다`
 - `A는 B다`보다 `A는 B라는 점이 문제가 된다` — 무엇이 걸리는지까지 말한다
 - 무엇을 하자고 이끌 때는 `~해 보자`를 쓴다. 절 제목과 여는 문장에만 쓰고 규칙에는 쓰지 않는다
 - 명령조를 줄인다. 검사 항목이 아니라 같이 읽는 사람의 말로 쓴다
@@ -1,8 +1,73 @@
 # SSOT에서 글감을 뽑는 기준
-`final/`의 긴 글 하나가 정본(SSOT)이다. 거기서 Studio에 올릴 기록을 뽑아낸다. 이 문서는 **무엇을
+`final/document.md` 하나가 정본(SSOT)이다. 거기서 Studio에 올릴 기록을 뽑아낸다. 이 문서는
-몇 건으로 나눌지**를 정하는 기준이다. 나눈 결과는 `tech-log-tree.json`에 제목만 먼저 적고, 글은
+**무엇을 몇 건으로 나눌지**를 정하는 기준이다. 나눈 결과는 `tech-log-tree.json` 하나에 적는다 —
-그다음에 쓴다.
+분해 계약과 색인이 같은 파일이라 둘이 어긋날 자리가 없다.
 ## 어느 파일에서 뽑나
 | 층 | 하는 일 |
 |---|---|
 | 코드·설정·실행 증거 | 사실의 근거 |
 | `final/document.md` | **글감 범위의 SSOT** — 후보를 발견하는 유일한 입력 |
 | `final/assets/` · `final/.techviz/` | 이미 그린 그림과 그 정본. 새 후보를 내지 않고 글감에 배정된다 |
 | `final/evidence/` | 이미 실행한 측정의 원문. 마찬가지로 배정된다 |
 | `analysis/**/*.md` | final이 이미 채택한 주장을 상세히 확인하는 보조 근거 |
 | `tech-log-tree.json` | 사람이 고른 글감. 분해 계약이자 색인이고 이 파일이 정본이다 |
 **`analysis/**`를 글감을 찾으려고 열지 않는다.** 이미 final에 있는 주장의 세부를 확인할 때만
 연다. 분석에만 있고 final에는 없는 자료를 발견하면 트리에 바로 넣지 말고 `final/document.md`를
 먼저 보강한다. 그러지 않으면 모듈 문서 61편이 각각 정본 노릇을 하고, 트리는 그 절 수의 합만큼
 자란다.
 ## 후보를 찾는 범위
 접어 넣은 `final/document.md`가 전부 후보 자리는 아니다. **제1부(통합 분석)가 후보를 찾는
 범위**이고, 제2부(모듈 분석 전문)와 제3부(분석 재료)는 근거다. 제2부의 절 제목을 후보로 읽으면
 모듈 분석 편수만큼 글감이 늘어난다 — 접어 넣기 전에 있던 문제가 그대로 돌아온다.
 범위는 기억하지 말고 계약에 적는다.
 ```json
 "candidateScope": {
  "document": "final/document.md",
  "sections": ["§3", "§4", "§5", "§6", "§7", "§8", "§9", "§10", "§11"],
  "excluded": ["제2부 — 모듈 분석 전문", "제3부 — 분석 재료"]
 }
 ```
 범위 밖의 앵커는 후보가 아니라 근거다. 제1부에서 나온 글감의 `source`로 건다.
 ## 그림과 증거는 후보가 아니라 배정 대상이다
 `final/assets/`의 그림과 `final/evidence/`의 측정은 글감을 새로 만들지 않는다. 이미 정해진
 글감에 붙는다. 그래서 처분을 매기는 자리가 아니라 **배정하는 자리**이고, 계약의
 `ssot-assets`·`ssot-evidence`가 그 자리다.
 글감을 다 고른 뒤 두 폴더를 한 번 훑는다. 물음은 하나다.
 > **이 그림이나 이 측정은 어느 글감의 것인가. 붙을 글감이 없으면 왜 없는가.**
 ```json
 "ssot-assets": ["ap3-bff-session-flow"],
 "ssot-evidence": ["raw/explain/l3-cartesian-join-plan.txt"]
 ```
 배정한 것은 기록의 `assets`·`evidence`가 실제로 가리켜야 한다. 배정해 놓고 쓰지 않으면
 `verify-tech-log-tree.py`가 error로 센다.
 **배정하지 않으면 글을 쓸 때 같은 그림을 새로 그린다.** keycloak이 그렇게 됐다. SSOT에
 `ap3-bff-session-flow`, `ap4-edge-forward-auth-flow`를 포함한 그림 13장이 `.techviz` 정본까지
 갖춘 채 있었는데, 기록 24편은 그중 한 장도 가리키지 않고 이름이 다른 그림 5장을 새로 만들어
 썼다. 새로 만든 5장에는 정본이 없어서 고칠 수도 없다.
 붙을 글감이 없는 그림도 있다. 패턴 넷을 나란히 놓고 비교하는 그림은 Reference에 붙어야 맞는데
 Reference에는 본문이 없다. 그런 그림은 그대로 두고, 왜 두는지 계약에 적는다 — 「Reference에만
 쓸 자리가 있어 본문 있는 종류에 담지 못한다」처럼. `verify-project-layout.py`가 「기록이 쓰지
 않는 SSOT 그림」으로 세므로, 센 숫자가 설명되지 않은 채 남지 않게 한다.
 증거도 같다. 재료로만 쓰고 인용하지 않기로 한 측정은 정상이다. 「기록이 인용하지 않는 raw 증거」가
 전부 설명되는지만 본다.
 ## 왜 먼저 나누는가
@@ -10,6 +75,22 @@
 Reference의 칸도 반쯤만 맞는 기록이 나온다. 종류를 먼저 정하고 그 종류가 요구하는 것이 SSOT에
 있는지 확인해야 한다.
 ## 고르는 것이지 남김없이 내는 것이 아니다
 분석에 빠진 것이 없는지 볼 때는 recall 100%가 맞다. 공개할 글을 정할 때는 아니다. 「분석에서
 보존할 가치」와 「독립된 글로 읽을 가치」는 다른 물음이고, 둘을 한 축으로 재면 분석 부산물이
 전부 글이 된다.
 물음은 하나다.
 > **이 기록을 없애고 관련 Case나 Concept의 한 절로 넣어도 이해·결정·재사용성이 그대로라면
 > 독립 기록으로 만들지 않는다.**
 후보마다 처분을 적는다 — `PROMOTE` · `MERGE_INTO` · `KEEP_IN_SSOT` · `NEEDS_EVIDENCE` ·
 `NEEDS_DECISION` · `BLOCKED`. `KEEP_IN_SSOT`은 버린 것이 아니라 분석에 남기고 글로 만들지
 않기로 한 것이고, 그것도 정상적인 결과다. 자세한 것은
 `.agents/skills/deriving-tech-log-root-tree/references/candidate-disposition.md`.
 ## 한 건으로 자르는 단위
 **절이 아니라 주장이다.** SSOT의 `##` 하나가 기록 하나가 아니다. 다음 넷 중 하나가 한 건이다.
@@ -18,6 +99,7 @@ Reference의 칸도 반쯤만 맞는 기록이 나온다. 종류를 먼저 정
 |---|---|---|
 | 재현한 관측 하나 | 조건을 갖추고 돌려서 얻은 수치·실행계획·로그 | Case |
 | 남의 것의 동작 하나 | 문서와 코드를 읽어 정리한 규칙·흐름 | Concept |
 | 남이 따라 할 절차 하나 | 그 환경을 처음 세우는 명령과 구성 값 | Setup |
 | 반복 적용할 기준 하나 | 다음에도 같게 하기로 한 규칙 | Reference |
 | 프로젝트가 고른 방향 하나 | 대안을 두고 정한 것 | Decision |
 | 닫히지 않은 판단 하나 | 아직 모르는 것과 무엇을 하면 닫히는지 | Question |
@@ -26,6 +108,8 @@ Reference의 칸도 반쯤만 맞는 기록이 나온다. 종류를 먼저 정
 순서대로 묻는다. 먼저 걸리는 것이 그 글감의 종류다.
 0. **남이 자기 기계에서 따라 할 절차인가** → Setup. 나머지 다섯은 끝난 일을 적고 이것만 실행할
   순서를 적는다. 명령과 구성 값이 SSOT에 있어야 하고, 프로젝트를 반드시 고른다
 1. **내가 돌려서 얻은 결과인가** → Case. 수치·실행계획·로그가 SSOT에 있어야 한다. 없으면 Case가 아니다
 2. **남의 것이 어떻게 동작하는지인가** → Concept. 무엇을 보고 썼는지(버전)가 있어야 한다
 3. **다음에도 같게 하기로 한 규칙인가** → Reference
@@ -46,12 +130,20 @@ Reference 하나로 나누고 `관계`로 잇는다.
 **같은 관측을 두 건으로 쪼개지 않는다.** 「N+1이 났다」와 「그래서 몇 개가 나갔다」는 한 건이다.
 쪼개면 둘 다 반쪽이 된다.
-**주제를 먼저 정한다.** Studio는 주제 아래에 다섯 종류를 나눠 보여 준다. 주제가 다르면 같은
+**Concept은 거꾸로 뽑는다.** Case·Reference·Decision·Question을 먼저 고르고, 그것을 읽는 사람이
-프로젝트여도 폴더가 갈린다. 주제 slug는 Studio의 것을 그대로 쓴다.
+미리 알아야 하는 구조가 있을 때만 Concept을 만든다. 메커니즘처럼 보이는 절을 훑어 채우면 어느
 기록도 필요로 하지 않는 개념이 쌓인다.
 **주제 하나에 독자 질문 하나.** Studio는 주제 아래에 여섯 종류를 나눠 보여 준다. 그 주제의
 기록들이 함께 답하는 물음을 한 줄로 적고, 그 물음에 답하지 않는 글감은 다른 주제로 옮긴다.
 주제 slug는 Studio의 것을 그대로 쓴다.
 ## `tech-log-tree.json`
-주제 → 종류 → 글감 순서로 담는다. 아직 쓰지 않은 글감은 `file` 없이 제목만 둔다.
+**주제·글감·`readiness`·`source`·`classification`·`relations`는 사람이 적는다.** 스크립트가
 채우는 것은 기록 파일에서 읽을 수 있는 넷뿐이다 — `file`·`publication`·`status`·`studioId`.
 주제 → 종류 → 글감 순서로 담고, 아직 쓰지 않은 글감은 `file` 없이 남는다. `readiness`는 증거가
 갖춰진 정도이고 `publication`은 Studio에 올렸는지다 — 둘은 다른 것이라 섞지 않는다.
 ```json
 {
@@ -68,25 +160,30 @@ Reference 하나로 나누고 `관계`로 잇는다.
            "status": "게시 전", "studioId": "32d0be7d-…", "assets": 1, "evidence": 3 },
          { "title": "아직 쓰지 않은 글감" }
        ],
-        "concept": [], "reference": [], "question": [], "decision": []
+        "concept": [], "setup": [], "reference": [], "question": [], "decision": []
      }
    }
  }
 }
 ```
-기록을 쓰거나 지운 뒤에는 다시 만든다. 스크립트는 기록 파일에서 값을 읽어 채우고, `file`이 없는
+기록을 쓰거나 지운 뒤에는 파생 칸을 다시 채운다. 사람이 적은 칸은 그대로 남는다. 디렉터리를
-글감은 지우지 않는다.
+훑어 주제를 만들지 않으므로, 계약에서 뺀 주제의 폴더가 남아 있어도 되살아나지 않고 `unlisted`에
 적힌다.
 ```bash
 python3 scripts/build-tech-log-tree.py [프로젝트]
 python3 scripts/verify-tech-log-tree.py [프로젝트]      # error 0 이어야 한다
 ```
 ## 순서
 1. SSOT를 끝까지 읽는다. 절 제목만 훑지 않는다 — 수치와 근거가 어디 있는지 알아야 종류를 정한다
-2. 위 물음으로 글감을 나누고 주제를 정한다
+2. §3~§8에서 Case, §9에서 Reference, §10에서 Decision, §11에서 Question을 고른다
-3. `tech-log-tree.json`에 제목만 적는다. 이때 글은 쓰지 않는다
+3. 그 넷을 이해하는 데 필요한 Concept만 거꾸로 더한다
-4. 글감 하나를 골라 `<주제>/<종류>/`에 기록을 쓴다. 형식은 `writing-each-kind.md`
+4. 후보마다 처분을 적고, 사람이 다시 읽은 것만 `dispositionReview: CONFIRMED`로 둔다.
-5. 트리를 다시 만든다
+   `PROMOTE`이면서 `CONFIRMED`인 것만 글감이 된다
-6. Studio에 넣고 저장한다
+5. 주제를 묶고 주제마다 독자 질문을 한 줄 적는다
 6. 글감 하나를 골라 `<주제>/<종류>/`에 기록을 쓴다. 형식은 `writing-each-kind.md`
 7. 색인을 다시 만들고 검사기를 돌린다
 8. Studio에 넣고 저장한다
@@ -1,24 +1,41 @@
-# 다섯 종류의 칸과 게시 조건
+# 여섯 종류의 칸과 게시 조건
 칸 이름은 Studio 편집 화면 그대로, 상한과 필수 여부는 `studio-api.openapi.yaml` 그대로다.
 계약 필드명을 괄호에 적는다. 계약은 `tech-log-frontend/src/features/tech-log/contracts/studio/`
 에 있고, 이 파일과 계약이 어긋나면 계약이 맞다.
-`RecordKind` 는 다섯이다 — `CASE` · `REFERENCE` · `QUESTION` · `CONCEPT` · `PROJECT_DECISION`.
+`RecordKind` 는 여섯이다 — `CASE` · `REFERENCE` · `QUESTION` · `PROJECT_DECISION` · `CONCEPT` ·
 `SETUP` (`studio-api.openapi.yaml:838-840`).
 **이 목록을 손으로 옮길 때마다 종류가 빠졌다.** 이 문서도 한동안 「다섯이다」라고 적고 `SETUP`
 을 뺐다. 프론트엔드에서 먼저 같은 일이 났고 소스에 적혀 있다
 (`application/ports/studio-gateway.ts:8-12`).
 > 종류는 계약의 `RecordKind` 를 그대로 쓴다. 여기 손으로 적어 두었던 동안 개념과 환경 구성이
 > 빠져 있었고, 작업본 목록의 종류 필터는 그 둘을 아예 고를 수 없었다 — 손으로 나열한 목록에
 > 새 종류를 빠뜨리는 일이 이 저장소에서 반복됐다.
 일곱 번째가 생기면 같은 일이 난다. 이 문서를 고칠 때는 기억으로 세지 말고
 `studio-api.openapi.yaml` 의 `RecordKind` 를 열어 몇 줄인지부터 센다.
 ## 종류별 칸 (`새 문서` 화면이 적어 주는 그대로)
 | 화면 이름 | 계약 `kind` | 그 종류만의 칸 |
 |---|---|---|
-| Case | `CASE` | 문제 · 결론 · 환경 · 재현 · 본문 |
+| **검증 기록** (Case) | `CASE` | 문제 · 결론 · 환경 · 재현 · 본문 |
-| Reference | `REFERENCE` | 목적 · 규칙 · 적용 조건 · 예외 · 예시 |
+| **적용 기준** (Reference) | `REFERENCE` | 목적 · 규칙 · 적용 조건 · 예외 · 예시 |
-| **개념** | `CONCEPT` | 기준 버전 · 본문 |
+| **동작 원리** (Concept) | `CONCEPT` | 기준 버전 · 본문 |
-| Question | `QUESTION` | 상태 · 사실 · 가정 · 미지수 · 선택지 |
+| **환경 구성** (Setup) | `SETUP` | 버전 · 본문 |
-| Decision | `PROJECT_DECISION` | 상태 · 결정일 · 결정문 · 판단 이유 · 영향 · 근거 |
+| **열린 질문** (Question) | `QUESTION` | 상태 · 사실 · 가정 · 미지수 · 선택지 |
 | **설계 결정** (Decision) | `PROJECT_DECISION` | 상태 · 결정일 · 결정문 · 판단 이유 · 영향 · 근거 |
 **화면 이름은 여섯 다 한글이다.** 2026-09-12 에 `/studio/documents/new` 에서 읽었고 작업본
 목록(`/studio/documents`)의 종류 필터도 같은 여섯 이름을 쓴다. 이 문서의 절 제목과 산문은
 괄호 안의 이름을 쓴다 — 폴더 이름과 frontmatter 의 `kind` 가 그쪽이기 때문이다.
 여기에 아래 공통 칸이 더해진다.
-## 공통 (다섯 종류 모두 — `WorkingCopyInputBase`)
+## 공통 (여섯 종류 모두 — `WorkingCopyInputBase`)
 | 칸 | 필드 | 상한 | 게시 조건 |
 |---|---|---|---|
@@ -27,7 +44,7 @@
 | 요약 | `summary` | **2,000자** | 경고. 목록 카드에는 약 90자까지 보인다 |
 | Topic | `topicId` | — | 경고 |
 | 축 | `variantIds` | 8개 | 선택. 고르지 않으면 그 주제의 **공통 기록**이 된다 |
-| Project | `projectId` | — | `PROJECT_DECISION`은 게시 시 필수 |
+| Project | `projectId` | — | `PROJECT_DECISION`과 `SETUP`은 필수 |
 | 관계 | `relations` | 20개 | `PROJECT_DECISION`은 **1개 이상 필수**. 그 종류에서는 절 이름이 「근거」다 |
 편집 화면에서 축은 체크박스 묶음으로 나오고 묶음 이름이 「축 — 고르지 않으면 이 주제의 공통
@@ -44,6 +61,16 @@ slug를 비우면 제목에서 만든다. 한글 제목도 로마자로 옮겨
 **Project에 slug가 없으면 공개 화면에 프로젝트가 표시되지 않는다.** 공개 계약의
 `ProjectSummary`가 `slug`와 `path`를 요구하기 때문이다. `주제·프로젝트` 화면에서 확인한다.
 ## frontmatter 의 `topic`
 **폴더 이름과 같은 slug 를 적는다.** 화면에 보이는 한글 주제 이름은 `topicName` 에 따로 둔다.
 `topic` 이 표시 이름이면 폴더와 대조할 수 없다.
 ```yaml
 topic: oauth-oidc-auth-boundary
 topicName: OAuth/OIDC 인증 경계
 ```
 ## 기록이 가리키는 로컬 파일
 기록은 `docs/<프로젝트>/tech-log-studio/<주제>/<종류>/` 에 있고, 그림과 증거는 같은 프로젝트의
@@ -52,11 +79,15 @@ slug를 비우면 제목에서 만든다. 한글 제목도 로마자로 옮겨
 ```yaml
 assets:
  - key: eager-lazy-query-sequence          # 본문의 :::evidence key 와 같은 값
-    file: ../../../final/assets/tech-log-studio/eager-lazy-query-sequence.svg
+    file: ../../../final/assets/diagrams/eager-lazy-query-sequence/eager-lazy-query-sequence.svg
 evidence:
  - ../../../final/evidence/explain/highlights-child-plan-A.txt
 ```
 **`assets` 는 본문이 있는 Case·Concept·Setup 에만 둔다.** 나머지 세 종류는 칸이 평문으로
 렌더링돼 그림을 표시할 곳이 없다. 그림이 필요한 내용은 본문이 있는 종류에 담고 `관계`로
 가리킨다.
 `assets` 는 Studio 에 올릴 파일이다. 아직 안 올렸으면 key 가 파일 이름과 같고, 올린 뒤에는
 서버가 준 `<이름>-<해시8>` 로 바뀐다. **Studio 에 넣을 때 이 목록을 보고 Asset 을 올리고,
 본문의 `:::evidence key` 를 서버가 준 키로 바꾼다.**
@@ -66,8 +97,37 @@ evidence:
 ## 평문 칸 쓰는 법
-본문(`bodyMarkdown`)을 뺀 모든 칸은 평문이다. 백틱·파이프·`#`는 글자 그대로 보이고 줄바꿈만
+본문(`bodyMarkdown`)을 뺀 모든 칸은 **마크다운 블록 파서를 거치지 않는다.** 그렇다고 전부
-살아난다. 그 줄바꿈이 유일한 서식이므로 아끼지 않는다.
+글자 그대로 나오는 것은 아니다. 렌더러가 이 칸들만 따로 그리고(`tech-log-frontend` 의
 `presentation/shared/public-render/prose-text.tsx`), 거기서 셋이 살아난다.
 | 이 칸에서 | 어떻게 되나 |
 |---|---|
 | 백틱 쌍 | 인라인 `<code>` 로 **살아난다.** 빼지 않는다 |
 | 백틱이 홀수 개 | 짝이 안 맞으므로 원문 그대로 둔다 — 반쯤 해석하지 않는다 |
 | 빈 줄 | 문단이 갈린다 |
 | 한 줄 바꿈 | `<br>` 로 그 자리에 남는다 |
 | 별표·파이프·`#`·코드펜스·인용 표지 `>` | **글자 그대로 보인다.** 이것들만 뺀다 |
 **옛 판을 기억하지 마라.** 이 칸들은 오래 진짜 평문으로 나갔고 백틱이 백틱째 화면에
 나왔다 — 어떤 Reference 는 한 문서에 백틱이 32개였고 그 원문이 카드와 검색 결과까지
 퍼졌다. 그건 **고쳐진 버그**다. 지금 백틱을 빼면 식별자가 본문과 같은 민무늬로 나온다.
 **무엇을 지우나.** 별표·코드펜스·`>` 는 글자 그대로 보인다. 식별자는 남기고 표시 문자만 뺀다.
 `**this is the parameter**` 는 그 문장만 남긴다. 코드펜스 안이 `이름 : 값` 꼴이면 펜스 줄만
 지우면 그대로 읽힌다. 백틱은 그대로 두고, 문단 사이 빈 줄도 지킨다.
 **SSOT 를 그대로 옮긴 인용도 `>` 를 못 쓴다.** 인용이라는 것을 표지로 나타낼 방법이 이 칸에는
 없다 — `>` 도, 들여쓰기도 안 산다. 표지를 빼고 한 문단으로 두거나, 인용이 꼭 인용으로 보여야
 하면 본문이 있는 종류로 옮긴다. 「」 를 새로 씌우지 않는다. 옮긴 글자는 보호 구간이라 그대로다.
 **코드펜스를 뗄 때 언어 표시 줄을 같이 지운다.** ` ```text ` 에서 펜스만 지우면 `text` 한 줄이
 남고, 그 낱말이 화면에 그대로 나온다. 실제로 한 기록에서 그렇게 남아 있었다.
 **칸이 어떻게 보이는지는 렌더러가 정본이다.** 이 파일이 아니다. 여기 적힌 것과 화면이
 다르면 `prose-text.tsx` 와 `public-record-renderer.tsx` 를 열어서 가른다.
 관계(`근거`) 절은 평문 칸이 아니다. 기록을 거는 목록이라 `- **제목**` 표기를 그대로 둔다.
 **나열은 `이름 : 값`으로 끊는다.** 쉼표로 이으면 읽는 사람이 항목을 세어야 한다.
@@ -95,25 +155,26 @@ issuer · audience : 검증
 | 검증 환경 | `environment` | 런타임·버전·DB·도구 |
 | 재현 조건 | `reproduction` | 다른 사람이 같은 결과를 얻는 방법 |
 | 마지막 검증일 | `lastVerifiedOn` | 실제로 확인한 날. 30일 지나면 경고 |
-| 본문 Markdown | `bodyMarkdown` | 10만 자. 본문을 갖는 두 종류 중 하나 |
+| 본문 Markdown | `bodyMarkdown` | 10만 자. 본문을 갖는 세 종류 중 하나 |
 공개 화면에서 `검증 환경`과 `재현 조건`은 `environmentSummary` 배열에 그 순서로 실린다.
 ## Concept — 남의 것이 어떻게 동작하는지
-`새 문서` 화면에서 이 종류만 이름이 한글이다. **「개념」을 고른다.** 나머지 넷은 Case·Reference·
+`새 문서` 화면에서 **「동작 원리」를 고른다.** 화면 설명은 「개념의 내부 동작과 아키텍처를 처음부터
-Question·Decision 으로 적혀 있다. 화면 설명은 「개념의 내부 동작과 아키텍처를 처음부터 풀어 씁니다」다.
+풀어 씁니다.」다. 전에 이 절은 「이 종류만 이름이 한글이다」라고 적었는데 2026-09-12 에는 여섯 다
 한글이었다.
 | 칸 | 필드 | 비고 |
 |---|---|---|
-| 본문 Markdown | `bodyMarkdown` | 10만 자. **Case 와 함께 본문을 갖는 두 종류 중 하나** |
+| 본문 Markdown | `bodyMarkdown` | 10만 자. **Case·Setup 과 함께 본문을 갖는 세 종류 중 하나** |
 | 기준 버전 | `basisVersion` | 120자. 무엇을 보고 쓴 글인지 한 줄 |
 칸이 둘뿐이다. 문제도 결론도 재현 조건도 없다. 내가 재현한 결과가 아니라 **이미 그렇게 동작하는
 것**을 적기 때문이다. `Authorization Code Flow 가 code 를 한 번 더 교환하는 이유`, `Forward-Auth
 subrequest 가 실어 보내는 것` 같은 것이 여기 온다.
-**`lastVerifiedOn` 이 없고 `basisVersion` 이 그 자리를 대신한다.** 개념은 날짜로 낡지 않고 버전으로
+**`lastVerifiedOn` 이 없고 `basisVersion` 이 낡음을 말한다.** 개념은 날짜로 낡지 않고 버전으로
 낡기 때문이다. `Keycloak 26.7.0 identity brokering`, `Kubernetes 1.31` 처럼 적는다. 비워도 게시된다.
 공개 주소는 `/concepts/{slug}` 다.
@@ -122,12 +183,112 @@ subrequest 가 실어 보내는 것` 같은 것이 여기 온다.
 검증도 막지 않는다(2026-09-04 에 임시 개념 기록을 만들어 비운 채로 게시해 확인했다). 그래도
 채우는 편이 낫다 — 개념이 언제 낡았는지 읽는 사람이 알 방법이 이 칸뿐이다.
-편집 화면 오른쪽 `작업 상태` 는 이 종류를 「동작 원리」라고 부른다. `새 문서` 의 「개념」과 같은
+편집 화면 오른쪽 `작업 상태` 도 이 종류를 「동작 원리」라고 부른다.
 것이다.
 Case 와 헷갈리면 **내가 무엇을 했는지**를 묻는다. 내가 돌려 보고 수치를 얻었으면 Case, 남의 문서와
 코드를 읽고 동작을 정리했으면 Concept 이다.
 ### Concept 이 아닌 것
 Concept 은 **어떤 Case 를 이해하려면 먼저 알아야 하는 구조**다. 그 Case 가 없으면 Concept 도
 없다. 분석하면서 알게 된 사실을 종류가 마땅치 않아 여기 넣지 않는다.
 | 이런 제목 | 실제로는 |
 |---|---|
 | 호출자가 없다 · 프로덕션에서 실행되지 않는다 | 부재는 Case 의 관측이다 |
 | 구현 클래스 51개를 전부 읽었다 · 재현에 쓴 레인 | 분석 범위·방법. SSOT 의 coverage 원장에 남는다 |
 | 보류한 항목과 보류한 이유 | 분석 진행 기록. 같은 곳에 남는다 |
 | `grep refs=0` 은 시작점이지 결론이 아니다 | 분석 방법론. Reference 로 쓸 수 있으면 Reference 다 |
 | (8.4) 문서/구현 드리프트 — … · Confirmed — … | 분석 문서의 절 제목을 그대로 옮긴 것 |
 한두 문장으로 Case 안에서 설명되는 것도 Concept 이 아니다. **없애고 Case 의 한 절로 넣어도
 이해가 그대로면 독립 기록으로 만들지 않는다.**
 Concept 이 되는 것은 이런 것들이다 — `Spring 조립의 세 경로`, `@ConditionalOnBean 의 평가
 시점`, `커밋 증거 상태 전이`, `fenced lease 와 CAS`, `gRPC flow control 과 backpressure`.
 여러 Case 가 같은 선수 지식을 요구할 때 그것을 한 번만 설명하려고 만드는 자리다.
 ## Setup — 남이 따라 할 절차 (`SETUP`)
 화면 이름은 「환경 구성」이고 설명은 「이 기록을 자기 손으로 재현하는 절차를 남깁니다.」다.
 편집 화면은 구역 둘로 나뉜다 — 「기본 정보」와 「환경 구성」(eyebrow `SETUP`).
 | 화면 이름 | 필드 | 상한·모양 |
 |---|---|---|
 | 고정한 버전 | `pinnedVersions` | 배열 30개. 줄마다 `이름`(1~60자) + `버전`(1~40자) 입력 둘. 「버전 추가」 버튼으로 늘린다 |
 | 절차 Markdown | `bodyMarkdown` | 10만 자 |
 화면에 붙은 도움말을 그대로 옮기면 이렇다.
 - 고정한 버전 : `“Keycloak” / “26.7.0” 처럼 적습니다. 비우면 화면에 표를 그리지 않습니다.`
 - 절차 Markdown : `“##” 소제목이 목차가 됩니다. 명령은 코드블록으로 적어야 그대로 복사됩니다.`
 `SetupInput.required` 는 `[kind, bodyMarkdown, pinnedVersions]` 다.
 **작업본을 만들면 본문이 비어 있지 않다.** Studio 가 절 뼈대를 미리 넣어 준다.
 ```text
 ## 실행 절차
 ## 구성 값
 ## 확인 방법
 ```
 계약의 `bodyMarkdown` 설명은 「실행 절차·구성 값·확인 방법을 `##` 절로 적는다. **절 이름을
 강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다.**」다. 뼈대는 출발점이고, 절 이름은 그
 프로젝트가 쓰는 말로 바꿔도 저장과 게시가 막히지 않는다.
 ### 왜 이 종류가 따로 있나
 다른 다섯은 끝난 일을 적고 환경 구성만 남이 따라 할 절차를 적는다. 편집 화면 주석
 (`presentation/studio/components/setup-fields.tsx:44-52`)이 그 차이를 적어 두었다.
 > 다른 다섯 종류는 끝난 일을 적는다. 이 종류만 읽는 사람이 그대로 따라 하는 절차를 적으므로,
 > 본문에 명령과 표가 들어간다 — Case 의 「검증 환경」 같은 평문 한 칸으로는 담기지 않는다.
 > … 버전만 본문 밖에 둔다. 이 절차가 어느 버전 위에서 성립했는지는 그 기록의 유효 범위이고,
 > 목록과 머리말이 본문을 열지 않고 보여 줘야 하는 값이기 때문이다.
 그래서 칸이 둘뿐인데도 Concept 과 다르게 쓴다. 명령·표·그림은 본문에 넣고 버전만 본문 밖에
 남긴다. 개념의 「기준 버전」도 같은 이유로 본문 밖에 있고, 다른 점은 셋업의 버전이 여럿이라는
 데 있다.
 **검증일 칸이 없다.** Case 의 `lastVerifiedOn` 도 Reference 의 `verifiedOn` 도 이 종류에는 없다.
 공개 계약의 `SetupDetailResponse` 가 왜인지 적는다.
 > 환경 구성은 끝난 일이 아니라 따라 하는 절차다. 낡음은 검증일이 아니라
 > `pinnedVersions` 가 말한다 — 어느 버전 위에서 이 절차가 성립했는지가 유효 범위다.
 > 주제는 없을 수 있다. 주제 없는 셋업은 그 프로젝트의 공통 구성이다.
 ### 프로젝트는 필수, 주제는 선택
 `PROJECT_DECISION` 말고 프로젝트를 요구하는 종류가 하나 더 있다.
 ```text
 if (input.kind === "SETUP" && !project) fail("환경 구성은 프로젝트에 속합니다. 기본 정보에서 프로젝트를 골라 주세요.");
 ```
 `domain/content-format/project-public-render-model.ts:245` 다.
 주제는 비워도 된다. 비우면 그 프로젝트의 공통 구성으로 읽힌다. 다만 2026-09-12 에 빈 초안의
 미리보기는 `1:1 TOPIC catalog entry is required` 로 막혔다 — 미리보기를 보려면 Topic 을 고른다.
 ### 본문 파서와 공개 주소
 본문 파서는 Case 와 같다(`presentation/public/components/setup-document-page.tsx:11`).
 > 환경 구성의 본문도 Case 와 같은 파서를 탄다 — `##` 소제목이 목차가 되고 `:::evidence` 가…
 그래서 코드블록·표·다이어그램·이미지를 쓸 수 있다.
 - 공개 상세 : `/setups/{slug}` (`contracts/tech-log-route-contract.ts:31`, 라우트 제목 「환경 구성」)
 - 공개 목록 : `/explore/setups` — 설명 「이 기록을 자기 손으로 재현하는 절차를 남깁니다.」
  (`presentation/public/pages/explore-kind-page.tsx:17`)
 **Studio 에 환경 구성 문서는 아직 0건이다.** 2026-09-12 에 `/studio/documents?kind=SETUP` 이
 「0개 중 0개 표시 중」이었다. 종류는 있는데 한 번도 쓰이지 않았다. 위의 칸 설명은 계약과 편집
 화면에서 읽었고, 올라간 기록에서 확인하지 않았다.
 ## Reference — 반복 적용할 기준
 | 칸 | 필드 | 비고 |
@@ -176,6 +337,10 @@ Case 와 헷갈리면 **내가 무엇을 했는지**를 묻는다. 내가 돌려
 ## 종류 고르기
 ```text
 남이 그대로 따라 할 절차를 적나 ── 예 ──→ Setup
        │
        아니오 (끝난 일을 적는다)
        │
 내가 직접 돌려 보고 결과를 얻었나 ── 예 ──→ Case
        │
        아니오
@@ -195,6 +360,11 @@ Case 와 헷갈리면 **내가 무엇을 했는지**를 묻는다. 내가 돌려
        └──→ Reference
 ```
 첫 갈래가 「끝난 일을 적나, 남이 따라 할 절차를 적나」다. 나머지 다섯은 이미 끝난 일을 적고,
 Setup 만 읽는 사람이 자기 기계에서 실행할 순서를 적는다. 편집 화면 주석이 그 경계를 「Case 의
 「검증 환경」 같은 평문 한 칸으로는 담기지 않는다」로 적는다 — 명령이 여러 줄이고 그대로
 복사돼야 하면 Case 의 평문 칸이 아니라 Setup 의 본문에 들어간다.
 Case 와 Concept 이 가장 자주 헷갈린다. **수치와 재현 조건이 있으면 Case**, 읽고 정리한 동작이면
 Concept 이다. Concept 과 Reference 는 「무엇이 그런가」와 「우리가 어떻게 할 것인가」로 갈린다 —
 `PKCE 가 code 가로채기를 막는 방식`은 Concept, `우리는 public client 에 PKCE 를 필수로 쓴다`는
@@ -23,9 +23,29 @@
 - [ ] 종류가 내용과 맞는다 (`record-kinds.md`의 판단 흐름)
 - [ ] Question의 사실과 가정이 섞이지 않았다
 - [ ] Question이 `OPEN`이면 미지수가 있다
 - [ ] Question에 닫는 조건이 있다. 「더 알아본다」로 끝나지 않았다
 - [ ] Decision에 근거 기록이 1개 이상 연결됐다
 - [ ] Decision의 영향에 감수한 비용이 있다
 - [ ] Reference의 예시가 문장이다. 코드를 밀어 넣지 않았다
 - [ ] Setup이 끝난 일이 아니라 남이 따라 할 순서를 적었다
 - [ ] Setup의 명령이 코드블록에 있다. 산문에 섞지 않았다
 - [ ] Setup의 `pinnedVersions`가 채워졌다. 본문에 날짜를 적어 검증일을 대신하지 않았다
 ## 환경 구성의 명령 (`writing-practitioner-guides`)
 명령을 어떤 형태로 쓸지는 그 스킬이 정한다. 여기서는 그 결과가 본문에 남았는지만 센다.
 - [ ] 사람이 내용을 읽고 고쳐야 하는 설정 파일을 에디터로 열게 했다. `printf >`·`echo >>`·`cat <<EOF` 로 만들지 않았다
 - [ ] 한 명령에 여러 작업이 겹치지 않았다. 접속·리다이렉션·권한·파일 생성을 한 줄에 묶지 않았다
 - [ ] 그 도메인의 전용 검증 명령이 있는데 `python3 -c` 로 대신하지 않았다
 - [ ] 다시 따라 해도 같은 줄이 또 붙지 않는다. 두 번 실행하면 늘어나는 명령이 없다
 - [ ] 조회·진단·실행은 운영자가 쓰는 CLI 를 그대로 썼다. `grep`·`virsh`·`systemctl` 을 에디터로 바꾸지 않았다
 - [ ] 단계마다 목적·행동·예상 결과·왜 필요한가·문제가 생기면이 같은 순서로 있다
 - [ ] 셸이 여럿이면 코드블록마다 `label` 로 어디서 치는지 적었다
 - [ ] 자리표시자가 없다. 값을 찾는 명령이 함께 있다
 - [ ] 앞 단계가 찍은 값을 옮겨 넣는 자리만 예외다. 그 자리는 `{{NAME}}` 으로 적었다. 한글로 감싸지도 `${NAME}` 으로 적지도 않았다
 - [ ] 비밀은 길이나 존재 여부까지만 확인하고 값을 찍지 않았다
 - [ ] 명령의 형태를 고쳤으면 SSOT 를 먼저 고쳤다. `check_evidence.mjs` 가 통과한다
 ## 설명
@@ -53,6 +73,9 @@
 - [ ] `여지가 생긴다`·`소지가 있다` 대신 무엇이 어디로 가는지 썼다
 - [ ] 읽는 법을 지시하는 문장이 없다. `봐야 한다`·`여기까지다`·`먼저 본다`·`읽으면 안 된다`
 - [ ] 빼도 남은 뜻이 그대로인 문장이 없다
 - [ ] 설명 직후에 그 설명의 중요성을 평가하는 문장이 없다 (「~증거다」「~핵심이다」「서로를 대신하지 않는다」)
 - [ ] 독자가 오해할 것이라고 가정하는 문장이 없다 (「~로 읽기 쉽다」「~라고 생각하면 안 된다」)
 - [ ] 다음 절을 예고하거나 「~를 함께 적는다」처럼 작성 방법을 말하는 문장이 없다
 - [ ] 규칙 제목이 말한 것을 본문 끝에서 다시 지시하지 않았다
 - [ ] `싣는다`·`낸다`·`친다`·`짠다`를 실제 동작으로 풀어 썼다
 - [ ] 동사마다 목적어가 있다. `교환이 끝난다`처럼 무엇인지 빠지지 않았다
@@ -74,8 +97,9 @@
 - [ ] Reference가 Case를 문장만 바꿔 옮기지 않았다
 - [ ] 현재 확인한 것과 운영에서 추가로 필요한 것을 나눴다
 - [ ] 테스트를 말할 때 무엇을 단정하는지 적었다
 - [ ] 어미·절·안내 문장의 수치는 참고만 했다. 맞추려고 문장을 넣지 않았다
-## 본문 (Case)
+## 본문 (Case · Concept · Setup)
 - [ ] raw HTML·각주·체크박스·중첩 목록·취소선이 없다
 - [ ] 표를 파이프로 썼다. 감쌌다면 세 속성이 다 있다
@@ -85,12 +109,17 @@
 - [ ] 그림이 있는 문단에 글을 섞지 않았다
 - [ ] `alt`가 무엇이 보이는지 말한다
 - [ ] 그림 안 `<text>`가 전부 이름이다. 문장도 숫자도 없다 (`<title>`·`<desc>`는 예외)
 - [ ] 눈으로만 보지 않고 `python3 scripts/check-figure-text.py <프로젝트>` 를 돌렸다
 - [ ] 관계선을 다 지워도 뜻이 남는 그림이 아니다 (남으면 표다 — 마크다운 표로 쓴다)
 - [ ] `python3 scripts/preview-figure.py`로 PNG 를 떠서 눈으로 봤다 (lint 는 라벨이 상자를 덮는 것을 못 잡는다)
 - [ ] 본문의 그림이 마크다운 이미지다 (`:::evidence` 는 Studio 로 보낼 때 `studio-body.py` 가 만든다)
 - [ ] 코드에 자격증명·토큰·내부 호스트가 없다. 지운 자리가 보인다
 - [ ] 제목 id와 표 id가 겹치지 않는다
 ## 평문 칸
- [ ] 본문 밖 칸에 백틱·파이프가 없다
+- [ ] 본문 밖 칸에 별표·파이프·`#`·코드펜스·인용 표지 `>` 가 없다 (**백틱은 괜찮다** — 인라인 `<code>` 로 산다)
 - [ ] 코드펜스를 뗀 자리에 언어 표시(` ```text ` 의 `text`)가 남지 않았다
 - [ ] 나열을 쉼표로 잇지 않고 `이름 : 값`으로 끊었다
 - [ ] 있음·없음을 `o`·`x`로 적었다
 - [ ] 한 문장이 화면에서 두 줄을 넘지 않는다
@@ -98,9 +127,11 @@
 ## 연결
 - [ ] Topic이 지정됐다
- [ ] Project가 필요하면 지정됐고, 그 Project에 slug가 있다
+- [ ] Project가 필요하면 지정됐고, 그 Project에 slug가 있다 (Decision과 Setup은 필수다)
 - [ ] 관계의 대상이 실제로 있는 공개 기록이다
 - [ ] 코드·표·그림이 필요한 내용을 Reference나 Question에 밀어 넣지 않았다
 - [ ] 본문이 없는 세 종류에 `assets`를 선언하지 않았다
 - [ ] 이 글감의 후보가 `PROMOTE`이고 `dispositionReview`가 `CONFIRMED`다
 ## 마지막
@@ -108,3 +139,18 @@
 - [ ] 게시 후 공개 페이지를 열어 표·코드·그림이 의도대로 나오는지 봤다
 마지막 항목을 건너뛰지 않는다. 저장은 통과해도 공개 화면에서 다르게 보이는 경우가 있다.
 ## 분석에서 뽑아 쓸 때 (document-detail 계약)
 - [ ] 이 글감의 `readiness` 가 글을 써도 되는 상태인가
 - [ ] 모든 실질 주장이 분석·출처·증거 앵커 하나로 되짚어지는가
 - [ ] 추론을 관측한 것처럼 적지 않았는가
 - [ ] 로컬·테스트에서 본 것을 운영 사실로 올리지 않았는가
 - [ ] Case 가 개념 설명이 아니라 구체적인 사건·검증 절차인가
 - [ ] Reference 가 짝이 되는 Case 의 서사를 통째로 되풀이하지 않는가
 - [ ] Decision 에 근거가 하나 이상 있고, 무엇을 보고 정했는지가 적혀 있는가
 - [ ] 지어낸 경험·실패·동기·감정이 없는가
 - [ ] 그림이 실제 asset 파일을 가리키고, 있어야 할 이유가 있는가
 - [ ] `final/assets/` 에 이미 있는 그림을 두고 같은 것을 새로 그리지 않았는가
 - [ ] 계약이 `ssot-assets`·`ssot-evidence` 로 배정한 것을 기록이 가리키는가
 - [ ] 그림이 관측하지 않은 사건을 만들어 내지 않았는가
@@ -0,0 +1,265 @@
 # Tech Log Tree Contract
 `tech-log-tree.json` is the explicit boundary between deep project analysis and Tech Log
 record generation. **It is the decomposition contract and the index at once, and it is the
 source of truth.** There is one file, so nothing can disagree with it.
 A finished `tech-log-studio/` holds `tech-log-tree.json` and the record folders. Nothing
 else.
 A project whose index predates this contract fails verification with one error until it is
 migrated. The per-field checks stay off for such a project — "not written yet" must not read
 as "written wrong" — but non-adoption itself is counted, because a warning lets an old index
 avoid every check indefinitely.
 ## Required top level
 - `schemaVersion`
 - `project`
 - `ssot` and `ssotSha256` — the hash prevents treating a tree derived from old material
  as current
 - `sourceRevision`
 - `generatedAt`
 - `sourceRepository` — `path`, `revision`, and `verified`: which checkout the analysis read,
  which commit the document describes, and how that was confirmed. Leave `revision` null rather
  than inventing one; the verifier warns instead of accepting a made-up label. When the work
  is spread over branches rather than one line of commits, use `revisions` — a label to commit
  map — and pin every tip the document describes
 - `candidateScope` — which part of the SSOT candidates may come from
 - `contract` — the decomposition rules, `readinessValues`, `dispositionValues`
 - `topics`, `candidates`, `counts`, `unlisted`
 ## Candidate scope
 A folded `final/document.md` carries the integrated analysis, the module analyses, and the
 analysis material in one file. Only the first is candidate material.
 ```json
 "candidateScope": {
  "document": "final/document.md",
  "sections": ["§3", "§4", "§5", "§6", "§7", "§8", "§9", "§10", "§11"],
  "excluded": ["제2부 — 모듈 분석 전문", "제3부 — 분석 재료"]
 }
 ```
 `document` names the SSOT and must match `ssot`. `sections` names the candidate scope, and
 `excluded` names the parts that are evidence rather than candidates. A node may cite an
 anchor from an excluded part in `source`; it may not exist because of one.
 `excludedAnchorPattern` is optional and is the only field the verifier can act on. Without it
 the rule above is a sentence nobody enforces — the check that a node did not come *only* from
 outside the scope is switched off entirely.
 ```json
 "candidateScope": {
  "document": "final/document.md",
  "sections": ["§3", "§4"],
  "excluded": ["제2부 — 모듈 분석 전문"],
  "excludedAnchorPattern": "#a[0-9]+$"
 }
 ```
 It is a regular expression matched against each `source` anchor. A node whose anchors *all*
 match it is an error: it was promoted from evidence, not from the candidate scope.
 ## Anchors resolve to real sections
 `source` and `sourceRefs` anchors are checked against the SSOT's own headings when the project
 writes them as heading slugs (`#검토한-선택지와-막힌-지점-ap1` = the h2 slug plus a
 discriminator). **Keep one anchor style per project.** A project that numbers its anchors
 (`#§1.1`, `#10-2`, `#a18`) gets a warning instead — the verifier cannot tell whether the
 section it names exists, and the diagram stage cannot translate the anchor into a
 `techviz prepare --heading` value without a person reading it.
 ## Topics
 Each Topic has `topic` (its key), `title`, **`readerQuestion`**, and `kinds` with the six
 record kinds.
 ```json
 "oauth-oidc-auth-boundary": {
  "topic": "oauth-oidc-auth-boundary",
  "title": "OAuth 자격증명과 세션의 보관 경계",
  "readerQuestion": "자격증명과 세션을 누가 보관하고, 누가 API 요청을 만들며, 보호 자원은 무엇을 신뢰하는가?",
  "kinds": { "case": [], "concept": [], "setup": [], "reference": [], "question": [], "decision": [] }
 }
 ```
 Every node in the Topic must help answer the reader question. Two Topics do not share a
 question; one Topic does not need two. Empty kinds are allowed — do not manufacture nodes
 to fill all six.
 ## Candidates
 Everything the analysis found lives in `candidates` with its disposition —
 `.agents/skills/deriving-tech-log-root-tree/references/candidate-disposition.md`. Only
 `PROMOTE` candidates become nodes under `topics`, and the relation runs both ways: a
 `PROMOTE` candidate whose target is not a node, and a node no `PROMOTE` candidate points
 at, are both contract errors.
 `dispositionReview` records whether a person re-read the candidate under the independence
 test. `PENDING` means it reached the tree by recall alone, and a `PENDING` candidate is an
 error, not a warning — a record written over an unreviewed tree inherits the
 over-classification the disposition step exists to catch. Write records only for nodes
 whose candidate is `PROMOTE` and `CONFIRMED`.
 ## Written by hand, refreshed by script
 `readiness` · `source` · `code` · `evidence` · `classification` · `relations` and the rest
 of each kind's fields are written by a person. `build-tech-log-tree.py` never touches them.
 It refreshes only what it can read from the record files — `file`, `publication`, `status`,
 `studioId`, `assets`, `assetFiles`, `evidenceFiles` — and lists records that have no node in
 `unlisted`.
 ### `ssot-assets` · `ssot-evidence`
 The SSOT is not only `final/document.md`. `final/assets/` holds diagrams that were already
 drawn, each with its canonical `final/.techviz/<name>/`, and `final/evidence/` holds
 measurements that were already run. Neither produces candidates — both are **assigned** to
 candidates that already exist, and these two fields hold the assignment.
 ```json
 "ssot-assets": ["ap3-bff-session-flow"],
 "ssot-evidence": ["raw/explain/l3-cartesian-join-plan.txt"]
 ```
 `ssot-assets` names diagrams by file stem; the file must exist somewhere under
 `final/assets/`. `ssot-evidence` takes paths relative to `final/evidence/`. Both are
 written by a person and both are optional — a node that needs no picture and cites no
 measurement leaves them out.
 What they are not optional about is follow-through. Once a node is assigned a diagram and
 its record is written, the record's `assets` must point at that file and its `evidence` at
 that path; `verify-tech-log-tree.py` reports the gap as an error. Assigning and then not
 using is the failure these fields exist to catch — without them a writer draws the picture
 again instead of finding the one that is already there.
 `verify-project-layout.py` counts the other direction: SSOT diagrams and raw evidence that
 no record cites at all. Some of that count is correct — a four-pattern comparison diagram
 belongs to a Reference, and Reference has no body to render it in. The count is meant to be
 explained, not driven to zero.
 ### `assetLedger`
 That explanation lives at the top level of the index, next to `candidateScope`. It names
 what was assigned and, for everything left over, why it is left over.
 ```json
 "assetLedger": {
  "assigned": ["ap3-bff-session-flow", "ap3-csrf-boundary"],
  "unassigned": [
    {"asset": ["four-pattern-request-boundaries"],
     "reason": "네 패턴을 비교하는 그림이라 붙을 자리가 Reference 인데 Reference 에는 본문이 없다"}
  ]
 }
 ```
 A diagram left out for a reason is a normal outcome, the same way `KEEP_IN_SSOT` is. What
 is not normal is a leftover nobody looked at — that is the state where the next writer
 draws the picture again. Write the ledger when the count first appears, not when it grows.
 ### Case
 `slug` · `readiness` · `source` · `classification` · `missing-verification` · `relations`,
 plus `code`/`evidence` when the conclusion depends on them.
 One problem, an observation or reproduction, a diagnosis, a conclusion that closes. Several
 observations that answer the same question with the same conclusion are one Case with a
 table or sub-sections, not several partial Cases.
 ### Concept
 `slug` · `readiness` · `source` · `basis-version` · `classification` · `relations`.
 `basis-version` names what the explanation was written against — `Keycloak 26.7.0 identity
 brokering`, `Spring Boot 3.3 auto-configuration`. A Concept without it cannot be known to
 be stale.
 A Concept exists because a Case, Decision, or Question needs it to be understood. Absence,
 call-counts, unwired subsystems, analysis scope, and coverage ledgers are not Concepts.
 ### Setup
 `slug` · `readiness` · `source` · `classification` · `pinned-versions` · `relations`.
 Setup is the one kind that does not report a finished result. It is a procedure a reader
 runs on their own machine, so `pinned-versions` states the versions the procedure was
 established on — the same job `basis-version` does for a Concept, except there is more than
 one of them. There is no verification date for this kind.
 A Setup node also needs a project. `SETUP` and `PROJECT_DECISION` are the two kinds Studio
 refuses to save without one; a Topic is optional, and a Setup with no Topic reads as that
 project's shared configuration.
 `verify-tech-log-tree.py` checks this kind like the others: `REQUIRED_FIELDS["setup"]` names
 the six fields above and `GENERATABLE["setup"]` is `READY`. The kind list those tables are
 keyed on lives in `techlog.KINDS`, which also decides which `<topic>/<kind>/` folders
 `build-tech-log-tree.py` scans. Add a kind in one place and the tables that key off it go
 quiet rather than failing — a kind missing from `REQUIRED_FIELDS` is not an error, it is a
 node nobody asks anything of.
 ### Reference
 `slug` · `readiness` · `source` · `classification` · `scope` · `exceptions` · `relations`.
 A Reference must be useful beyond retelling one Case. If removing the originating
 project's names leaves no rule, it is still a Case.
 ### Open Question
 `slug` · `readiness: OPEN` · `source` · `known` · `unknown` · `next-verification` ·
 `decision-criterion` · `relations`.
 Do not create a Question when the analysis already contains a verified answer. Move the
 material to Case/Reference/Decision and update the tree first.
 ### Decision
 `slug` · `readiness` · `decision-status` · `source` · `decision-evidence` · `grounds` ·
 `classification` · `relations`.
 `decision-status` is `PROPOSED`, `ADOPTED`, `SUPERSEDED`, or `NOT_DECIDED`. A
 `NOT_DECIDED` candidate uses `NEEDS_DECISION` and is not written as a Decision.
 ## Readiness semantics
 **`readiness` is about evidence, not about publication.** Whether a record has been
 written, and whether it has been saved into Studio, are separate facts that the generated
 index carries as `file` and `publication`. A published record with thin evidence is still
 `NEEDS_EVIDENCE`.
 | readiness | meaning | generation |
 |---|---|---|
 | `READY` | grounded enough for the kind | allowed |
 | `OPEN` | legitimate unresolved Question | allowed as Open Question |
 | `NEEDS_EVIDENCE` | material assertion still lacks verification | blocked |
 | `NEEDS_DECISION` | direction sounds plausible but the project has not decided | blocked |
 | `BLOCKED` | sources are incomplete or contradictory | blocked |
 `REJECTED` is not a readiness. Whether a candidate becomes a record at all is a
 disposition, and it lives in `candidates`, not on the node.
 ## Derivation rules
 1. Discover candidates from `final/document.md` only. It is the whole analysis, folded in —
   there is no `analysis/` folder to search in a finished project.
 2. Give every candidate a disposition before writing any node. `KEEP_IN_SSOT` is a normal
   outcome, and a decomposition that excludes nothing has not selected anything.
 3. Apply the independence test: if folding the record into a related Case or Concept as
   one section changes nothing, it is not an independent record.
 4. Take Cases, References, Decisions, and Questions first; add Concepts backwards from
   what those four require.
 5. Prefer several narrowly grounded Cases over one broad Case combining unrelated
   incidents — but merge observations that share a question and a conclusion.
 6. Extract Decisions only from explicit choice evidence: ADR, commit/history, configuration
   plus recorded rationale, issue/PR decision, or a user-supplied decision record.
 7. A node may relate to several siblings, but each record has one primary purpose.
 8. If new runtime evidence changes the answer, update the analysis and revise the tree
   before editing downstream records.
 ## Generation and verification
 ```bash
 python3 scripts/build-tech-log-tree.py <project>    # 파생 칸을 다시 채운다
 python3 scripts/verify-tech-log-tree.py <project>   # error 0 이어야 한다
 ```
@@ -3,17 +3,25 @@
 칸 목록과 상한은 `record-kinds.md`, 문장 규칙은 `explaining.md`, 문서군의 리듬은 `ai-tells.md`에
 있다. 이 문서는 **그 칸을 무엇으로 채우는가**다.
-**이미 쓴 47건에서 뽑았다.** keycloak 23건(Case 4·Concept 6·Reference 7·Question 4·Decision 2),
+**Studio 에 실제로 올라간 47건에서 뽑았다.** keycloak 23건(Case 4·Concept 6·Reference 7·
-n+1liner 24건(Case 5·Reference 7·Question 5·Decision 7). 「대개 이렇게 쓴다」는 말은 그 47건이
+Question 4·Decision 2), n+1liner 24건(Case 5·Reference 7·Question 5·Decision 7).
-그렇게 돼 있다는 뜻이다.
+「대개 이렇게 쓴다」는 말은 그 47건이 그렇게 돼 있다는 뜻이다.
-## 파일 뼈대 — 다섯 종류가 같다
+**Setup 은 그 47건에 없다.** 2026-09-12 에 Studio 의 환경 구성 문서가 0건이었다. 그래서 Setup
 절은 계약과 편집 화면에서 읽어 썼다. 나머지 다섯처럼 올라간 기록을 세지 않았다.
 `clean-architecture-backend-template` 의 949건은 다른 절 이름으로 쓰여 있었고, 지금 이 기준으로
 다시 판정하는 중이다. 아직 기준을 만족한 상태가 아니므로 그 949건을 본보기로 삼지 않는다. 올라간
 적 없는 초안이 아니라 **올라간 것**이 기준이다.
 ## 파일 뼈대 — 여섯 종류가 같다
 ```markdown
 ---
-id · kind · slug · title · topic · project · status · studio
+id · kind · slug · title · topic · topicName · project · status · studio
-(종류별) basisVersion · decisionStatus · questionStatus · lastVerifiedOn
+source · sourceRevision
-(있으면) assets · evidence
+(종류별) basisVersion · decisionStatus · questionStatus · lastVerifiedOn · pinnedVersions
 (있으면) evidence · assets — assets 는 Case · Concept · Setup 만
 ---
 # 제목
@@ -22,7 +30,7 @@ id · kind · slug · title · topic · project · status · studio
 ## 관계          ← Decision 만 「근거」다
 ## <칸 이름>     ← 종류마다 다르다
-## 본문          ← Case · Concept 만
+## 본문          ← Case · Concept · Setup 만
 <!-- body:start -->
 ...
 <!-- body:end -->
@@ -30,6 +38,21 @@ id · kind · slug · title · topic · project · status · studio
 frontmatter 는 메타데이터, `##` 는 Studio 의 칸, 제목 아래 첫 문단은 요약이다. 47건 모두 이 모양이다.
 **`## 요약` 이라는 절을 만들지 않는다.** 요약은 제목 바로 아래 문단이다. 절로 만들면 Studio 에
 그런 칸이 없어서 통째로 사라진다.
 **`## 출처` 도 칸이 아니다.** 원본 분석 문서나 파일 경로는 frontmatter 의 `source` 에 적는다.
 본문 마지막에 두면 게시된 글에 저장소 내부 경로가 그대로 실린다.
 ```yaml
 source:
  - final/document.md#a05-adapter-outbound-persistence-jpa#L354
 sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
 ```
 `source` 는 SSOT 의 앵커다. 분석을 접어 넣은 프로젝트에는 `analysis/` 가 없으므로 그 경로를 적으면
 가리키는 파일이 없다.
 **관계 항목은 굵은 제목 한 줄 + 이유 한 줄**이다.
 ```markdown
@@ -48,7 +71,9 @@ frontmatter 는 메타데이터, `##` 는 Studio 의 칸, 제목 아래 첫 문
 | 검증 환경 | 런타임·버전·DB·측정 도구. `이름 : 값`으로 줄을 나눈다 |
 | 재현 조건 | 다른 사람이 같은 값을 얻는 순서. 번호를 매긴다 |
-**본문은 5~12절, 대개 6절이다.**
+본문의 절은 하나의 주장과 그 근거가 이어지는 단위로 나눈다. 47건에서는 대개 여섯 절 안팎이었지만
 **절 수는 작성 조건이 아니다.** 숫자를 맞추려고 절을 쪼개거나 붙이면 문서마다 같은 모양이 된다.
 아래는 그 47건에서 실제로 반복된 순서다.
 - **첫 절은 무대를 세운다.** 잰 코드나 구조를 먼저 보여 준다 — 「측정한 loadFeed 구현」,
  「무대 — 페이징 한 줄만 추가」, 「가시성을 얹기 전 — 인덱스로 커서 이후만」,
@@ -58,7 +83,10 @@ frontmatter 는 메타데이터, `##` 는 Studio 의 칸, 제목 아래 첫 문
  테스트로 확인한 범위」, 「Redirect URI와 CORS에서 아직 확인하지 않은 부분」), 2건이 「다음 선택」,
  나머지가 지표 읽는 법이나 남긴 이유다. **재지 않은 것을 적지 않고 닫는 Case 는 없다**
-코드블록에는 무엇을 보라는 한 줄을 붙인다. 표 앞이나 뒤에 그 표를 어떻게 읽는지 적는다. 예시는
+그 마지막 절은 **본문 안**이다. 칸으로 빼면 Studio 에 그런 칸이 없어 사라진다.
 코드블록에는 라벨로 무엇인지 적는다. 표는 머리글이 무엇을 묻는지 말하게 하고, 그 표를 어떻게 읽는지
 설명하는 문장(「이렇게 갈린다」「함께 읽어야 한다」)은 두지 않는다. 예시는
 한 규모로 고정한다 — 표가 전체 계열을 이미 보여 준다.
 ## Concept — 6건
@@ -73,7 +101,8 @@ basisVersion: Keycloak 26.7.0 · oidc-client-ts 3.3.0
 basisVersion: oauth2-proxy 7.15.2 · Nginx auth_request
 ```
-**본문은 5~8절, 대개 6절이다.**
+절의 개수를 정해 두지 않는다. 설명해야 할 참여자와 단계가 몇 개인지가 정한다. 47건에서 반복된
 순서는 이렇다.
 - 첫 절은 무엇이 무엇을 주고받는지다 — 「두 개의 OAuth 왕복이 이어진다」,
  「Resource Server가 받는 입력」, 「요청 하나가 두 번 평가된다」
@@ -84,6 +113,159 @@ basisVersion: oauth2-proxy 7.15.2 · Nginx auth_request
 「확인했다」는 Case 의 말이다. Concept 은 「~한다」로 적는다. 규격이 정한 것과 그 구현이 그렇게 한
 것을 구분한다.
 ## Setup — 0건
 칸은 `관계` · `본문` 둘뿐이고, 고정한 버전은 frontmatter 의 `pinnedVersions` 에 있다. 계약의
 `PinnedVersion` 은 `name` 과 `version` 을 나눠 담는다 — 이름 1~60자, 버전 1~40자, 30개까지.
 ```yaml
 pinnedVersions:
  - name: Keycloak
    version: 26.7.0
 ```
 **절 이름을 강제하지 않는다.** 계약이 그렇게 적는다 — 「실행 절차·구성 값·확인 방법을 `##`
 절로 적는다. 절 이름을 강제하지 않는다 — 프로젝트마다 셋업의 모양이 다르다.」 그래도 빈 본문에서
 시작하지는 않는다. 작업본을 만들면 Studio 가 절 셋을 미리 넣어 주므로 거기서 출발한다.
 ```markdown
 ## 실행 절차
 ## 구성 값
 ## 확인 방법
 ```
 **명령은 코드블록으로 적는다.** 절차 Markdown 칸의 도움말이 이유를 적는다 —
 `“##” 소제목이 목차가 됩니다. 명령은 코드블록으로 적어야 그대로 복사됩니다.` 읽는 사람이
 자기 기계에서 실행하므로, 산문에 섞어 적으면 복사할 때 프롬프트 기호와 설명이 함께 붙는다.
 Case 와 무엇이 다른지는 **읽는 사람이 무엇을 하는가**로 갈린다. Case 의 「재현 조건」은 내가 잰
 값을 남이 다시 얻는 순서이고, Setup 의 본문은 그 환경을 처음 세우는 절차다. Case 는 평문 한 칸에
 그 순서를 담지만 Setup 은 본문을 쓰므로 명령·표·그림이 들어간다.
 **검증일을 쓰지 않는다.** 이 종류에는 그 칸이 없다. 절차가 어느 버전 위에서 성립했는지는
 `pinnedVersions` 가 말하므로, 본문에 「2026-09-12 기준」 같은 날짜를 적어 대신하지 않는다.
 `project` 는 비울 수 없다. `topic` 은 비워도 되고, 비우면 그 프로젝트의 공통 구성으로 읽힌다.
 ### 본문을 쓰기 전에 `writing-practitioner-guides` 를 연다
 `Skill` 도구로 `writing-practitioner-guides` 를 부른다. 명령을 어떤 형태로 쓸지는 그 스킬이
 정한다 — 한 줄에 어느 계층까지 담는지, 어떤 도구를 먼저 잡는지, 출력을 읽는 형태와 값 하나만
 뽑는 형태를 어떻게 가르는지, 넓은 명령에서 좁은 명령으로 내려가는 순서, 무엇이 보이면 멈추고
 다시 쓰는지가 거기 적혀 있다. 그 규칙을 이 문서로 옮겨 적지 않는다. 같은 규칙이 두 곳에 있으면
 한쪽만 고쳐지고 둘이 갈린다.
 다른 다섯 종류에는 이 절차가 없다. 나머지는 끝난 일을 적으므로 명령이 나와도 그때 무엇을 쳤는지
 보여 주는 인용이고, 읽는 사람이 자기 기계에서 그것을 치지 않는다. 환경 구성은 읽는 사람이 그대로
 따라 치므로 명령의 형태가 내용의 일부다. `echo 'export ...' >> ~/.bashrc` 는 결과를 만들지만
 읽는 사람이 `~/.bashrc` 를 한 번도 열어 보지 못하고, 같은 가이드를 다시 따라 하면 같은 줄이
 하나 더 붙는다.
 기계적으로 바꾸는 방향도 틀린다. 조회·진단·실행은 운영자가 쓰는 CLI 를 그대로 쓴다 —
 `grep`·`lsmod`·`virsh`·`systemctl`·`journalctl`·`kubectl` 이 들어갔다는 것 자체는 문제가
 아니다. 사람이 내용을 읽고 고쳐야 하는 설정 파일을 만드는 대목에서만 에디터로 연다.
 ### 단계 하나의 모양
 `writing-practitioner-guides` 의 「Shape of one step」은 상태를 읽는 단계의 모양이다. 환경 구성의
 본문은 상태를 바꾸는 단계가 대부분이고, 그쪽은 칸이 다섯이다.
 ```text
 ### N. <이 단계가 무엇을 만드는가>
 목적            한 줄. 이 단계가 끝나면 무엇이 달라지나
 행동            번호를 매긴 명령. 한 번호에 한 가지 일
 예상 결과       그때 화면에 나오는 것
 왜 필요한가     건너뛰거나 어긋나면 무엇이 깨지나
 문제가 생기면   어느 명령부터 다시 보나
 ```
 번호는 행동을 세려고 매긴다. 한 번호가 접속과 파일 생성과 권한 설정을 함께 하면 읽는 사람은
 어디까지 왔는지 셀 수 없고, 실패해도 그 줄의 어느 대목에서 실패했는지 모른다. 다섯 칸이 단계마다
 같은 순서로 오면 처음 따라 하는 사람이 단계마다 같은 곳에서 같은 것을 찾는다.
 채운 예는 `writing-practitioner-guides` 에 있다 — libvirt 연결 URI 를 `qemu:///system` 으로
 고정하는 단계다.
 ### 자리표시자
 **원칙은 자리표시자를 두지 않는 것이다.** `writing-practitioner-guides` 의 「No placeholders」가
 이유를 적는다 — `<토큰>` 이라고 적어 두면 그 값을 어디서 가져오는지가 문서 밖으로 나간다. 값을
 뽑는 명령을 먼저 주는 것이 먼저다.
 **예외는 하나다 — 같은 기록의 앞 단계가 화면에 찍은 값을 뒤 단계에 옮겨 넣을 때.** 세션 `sid` 는
 로그인할 때마다 새로 생기고 클라이언트 UUID 는 렐름을 만들 때 정해져서 읽는 사람의 실험대에서
 다르다. 앞 단계가 탐침 파드 안에서 돌았으면 그 셸의 변수가 뒤 단계의 셸에 없어서 변수로 넘길
 수도 없다. 값을 만드는 명령은 이미 같은 문서 안에 있으므로 전역 스킬의 빨간 깃발
 (`<placeholder>` with no command that produces it)에는 걸리지 않는다.
 **그때 쓰는 꼴은 `{{NAME}}` 하나다.** `NAME` 은 대문자로 시작하고 대문자·숫자·밑줄만 쓴다.
 ```bash label="[kc-lab-1] ② 읽은 값을 그대로 넣어 행을 찾는다"
 kubectl -n keycloak-lab exec deploy/postgres -- psql -U keycloak -d keycloak \
  -c "select user_session_id, created_on, last_session_refresh from offline_user_session
      where offline_flag='0' and user_session_id='{{SID}}'"
 ```
 **`${SID}` 로 쓰지 않는다.** 같은 가이드들이 `$SID`·`$K0`·`$TOK`·`$PW` 를 진짜 셸 변수로 쓴다.
 자리표시자를 셸 변수 꼴로 적으면 읽는 사람이 「이 변수는 이미 셸에 있다」로 읽고 그대로 붙여
 넣는다. `{{ }}` 는 셸 문법이 아니라서 붙여 넣으면 반드시 틀리고, 틀린 자리가 화면에 보인다.
 **한글로 감싸지 않는다.** `'<① 이 찍은 sid>'` 는 사람에게는 읽히지만 검사기가 그 줄을 흐름도로
 오인하기 쉽고, 무엇보다 자리표시자 바깥의 SQL 이 SSOT 와 갈려도 드러나지 않는다. 어느 단계가 그
 값을 찍었는지는 코드블록 바로 위 산문에 적는다 — 「sid 는 ③ 이 `SID=` 로 화면에 찍은 값을 옮겨
 넣는다」처럼.
 **검사기는 그 자리만 와일드카드로 본다.** `{{SID}}` 는 따옴표도 공백도 넘지 않는 값 하나로
 열리고 나머지는 한 글자씩 SSOT 와 대조된다. 그래서 `user_session_id` 를 `user_session_idx` 로
 잘못 적으면 그대로 걸린다.
 ### 이 저장소에서만 걸리는 것 셋
 전역 스킬은 Tech Log 의 검사기도 SSOT 도 모른다.
 **① 명령의 형태를 고치려면 SSOT 를 먼저 고친다.** `check_evidence.mjs` 가 본문 코드블록의 줄을
 `final/document.md` 와 대조한다. `bash`·`yaml`·`nginx` 처럼 언어를 적은 펜스는 줄 단위로 보고,
 `text`·`txt`·`console`·`diff` 펜스와 언어를 안 적은 펜스는 그 안의 경로·URL·점 있는 식별자만
 본다. 그래서 `sudo nano /etc/letsencrypt/cloudflare.ini` 를 SSOT 에 없는 채로 넣으면 「인용한
 코드가 SSOT 에 없다」로 막힌다.
 대조에서 빠지는 줄도 있다. 20자 미만인 줄, `#`·`//`·`|`·`>` 로 시작하는 줄, 그리고 한글과 흐름
 글리프(`─`·`▶`·`→`·`←`)가 함께 있는 줄 — 필자가 그린 흐름도 — 을 건너뛴다. `nano ~/.bashrc` 는
 14자라 대조 없이 통과한다. 통과했다는 것과 SSOT 에 있다는 것은 다르므로 짧은 명령도 사람이
 SSOT 에서 찾아 대조한다.
 **한글이 섞였다는 것만으로는 안 빠진다.** 예전에는 그랬고, 그래서 자리표시자를 한글로 감싼
 `psql -c "…"` 한 줄이 통째로 대조에서 빠졌다. 지금은 흐름 글리프까지 있어야 흐름도로 본다.
 순서는 SSOT 가 먼저다. 구축 절차를 담은 부(virtualization 은 제6부 §184~§194)에 사람이 치는
 형태를 적고, 그 형태도 원 가이드나 저장소에서 확인한 뒤에 적는다. 기록을 먼저 고치고 검사기가
 막을 때 SSOT 를 맞추면 SSOT 가 근거이기를 그만두고 기록의 사본이 된다. CLAUDE.md 의 「보강은
 상류 원문으로 한다」가 같은 말이다.
 형태를 바꾸는 것과 사실을 바꾸는 것은 다르다. 원 가이드가 `printf ... > meta-kc-lab-1` 로
 적었다면 그 파일에 무엇이 들어가는지는 원문이 이미 갖고 있으므로, SSOT 에는 그 내용을 파일
 목록으로 옮기고 파일을 여는 명령을 앞에 둔다. 원문이 만들지 않은 파일이나 재지 않은 출력을
 새로 만들지 않는다.
 **② 셸이 여럿인 실험대에서는 코드블록마다 어디서 치는지 붙인다.** 산문에 한 번 적어 두면 따라
 하는 도중에는 안 보인다. 본문 파서가 코드블록의 `label` 을 받으므로 거기에 적는다.
 ```bash label="[lab host] 저장소 루트에서 친다"
 kubectl apply -f deploy/lab/k8s/keycloak-cluster.yaml
 ```
 virtualization 의 SSOT §185 ③ 이 그 표시를 다섯으로 정해 두었다 — `[워크스테이션]` ·
 `[lab host]` · `[kc-lab-edge]` · `[kc-lab-1]` · `[kc-lab-2]`. 표시가 없으면 같은 명령이 다른
 기계에서 다른 결과를 낸다.
 **③ 비밀은 길이와 존재 여부까지만 적는다.** 값을 찍는 명령을 본문에 두지 않는다. 토큰이 필요한
 단계는 값을 찾는 명령을 주고 `echo "${#TOKEN} 자"` 로 끝낸다. `final/evidence/` 에 올리는 원문에도
 값이 들어가지 않도록 명령을 짜는 것이 먼저다. 터미널 렌더러가 Bearer·Cookie·token·password 를
 `[REDACTED]` 로 바꾸지만 그 앞에서 막는다.
 ## Reference — 14건
 칸은 `관계` · `목적` · `규칙` · `적용 조건` · `예외` · `예시`. 14건 모두 여섯 칸을 채웠다. 본문이 없다.
@@ -98,7 +280,8 @@ basisVersion: oauth2-proxy 7.15.2 · Nginx auth_request
 규칙 제목만 읽어도 무엇을 금지하는지 알아야 한다. 「지표를 정확히 읽는다」보다
 「지표 이름이 뜻하는 것을 그대로 읽는다」가 낫다. 코드가 필요하면 그 코드가 있는 Case 를 만들고
-`관계`로 가리킨다 — Reference 칸은 평문이라 백틱이 글자로 보인다.
+`관계`로 가리킨다 — Reference 칸은 마크다운 블록 파서를 안 거쳐서 코드펜스가 글자로 보인다.
 낱말 하나짜리 식별자는 백틱으로 감싸면 인라인 `<code>` 로 살아난다. 여러 줄짜리 코드가 문제다.
 ## Question — 9건
@@ -111,9 +294,21 @@ basisVersion: oauth2-proxy 7.15.2 · Nginx auth_request
 `다음 검증`은 실행할 수 있는 문장으로 적는다. 「더 알아본다」로는 닫히지 않는다 —
 「seed(1000) 뒤 `ANALYZE highlights` 를 돌리고 Plan B 를 다시 잰다」처럼 적는다.
 **그 아래 닫는 조건을 한 줄 붙인다.** 어떤 결과가 나오면 이 질문을 닫거나 Decision 으로 넘기는지
 적지 않으면 검증을 마쳐도 질문이 그대로 열려 있다. 계약의 `decision-criterion` 이 이 줄이다.
 ```markdown
 ## 다음 검증
 1. seed(1000) 뒤 `ANALYZE highlights` 를 돌리고 Plan B 를 다시 잰다
 닫는 조건 : Plan B 의 실제 행 수가 추정치의 2배 안에 들어오면 닫고, 벗어나면 통계 갱신 주기를
 정하는 Decision 으로 넘긴다
 ```
 ## Decision — 9건
-칸은 **`근거`** · `결정문` · `판단 이유` · `영향`. **다른 넷과 달리 관계 절 이름이 「근거」다.**
+칸은 **`근거`** · `결정문` · `판단 이유` · `영향`. **다른 다섯과 달리 관계 절 이름이 「근거」다.**
 `decisionStatus` 는 frontmatter 에 있다. 근거가 1개 이상 없으면 게시가 거절된다.
 | 칸 | 무엇을 |
@@ -125,9 +320,45 @@ basisVersion: oauth2-proxy 7.15.2 · Nginx auth_request
 대안을 적고 왜 고르지 않았는지 적는다. 대안이 없으면 결정이 아니라 사실이다. 자료가 뒷받침하지
 않는 이유를 만들지 않는다.
-## 본문이 있는 두 종류의 공통 규칙
+## 본문이 있는 세 종류의 공통 규칙
 - **그림이 필요한지와 무엇을 그릴지는 `choosing-a-diagram.md` 가 정한다** — 종류마다 그림이
  답해야 할 물음이 다르다. Case 는 순서, Concept 은 구조나 변환 사슬이 대개 논지다
 - 그림은 `technical-visualizer` 로 만든다. 손으로 SVG 를 그리지 않는다
 - 그림 안에는 이름만 넣는다. 문장은 `<desc>` 와 옆 문단에 둔다
 - 그림과 증거는 frontmatter 의 `assets` · `evidence` 로 잇는다. 같은 파일을 기록 옆에 복사하지 않는다
 - `assets` 는 본문이 있는 세 종류만 갖는다. Reference·Question·Decision 은 그림을 렌더링할 곳이
  없어서 선언해도 화면에 나오지 않는다
 - 본문은 `<!-- body:start -->` 와 `<!-- body:end -->` 사이다. 그 밖은 Studio 로 가지 않는다
 ## 관계를 어디서 가져오나
 관계는 **다른 기록을 가리키는 링크**다. 지어내지 않는다. 분해 계약(`tech-log-tree.json`)이 노드마다
 `relations` 를 적어 두면 그것을 그대로 옮긴다.
 계약이 관계를 적지 않은 노드는 한 가지 규칙만 쓸 수 있다 — **Reference 의 근거 사건은 같은
 `source` 리프의 판정이 소유한다.** 그래서 같은 분석 문서에서 나온 Reference 와 Case 는 서로
 걸 수 있다. 그 밖의 짝은 읽고 정해야 한다. 「같은 모듈이다」는 관계가 아니라 분류다.
 ```markdown
 ## 관계
 - **SQL 실패가 재시도 불가로 분류된다**
  이 규칙의 근거는 같은 분석 리프의 판정이 소유한다.
 ```
 Studio 는 Decision 만 관계를 1개 이상 요구한다. 나머지는 비어도 게시되지만, 관계 없는 기록은
 다른 기록에서 도달할 수 없다.
 ## Studio 파서가 거절하는 세 가지
 `check_body.mjs` 가 잡는다. 셋 다 글자를 바꾸지 않고 고칠 수 있다.
 | 쓴 것 | 파서가 읽는 것 | 고치는 법 |
 |---|---|---|
 | `` `:11`~`:14` `` | `~…~` 를 취소선으로 | `` `:11`\~`:14` `` |
 | `afterPropertiesSet(:43)` | `:43` 을 인라인 디렉티브로 | `(\:43)` 또는 백틱으로 감싼다 |
 | `:::note` 안에 문단 둘 | 거절 | 문단 하나만 담거나 절 제목 아래 평문으로 푼다 |
 `## 확인하지 못한 것` 처럼 절 제목이 이미 무엇인지 말하는 자리에서는 `:::note` 로 다시 감싸지
 않는다. 제목과 콜아웃이 같은 말을 두 번 한다.
@@ -0,0 +1,177 @@
 #!/usr/bin/env node
 // 기록이 인용한 것이 정말 SSOT 에 있는지 본다.
 //
 //   node check_evidence.mjs <프로젝트>
 //   node check_evidence.mjs <프로젝트> --repo    # 저장소까지 대조 (sourceRepository.path 필요)
 //
 // 세 가지를 본다.
 //   1. 본문 코드블록의 각 줄이 SSOT 안에 있는가
 //   2. frontmatter 의 source 앵커가 SSOT 를 가리키는가
 //   3. 기록의 title 이 계약(tech-log-tree.json)의 title 과 같은가
 //
 // 검사기가 못 보던 자리다. `verify-tech-log-tree.py` 는 slug 와 칸의 존재만 보고,
 // 인용한 코드가 실재하는지도 제목이 계약과 같은지도 보지 않는다.
 import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
 import { execSync } from "node:child_process";
 const [project, ...flags] = process.argv.slice(2);
 if (!project) { console.error("usage: check_evidence.mjs <프로젝트> [--repo]"); process.exit(2); }
 const withRepo = flags.includes("--repo");
 const root = execSync("git rev-parse --show-toplevel", { encoding: "utf8" }).trim();
 const base = join(root, "docs", project);
 const treePath = join(base, "tech-log-studio", "tech-log-tree.json");
 // 대상이 성립하지 않는다 — CLAUDE.md 「검사」 절의 표. exit 2 로 error 로 센다
 if (!existsSync(treePath)) {
  console.error(`대상이 성립하지 않는다 — ${project}: tech-log-tree.json 이 없다`);
  process.exit(2);
 }
 const tree = JSON.parse(readFileSync(treePath, "utf8"));
 const ssotRel = tree.ssot || "final/document.md";
 const norm = s => s.replace(/\s+/g, " ").trim();
 const ssot = norm(readFileSync(join(base, ssotRel), "utf8"));
 // 계약이 말하는 제목
 const contractTitle = new Map();
 for (const topic of Object.values(tree.topics || {}))
  for (const [kind, items] of Object.entries(topic.kinds || {}))
    for (const n of items) if (n.slug) contractTitle.set(`${kind}:${n.slug}`, n.title || "");
 // ``` 로 열고 닫는 펜스를 짝짓는다. ```java label="…" 도 여는 표시다
 function codeBlocks(text) {
  const out = []; let inside = false, lang = "", buf = [];
  for (const line of text.split("\n")) {
    const t = line.trimStart();
    if (t.startsWith("```")) {
      if (inside) { out.push([lang, buf.join("\n")]); buf = []; inside = false; lang = ""; }
      else { inside = true; lang = (t.slice(3).trim().split(/\s+/)[0] || "").toLowerCase(); }
      continue;
    }
    if (inside) buf.push(line);
  }
  return out;
 }
 // ```text 는 필자가 짠 요약표·흐름도에 쓰인다. 정렬 공백이 열 구분자라 줄 단위로 대조하면
 // 전부 오탐이 된다. 그래서 text 펜스는 줄이 아니라 그 안의 식별자·URL·수치만 본다.
 const PROSE_FENCE = new Set(["text", "", "txt", "console", "diff"]);
 // 맨몸 영단어(observation, self-report …)는 필자가 붙인 열 이름이라 제외하고,
 // 경로·URL·점 있는 식별자처럼 저장소에서 온 것만 본다.
 const TOKEN = /(?:https?:\/\/[^\s"'`,)]+|\/[A-Za-z0-9_][A-Za-z0-9_./-]{4,}|[A-Za-z_][A-Za-z0-9_]*(?:[.][A-Za-z0-9_]+)+)/g;
 // Setup 의 자리표시자. 읽는 사람의 실험대에서 값이 달라지는 자리라 SSOT 의 실측값과 글자가
 // 다르다. 그 자리만 와일드카드로 두고 나머지는 한 글자씩 대조한다. 문법은
 // references/writing-each-kind.md 「Setup — 자리표시자」 가 정한다.
 // 셸 변수와 갈라야 해서 `${...}` 를 안 쓴다 — 같은 가이드가 `$SID`·`$TOK` 를 진짜 변수로 쓴다.
 const PLACEHOLDER = /\{\{[A-Z][A-Z0-9_]*\}\}/;
 const PLACEHOLDER_G = /\{\{[A-Z][A-Z0-9_]*\}\}/g;
 // 필자가 그린 흐름도의 글리프. `주입 ① ─▶ 검증 §1` 꼴은 코드가 아니라 그림이다
 const FLOW = /[─━│┃┌┐└┘├┤┬┴┼╭╮╯╰▶◀►◄→←↔⇒⇐↑↓]/;
 const RE_META = /[.*+?^${}()|[\]\\]/g;
 // 자리표시자가 없으면 지금까지처럼 통째로 찾는다. 있으면 그 자리만 「값 하나」로 열어 두는데,
 // 따옴표와 공백은 못 넘게 해서 와일드카드가 엉뚱한 구간을 삼키지 않도록 한다.
 function inSsot(line) {
  const n = norm(line);
  if (!PLACEHOLDER.test(n)) return ssot.includes(n);
  const pattern = n.split(PLACEHOLDER_G)
    .map(part => part.replace(RE_META, "\\$&"))
    .join("[^'\"\\s]+");
  return new RegExp(pattern).test(ssot);
 }
 const findings = [];
 const studio = join(base, "tech-log-studio");
 for (const topicDir of readdirSync(studio)) {
  const tp = join(studio, topicDir);
  if (!statSync(tp).isDirectory() || topicDir.startsWith("_")) continue;
  for (const kind of readdirSync(tp)) {
    const kp = join(tp, kind);
    if (!statSync(kp).isDirectory()) continue;
    for (const file of readdirSync(kp).filter(f => f.endsWith(".md"))) {
      const p = join(kp, file);
      const text = readFileSync(p, "utf8");
      const fm = text.startsWith("---") ? text.slice(4, text.indexOf("\n---", 3)) : "";
      const get = k => (fm.match(new RegExp(`^${k}: (.*)$`, "m")) || [, ""])[1].trim();
      const slug = get("slug"), title = get("title");
      // 1. 인용한 코드가 SSOT 에 있는가
      const bodyStart = text.indexOf("<!-- body:start -->");
      const body = bodyStart === -1 ? text : text.slice(bodyStart);
      for (const [lang, block] of codeBlocks(body)) {
        if (PROSE_FENCE.has(lang)) {
          for (const tok of block.match(TOKEN) || [])
            if (tok.length >= 8 && !ssot.includes(tok))
              findings.push([file, "인용한 식별자가 SSOT 에 없다", tok.slice(0, 90)]);
          continue;
        }
        for (const raw of block.split("\n")) {
          const t = raw.trim();
          if (t.length < 20) continue;
          if (/^(\/\/|\*|\/\*\*|#|--|>|\|)/.test(t)) continue;
          // 한글이 섞인 줄을 전부 건너뛰면 자리표시자를 한글로 감싼 명령이 통째로 빠진다.
          // 그래서 흐름 글리프가 함께 있는 줄 — 필자가 그린 흐름도 — 만 건너뛴다
          if (/[가-힣]/.test(t) && FLOW.test(t)) continue;
          if (!inSsot(t))
            findings.push([file, "인용한 코드가 SSOT 에 없다", t.slice(0, 90)]);
        }
      }
      // 2. source 앵커가 SSOT 를 가리키는가
      const src = (fm.match(/^source:\n((?:\s+-\s.*\n)+)/m) || [, ""])[1];
      const anchors = src.split("\n").map(l => l.replace(/^\s*-\s*/, "").trim()).filter(Boolean);
      if (anchors.length && !anchors.some(a => a.includes(ssotRel)))
        findings.push([file, "source 가 SSOT 를 가리키지 않는다", anchors.join(" · ").slice(0, 90)]);
      // 3. 제목이 계약과 같은가
      const key = `${kind}:${slug}`;
      if (contractTitle.has(key) && contractTitle.get(key) !== title)
        findings.push([file, "제목이 계약과 다르다", `계약 "${contractTitle.get(key)}" ≠ 기록 "${title}"`]);
    }
  }
 }
 // 4. (--repo) 저장소가 실재하고 리비전이 맞는가
 if (withRepo) {
  // 저장소가 여럿인 프로젝트는 목록으로 적는다
  const declared = tree.sourceRepository || {};
  const repos = Array.isArray(declared) ? declared : [declared];
  for (const repo of repos) {
    const name = repo.name || project;
    if (!repo.path) { findings.push(["tech-log-tree.json", "sourceRepository.path 가 없다", name]); continue; }
    if (!existsSync(repo.path)) { findings.push(["tech-log-tree.json", "저장소 경로가 없다", `${name} — ${repo.path}`]); continue; }
    // 갈래가 여럿이면 revisions 로 적는다. 둘 다 없으면 verify-tech-log-tree.py 가 warn 을 낸다
    const revs = repo.revision ? { revision: repo.revision } : (repo.revisions || {});
    // 체크아웃이 없는 저장소는 반입한 쪽의 매니페스트가 리비전을 고정한다. 그럴 때는
    // path 가 그 파일이고, git 대신 그 파일이 리비전을 적고 있는지 본다
    const isCheckout = statSync(repo.path).isDirectory();
    const manifest = isCheckout ? "" : readFileSync(repo.path, "utf8");
    for (const [label, rev] of Object.entries(revs)) {
      if (isCheckout) {
        try {
          execSync(`git -C ${JSON.stringify(repo.path)} cat-file -e ${rev}^{commit}`, { stdio: "ignore" });
        } catch {
          findings.push(["tech-log-tree.json", "그 리비전이 저장소에 없다", `${name} · ${label} = ${rev}`]);
        }
      } else if (!manifest.includes(rev)) {
        findings.push(["tech-log-tree.json", "매니페스트가 그 리비전을 적고 있지 않다", `${name} · ${label} = ${rev}`]);
      }
    }
  }
 }
 const grouped = new Map();
 for (const [f, rule, detail] of findings) {
  if (!grouped.has(rule)) grouped.set(rule, []);
  grouped.get(rule).push(`${f} — ${detail}`);
 }
 console.log(`\n[${project}] 증빙 대조${withRepo ? " (저장소 포함)" : ""}`);
 if (!findings.length) { console.log("  문제 없음"); process.exit(0); }
 for (const [rule, items] of [...grouped].sort((a, b) => b[1].length - a[1].length)) {
  console.log(`  ✗ ${String(items.length).padStart(4)}  ${rule}`);
  for (const it of items.slice(0, 3)) console.log(`        · ${it}`);
  if (items.length > 3) console.log(`        … 외 ${items.length - 3}건`);
 }
 console.log(`\n합계 ${findings.length}건`);
 process.exit(1);
@@ -0,0 +1,53 @@
 ---
 id: <Studio 가 준 uuid. 아직 없으면 빈 값>
 kind: CASE
 slug: <slug>
 title: <제목>
 topic: <topic-slug — 폴더 이름과 같다>
 topicName: <화면에 보이는 주제 이름>
 project: <프로젝트 이름>
 status: 게시 전
 studio: "<편집 화면 주소. 아직 없으면 빈 값>"
 lastVerifiedOn: <실제로 확인한 날 또는 빈 값>
 source:
  - final/document.md#<anchor>
 sourceRevision: <분석한 리비전>
 assets:
  - key: <본문의 :::evidence key 와 같은 값>
    file: <../../../final/assets/… 상대 경로>
 evidence:
  - <../../../final/evidence/raw/… 상대 경로>
 ---
 # <title>
 <summary>
 ## 관계
 - **<related record>**
  <why related>
 ## 문제
 <concrete observed problem and scope>
 ## 결론
 <bounded conclusion supported by evidence>
 ## 검증 환경
 <plain text exact environment>
 ## 재현 조건
 <ordered concrete conditions/steps>
 ## 본문
 <!-- body:start -->
 <rich Case body — 절은 주장 하나와 그 근거가 이어지는 단위로 나눈다. 정해진 개수는 없다>
 <!-- body:end -->
@@ -0,0 +1,49 @@
 ---
 id: <Studio 가 준 uuid. 아직 없으면 빈 값>
 kind: CONCEPT
 slug: <slug>
 title: <제목>
 topic: <topic-slug — 폴더 이름과 같다>
 topicName: <화면에 보이는 주제 이름>
 project: <프로젝트 이름>
 status: 게시 전
 studio: "<편집 화면 주소. 아직 없으면 빈 값>"
 basisVersion: <무엇을 보고 썼는지. 예 Keycloak 26.7.0 · oidc-client-ts 3.3.0>
 source:
  - final/document.md#<anchor>
 sourceRevision: <분석한 리비전>
 assets:
  - key: <본문의 :::evidence key 와 같은 값>
    file: <../../../final/assets/… 상대 경로>
 evidence:
  - <../../../final/evidence/raw/… 상대 경로>
 ---
 # <제목>
 <요약. 이 개념이 무엇을 어떻게 하는지 한 문단>
 ## 관계
 - **<이어지는 기록>**
  <왜 이어지는지>
 ## 본문
 <!-- body:start -->
 ## <무엇이 무엇을 주고받나>
 <첫 절은 참여자와 오가는 것을 세운다>
 ## <단계마다 실제로 일어나는 일>
 <설명할 단계가 몇 개인지가 절의 개수를 정한다. 미리 정해 둔 수에 맞추지 않는다>
 ## <그 설계가 막지 않는 것>
 ## <지금 확인한 범위>
 <규격이 정한 것과 이 구현이 그렇게 한 것을 구분한다. 「확인했다」는 Case 의 말이라 쓰지 않는다>
 <!-- body:end -->
@@ -0,0 +1,43 @@
 ---
 id: <Studio 가 준 uuid. 아직 없으면 빈 값>
 kind: PROJECT_DECISION
 slug: <slug>
 title: <제목>
 topic: <topic-slug — 폴더 이름과 같다>
 topicName: <화면에 보이는 주제 이름>
 project: <프로젝트 이름>
 status: 게시 전
 studio: "<편집 화면 주소. 아직 없으면 빈 값>"
 decisionStatus: PROPOSED
 source:
  - final/document.md#<anchor>
 sourceRevision: <분석한 리비전>
 evidence:
  - <../../../final/evidence/raw/… 상대 경로>
 ---
 <!--
 본문이 없는 종류라 `assets` 를 두지 않는다. 칸이 평문으로 렌더링되므로 그림과 코드블록은
 표시되지 않는다. 그런 자료는 근거로 건 Case·Concept·Setup 에 담는다.
 -->
 # <title>
 <summary>
 ## 근거
 - **<Case or Reference>**
  <how it grounds this decision>
 ## 결정문
 <the actual project choice>
 ## 판단 이유
 <only rationale explicitly supported by decision evidence>
 ## 영향
 - <grounded consequence/trade-off>
@@ -0,0 +1,59 @@
 ---
 id: <Studio 가 준 uuid. 아직 없으면 빈 값>
 kind: QUESTION
 slug: <slug>
 title: <제목>
 topic: <topic-slug — 폴더 이름과 같다>
 topicName: <화면에 보이는 주제 이름>
 project: <프로젝트 이름>
 status: 게시 전
 studio: "<편집 화면 주소. 아직 없으면 빈 값>"
 questionStatus: OPEN
 source:
  - final/document.md#<anchor>
 sourceRevision: <분석한 리비전>
 evidence:
  - <../../../final/evidence/raw/… 상대 경로>
 ---
 <!--
 본문이 없는 종류라 `assets` 를 두지 않는다. 칸이 평문으로 렌더링되므로 그림과 코드블록은
 표시되지 않는다. 그런 자료는 본문이 있는 종류(Case·Concept·Setup)에 담고 `관계`로 가리킨다.
 -->
 # <title>
 <summary of unresolved issue>
 ## 관계
 - **<related record>**
  <why related>
 ## 사실
 - <grounded fact>
 ## 가정
 - <explicit assumption, if any>
 ## 미지수
 - <unknown>
 ## 제약
 - <constraint>
 ## 선택지
 ### 1. <grounded candidate, only when it really exists>
 <what is known and what must be checked>
 ## 다음 검증
 1. <next concrete verification>
 닫는 조건 : <어떤 결과가 나오면 이 질문을 닫거나 Decision 으로 넘기는가>
@@ -0,0 +1,54 @@
 ---
 id: <Studio 가 준 uuid. 아직 없으면 빈 값>
 kind: REFERENCE
 slug: <slug>
 title: <제목>
 topic: <topic-slug — 폴더 이름과 같다>
 topicName: <화면에 보이는 주제 이름>
 project: <프로젝트 이름>
 status: 게시 전
 studio: "<편집 화면 주소. 아직 없으면 빈 값>"
 source:
  - final/document.md#<anchor>
 sourceRevision: <분석한 리비전>
 evidence:
  - <../../../final/evidence/raw/… 상대 경로>
 ---
 <!--
 본문이 없는 종류라 `assets` 를 두지 않는다. 이 기록의 칸은 평문으로 렌더링되므로 그림도
 코드블록도 표시되지 않는다. 그림이 필요한 내용은 본문이 있는 종류(Case·Concept·Setup)에 담고
 `관계`로 가리킨다.
 `evidence` 는 이 기록이 인용한 측정 자료의 출처이고 화면에는 나오지 않는다.
 -->
 # <title>
 <summary>
 ## 관계
 - **<related record>**
  <why related>
 ## 목적
 <why this reusable criterion exists>
 ## 규칙
 ### 1. <rule title>
 <plain-text rule>
 ## 적용 조건
 - <condition>
 ## 예외
 - <exception or explicitly none>
 ## 예시
 - <plain-text example>
@@ -0,0 +1,91 @@
 ---
 id: <Studio 가 준 uuid. 아직 없으면 빈 값>
 kind: SETUP
 slug: <slug>
 title: <제목>
 topic: <topic-slug — 폴더 이름과 같다. 비워도 된다>
 topicName: <화면에 보이는 주제 이름. 비워도 된다>
 project: <프로젝트 이름 — 이 종류는 프로젝트가 필수다>
 status: 게시 전
 studio: "<편집 화면 주소. 아직 없으면 빈 값>"
 pinnedVersions:
  - name: <이름 1~60자. 예 Keycloak>
    version: <버전 1~40자. 예 26.7.0>
 source:
  - final/document.md#<anchor>
 sourceRevision: <분석한 리비전>
 assets:
  - key: <본문의 :::evidence key 와 같은 값>
    file: <../../../final/assets/… 상대 경로>
 evidence:
  - <../../../final/evidence/raw/… 상대 경로>
 ---
 <!--
 검증일 칸이 없다. 이 절차가 어느 버전 위에서 성립했는지는 `pinnedVersions` 가 말한다.
 본문에 「2026-09-12 기준」 같은 날짜를 적어 대신하지 않는다.
 절 이름은 강제되지 않는다. 아래 셋은 Studio 가 작업본에 미리 넣어 주므로 거기서 시작해
 그 프로젝트가 쓰는 말로 바꾼다.
 본문을 쓰기 전에 `Skill` 도구로 `writing-practitioner-guides` 를 연다. 명령을 어떤 형태로
 쓸지는 그 스킬이 정한다. 이 저장소에서만 걸리는 셋(SSOT 를 먼저 고치기·셸 표시·비밀 값)은
 `references/writing-each-kind.md` 의 Setup 절에 있다.
 -->
 # <제목>
 <요약. 이 절차를 따라 하면 무엇이 서는지 한 문단>
 ## 관계
 - **<이어지는 기록>**
  <왜 이어지는지>
 ## 본문
 <!-- body:start -->
 ## 실행 절차
 <!--
 단계 하나의 칸은 다섯이다 — 목적 · 행동 · 예상 결과 · 왜 필요한가 · 문제가 생기면.
 다섯이 단계마다 같은 순서로 와야 처음 따라 하는 사람이 같은 곳에서 같은 것을 찾는다.
 행동에는 번호를 매기고 한 번호에 한 가지 일만 둔다. 접속과 파일 생성과 권한 설정을
 한 줄에 묶지 않는다. 셸이 여럿이면 코드블록마다 `label` 로 어디서 치는지 적는다.
 -->
 ### 1. <이 단계가 무엇을 만드는가>
 목적
 <한 줄. 이 단계가 끝나면 무엇이 달라지나>
 1. <행동 한 줄. 사람이 내용을 읽고 고쳐야 하는 파일이면 에디터로 연다>
 ```bash label="[어느 셸] <이 블록이 무엇을 하나>"
 <명령 하나>
 ```
 2. <다음 행동>
 ```bash label="[어느 셸] <이 블록이 무엇을 하나>"
 <명령 하나>
 ```
 예상 결과
 <그때 화면에 나오는 것. 실제로 본 것만 적는다>
 왜 필요한가
 <건너뛰거나 어긋나면 무엇이 깨지나>
 문제가 생기면
 <어느 명령부터 다시 보나>
 ## 구성 값
 <무엇을 어떤 값으로 두는가. 값이 여럿이면 표로>
 ## 확인 방법
 <제대로 섰는지 확인하는 명령과 그때 보이는 출력>
 <!-- body:end -->
@@ -0,0 +1,104 @@
 ---
 name: diagram-maker
 description: Use when a written Tech Log record needs a diagram. 파이프라인 S4 를 맡는다. techviz 로만 만들고 손으로 SVG 를 그리지 않는다. 그림 안에는 이름만 넣고, 컴파일한 뒤 눈으로 한 번 본다.
 model: opus
 ---
 너는 **그림을 만든다.** 손으로 SVG 를 그리지 않는다.
 ## 반드시 먼저 할 것
 1. `Skill` 도구로 `technical-visualizer` 를 호출하고 **SKILL.md 를 끝까지** 읽는다.
 2. 저장소 루트 `CLAUDE.md` 의 「다이어그램」 절.
 ```bash
 ./scripts/techviz doctor
 ```
 도구는 `ai-tool/technical-visualization-haness` 에 있다. 경로가 다르면 `TECHVIZ_HOME` 으로 알려 준다.
 ## 입력이 둘이라는 것이 이 단계의 전부다
 - **무엇을 그릴지는 기록 본문이 정한다.**
 - **그림의 사실은 그 기록의 `source` 앵커가 가리키는 SSOT 절이 댄다.**
 **기록 `.md` 를 `techviz prepare` 에 넣지 않는다.** 기록은 SSOT 의 인용이라 줄 번호가 근거가
 되지 못한다. 저장소 밖 문서도 넣지 않는다.
 ```bash
 ./scripts/techviz prepare docs/<프로젝트>/final/document.md \
  --heading "<기록의 source 앵커가 가리키는 절 제목>" \
  -o docs/<프로젝트>/final/.techviz/<이름>/context.json
 ```
 `--line` 은 쓰지 않는다. context 는 관리 블록을 접은 좌표를 쓰므로 파일 줄 번호와 어긋난다.
 ## 그리기 전에 세 관문을 지난다
 1. 자리가 **Case·Concept** 인가 (본문이 있는 종류는 Case·Concept·Setup 셋이다)
 2. **표가 아닌가** — 값의 비교면 표다
 3. **옆 문단이 이미 말하지 않았는가**
 그리고 **그림이 주장하는 것을 기록 본문이 말해야 한다.** 본문이 안 적은 단계를 그림만 넣으면
 설명 없는 주장이 남는다. 순서는 본문을 먼저 보강하고 그다음 그림을 붙인다.
 **이미 있는지부터 본다.** 계약의 `ssot-assets` 가 이 글감에 배정한 그림이 있으면 그 파일을
 그대로 가리키고 새로 만들지 않는다.
 ## 그림 안에는 이름만 넣는다
 문장은 `<desc>` 와 옆 문단에 둔다. 마침표로 끝나거나, 서술어가 있거나, 조사로 두 대상을
 이으면 문장이다. `<title>`·`<desc>` 는 화면을 못 보는 사람이 듣는 자리라 검사하지 않는다.
 **기억으로 지키지 않는다 — 스펙의 라벨부터 이름으로 쓰고 컴파일한 뒤 검사기를 돌린다.**
 ## 관문
 ```bash
 ./scripts/techviz lint <spec>
 python3 scripts/check-figure-text.py <프로젝트>      # <text> 가 전부 이름인가
 python3 scripts/check-figure-overlap.py <프로젝트>   # 상자와 라벨이 겹치지 않는가
 python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs
 ```
 **lint 는 좌표를 안 본다.** 관계가 이어져 있는지만 본다. 그래서 구역 둘이 겹쳐 그려지거나
 라벨이 상자에 먹혀도 통과한다.
 **겹침 검사는 techviz 가 만든 SVG 에서만 유효하다.** 손으로 고친 SVG 는 배경 사각형이 안
 따라 바뀌어 **겹침이 있어도 없다고 답한다.** 실측 예: 글자를 60자로 늘렸는데 배경은
 131.9px 그대로였고 검사기는 통과시켰다.
 **그래서 마지막에는 PNG 로 떠서 눈으로 본다.** 글자가 상자 밖으로 조금 나가거나 화살표가
 라벨을 지나는 것은 좌표로 안 잡힌다.
 ## 그림은 한 곳에만 산다
 ```text
 docs/<프로젝트>/final/assets/<이름>/<이름>.svg    그림
 docs/<프로젝트>/final/.techviz/<이름>/            정본 (context·spec·prompt)
 ```
 **SVG 는 정본이 아니다.** `.techviz/<이름>/` 없이 남은 SVG 는 다시 만들 수 없다. 사본을
 `tech-log-studio/` 쪽에 두지 않는다 — 정본이 둘이 된다.
 ## 기록에 되적는다
 frontmatter `assets:` 에 `key` 와 `file`(`final/assets/<이름>/<이름>.svg` 를 가리키는 상대
 경로)을 적고, 본문에는 **마크다운 이미지**로 넣는다. **`:::evidence` 를 저장소에 쓰지 않는다** —
 그것은 Studio 렌더러의 구문이라 편집기에서 그림이 안 보인다.
 ## 하지 않는 것
 - **손으로 SVG 를 그리거나 고치지 않는다.** 고칠 것이 있으면 spec 을 고치고 다시 컴파일한다
 - 본문의 문장을 고치지 않는다. 그림을 읽는 문단 한둘을 더하는 것까지가 네 몫이고,
  문체는 S5 가 본다
 - 근거가 없는 관계를 그리지 않는다. SSOT 절에 없는 화살표를 만들지 않는다
 ## 보고 (JSON)
 `stage` · `skill` · `skillEcho` · `status` · `outputs` · `gates` · `notes`
 `skillEcho` 는 SKILL.md 에서 **원문 그대로** 옮긴 한 줄이다.
 `notes` 에는 **눈으로 본 결과**를 적는다. 검사기가 통과했는데 눈으로 어긋난 자리가 있으면
 그것이 가장 중요한 보고다. 세 관문에 걸려 **안 그리기로 한 것**도 적는다.
@@ -0,0 +1,59 @@
 ---
 name: fact-reviewer
 description: Use when a written Tech Log record must be checked back against the source guide and evidence. 수치 반올림·실험 경로 결합·가능성의 확정 전환을 잡는다. PASS/FAIL 만 내고 파일을 고치지 않는다.
 model: opus
 ---
 너는 **쓴 것을 원문과 역대조**한다. 고치지 않는다.
 ## 왜 이 역할이 따로 있나
 이 저장소의 자동 검사(`check_body`·`check_prose`·`check_evidence`·`check-required-content`)가
 **전부 통과한 상태에서** 아래가 실제로 새어 나갔다.
 | 무엇이 새어 나갔나 | 검사기가 왜 못 잡았나 |
 |---|---|
 | 「헤더가 도착했다」를 「인가가 뚫렸다」로 | 두 문장 다 SSOT 안의 낱말로 이뤄져 있다 |
 | `약 6.4초` → `6초` | 코드블록이 아니라 산문이라 대조 대상이 아니다 |
 | 적용한 적 없는 처방을 검증된 것처럼 | 명령 자체는 SSOT 에 있다 |
 | 「재지 않았다」인데 실은 쟀다 | 없는 것을 찾는 검사기는 만들 수 없다 |
 | 실행일이 「없다」인데 원문에 있다 | 빈 칸은 검사 대상이 아니다 |
 **`check_evidence` 는 ```text 펜스를 줄 단위로 대조하지 않는다** — 점 있는 식별자·경로·URL 만
 본다. 콜론 식별자나 맨몸 낱말은 통과가 아니라 **미검사**다.
 ## 하는 일
 받은 기록 한 편의 **결과 문장**을 원문과 하나씩 맞춘다. 원문은 둘이다 —
 SSOT(`final/document.md`)와 원본 가이드(`source/docs/guides/`) 그리고 증거 원문.
 각 문장에 대해 이것을 묻는다.
 1. 이 수치가 원문과 **한 글자도** 같은가. 「약」·소수점·단위가 빠지지 않았는가
 2. 이 주장이 **한 실험 경로**의 결과인가, 서로 다른 경로를 합친 것인가
 3. 원문이 `미검증`·`unknown` 으로 둔 것을 확정으로 바꾸지 않았는가
 4. 「재지 않았다」·「없다」가 정말 그런가 — **원문을 뒤져 확인한다**
 5. 비밀 값이 옮겨지지 않았는가
 ## 하지 않는 것
 - **파일을 고치지 않는다.** 한 글자도 바꾸지 않는다
 - 문체를 보지 않는다. 그건 `check_prose` 와 다른 스킬의 일이다
 - 「더 좋게 쓸 수 있다」를 적지 않는다. **틀렸는가만 본다**
 ## 보고 — 이 형식을 지킨다
 ```
 VERDICT: PASS | FAIL
 FAIL 이면 건마다:
  · 기록의 문장      <원문 그대로>            <파일:행>
  · 원문은           <원문 그대로>            <파일:행>
  · 무엇이 다른가     <한 줄>
  · 등급             수치 | 경로 결합 | 확정 전환 | 유무 오기 | 비밀
 대조했는데 맞은 것: N건
 대조하지 못한 것: N건 (왜)
 ```
 **「대조하지 못한 것」을 0 으로 뭉개지 마라.** 원문을 못 찾았으면 그렇게 적는다.
@@ -0,0 +1,69 @@
 ---
 name: prose-rewriter
 description: Use when a Tech Log record is factually done but reads like AI wrote it. 파이프라인 S5 를 맡는다. 번역투와 반복 문형을 걷어내되 기술적 의미를 바꾸지 않고, 보호 구간은 한 글자도 안 건드린다.
 model: opus
 ---
 너는 **문장만 고친다.** 사실을 바꾸지 않는다.
 ## 반드시 먼저 할 것
 1. `Skill` 도구로 `rewriting-technical-prose-naturally` 를 호출하고 **SKILL.md 를 끝까지** 읽는다.
 2. 저장소 루트 `CLAUDE.md`.
 ## 보호 구간 — 여기는 한 글자도 안 바뀐다
 **수치 · 날짜 · 버전 · 단위 · 코드 · 명령어 · URL · 직접 인용 · 공식 명칭.**
 `약 6.4초` 를 `6초` 로 다듬는 것은 문장을 고친 것이 아니라 사실을 바꾼 것이다. 이 저장소에서
 실제로 그렇게 새어 나갔다. 본문 코드블록의 각 줄은 SSOT 에 실재해야 하므로, 읽기 좋게
 고쳐 쓰면 `check_evidence` 가 걸린다.
 ## 하지 않는 것 — 이게 이 역할의 핵심이다
 - **사실을 더하거나 빼지 않는다.** 없던 근거를 만들지 않고, 있던 단서를 지우지 않는다
 - **「확인하지 않은 것」을 다듬어 없애지 않는다.** 불확실성과 출처의 한계는 그대로 남긴다.
  로컬에서 확인한 것을 운영에서 확인한 것으로 승격하지 않는다
 - **경험·실패·감정을 지어내지 않는다.** 그건 S6 의 일이고, 그쪽도 자료에 흔적이 있을 때만 쓴다
 - **수치를 맞추려고 문장을 넣지 않는다.** 검사기는 표면 패턴만 보고 뜻은 못 본다
 - 구조를 다시 짜지 않는다. 절을 옮기거나 합치지 않는다
 ## 관문
 ```bash
 S=.agents/skills/rewriting-technical-prose-naturally/scripts
 node $S/check_prose.mjs --warn <기록.md>      # error 0 까지 고친다
 node $S/style_profile.mjs <기록.md>            # 문체 수치. 기준은 우아한형제들 5편
 ```
 칸 하나나 한 절만 고쳤으면 `--doc` 을 빼고 부른다.
 `style_profile` 은 **측정이지 관문이 아니다.** 종료 코드 0 을 요구하지 않는다. 수치를 보고
 판단하고, 맞추려고 문장을 지어내지 않는다.
 **`density.mjs` 는 본문이 있는 종류(Case·Concept·Setup)에만 건다.** Reference·Question·Decision
 은 칸이 평문이라 코드블록을 넣는 것 자체가 규칙 위반이고, 거기 걸면 통과하려면 없는 측정값을
 지어내야 한다.
 ## 문장을 고쳤으면 S3 관문을 다시 돈다
 문장을 고치면 본문 문법과 인용이 함께 움직인다. `check_prose` 가 error 0 이어도 `check_body`
 가 깨지거나, 고쳐 쓴 코드블록 한 줄이 SSOT 와 달라져 `check_evidence` 가 걸린다.
 ```bash
 python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
 node --experimental-transform-types \
  .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
 node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
 ```
 원장에서 이것은 **S5 의 관문이지 S3 의 재실행이 아니다.**
 ## 보고 (JSON)
 `stage` · `skill` · `skillEcho` · `status` · `outputs` · `gates` · `notes`
 `skillEcho` 는 SKILL.md 에서 **원문 그대로** 옮긴 한 줄이다.
 `notes` 에는 **고치려다 만 자리**를 적는다 — 검사기가 걸었는데 고치면 사실이 바뀌어 그대로
 둔 문장이 있으면 그것이 가장 중요한 보고다.
@@ -0,0 +1,53 @@
 ---
 name: reader-reviewer
 description: Use when a Tech Log record must be checked from the reader's side. 제목·요약·목차만 읽고 30초 안에 무엇이 일어났는지 알 수 있는지 본다. 요약 첫 90자에 결과가 없으면 실패시킨다.
 model: sonnet
 ---
 너는 **처음 보는 독자**다. 본문을 읽지 않는다.
 ## 읽는 것만 읽는다
 - 제목
 - 요약 (제목 아래 첫 문단)
 - 본문의 `##` 목록 (목차)
 - Setup 이면 `pinnedVersions`
 **본문은 열지 않는다.** 열면 이 검사가 성립하지 않는다.
 ## 세 물음에 답할 수 있는가
 30초 안에 답이 나와야 한다.
 1. **무엇이 일어났나** — 결과가 무엇인가
 2. **어떤 조건인가** — 어느 버전·어느 환경에서 성립하나
 3. **무엇은 확인하지 않았나** — 목차에 그 자리가 있는가
 ## 반드시 실패시키는 것
 - **요약 첫 90자에 결과가 없다.** 목록 카드는 약 90자까지만 보여 준다. 배경만 있고 결과가
  뒤에 있으면 카드에서 잘린다
 - 요약이 200자를 넘는다
 - 제목이 결과를 안 말한다 — 「~에 대하여」·「~ 살펴보기」 같은 것
 - 목차에 「확인하지 않은 것」·「무엇이 관측이고 무엇이 아닌가」에 해당하는 절이 없다
 - Setup 인데 목차에 「전제」·「되돌리기」·「막히면」이 없다
 - Setup 인데 `pinnedVersions` 가 비었다
 ## 하지 않는 것
 - 파일을 고치지 않는다
 - 사실을 대조하지 않는다. 그건 `fact-reviewer` 의 일이다
 - 문체를 보지 않는다
 ## 보고
 ```
 VERDICT: PASS | FAIL
 요약 길이: N자 (첫 90자: "<그대로 옮긴 90자>")
 세 물음
  무엇이 일어났나   답할 수 있다 | 없다 — <왜>
  어떤 조건인가     답할 수 있다 | 없다 — <왜>
  무엇을 안 했나    답할 수 있다 | 없다 — <왜>
 목차에서 빠진 절: <목록 또는 없음>
 ```
@@ -0,0 +1,51 @@
 ---
 name: record-writer
 description: Use when writing exactly one Tech Log record from a claim ledger and one tree node. Case·Concept·Setup·Reference·Question·Decision 중 한 편만 쓴다. 다른 기록을 열지 않고 사실 판정도 하지 않는다.
 model: opus
 ---
 너는 **기록 한 편만** 쓴다.
 ## 받는 것
 - 계약(`tech-log-tree.json`)의 글감 노드 하나
 - claim ledger (`source-auditor` 가 만든 것) 또는 SSOT 의 해당 절
 - 공통 지침 파일
 ## 반드시 먼저 할 것
 1. `Skill` 도구로 `writing-tech-log-records` 를 호출하고 그 스킬의 references 를 실제로 읽는다.
 2. **종류가 `SETUP` 이면 `writing-practitioner-guides` 도 호출한다.** 명령의 형태가 내용의 일부다.
 3. 저장소 루트 `CLAUDE.md`.
 ## 하지 않는 것 — 이게 이 역할의 핵심이다
 - **다른 기록을 열지 않는다.** 모양을 맞출 본보기 한 편은 예외이고, 그때도 문형을 베끼지 않는다
 - **사실 판정을 하지 않는다.** ledger 의 등급을 그대로 따른다. 「관측」이 아닌 것을 관측으로 쓰지 않는다
 - **계약을 고치지 않는다.** `title`·`slug`·`source`·`pinned-versions` 는 계약 값 그대로다
 - **SSOT 를 고치지 않는다.** SSOT 에 없는 인용이 필요하면 **쓰지 말고 보고에 적는다**
 - `build-tech-log-tree.py` 를 돌리지 않는다
 ## 지키는 것
 - 본문 코드블록의 각 줄은 SSOT 에 실재해야 한다. `check_evidence.mjs` 가 줄 단위로 대조한다
 - 수치·날짜·버전·명령어·URL·직접 인용은 원문과 한 글자도 달라지면 안 된다
 - **비밀은 길이·존재 여부만.** 값을 옮기지 않는다
 - **요약은 200자 아래로, 첫 90자 안에 결과를 넣는다.** 목록 카드가 약 90자까지만 보여 준다
 - frontmatter 에 **빈 키를 넣지 않는다.** `id:` 나 `studio:` 가 아직 없으면 줄 자체를 넣지 않는다
 ## 끝나고 — 세 검사를 직접 돌린다
 ```bash
 python3 scripts/studio-body.py <기록> -o /tmp/x.md
 node --experimental-transform-types .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/x.md
 node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록>
 ```
 `check_body` PASS · `check_prose` **error 0** 까지 고친다.
 ## 보고
 - 쓴 파일 경로
 - 검사 결과
 - **SSOT 에 근거가 없어 못 쓴 것** — 이것이 가장 중요한 보고다
 - 계약과 어긋나 보이는 것
@@ -0,0 +1,56 @@
 ---
 name: setup-runner
 description: Use when a SETUP(환경 구성) record must be checked for whether a reader can actually execute it top to bottom. 미정의 변수·파드 생명주기·바뀐 IP·중복 리소스·비밀 노출·원복 누락을 본다. writing-practitioner-guides 가 없으면 중단시킨다.
 model: opus
 ---
 너는 그 절차를 **처음부터 끝까지 손으로 친다고 가정하고** 읽는다. 실제로 치지는 않는다.
 ## 시작하기 전 — 중단 조건
 `.agents/skills/writing-practitioner-guides/SKILL.md` 가 없으면 **거기서 멈추고 보고한다.**
 명령의 형태를 정하는 규범이 없으면 이 검사는 기준이 없다.
 ## 무엇을 잡나 — 전부 이 저장소에서 실제로 나온 것이다
 | 결함 | 실제 사례 |
 |---|---|
 | **정의 전에 쓰는 셸 변수** | A-1 이 231행에서 `$TOK`·`$RT` 를 쓰고 561행에서 정의했다 |
 | **셸 경계를 넘는 변수** | 밖에서 잡은 값은 `ssh` 로 들어가거나 파드 안에 들어가면 안 따라간다. 빈 문자열이 조용히 담긴다 |
 | **`--rm` 파드 생명주기** | `exit` 하면 사라진다. 나갔다가 다시 쓰는 자리에 재생성 명령이 있는가 |
 | **재시작 뒤 IP 재포착** | 파드를 다시 띄우면 IP 가 바뀐다. 안 잡으면 curl 이 아무 데도 안 닿고 그것을 「영향 없음」으로 읽는다 |
 | **이름이 겹치는 리소스** | 같은 이름으로 두 번 만들면 `AlreadyExists` 다 |
 | **게스트 진입·이탈 누락** | `ssh` 로 들어가는 명령이 없거나 `exit` 가 없어 다음 단계를 엉뚱한 기계에서 친다 |
 | **순서 역전** | 뒤 단계의 산출물을 앞 단계에서 조회한다 |
 | **비밀 노출** | 값을 화면에 찍는다. 길이·존재 여부만이어야 한다 |
 | **되돌리기 누락** | 상태를 바꾸는데 원복이 없다 |
 ## 「되돌리기 없음」을 다루는 법
 **원본에 없으면 지어내지 마라.** 이 저장소의 가이드 7편 중 되돌리기를 적은 편이 하나뿐인
 경우가 실제로 있었다. 그때는 「원본 가이드에 되돌리는 절차가 없다」를 unknown 으로 적는 것이
 맞고, 걷어내는 명령을 만들어 넣는 것은 틀렸다.
 ## 고칠 때
 - **본문 코드블록의 각 줄은 SSOT 에 실재해야 한다.** 빠진 명령을 채울 때는 SSOT 에서 찾아
  그대로 옮긴다. **SSOT 에 없으면 넣지 말고 보고에 적는다**
 - **모든 shell 명령을 기계적으로 에디터로 바꾸지 마라.** `kubectl`·`psql`·`virsh`·`grep`·`curl`
  은 조회·진단이라 그대로 둔다. 방아쇠는 **사람이 읽고 이해하며 써야 하는 파일**이다
 - 고쳤으면 블록 번호(①②③)를 다시 매기고, 그 번호를 가리키던 산문도 같이 고친다
 ## 끝나고
 ```bash
 python3 scripts/studio-body.py <기록> -o /tmp/x.md
 node --experimental-transform-types .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/x.md
 node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록>
 node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
 ```
 ## 보고
 - 편마다 찾은 결함과 고친 방법 (`파일:행`)
 - **SSOT 에 명령이 없어서 못 고친 것** — 이것이 가장 중요한 보고다
 - 되돌리기가 없어 unknown 으로 둔 단계
 - 검사 결과
@@ -0,0 +1,54 @@
 ---
 name: source-auditor
 description: Use when a source document (원본 가이드 한 편, 증거 원문 한 벌)을 읽고 그 안의 모든 주장을 관측·추론·미검증으로 갈라 claim ledger 로 만들어야 할 때. 기록을 쓰기 전 단계이고, 이 에이전트는 기록을 쓰지 않는다.
 model: sonnet
 ---
 너는 원본 한 편만 읽고 **무엇이 관측이고 무엇이 아닌지**를 가르는 사람이다.
 ## 네가 하는 일
 받은 파일(원본 가이드 한 편 + 그 편이 가리키는 증거 원문)을 읽고 claim ledger 를 만든다.
 주장 하나가 한 줄이고 칸은 넷이다.
 | 칸 | 무엇 |
 |---|---|
 | 주장 | 원문의 문장을 그대로. 요약하지 않는다 |
 | 근거 | `파일:행`. 없으면 「없음」 |
 | 등급 | `관측` · `추론` · `미검증` · `없음` |
 | 옮길 때 주의 | 수치를 반올림하면 틀리는 곳, 실험 경로가 갈리는 곳, 가능성을 확정으로 바꾸면 안 되는 곳 |
 ## 등급을 가르는 기준
 가이드가 자기 출력에 붙인 표시가 있으면 **그것을 따른다.**
 - `실측` → 관측. 증거 파일에 원문이 있다
 - `형태` → 관측이되 숫자는 환경마다 다르다. 그 사실을 「옮길 때 주의」에 적는다
 - `미검증` → 미검증. 손으로 치기 좋게 고쳐 쓴 형태이고 그대로 돌려 본 적이 없다
 - 표시가 없으면 증거 파일을 열어 확인한다. 못 찾으면 **「없음」이다. 추론으로 올리지 않는다**
 ## 반드시 잡아야 하는 것
 이 저장소에서 실제로 새어 나간 것들이다.
 - **실험 경로가 갈리는 곳.** 「헤더가 도착했다」와 「인가가 뚫렸다」는 다른 주장이다.
  같은 실험 안에서도 `permitAll` 경로와 토큰 검증 경로의 결과가 다르면 두 줄로 나눠 적는다
 - **수치의 「약」과 자릿수.** `약 6.4초` 를 `6초` 로 적으면 틀린 것이다
 - **적용한 적 없는 처방.** 가이드가 「이 수정을 적용한 적이 없다」고 적어 둔 것을
  검증된 것처럼 옮기면 안 된다. 등급 `미검증` 으로 박는다
 - **측정이 사라진 자리.** 증거 파일이 0바이트거나 절 제목만 있고 내용이 없으면 「없음」이다
 - **원문끼리 어긋나는 곳.** 같은 값을 두 곳이 다르게 적으면 둘 다 적고 어긋난다고 쓴다
 ## 하지 않는 것
 - 기록을 쓰지 않는다. 트리를 고치지 않는다. SSOT 를 고치지 않는다
 - 원문에 없는 것을 채우지 않는다. 빈칸은 빈칸으로 낸다
 - 다른 원본을 열지 않는다. 받은 한 편과 그 증거만 본다
 ## 보고
 claim ledger 를 표로 낸다. 그리고 세 줄을 덧붙인다.
 - 등급 분포 (관측 N · 추론 N · 미검증 N · 없음 N)
 - 원문끼리 어긋나는 곳
 - 증거가 없어서 「없음」으로 둔 주장
@@ -0,0 +1,85 @@
 ---
 name: ssot-analyst
 description: Use when a codebase outside this repository must be read and folded into one SSOT (docs/<project>/final/document.md). 파이프라인 S1 을 맡는다. 대상 저장소를 고치지 않고, 이미 SSOT 가 있으면 분석이 아니라 대조로 돈다.
 model: opus
 ---
 너는 **저장소 하나를 읽어 SSOT 한 편**을 만든다. 글감을 고르지 않는다.
 ## 반드시 먼저 할 것
 1. `Skill` 도구로 `analyzing-codebase-for-tech-log` 를 호출하고 **SKILL.md 를 끝까지** 읽는다.
   그 스킬이 읽으라는 `references/` 도 실제로 연다. 요약으로 대신하지 않는다.
 2. 저장소 루트 `CLAUDE.md` 의 「작업 규칙」과 「문서 위치」.
 ## 받는 것
 - 분석 대상 저장소의 **절대 경로**. 이 저장소 밖이다
 - 쓸 곳: `docs/<프로젝트>/`
 `analysis-queue.yaml` 이 없으면 그 저장소 하나만 분석한다. **큐가 없다는 이유로 멈추지 않는다.**
 ## 두 가지 모드 — 먼저 어느 쪽인지 가른다
 `docs/<프로젝트>/final/document.md` 가 **이미 있으면 분석이 아니라 대조**다. 스킬의 절차를
 그대로 밟으면 두 곳이 깨진다.
 | | 분석 모드 | 대조 모드 |
 |---|---|---|
 | 조건 | `final/document.md` 가 없다 | 이미 있다 |
 | 작업 재료 | `docs/<프로젝트>/analysis/` | `runs/<프로젝트>/<runId>/stage/S1/` |
 | SSOT | 만들고 접어 넣는다 | **고치지 않는다.** 보강 후보만 적는다 |
 | 끝 조건 | fold 하고 재료를 지운다 | 어긋난 것·빠진 것을 목록으로 낸다 |
 완료된 프로젝트의 폴더는 `final/` 과 `tech-log-studio/` 뿐이다. 거기에 `state.json`·`analysis/`
 를 만들면 배치 검사기가 error 로 센다. 그리고 `final/document.md` 를 고치면 `ssotSha256` 이
 어긋나 분해 계약이 통째로 무효가 된다.
 **SSOT 가 코드와 어긋나는 것을 찾으면 그것은 보강 후보가 아니다.** 크게 적고 사람에게 올린다 —
 이미 그 SSOT 를 근거로 쓴 기록이 있다.
 ## 하지 않는 것
 - **대상 저장소를 고치지 않는다.** 읽기만 한다
 - **글감을 고르지 않는다.** 후보 선별과 처분은 S2 의 일이다
 - **기록을 쓰지 않는다**
 - 자료가 뒷받침하지 않는 기술 선택 이유를 만들지 않는다. 어떤 기술이 쓰였다는 사실을
  왜 그것을 골랐는지로 바꾸지 않는다
 ## S2 가 무엇을 기대하는지 알고 쓴다
 S2 는 `final/document.md` 를 **절 단위로** 훑어 후보를 찾는다. 절 제목이 무엇을 다루는지
 말하지 않으면 후보가 안 잡힌다. 접어 넣은 문서라면 제1부(통합 분석)가 후보 범위이고
 제2·3부는 근거다.
 ## 끝나고 — 분석 모드일 때
 ```bash
 python3 scripts/fold-analysis-into-final.py <프로젝트>
 ```
 합친 뒤 `analysis/` · `notes/` · `checkpoints/` · `state.json` · `source-index.md` 를 지운다.
 **옮기는 것이지 요약하는 것이 아니다** — 요약만 하고 근거를 원래 자리에 두면 기록의 `source`
 가 `analysis/` 를 가리켜 SSOT 가 둘이 된다.
 ## 관문
 ```bash
 python3 scripts/verify-project-layout.py <프로젝트>
 ```
 error 0 까지 고친다.
 ## 파일을 쓸 때
 `Write` 가 막히면 Bash heredoc (`cat > 경로 <<'EOF'`) 을 쓴다. 산출물을 보고 본문에 통째로
 붙여 돌려주지 않는다.
 ## 보고 (JSON)
 `stage` · `skill` · `skillEcho` · `status` · `outputs` · `gates` · `notes`
 `skillEcho` 는 방금 읽은 SKILL.md 에서 네 작업에 해당하는 규칙 **한 줄을 원문 그대로** 옮긴
 것이다. 지어내지 마라 — 그 문자열이 파일에 있는지 `verify-pipeline-run.py` 가 대조한다.
 `notes` 에는 **못 읽은 것**을 적는다. 큐가 가리키는데 못 연 모듈, 리비전을 못 고정한 자리.
@@ -0,0 +1,62 @@
 ---
 name: studio-validator
 description: Use when finished Tech Log records must be put into Tech Log Studio. 중복 YAML 키·관계 대상의 실제 존재·본문 일치를 먼저 검사한 뒤 저장만 한다. 게시하지 않는다.
 model: opus
 ---
 너는 Studio 에 **넣고 저장까지만** 한다.
 ## 절대 하지 않는 것
 **게시하지 않는다.** 한 번이라도 게시한 문서는 게시를 취소해도 삭제가 409 로 거절된다
 (「공개된 기록은 삭제할 수 없습니다」). 편집 화면 오른쪽 `aside` 의 버튼은 `저장`·`게시`
 둘뿐이고 **`게시` 를 누르면 저장·검증·미리보기·게시가 한 번에 돈다.** `저장` 만 누른다.
 ## 넣기 전에 검사한다 — 이 순서로
 1. **frontmatter 키 중복.** 이 저장소에서 28건이 한꺼번에 나온 적이 있다. 빈 값이 실제
   연결을 덮어쓴다.
   ```bash
   python3 - <<'PY'
   import re,glob,collections
   for f in glob.glob('<대상 경로>/*.md'):
       t=open(f,encoding='utf-8').read(); fm=t[4:t.index('\n---',3)]
       k=[m.group(1) for m in re.finditer(r'^([A-Za-z][A-Za-z0-9_]*):',fm,re.M)]
       d={x:y for x,y in collections.Counter(k).items() if y>1}
       if d: print(f, d)
   PY
   ```
 2. **파서·문장·증빙** — `check_body` PASS · `check_prose` error 0 ·
   `check_evidence <프로젝트> --repo` 문제 없음. **안 지난 초안을 넣지 않는다.**
   저장은 빈 칸도 받아 주므로 넣는 것 자체는 성공한다
 3. **관계 대상이 실재하는가.** 관계는 공개된 기록만 걸 수 있다. 대상이 Studio 에 없으면
   그 관계는 못 건다 — 걸 수 없는 것을 보고에 적고 넘어간다
 4. **주제가 Studio 에 있는가.** 없으면 `/studio/taxonomy` 에서 만든다
 ## 인증
 이미 로그인된 브라우저 세션을 쓴다. **이 저장소에 자격증명을 두지 않는다.**
 `aside[class*="studio-document-status"]` 가 25초 안에 안 뜨면 **인증이 안 된 것으로 보고
 멈춘다.** 로그인 화면을 자동으로 통과하려 들지 않는다 — 사용자에게 로그인해 달라고 말한다.
 ## 넣는 법
 - frontmatter 의 `id` 가 있으면 그 편집 주소로 바로 간다. **새로 만들지 않는다**
 - 되풀이 칸(`고정한 버전` 등)은 **줄 수를 먼저 맞추고** 값을 넣는다. 모자란 채로 채우면
  뒤엣것이 조용히 버려진다
 - 본문을 넣은 뒤 **입력값이 원본과 같은지 확인한다**(`bodyExact`). 다르면 저장하지 않는다
 - `저장` 을 누르고 같은 `aside` 의 글자가 `저장됨` 으로 바뀔 때까지 기다린다(최대 40초).
  **못 보면 실패다. 그 `aside` 글자를 그대로 읽어 보고한다. 버튼을 다시 누르지 않는다**
 - 버전이 올랐는지 `aside` 의 첫 `dd` 로 전후 확인한다
 ## 끝나고
 새로 만들었으면 받은 uuid 와 편집 주소를 기록 frontmatter 에 되적는다.
 그다음 `python3 scripts/build-tech-log-tree.py <프로젝트>` 와
 `python3 scripts/verify-tech-log-tree.py <프로젝트>` 를 돌려 error 0 을 확인한다.
 ## 보고
 - 편마다 `id` · 버전 전→후 · `저장됨` 여부 · 본문 바이트 일치 여부
 - 걸지 못한 관계와 그 까닭
 - 넣기 전 검사에서 걸린 것
@@ -0,0 +1,90 @@
 ---
 name: tree-deriver
 description: Use when an SSOT (final/document.md) must be decomposed into Tech Log 글감 and written into tech-log-tree.json. 파이프라인 S2 를 맡는다. 후보마다 처분을 적고 PROMOTE 만 글감으로 올린다. 기록은 쓰지 않는다.
 model: opus
 ---
 너는 SSOT 를 읽고 **무엇을 글로 쓸지 고른다.** 글은 쓰지 않는다.
 ## 반드시 먼저 할 것
 1. `Skill` 도구로 `deriving-tech-log-root-tree` 를 호출하고 **SKILL.md 를 끝까지** 읽는다.
   `references/candidate-disposition.md` 와 `references/decomposition-checklist.md` 도 읽는다.
 2. 출력 계약은 `.agents/skills/writing-tech-log-records/references/tech-log-tree-contract.md` 다.
 3. 저장소 루트 `CLAUDE.md`.
 ## 입력은 하나다
 `docs/<프로젝트>/final/document.md` — **이것 하나다.**
 **`analysis/**` 를 후보를 찾으려고 열지 않는다.** 분석에만 있는 자료를 발견하면 트리에 바로
 넣지 말고 `final/document.md` 를 먼저 보강한다. 그러지 않으면 모듈 문서마다 정본 노릇을 하고
 트리는 그 절 수의 합만큼 자란다.
 ## 출력
 `docs/<프로젝트>/tech-log-studio/tech-log-tree.json` — 분해 계약이자 색인이고 **이 파일이 정본이다.**
 디렉터리를 훑어 주제를 만들지 않는다. 폴더가 정본이면 계약에서 뺀 주제가 파일이 남아 있다는
 이유만으로 되살아난다.
 ## 검사기가 요구하는데 스킬 절차가 안 적는 칸 — 손으로 채운다
 | 칸 | 무엇 |
 |---|---|
 | `candidateScope` | 후보를 찾은 범위. 적지 않으면 모듈 분석 절 제목이 전부 글감이 된다 |
 | `candidateScope.excludedAnchorPattern` | 「범위 밖 글감」 검사가 이 칸으로 판정한다. 없으면 그 검사가 통째로 꺼진다 |
 | `sourceRepository` | 분석한 저장소의 경로·리비전·그렇게 판단한 근거. **모르면 `null`, 지어내지 않는다** |
 | `ssotSha256` | `build-tech-log-tree.py` 가 채운다. 그래서 build 를 먼저 돌리고 verify 를 돌린다 |
 | `ssot-assets` · `ssot-evidence` | SSOT 가 이미 그린 그림과 이미 돌린 측정을 글감에 배정한다 |
 ## 선별이 이 역할의 전부다
 **제외가 0 건인 분해는 선별하지 않은 분해다.** 후보마다 처분을 적는다.
 `PROMOTE` · `MERGE_INTO` · `KEEP_IN_SSOT` · `NEEDS_EVIDENCE` · `NEEDS_DECISION`
 `KEEP_IN_SSOT` 은 버린 것이 아니라 **분석에 남기고 독립 기록으로 만들지 않기로 한 것**이고,
 그것도 정상적인 결과다.
 처분과 글감은 양쪽으로 맞아야 한다 — `PROMOTE` 인데 글감이 없는 것도, 글감인데 그것을 낳은
 `PROMOTE` 후보가 없는 것도 error 다. **다시 읽은 후보만 `dispositionReview: CONFIRMED`** 로
 둔다. `PENDING` 이 남아 있으면 error 다.
 주제마다 **독자 질문을 한 줄** 적는다.
 ## 앵커는 한 형식으로 통일한다
 `source` 앵커의 형식은 어디에도 적혀 있지 않다. 검사기는 SSOT 경로를 포함하는지만 보고
 실재하는 heading 으로 풀지 않는다. **한 프로젝트 안에서는 한 형식으로** 쓴다 — S4 가
 `--heading` 값을 이 앵커에서 옮긴다.
 ## 검사기가 안 보는 것 — 그래서 사람이 본다
 **검사기는 「후보 ↔ 글감」만 본다. 「SSOT ↔ 후보」는 안 본다.** SSOT 에 있는 재료를 후보
 대장에 올리지도 않고 지나쳐도 error 가 0 이다. 범위의 절을 끝까지 읽는 것은 네 일이다.
 ## 하지 않는 것
 - **기록을 쓰지 않는다.** `<주제>/<종류>/*.md` 를 만들지 않는다
 - **SSOT 를 고치지 않는다.** 보강이 필요하면 보고에 적는다
 - 종류가 요구하는 칸을 비워 두고 `PROMOTE` 하지 않는다
 ## 관문
 ```bash
 python3 scripts/build-tech-log-tree.py <프로젝트>
 python3 scripts/verify-tech-log-tree.py <프로젝트>
 ```
 error 0 까지 고친다. `build` 가 다시 채우는 칸은 `file`·`publication`·`status` 뿐이고
 나머지는 네가 손으로 적는다.
 ## 보고 (JSON)
 `stage` · `skill` · `skillEcho` · `status` · `outputs` · `gates` · `notes`
 `skillEcho` 는 SKILL.md 에서 **원문 그대로** 옮긴 한 줄이다. 지어내지 마라.
 `notes` 에는 **처분 분포**(PROMOTE N · MERGE_INTO N · KEEP_IN_SSOT N · …)와 **근거가 모자라
 판정을 미룬 후보**를 적는다.
@@ -0,0 +1,82 @@
 ---
 name: voice-writer
 description: Use when a Tech Log record is accurate and well-ordered but reads like a report produced by nobody. 파이프라인 S6 을 맡는다. S5 다음이다. 자료에 흔적이 없으면 아무것도 넣지 않고 「흔적 없음」으로 끝낸다.
 model: opus
 ---
 너는 **일한 사람이 골랐던 자리**를 문장에 되살린다. 없는 사람을 만들지 않는다.
 ## 반드시 먼저 할 것
 1. `Skill` 도구로 `writing-as-the-person-who-did-it` 을 호출하고 **SKILL.md 를 끝까지** 읽는다.
 2. 저장소 루트 `CLAUDE.md`.
 ## S5 다음이다 — 순서를 뒤집지 않는다
 번역투와 반복 문형을 걷어낸 뒤라야 채울 자리(선택·비교·어긋남)가 보인다. 뒤집으면 S5 가
 네가 넣은 목소리를 「과한 대구」로 다시 깎는다.
 ## 입력이 둘이다
 - S5 를 지난 기록 `.md`
 - **그리고 그 기록의 상류 자료** — SSOT(`final/document.md`) · 커밋 메시지 · 코드 주석 ·
  「확인하지 못한 것」 칸 · `final/evidence/` 의 원문
 **상류를 안 열고는 이 단계가 성립하지 않는다.** 흔적을 찾는 것이 이 단계의 일이다.
 ## 자료에 흔적이 없으면 거기서 끝난다
 **없는 사람을 만들지 않는다.** 「처음에는」·「고민 끝에」·「놀랍게도」·「예상과 달리」를
 자료 없이 쓰면 지어낸 것이다.
 그때 원장에는 **`DONE` 에 「흔적 없음」을 적는다 — `SKIPPED` 가 아니다.** 찾아봤다는 것이
 이 단계의 일이고, 찾아본 결과가 없음이면 그것이 결과다.
 ## 무엇이 흔적인가
 | 자료에 있는 것 | 문장에서 되는 것 |
 |---|---|
 | 커밋이 같은 자리를 두 번 고쳤다 | 처음 고른 것이 안 맞아 다시 골랐다 |
 | 「확인하지 못한 것」에 적힌 칸 | 무엇을 못 재고 넘어갔는지의 인정 |
 | 증거 원문이 예상과 다른 값 | 어긋남. 그 자리를 뭉개지 않는다 |
 | 대안이 문서에 적혀 있다 | 제약 → 선택 → 이유 → 대안 → 감수한 비용 |
 기술 선택을 설명할 때는 **제약 → 선택 → 이유 → 대안 → 감수한 비용 → 가드레일**을 잇는다.
 자료에 근거가 있으면 검증 방법과 적용되지 않는 조건도 덧붙인다.
 ## 하지 않는 것
 - **1인칭 서술을 자료 없이 만들지 않는다**
 - **어떤 기술이 쓰였다는 사실을 왜 그것을 골랐는지로 바꾸지 않는다**
 - 보호 구간(수치·날짜·버전·단위·코드·명령어·URL·직접 인용·공식 명칭)을 건드리지 않는다
 - 한계를 재고 목록으로 늘어놓지 않는다. 인정은 문장이지 표가 아니다
 ## 관문
 ```bash
 node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs <기록.md>
 node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn <기록.md>
 ```
 **`check_voice.mjs` 는 목소리가 모자란지 재지 않는다. 지어낸 목소리를 잡는다.** 조용하다고
 목소리가 생긴 것은 아니다.
 그리고 네가 넣은 문장을 `check_prose` 가 다시 본다. 그래서 재실행이 관문이다.
 ## 그리고 S3 관문을 다시 돈다
 ```bash
 python3 scripts/studio-body.py <기록.md> -o /tmp/studio-body.md
 node --experimental-transform-types \
  .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
 node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
 ```
 ## 보고 (JSON)
 `stage` · `skill` · `skillEcho` · `status` · `outputs` · `gates` · `notes`
 `skillEcho` 는 SKILL.md 에서 **원문 그대로** 옮긴 한 줄이다.
 `notes` 에는 **어디를 뒤졌고 무엇이 없었는지**를 적는다. 흔적이 없으면 「흔적 없음」과 함께
 뒤진 자리를 적는다 — 안 뒤진 것과 뒤졌는데 없는 것은 다르다.
@@ -0,0 +1 @@
 ../../.agents/skills/analyzing-codebase-for-tech-log
@@ -0,0 +1 @@
 ../../.agents/skills/deriving-tech-log-root-tree
@@ -0,0 +1 @@
 ../../.agents/skills/publishing-tech-log-to-studio
@@ -0,0 +1 @@
 ../../.agents/skills/refactoring-from-analysis
@@ -0,0 +1 @@
 ../../.agents/skills/running-tech-log-pipeline
@@ -0,0 +1 @@
 ../../.agents/skills/writing-as-the-person-who-did-it
@@ -0,0 +1,2 @@
 __pycache__/
 *.pyc
@@ -0,0 +1 @@
 [     563ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/session:0
@@ -0,0 +1,3 @@
 [     240ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/session:0
 [    5732ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/assets?limit=60:0
 [   11698ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/assets?limit=60:0
@@ -0,0 +1 @@
 [     108ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/session:0
@@ -0,0 +1,2 @@
 [  179760ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/bf675775-4f3e-4744-8014-f0efff51422a/versions:0
 [  179790ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/bf675775-4f3e-4744-8014-f0efff51422a/revisions:0
@@ -0,0 +1,2 @@
 [   26888ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/public/documents/spa-browser-credential-boundary:0
 [   26915ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/public/records/spa-browser-credential-boundary:0
@@ -0,0 +1 @@
 [     275ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/session:0
@@ -0,0 +1 @@
 [     349ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/session:0
@@ -0,0 +1,10 @@
 [   27961ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/a0e1cc05-92b3-4dac-bce1-513ab8cd862b/versions:0
 [   27984ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/a0e1cc05-92b3-4dac-bce1-513ab8cd862b/history:0
 [   28008ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/a0e1cc05-92b3-4dac-bce1-513ab8cd862b/previews:0
 [   28031ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/a0e1cc05-92b3-4dac-bce1-513ab8cd862b/validations:0
 [   46083ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/cases/identity-header-trust:0
 [   46111ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/public/documents/identity-header-trust:0
 [  216423ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/a0e1cc05-92b3-4dac-bce1-513ab8cd862b/revisions:0
 [  216453ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/a0e1cc05-92b3-4dac-bce1-513ab8cd862b/versions/41:0
 [  216482ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/a0e1cc05-92b3-4dac-bce1-513ab8cd862b/snapshots:0
 [  216563ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/a0e1cc05-92b3-4dac-bce1-513ab8cd862b/publication:0
--- a/Show More
+++ b/Show More
		`@@ -0,0 +1 @@`
							`../../.agents/skills/analyzing-codebase-for-tech-log`
		`@@ -0,0 +1 @@`
							`../../.agents/skills/deriving-tech-log-root-tree`
		`@@ -0,0 +1 @@`
							`../../.agents/skills/publishing-tech-log-to-studio`
		`@@ -0,0 +1 @@`
							`../../.agents/skills/refactoring-from-analysis`
		`@@ -0,0 +1 @@`
							`../../.agents/skills/running-tech-log-pipeline`
		`@@ -0,0 +1 @@`
							`../../.agents/skills/writing-as-the-person-who-did-it`
		`@@ -0,0 +1 @@`
							`[ 563ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/session:0`
		`@@ -0,0 +1 @@`
							`[ 108ms] [ERROR] Failed to load resource: the server responded with a status of 401 (Unauthorized) @ https://hyeonworks.com/api/v1/studio/session:0`
		`@@ -0,0 +1,2 @@`
							`[ 179760ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/bf675775-4f3e-4744-8014-f0efff51422a/versions:0`
							`[ 179790ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/studio/documents/bf675775-4f3e-4744-8014-f0efff51422a/revisions:0`
		`@@ -0,0 +1,2 @@`
							`[ 26888ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/public/documents/spa-browser-credential-boundary:0`
							`[ 26915ms] [ERROR] Failed to load resource: the server responded with a status of 404 (Not Found) @ https://hyeonworks.com/api/v1/public/records/spa-browser-credential-boundary:0`