pipeline: make tech-log-tree.json the one decomposition contract and enforce it

리뷰 두 건을 반영했다.

계약
- 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>
This commit is contained in:
DongHyeonka
2026-09-07 12:39:20 +09:00
co-authored by Claude Fable 5.1
parent 73026cada6
commit 9d2a3725c5
54 changed files with 3583 additions and 871 deletions
@@ -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라는 점이 문제가 된다` — 무엇이 걸리는지까지 말한다
- 무엇을 하자고 이끌 때는 `~해 보자`를 쓴다. 절 제목과 여는 문장에만 쓰고 규칙에는 쓰지 않는다
- 명령조를 줄인다. 검사 항목이 아니라 같이 읽는 사람의 말로 쓴다