docs(TechLog): 설명 뒤에 붙은 평가·예고·되풀이를 걷어낸다

rewriting-technical-prose-naturally 를 서브에이전트 셋으로 나눠 56편에 적용했다. ai-tells.md 의 첫 절대로 다른 표현으로 바꾸는 대신 문장을 통째로 지웠다. 설명한 것의 중요성을 다시 평가하는 꼬리 19 이미 설명한 것을 추상어로 되풀이 19 독자에게 읽는 법을 지시하거나 오해를 가정 9 자료가 뒷받침하지 않는 덧붙인 이득 4 문서군 전체의 문형 편중도 풀었다 — 함께 27→7(한 묶음), 그대로 22→12(두 묶음), 하게 된다 1→0. 한 편에서 세 번 반복되던 「같은 병이 ~에서도 났다」와 두 기록에 같은 문장으로 있던 세 쌍을 갈랐다. 계약 제목 「여덟 자리」가 본문의 「여덟 곳」과 어긋나 있었다. 제목이 spatial-metaphor 규칙에도 걸리므로 계약과 기록을 함께 「여덟 곳」으로 맞췄다. 검사 넷 전부 통과한다 — check_prose 56편 error 0 · check_body PASS · check_evidence --repo 문제 없음 · verify-tech-log-tree error 0 warn 0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 16:03:16 +09:00
parent fc23660871
commit 0650d91def
54 changed files with 120 additions and 436 deletions
@@ -14,7 +14,7 @@ source:

 # 결정에는 상세 화면이 없어 목록 항목이 문서 전체를 실어야 했다

-공개 결정 화면에서 제목 자리에 결정문 전문이 나오고, 요약이 없고, 줄바꿈이 전부 접히고, 영향과 근거가 늘 비어 있었다. 네 증상이 한 구조에서 나왔다 — 결정에는 상세 화면이 없고 공개 주소가 목록 위의 앵커다. 그래서 화면이 그리는 칸이 전부 목록 항목에 있어야 했다.
+공개 결정 화면에서 제목 칸에 결정문 전문이 나오고, 요약이 없고, 줄바꿈이 전부 접히고, 영향과 근거가 늘 비어 있었다. 네 증상이 한 구조에서 나왔다 — 결정에는 상세 화면이 없고 공개 주소가 목록 위의 앵커다. 그래서 화면이 그리는 칸이 전부 목록 항목에 있어야 했다.

 ## 관계

@@ -35,7 +35,7 @@ source:

 네 증상이 전부 목록 항목의 빈칸에서 나왔다.

-제목 자리 : statement 를 대신 썼다
+제목 칸 : statement 를 대신 썼다
 요약 : 실을 칸이 없었다
 줄바꿈 : 접혔다
 영향과 근거 : 프론트가 빈 배열로 고정해 뒀다
@@ -63,26 +63,22 @@ tech-log-frontend : 31afb4d 이후

 결정은 자기 화면을 갖지 않는다. 공개 라우트는 `/projects/{slug}/decisions` 하나이고, 개별 결정은 그 목록 위의 앵커로 간다.

-이 구조에서는 화면이 그리는 칸이 전부 목록 항목에 있어야 한다. 상세를 부를 곳이 없기 때문이다.
+상세를 부를 곳이 없으므로 화면이 그리는 칸이 전부 목록 항목에 있어야 한다.

 ## 네 증상이 한 원인이었다

-`ProjectDecisionItem` 에 `title` 이 없어서 프론트가 `statement` 를 제목 자리에 썼다. 결정문은 한 문장이 아니라 문단일 수 있으므로 제목 자리에 전문이 들어갔다.
+`ProjectDecisionItem` 에 `title` 이 없어서 프론트가 `statement` 를 제목 칸에 썼다. 결정문은 한 문장이 아니라 문단일 수 있으므로 제목 칸에 전문이 들어갔다.

 `summary` 가 없어서 요약 줄이 비었다. `consequences` 와 `evidence` 가 없어서 프론트가 그 둘을 빈 배열로 고정해 뒀다.

 줄바꿈은 다른 이유였다. 마크다운이 아닌 칸의 줄바꿈을 화면이 접고 있었다.

-## 저장된 값은 그대로 있었다
+## DB 에는 값이 다 있었다

 DB 를 조회하면 작성자가 쓴 제목과 여러 줄 요약과 영향 4건이 있었다. 어느 것도 화면까지 오지 못했다.

-## 화면 쪽에서 역으로 확인한다
-
-이 부류는 응답에서 출발하면 보이지 않는다. 응답에 없는 칸을 찾는 일이기 때문이다. 화면이 그리는 칸을 먼저 적고 그 칸이 응답에 있는지 하나씩 맞춰야 한다.
-
 ## 확인하지 못한 것

-저장된 값이 그대로였다는 것은 조회로 확인했다. 그 시점의 화면 캡처는 남기지 않았다.
+저장된 값은 조회로 확인했다. 그 시점의 화면 캡처는 남기지 않았다.

 <!-- body:end -->
@@ -28,7 +28,7 @@ source:

 ## 문제

-관계 목록은 한 줄에 대상의 종류와 작성자가 쓴 이유와 대상의 요약을 보인다. 라벨은 고쳤는데 요약 자리가 계속 비어 있었다.
+관계 목록은 한 줄에 대상의 종류와 작성자가 쓴 이유와 대상의 요약을 보인다. 라벨은 고쳤는데 요약 칸이 계속 비어 있었다.

 계약에는 요약이 있었다. DB 에도 값이 있었다. 화면까지 오지 못했다.

@@ -74,7 +74,7 @@ tech-log-backend : 92679f5 이후

 ## 계약에 칸을 더할 때 required 를 따로 판단한다

-`ResolvedRelation` 에 `summary` 를 더했다. required 에는 넣지 않았다. 이미 나가 있는 응답에는 그 칸이 없으므로, required 로 올리면 배포 순서에 따라 검증이 깨진다.
+`ResolvedRelation` 에 `summary` 를 더하면서 required 에는 넣지 않았다. 이미 나가 있는 응답에는 그 칸이 없어서, required 로 올리면 배포 순서에 따라 검증이 깨진다.

 ## 한 칸에 셋이 뭉쳐 있었다

@@ -82,11 +82,11 @@ tech-log-backend : 92679f5 이후

 | 무엇 | 뜻 | 경로별로 어떻게 나왔나 |
 |---|---|---|
-| 대상의 종류 | 「근거」「관련 기준」 같은 분류 | 렌더 모델 경로: 작성자의 문장이 이 자리에 눌려 나옴 |
+| 대상의 종류 | 「근거」「관련 기준」 같은 분류 | 렌더 모델 경로: 작성자의 문장이 이 칸에 눌려 나옴 |
 | 작성자가 쓴 이유 | 「다음에 무엇을 읽을지」의 답 | 공개 조회 경로: **아예 버려짐** |
 | 대상의 요약 | 대상이 무엇인지 | — |

-셋을 `label` · `note` · `summary` 로 갈랐다. 설명 자리에는 문장이 있으면 문장을, 없으면 요약을 보인다. 요약은 대상이 무엇인지 말하고, 문장은 왜 지금 그것을 읽어야 하는지 말한다.
+셋을 `label` · `note` · `summary` 로 갈랐다. 설명 칸에는 작성자가 쓴 문장이 있으면 그것을, 없으면 대상의 요약을 보인다.

 ## 확인하지 못한 것