chore: 문서 수정

.agents/skills/revising-korean-technical-prose/SKILL.md

@@ -7,24 +7,49 @@ description: Use when a Korean technical blog or reader-facing document should r
 
 ## 핵심 원칙
 
-기술 사실을 설명문으로 나열하지 말고, 작성자가 직접 코드를 보고 실행하면서 예상하고, 발견하고, 판단하고, 바꾼 과정으로 쓴다. 논리와 근거는 그대로 두고 서술 관점과 문장 형식만 고친다.
+기술 사실을 설명문으로 나열하지 말고, 서술자가 코드를 만들고 판단했거나 직접 확인한 과정으로 쓴다. 먼저 서술자가 코드의 작성자인지 외부 분석자인지 확정한다. 논리와 근거는 그대로 두고 서술 관점과 문장 형식만 고친다.
 
 [문장 패턴](references/sentence-patterns.md)을 처음부터 끝까지 읽은 뒤 수정한다.
 
+## 서술자의 위치부터 고정하기
+
+사용자가 자신이 만든 코드라고 밝혔다면 작성자 관점으로 쓴다. `처음 저장소를 열었습니다`, `코드를 따라가 보니`, `모듈을 훑어봤습니다`, `확인해 보니 이런 구조였습니다`처럼 다른 사람의 코드를 분석하는 표현을 쓰지 않는다.
+
+작성자 관점에서는 다음 내용을 앞에 둔다.
+
+- 만들 때 해결하려 한 문제
+- 당시 정한 기준과 선택
+- 그 선택을 코드와 빌드에 옮긴 방법
+- 구현을 끝낸 범위와 아직 연결하지 않은 범위
+- 선택하면서 받아들인 비용
+
+예를 들어 `처음 코드를 열었을 때 19개 모듈이 보였습니다`가 아니라 `코어의 클래스패스를 제한하고 선택형 어댑터를 분리하면서 19개 모듈로 만들었습니다`라고 쓴다. 소유 관계가 확인되지 않았다면 작성자 경험을 만들어 내지 않는다.
+
 ## 경험담 문체
 
 문서의 시작과 주요 전환에서는 `저는`이나 `제가`를 사용한다. 모든 문장에 반복하지는 않는다. 다음 흐름으로 문단 전체를 다시 쓴다.
 
-1. 처음 마주한 코드, 화면, 요청 또는 문제를 보여 준다.
+1. 처음 마주한 코드, 화면, 요청 또는 만들 때 해결하려 한 문제를 보여 준다.
 2. 당시의 예상이나 처음 보인 인상을 짧게 적는다.
 3. `그런데` 뒤에 실제 실행이나 코드 추적에서 발견한 차이를 둔다.
 4. 낯선 용어는 그때 이해한 내용처럼 바로 풀어 쓴다.
 5. 그 차이 때문에 무엇을 확인하고 선택하거나 바꿨는지 적는다.
 6. 결과와 함께 새로 생긴 비용이나 남은 문제를 적는다.
 
-여섯 요소의 이름은 출력하지 않고 필요한 요소만 쓴다. 독자가 작성자의 확인 순서를 따라가게 하며, 기준 문단이 `~했습니다`를 사용하면 같은 높임말을 유지한다.
+여섯 요소의 이름은 출력하지 않고 필요한 요소만 쓴다. 독자가 작성자의 판단과 확인 순서를 따라가게 하며, 기준 문단이 `~했습니다`를 사용하면 같은 높임말을 유지한다.
 
-`첫 번째 제약이다`를 지우거나 `호출 주체`를 구성요소 이름으로 바꾸는 것만으로는 교정이 끝나지 않는다. `처음에는`, `그런데 확인해 보니`, `그래서`, `그 결과`로 이어지는 경험의 흐름이 보여야 한다.
+`첫 번째 제약이다`를 지우거나 `호출 주체`를 구성요소 이름으로 바꾸는 것만으로는 교정이 끝나지 않는다. 경험의 흐름도 서술자의 위치에 맞춰야 한다. 외부 분석자는 `처음에는`, `그런데 확인해 보니`로 쓸 수 있지만, 작성자는 `만들 때`, `구현하면서`, `그래서 …로 나눴습니다`, `그 결과`로 자신의 판단과 작업을 설명한다.
+
+## 문장 종결을 문서 전체에서 맞추기
+
+사용자가 `~했습니다` 문체를 예시로 주었거나 기준 문서가 높임말이면, 제목·표의 명사구·인용문·코드 블록을 제외한 독자용 본문 전체를 다음 어투로 쓴다.
+
+- 직접 확인하거나 수행한 일: `확인했습니다`, `따라갔습니다`, `생각했습니다`
+- 현재 동작과 기술 설명: `사용합니다`, `호출합니다`, `막습니다`
+- 상태와 판단: `있습니다`, `없습니다`, `입니다`, `아닙니다`
+- 부정: `다루지 않습니다`, `보장하지 않습니다`
+
+한 문단만 `저는 확인했습니다`로 열고 뒤에서 `있다`, `한다`, `아니다`, `다루지 않는다`로 돌아가면 교정이 끝난 것이 아니다. 수정이 끝나면 fenced code를 제외한 본문에서 평서형 종결이 남았는지 따로 검색한다. 원문 코드, 직접 인용, 명령 출력은 어투를 바꾸지 않는다.
 
 ## 한국어 말하기 검사
 
@@ -38,7 +63,7 @@ description: Use when a Korean technical blog or reader-facing document should r
 
 ## 경험과 사실의 경계
 
-코드 비교, 실행, 요청 추적처럼 실제로 수행한 작업은 1인칭으로 서술할 수 있다. 사용자가 경험담 문체를 요구했다면 이 관점을 제거하지 않는다.
+코드 작성, 코드 비교, 실행, 요청 추적처럼 실제로 수행한 작업은 1인칭으로 서술할 수 있다. 사용자가 경험담 문체를 요구했다면 이 관점을 제거하지 않는다. 다만 코드를 만든 경험을 저장소를 처음 분석한 경험으로 바꾸지 않는다.
 
 다만 근거에 없는 감정, 대화, 조언, 실패, 성과, 작업 기간은 만들지 않는다. `놀랐습니다`, `누군가 조언했습니다`, `며칠이 걸렸습니다`처럼 확인할 수 없는 경험은 추가하지 않는다. 기술 선택의 이유도 새로 만들지 않는다.
 
@@ -52,17 +77,20 @@ description: Use when a Korean technical blog or reader-facing document should r
 
 ## 수정 절차
 
-1. 앞뒤 문단까지 읽고 작성자가 실제로 확인한 코드, 실행 결과와 판단을 찾는다.
-2. 독자가 경험을 따라갈 시작점과 `그런데` 뒤에 놓을 발견을 고른다.
-3. 주요 절을 1인칭 경험으로 열고, 기술 동작은 구체적인 구성요소와 동사로 설명한다.
-4. 낯선 용어를 처음 필요한 문장 옆에서 풀어 쓴다.
-5. 대조 문장은 소리 내어 읽고 `실제로는 무엇이 다른가`에 바로 답하는지 확인한다.
-6. 파일을 직접 수정한 뒤 사실, 조건, 불확실성이 바뀌지 않았는지 비교한다.
+1. 사용자 요청과 문서에서 코드 소유 관계를 확인하고 서술자를 작성자 또는 외부 분석자로 고정한다.
+2. 앞뒤 문단까지 읽고 작성자가 실제로 구현하거나 확인한 코드, 실행 결과와 판단을 찾는다.
+3. 독자가 경험을 따라갈 시작점과 `그런데` 뒤에 놓을 발견을 고른다.
+4. 주요 절을 1인칭 경험으로 열고, 기술 동작은 구체적인 구성요소와 동사로 설명한다.
+5. 낯선 용어를 처음 필요한 문장 옆에서 풀어 쓴다.
+6. 대조 문장은 소리 내어 읽고 `실제로는 무엇이 다른가`에 바로 답하는지 확인한다.
+7. 파일을 직접 수정한 뒤 사실, 조건, 불확실성이 바뀌지 않았는지 비교한다.
 
 ## 완료 조건
 
 - 작성자의 시작점, 발견, 행동과 결과가 보인다.
+- 코드 작성자의 문서가 외부 분석자의 저장소 검토처럼 읽히지 않는다.
 - 단순한 객관식 해설이나 결론 목록으로 읽히지 않는다.
 - 필요한 곳에서 `저는`이나 `제가`가 실제 서술 관점을 만든다.
+- 사용자 예시와 같은 높임말이 독자용 본문 전체에서 유지된다.
 - 한국인 개발자가 동료에게 설명할 때 쓸 수 있는 문장으로 읽힌다.
 - 기술적 의미와 문서 구조가 그대로 남는다.

.agents/skills/revising-korean-technical-prose/references/sentence-patterns.md

@@ -27,6 +27,20 @@
 
 여기서는 `호출 주체가 다르다`를 구성요소 이름으로 바꾸는 데서 멈추지 않는다. 작성자가 같은 화면을 보고, 예상과 다른 요청을 발견하고, 낯선 값을 이해한 뒤, 각 구성요소를 확인한 순서로 문단 전체를 다시 쓴다.
 
+## 작성자와 외부 분석자를 바꾸지 않는다
+
+사용자가 자신이 만든 코드를 설명한다면 다음 문장은 관점이 잘못됐다.
+
+수정 전:
+
+> 처음 저장소를 열었을 때 19개 모듈이 먼저 보였습니다. 각 빌드 파일을 따라가 보니 코어의 클래스패스를 제한하는 구조였습니다.
+
+수정 후:
+
+> 코어에서 금지한 프레임워크 타입이 보이지 않게 하려고 클래스패스를 모듈마다 나눴습니다. 선택형 어댑터까지 분리한 결과 19개 모듈이 됐습니다.
+
+작성자는 자신의 코드를 `열어 보고`, `훑어 보고`, `따라가며 발견한` 사람처럼 말하지 않는다. 만들 때 해결하려 한 문제, 정한 기준, 구현한 방법, 아직 연결하지 않은 범위와 받아들인 비용을 설명한다. 반대로 소유 관계를 알 수 없는 문서에 작성자 경험을 새로 붙이지 않는다.
+
 ## 한국어에서는 실제 차이를 바로 말한다
 
 수정 전:
@@ -57,7 +71,7 @@
 
 수정 후:
 
-> AP1과 AP2에서는 브라우저가 API를 직접 부른다. AP3에서는 BFF가 대신 호출하고, AP4에서는 Nginx가 요청을 이어 간다.
+> AP1과 AP2에서는 브라우저가 API를 직접 부릅니다. AP3에서는 BFF가 대신 호출하고, AP4에서는 Nginx가 요청을 이어 갑니다.
 
 `호출 주체가 다르다`고 분류하지 말고 실제 구성요소와 행동을 쓴다.
 
@@ -69,7 +83,7 @@
 
 수정 후:
 
-> 그래서 패턴 이름만 보고 구현되지 않은 운영 속성을 덧붙이면 안 된다.
+> 그래서 패턴 이름만 보고 구현되지 않은 운영 속성을 덧붙이면 안 됩니다.
 
 실제 순서를 뜻하지 않는 `첫 번째`, `두 번째`, `마지막`은 제거한다. 절차, 화면, 레이어처럼 순서 자체가 정보라면 유지한다.
 
@@ -81,7 +95,7 @@
 
 수정 후:
 
-> 브라우저가 Resource Server를 직접 부르는 방식은 유지해야 했다. 다만 client secret과 refresh token까지 JavaScript에 맡길 수는 없었다. 그래서 code 교환과 refresh token 보관은 confidential mediator가 맡았다.
+> 브라우저가 Resource Server를 직접 부르는 방식은 유지해야 했습니다. 다만 client secret과 refresh token까지 JavaScript에 맡길 수는 없었습니다. 그래서 code 교환과 refresh token 보관은 confidential mediator가 맡았습니다.
 
 `상황`, `선택`, `대안`, `가드레일`을 주어로 삼지 않는다. 그 자리에 요구, 행동, 이유, 남은 비용을 넣는다.
 
@@ -89,9 +103,9 @@
 
 용어를 삭제하거나 모두 번역하지 않는다. 처음 이해가 필요한 지점에서만 짧게 푼다.
 
-> 포팅은 코드를 다른 언어로 옮겨 다시 만드는 일이다.
+> 포팅은 코드를 다른 언어로 옮겨 다시 만드는 일입니다.
 
-> authorized client는 로그인한 사용자와 OAuth client에 연결된 token 묶음이다.
+> authorized client는 로그인한 사용자와 OAuth client에 연결된 token 묶음입니다.
 
 뒤 문장에서 이미 행동으로 뜻이 드러나면 별도의 정의를 반복하지 않는다.