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
@@ -63,13 +63,13 @@ tech-log-backend : 857e6a9 — 삭제 거절 사유를 클라이언트 안전

 ## 무엇이 구분되지 않았나

-버전 충돌은 「누가 먼저 고쳤다」이고 참조 존재는 「사용 중」이다. 문구가 셋을 함께 적으므로 작성자는 둘을 구분할 수 없다.
+버전 충돌은 「누가 먼저 고쳤다」이고 참조 존재는 「사용 중」이다. 문구가 셋을 한꺼번에 적으므로 작성자는 둘을 구분할 수 없다.

-두 경우에 해야 할 일이 다르다. 버전 충돌이면 다시 받아서 지우면 되고, 참조가 있으면 그 참조를 먼저 풀어야 한다.
+버전 충돌이면 다시 받아서 지우면 되고, 참조가 있으면 그 참조를 먼저 풀어야 한다.

 ## 서버의 답을 실어 나른다

-게이트웨이가 서버의 클라이언트 안전 메시지를 그대로 싣고 화면이 그것을 보인다. 서버가 답하지 않은 것은 화면이 만들지 않는다.
+게이트웨이가 서버의 클라이언트 안전 메시지를 그대로 싣고 화면이 그것을 보인다.

 ## 확인하지 못한 것

@@ -15,7 +15,7 @@ source:

 # 한 화면에 종류 이름이 아홉 개 떠 있었다 — 표가 여섯 벌이었다

-홈 한 화면에 문서 종류 이름이 아홉 개 떠 있었다. 최근 기록 목록은 계약의 enum 이름을, 바로 아래 「종류별로 읽기」는 사람이 붙인 이름을 쓰고 있었다. 독자는 둘이 같은 것이라는 단서를 어디서도 받지 못했다. 원인은 종류 이름 표가 화면마다 복사되어 여섯 벌이었다는 것이다.
+홈 한 화면에 문서 종류 이름이 아홉 개 떠 있었다. 최근 기록 목록은 계약의 enum 이름을, 바로 아래 「종류별로 읽기」는 사람이 붙인 이름을 쓰고 있었다. 독자는 둘이 같은 것이라는 단서를 어디서도 받지 못했다. 표가 화면마다 복사되어 여섯 벌이었기 때문이다.

 ## 관계

@@ -39,13 +39,11 @@ source:

 ## 결론

-종류 이름 표가 화면마다 복사되어 여섯 벌이었고, 그래서 갈라졌다.
-
 > 표가 화면마다 복사되어 **여섯 벌**이었고 그래서 갈라졌다: 같은 QUESTION 이 공개 화면에서 "Open Question", 작업본 목록과 게시 기록에서 "Question", 편집기 상태 줄에서 "QUESTION" 이었다. **쓰는 사람은 같은 문서를 화면마다 다른 이름으로 만난다.**

 종류에서 이름으로 가는 표 하나로 모았다.

-편집기 칸 이름도 공개 화면과 맞췄다. 쓰는 사람이 지금 채우는 칸이 공개 화면 어디로 가는지 외우지 않아도 된다.
+편집기 칸 이름도 공개 화면과 맞췄다.

 ## 검증 환경

@@ -71,7 +69,7 @@ tech-log-frontend : dc2fda7 · ca1cfa2 계열 · 82e992d

 두 목록이 세로로 붙어 있다. 위는 계약의 enum 이름을, 아래는 사람이 붙인 이름을 쓴다.

-이름을 바꾸기 전보다 나빠진 유일한 화면이었다. 바꾸기 전에는 양쪽이 다 enum 이름이라 적어도 같아 보였다.
+이 화면은 이름을 바꾸기 전보다 나빠졌다. 바꾸기 전에는 양쪽이 다 enum 이름이라 적어도 같아 보였다.

 ## 표가 여섯 벌이었다

@@ -79,7 +77,7 @@ tech-log-frontend : dc2fda7 · ca1cfa2 계열 · 82e992d

 ## 표 하나로 모았다

-종류에서 표시 이름으로 가는 표를 하나 만들고 여섯 곳이 그것을 쓰게 했다. 종류가 늘면 그 표에 자리가 비었다고 컴파일러가 잡는다.
+종류에서 표시 이름으로 가는 표를 하나 만들고 여섯 곳이 그것을 쓰게 했다. 종류가 늘면 그 표에서 빠진 값을 컴파일러가 잡는다.

 ## 편집기 칸 이름도 맞췄다

@@ -36,7 +36,7 @@ source:
 두 번 바꿨다.

 1차 : 이름이 하는 일을 말하게 했다 — 직접 해보니 · 다음에 쓸 기준 · 아직 모르는 것 · 어떻게 동작하나 · 이렇게 하기로
-2차 : 역할은 그대로 말하되 문어체로 다시 세웠다 — 검증 기록 · 적용 기준 · 열린 질문 · 동작 원리 · 설계 결정
+2차 : 하는 일을 말하는 방향은 두고 문어체로 다시 세웠다 — 검증 기록 · 적용 기준 · 열린 질문 · 동작 원리 · 설계 결정

 1차 안이 기술 기록의 톤에 비해 가벼웠다.

@@ -84,9 +84,7 @@ QUESTION → 열린 질문

 ## 계약의 kind 는 그대로 뒀다

-바꾼 것은 화면에 보이는 이름이다. 계약의 `RecordKind` 는 다섯 값 그대로이고, 주소도 그대로다.
-
-표시 이름과 계약 값을 갈라 두면 이름을 다시 바꿀 때 계약을 건드리지 않아도 된다.
+바꾼 것은 화면에 보이는 이름이다. 계약의 `RecordKind` 는 다섯 값 그대로이고 주소도 바뀌지 않았다.

 ## 확인하지 못한 것

@@ -16,12 +16,12 @@ source:

 # 삭제를 막는 이유 다섯 가지가 전부 같은 한 문장으로 나온다

-작업본 삭제가 막히는 이유는 다섯 가지인데 전부 같은 한 문장으로 나온다. 실제 사례에서 막은 것은 프로젝트 링크 한 행이었고, 문구는 「다른 기록이 참조한다」고 말했다. 문구가 잘못된 것을 가리키고 있다.
+작업본 삭제가 막히는 이유는 다섯 가지인데 전부 같은 한 문장으로 나온다. 실제 사례에서 막은 것은 프로젝트 링크 한 행이었고, 문구는 「다른 기록이 참조한다」고 말했다.

 ## 관계

 - **서버는 하나를 답했는데 화면은 추측 셋을 출력했다**
-  화면 쪽 문구를 고친 사건이고, 서버 쪽 문구는 그대로 남았다.
+  화면 쪽 문구를 고친 사건이고, 서버 쪽 문구는 고치지 않았다.
 - **그 SQL 은 한 번도 실행된 적이 없었다**
  이 참조 검사를 실제 DB 에서 돌리게 만든 사건이다.
 - **화면은 못 읽은 것을 없다고 말하지 않는다**
@@ -14,7 +14,7 @@ source:

 # 톤을 지적받으면 고쳐 쓰지 말고 어떤 말을 쓸지 묻는다

-사용자가 프로필의 문구가 AI 스럽다고 지적했다. 고쳐 쓴 첫 번째 안도 거절당했고, 결국 사용자가 직접 쓴 텍스트를 그대로 실었다. 이 사이트의 글은 작성자가 자기 말로 쓴다. 더 나은 문장을 제안할 때와 그 사람의 말투로 쓸 때 필요한 것이 다르다.
+사용자가 프로필의 문구가 AI 스럽다고 지적했다. 고쳐 쓴 첫 번째 안도 거절당했고, 결국 사용자가 직접 쓴 텍스트를 그대로 실었다. 이 사이트의 글은 작성자가 자기 말로 쓴다.

 ## 관계

@@ -27,7 +27,7 @@ source:

 ## 목적

-작성자의 목소리로 쓰인 글을 고쳐 쓰다 두 번 거절당하는 것을 막는다. 톤을 지적할 때 사용자가 가리키는 것은 문장의 품질이 아니라 그 말을 누가 쓰는가다.
+작성자의 목소리로 쓰인 글을 고쳐 쓰다 두 번 거절당하는 것을 막는다.

 ## 규칙

@@ -48,7 +48,7 @@ Case 소제목에 쓰는 말이 「~한 것」 명사형이면 새 제목도 그

 오류 문구처럼 서버가 답한 사실을 그대로 실어야 하는 곳에서는 말투를 묻지 않는다. 무엇을 실을지를 먼저 정한다.

-계약이나 코드가 정한 이름은 이 규칙에서 뺀다. 표시 이름만 바꾸고 계약 값은 그대로 둔다.
+계약이나 코드가 정한 이름은 이 규칙에서 뺀다. 표시 이름만 바꾸고 계약 값은 건드리지 않는다.

 ## 예시

@@ -58,4 +58,4 @@ Case 소제목에 쓰는 말이 「~한 것」 명사형이면 새 제목도 그

 「무엇을 견줬나」는 의문형 꼬리에 이 기록에서 쓰지 않는 낱말이었다. 작성자가 Case 소제목에 쓰는 말은 「이 구조에서 감수한 것」처럼 「~한 것」 명사형이라 그쪽에 맞췄다.

-고쳐 쓴 첫 번째 안이 거절당한 뒤 사용자가 직접 쓴 텍스트를 그대로 실었다.
+고쳐 쓴 첫 번째 안이 거절당한 뒤 사용자가 직접 쓴 텍스트를 실었다.