DongHyeonkaandClaude Fable 5.1
9d2a3725c5
리뷰 두 건을 반영했다. 계약 - tech-log-tree.json 하나가 분해 계약이자 색인이다. 사람이 읽는 트리·Node Specification· 후보 대장은 없어졌고, 문서에 남아 있던 그 개념을 걷어냈다 - candidateScope — 후보를 찾는 SSOT 범위. 접어 넣은 제2부·제3부는 근거이지 후보가 아니다 - sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 리비전을 모르면 null 로 두고 지어내지 않는다. 갈래가 여럿이면 revisions - 검사기: 계약 미채택·PENDING·PROMOTE↔글감 양방향·candidateScope·sourceRepository 를 error/warn 으로 센다. 옛 스키마도 검사를 피하지 못한다. 테스트 22 → 31 기록 쓰기 - 템플릿 5종에 source·sourceRevision·topicName, Question 에 닫는 조건, 본문 없는 종류에서 assets 제거. 고정 절 개수 삭제 - check_evidence.mjs — 인용한 코드가 SSOT 에 있는지, 앵커가 SSOT 를 가리키는지, 제목이 계약과 같은지, 리비전이 저장소에 있는지. 게시된 기록에서 SSOT 와 다른 URL 을 잡았다 문체 - 문체 규칙의 정본을 ai-tells.md 로. explaining.md 의 질문체 제목·절 끝 대조 반복·그림 예고 규칙을 삭제해 충돌을 없앴다. 첫 절 「설명 뒤에 평가를 붙이지 않는다」에 지우는 사례 네 유형 - voice 스킬의 「독자 쪽을 본다」를 자료에 오독 기록이 있을 때로 좁히고, 평가만 더한 예시를 교체 - check_prose: 안내 문장을 요구하던 경고 제거, 문장이 끝나지 않은 채 문단이 끝나는 조각 검사 추가 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
5.5 KiB
후보의 처분 — 무엇을 독립 기록으로 만들고 무엇을 만들지 않는가
분석에서 나온 항목마다 처분을 하나 적는다. 처분은 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 | 대안 중 프로젝트가 실제 방향을 정했고 근거와 감수한 비용이 있다 | 기술이 존재한다는 사실, 권장사항, 아직 정하지 않은 방향 |
Case 를 언제 합치나
같은 질문에서 나와 같은 결론에 닿는 관측이면 한 Case 다. 인과 단위·의미 단위·검증 단위가 셋 다 같아야 합친다는 기준은 너무 좁다 — 그 기준에서는 같은 결함의 다섯 증상이 다섯 편이 된다.
관측이 여럿이면 한 Case 안에 표나 하위 절로 넣는다. 표의 행 하나가 될 것을 기록 하나로 만들지 않는다.
Concept 을 언제 만드나
Case·Decision·Question 을 먼저 고른 뒤 거꾸로 뽑는다. "이 Case 를 읽는 사람이 미리 알아야 하는 구조가 있는가"를 묻고, 있으면 그때 Concept 을 만든다. 메커니즘처럼 보이는 절을 훑어 채우면 어느 Case 도 필요로 하지 않는 개념이 쌓인다.
Concept 에는 basis-version 이 있어야 한다. 무엇을 보고 쓴 글인지 없으면 언제 낡았는지
읽는 사람이 알 방법이 없다.
제목이 이런 꼴이면 Concept 이 아니다.
호출자가 없다 → 부재는 Case 의 관측이다
프로덕션에서 실행되지 않는다 → 같은 이유
구현 클래스 51개를 전부 읽었다 → 분석 범위. KEEP_IN_SSOT
보류한 항목과 보류한 이유 → 분석 진행 기록. KEEP_IN_SSOT
(8.4) 문서/구현 드리프트 — … → 분석 문서의 절 제목을 그대로 옮긴 것
Confirmed — … → 같은 것. finding 등급이 제목에 남아 있다
대장에 적는 것
{
"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 인 이유는 하나다 — 경고로 두면 재판정하지 않은 트리로 글을 쓰기 시작할 수 있다.