DongHyeonkaandClaude Opus 5
ab59130196
이번 파이프라인 작업과 무관하게 작업 트리에 남아 있던 것을 그대로 올린다. 사용자가 「전부 커밋」으로 정했고, 이번 작업과 섞이지 않게 커밋만 나눴다. 대부분은 clean-architecture-backend-template 의 그림 정본 재배치다 — final/assets/diagrams/<이름>/ 에 있던 것이 CLAUDE.md 가 적은 배치인 final/assets/<이름>/ 로 옮겨졌고 .techviz/<이름>/ 이 함께 들어왔다. 삽입 줄의 대부분(3.15M)이 그 .techviz context.json 이다. 그 밖에 ca-tmpl·document-haness 의 정리, .claude/agents/ 열한 개, writing-practitioner-guides 스킬, .playwright-mcp 세션 산출물, scripts/check-ssot-facts.py 와 그 시험이 들어 있다. 이 커밋의 내용은 내가 만든 것이 아니라 이전 세션이 남긴 것이고 검증하지 않았다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
101 lines
5.7 KiB
Markdown
101 lines
5.7 KiB
Markdown
# 후보의 처분 — 무엇을 독립 기록으로 만들고 무엇을 만들지 않는가
|
|
|
|
분석에서 나온 항목마다 처분을 하나 적는다. 처분은 `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 인 이유는 하나다 — 경고로 두면 재판정하지 않은 트리로 글을 쓰기 시작할 수 있다.
|