chore: 문서를 작성할 때 한국어의 표현 작성 스킬 추가 및 1인칭 관점의 글 작성 검증 테스트 추가

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

@@ -0,0 +1,108 @@
+# 한국어 기술문서 문장 패턴
+
+## 기준이 되는 문장
+
+> 처음 Claude와 만든 코드는 Python이라는 언어로 짜여 있었습니다. 그런데 "Java나 Kotlin으로 포팅한 뒤 베타 배포하면 작업을 두 번 하지 않아도 된다"라는 조언을 받았습니다. 포팅이 뭔지 그때는 몰랐지만 코드를 다른 언어로 옮겨 다시 만드는 일이라고 합니다. 사내 표준이 Kotlin이니 어차피 옮길 거라면 지금 옮기라는 뜻이었습니다. 듣기엔 큰 작업 같은데 제가 한 일은 Claude에게 "FastAPI 대신 Kotlin과 Spring Boot로 바꿔 줘"라고 요청한 것뿐이었습니다. FastAPI는 Python으로, Spring Boot는 Kotlin으로 서버를 만들 때 쓰는 도구입니다. 이 문장 하나로 언어도 도구도 모두 바뀌었습니다.
+
+이 문단을 문장 형식과 서술 관점의 기준으로 삼는다. `제가`를 빼고 객관적인 설명문으로 바꾸면 안 된다. 독자가 기술을 배우는 동시에 작성자가 문제를 만나고 이해하고 행동한 순서를 따라갈 수 있어야 한다.
+
+- 처음에는 독자가 바로 그릴 수 있는 사람, 코드, 화면 또는 상황을 보여 준다.
+- 그다음 실제로 생긴 문제나 달라진 조건을 `그런데`, `다만`, `그래서`처럼 익숙한 말로 잇는다.
+- `포팅`처럼 독자가 모를 수 있는 말은 처음 필요한 자리에서 짧게 설명한다.
+- 조언이나 제약이 실제로 무슨 뜻인지 일상적인 문장으로 한 번 풀어 쓴다.
+- 판단, 행동, 결과를 한 문장에 압축하지 않고 차례로 보여 준다.
+- 짧은 문장과 긴 문장을 섞되, 일부러 구어체를 만들지는 않는다.
+- 작성자가 직접 확인하고 실행하고 바꾼 일은 `저는`과 `제가`를 사용해 경험으로 쓴다.
+- 근거에 없는 감정, 대화, 조언과 성과를 만들어 경험담을 꾸미지는 않는다.
+
+## 문단 전체를 다시 쓰는 예시
+
+수정 전:
+
+> 화면과 최종 값만 보면 네 구현은 같은 일을 하는 것처럼 보인다. 그런데 최초 입력부터 최종 출력까지 따라가 보면 code와 token을 다루는 곳도, API를 실제로 부르는 곳도 패턴마다 다르다.
+
+수정 후:
+
+> 처음 네 예제를 실행했을 때는 모두 로그인 뒤 같은 사용자 JSON을 보여 주었습니다. 그래서 처음에는 Keycloak을 연결하는 방법만 네 가지로 나눈 것처럼 보였습니다. 그런데 브라우저의 network 요청을 처음부터 따라가 보니 code와 token이 머무는 곳이 서로 달랐습니다. Authorization code는 로그인을 마친 사용자가 애플리케이션으로 돌아올 때 잠시 들고 오는 교환용 값입니다. 이 값을 access token으로 바꾸는 곳부터 확인했습니다. AP1에서는 브라우저가 직접 바꾸었고, AP2와 AP3에서는 Spring server가 바꾸었습니다. AP4에서는 oauth2-proxy가 같은 일을 맡았습니다. 화면은 같지만 실제 token 처리와 API 호출 방식은 다릅니다.
+
+여기서는 `호출 주체가 다르다`를 구성요소 이름으로 바꾸는 데서 멈추지 않는다. 작성자가 같은 화면을 보고, 예상과 다른 요청을 발견하고, 낯선 값을 이해한 뒤, 각 구성요소를 확인한 순서로 문단 전체를 다시 쓴다.
+
+## 한국어에서는 실제 차이를 바로 말한다
+
+수정 전:
+
+> 화면에 찍힌 이름은 같았지만 그 이름을 믿는 이유는 달랐습니다.
+
+수정 후:
+
+> 화면에서 보이는 이름은 같지만 실제 검증 방식은 다릅니다. AP1은 JWT의 서명과 issuer, audience를 확인하고, AP4는 edge를 거친 header와 internal token을 확인합니다.
+
+수정 전 문장은 뜻은 통하지만 한국인 개발자가 동료에게 설명할 때 잘 쓰지 않는 대조다. `믿는 이유`를 한 번 더 해석하게 하지 말고 실제로 다른 검증 방식을 바로 쓴다.
+
+다음 문장도 같은 기준으로 고친다.
+
+| 어색한 표현 | 자연스러운 방향 |
+|---|---|
+| 위험의 위치와 모양이 바뀌었습니다 | token을 옮길 때마다 session 저장소나 header 검증 같은 다른 문제가 생겼습니다 |
+| 두 값의 의미는 달랐습니다 | 하나는 JWT claim이고 다른 하나는 Nginx가 만든 header입니다 |
+| 보안 등급표가 아니었습니다 | 번호가 높다고 더 안전한 구조는 아니었습니다 |
+
+## 고쳐 쓰는 방법
+
+### 추상적인 주체
+
+수정 전:
+
+> 네 시스템은 서로 다른 credential과 서로 다른 호출 주체를 사용한다.
+
+수정 후:
+
+> AP1과 AP2에서는 브라우저가 API를 직접 부른다. AP3에서는 BFF가 대신 호출하고, AP4에서는 Nginx가 요청을 이어 간다.
+
+`호출 주체가 다르다`고 분류하지 말고 실제 구성요소와 행동을 쓴다.
+
+### 개요를 읽어 주는 서수
+
+수정 전:
+
+> 구현되지 않은 운영 속성을 추론하지 않는 것이 첫 번째 제약이다.
+
+수정 후:
+
+> 그래서 패턴 이름만 보고 구현되지 않은 운영 속성을 덧붙이면 안 된다.
+
+실제 순서를 뜻하지 않는 `첫 번째`, `두 번째`, `마지막`은 제거한다. 절차, 화면, 레이어처럼 순서 자체가 정보라면 유지한다.
+
+### 의미 분류명을 반복하는 문장
+
+수정 전:
+
+> 상황은 브라우저 호출을 유지해야 하는 경우다. 선택은 confidential mediator다.
+
+수정 후:
+
+> 브라우저가 Resource Server를 직접 부르는 방식은 유지해야 했다. 다만 client secret과 refresh token까지 JavaScript에 맡길 수는 없었다. 그래서 code 교환과 refresh token 보관은 confidential mediator가 맡았다.
+
+`상황`, `선택`, `대안`, `가드레일`을 주어로 삼지 않는다. 그 자리에 요구, 행동, 이유, 남은 비용을 넣는다.
+
+### 낯선 용어
+
+용어를 삭제하거나 모두 번역하지 않는다. 처음 이해가 필요한 지점에서만 짧게 푼다.
+
+> 포팅은 코드를 다른 언어로 옮겨 다시 만드는 일이다.
+
+> authorized client는 로그인한 사용자와 OAuth client에 연결된 token 묶음이다.
+
+뒤 문장에서 이미 행동으로 뜻이 드러나면 별도의 정의를 반복하지 않는다.
+
+## AI처럼 보이기 쉬운 신호
+
+다음 표현을 금지어로 취급하지 않는다. 문단의 구체적인 행동을 대신하고 있을 때만 고친다.
+
+- `관점`, `측면`, `구조`, `주체`, `경계`, `맥락`
+- `이를 통해`, `이러한`, `해당`, `~하는 것이 중요하다`
+- `상황은`, `선택은`, `대안은`, `비용은`, `가드레일은`
+- 실제 순서가 없는 `첫 번째`, `두 번째`, `마지막으로`
+- 같은 길이와 어순으로 반복되는 세 문장
+
+고친 뒤에도 기술적 정확성에 필요한 용어와 구분은 남겨 둔다.