Files

T

DongHyeonkaandClaude Opus 5 1f04117bbf docs(clean-architecture-backend-template): 제1부가 채택한 것만 글감으로 남기고 다시 고른다

글감 1,001개 중 제1부(§3~§11) 앵커를 하나라도 가진 것은 112개뿐이었다. 나머지 889개는
제2부 모듈 분석 65편의 절 제목에서 나온 것이고, 그것이 재판정이 필요했던 이유다.

  주제      44 → 16   (43개가 독자 질문 없이 있었다. 지금은 전부 있다)
  글감   1,001 → 123  (제1부 앵커 112 + 제1부가 채택했는데 비어 있던 자리 11)
  후보      965 → 1,088 · PENDING 905 → 0
  error   3,042 → 0

내려온 889개는 후보 대장에 KEEP_IN_SSOT 로 남는다 — 버린 것이 아니라 분석에 남기고 독립
기록으로 만들지 않기로 한 것이다. 그 글감을 받치던 기록 파일 828개는 지웠다. 계약이 정본이고,
파일이 남아 있다는 이유로 계약에서 뺀 주제가 되살아나면 안 된다. 이력에는 그대로 있다 —
git checkout a0ca2bb -- <경로>.

제1부가 채택했는데 글감이 없던 자리 열하나를 채웠다: mongo high-water mark 가 재전달 이벤트를
삼킨 P1, admin plane 이 가드만 켜고 서비스는 켜지 않은 것과 그 짝인 결정, 실패 어휘 세 층과
SQLState 매트릭스 병합 규칙, 부하 아래에서만 새는 admission 경계, 발행 증거와 완료 판정의
분리, keyset·JSONB 결정 둘.

Concept 17개에 basis-version 을 채우고, 계약 제목과 기록 제목이 갈라져 있던 23건을 기록 쪽에
맞췄다. candidateScope 에 excludedAnchorPattern 을 적어 제2부 앵커만 가진 글감이 다시 올라올
수 없게 한다.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-07 15:02:25 +09:00

10 KiB

Raw Blame History

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.

"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.

Topics

Each Topic has topic (its key), title, readerQuestion, and kinds with the five record kinds.

"oauth-oidc-auth-boundary": {
  "topic": "oauth-oidc-auth-boundary",
  "title": "OAuth 자격증명과 세션의 보관 경계",
  "readerQuestion": "자격증명과 세션을 누가 보관하고, 누가 API 요청을 만들며, 보호 자원은 무엇을 신뢰하는가?",
  "kinds": { "case": [], "concept": [], "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 five.

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.

"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.

"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.

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

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.
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.
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.
Take Cases, References, Decisions, and Questions first; add Concepts backwards from what those four require.
Prefer several narrowly grounded Cases over one broad Case combining unrelated incidents — but merge observations that share a question and a conclusion.
Extract Decisions only from explicit choice evidence: ADR, commit/history, configuration plus recorded rationale, issue/PR decision, or a user-supplied decision record.
A node may relate to several siblings, but each record has one primary purpose.
If new runtime evidence changes the answer, update the analysis and revise the tree before editing downstream records.

Generation and verification

python3 scripts/build-tech-log-tree.py <project>    # 파생 칸을 다시 채운다
python3 scripts/verify-tech-log-tree.py <project>   # error 0 이어야 한다

10 KiB Raw Blame History