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

2026-07-29 16:48:03 +09:00
parent c39406bbdd
commit 41501b5d06
520 changed files with 95494 additions and 2231 deletions
@@ -0,0 +1,68 @@
+---
+name: revising-korean-technical-prose
+description: Use when a Korean technical blog or reader-facing document should read like a first-person experience or retrospective, especially when settled facts are buried under abstract, formulaic, translated, or AI-generated prose.
+---
+
+# Revising Korean Technical Prose
+
+## 핵심 원칙
+
+기술 사실을 설명문으로 나열하지 말고, 작성자가 직접 코드를 보고 실행하면서 예상하고, 발견하고, 판단하고, 바꾼 과정으로 쓴다. 논리와 근거는 그대로 두고 서술 관점과 문장 형식만 고친다.
+
+[문장 패턴](references/sentence-patterns.md)을 처음부터 끝까지 읽은 뒤 수정한다.
+
+## 경험담 문체
+
+문서의 시작과 주요 전환에서는 `저는`이나 `제가`를 사용한다. 모든 문장에 반복하지는 않는다. 다음 흐름으로 문단 전체를 다시 쓴다.
+
+1. 처음 마주한 코드, 화면, 요청 또는 문제를 보여 준다.
+2. 당시의 예상이나 처음 보인 인상을 짧게 적는다.
+3. `그런데` 뒤에 실제 실행이나 코드 추적에서 발견한 차이를 둔다.
+4. 낯선 용어는 그때 이해한 내용처럼 바로 풀어 쓴다.
+5. 그 차이 때문에 무엇을 확인하고 선택하거나 바꿨는지 적는다.
+6. 결과와 함께 새로 생긴 비용이나 남은 문제를 적는다.
+
+여섯 요소의 이름은 출력하지 않고 필요한 요소만 쓴다. 독자가 작성자의 확인 순서를 따라가게 하며, 기준 문단이 `~했습니다`를 사용하면 같은 높임말을 유지한다.
+
+`첫 번째 제약이다`를 지우거나 `호출 주체`를 구성요소 이름으로 바꾸는 것만으로는 교정이 끝나지 않는다. `처음에는`, `그런데 확인해 보니`, `그래서`, `그 결과`로 이어지는 경험의 흐름이 보여야 한다.
+
+## 한국어 말하기 검사
+
+소리 내어 읽고 한국인 개발자가 동료에게 할 말인지 확인한다. 번역은 맞지만 실제로 말하지 않을 표현이면 다시 쓴다.
+
+대조할 때는 `겉으로 보이는 것 → 실제 동작`을 바로 연결한다.
+
+> 화면에서 보이는 이름은 같지만 실제 검증 방식은 다릅니다.
+
+`이름을 믿는 이유`, `위치와 모양`, `의미와 관점`처럼 추상적인 말을 대조의 결론으로 두지 않는다. `실제로는` 뒤에 JWT 검증, header 확인, token 저장처럼 코드에서 일어나는 차이를 쓴다. `같지만`, `달랐습니다`, `이유`를 금지어로 찾지 말고 문장이 실제 대상을 바로 말하는지 확인한다.
+
+## 경험과 사실의 경계
+
+코드 비교, 실행, 요청 추적처럼 실제로 수행한 작업은 1인칭으로 서술할 수 있다. 사용자가 경험담 문체를 요구했다면 이 관점을 제거하지 않는다.
+
+다만 근거에 없는 감정, 대화, 조언, 실패, 성과, 작업 기간은 만들지 않는다. `놀랐습니다`, `누군가 조언했습니다`, `며칠이 걸렸습니다`처럼 확인할 수 없는 경험은 추가하지 않는다. 기술 선택의 이유도 새로 만들지 않는다.
+
+다음 항목은 그대로 보존한다.
+
+- 제목과 절의 순서, 주장, 선택 이유, 대안, 비용, 가드레일, 근거 범위
+- 숫자, 버전, 식별자, 코드, 명령, 표, 링크, 다이어그램, 의도한 분량
+- 현재 동작, 테스트가 확인한 동작, 아직 확인하지 않은 동작의 차이
+
+문장 순서와 문단 구분은 경험의 흐름을 만들기 위해 조정할 수 있다. 논리, 사실성, 분량, 다이어그램과 정보 구조는 다시 평가하지 않는다.
+
+## 수정 절차
+
+1. 앞뒤 문단까지 읽고 작성자가 실제로 확인한 코드, 실행 결과와 판단을 찾는다.
+2. 독자가 경험을 따라갈 시작점과 `그런데` 뒤에 놓을 발견을 고른다.
+3. 주요 절을 1인칭 경험으로 열고, 기술 동작은 구체적인 구성요소와 동사로 설명한다.
+4. 낯선 용어를 처음 필요한 문장 옆에서 풀어 쓴다.
+5. 대조 문장은 소리 내어 읽고 `실제로는 무엇이 다른가`에 바로 답하는지 확인한다.
+6. 파일을 직접 수정한 뒤 사실, 조건, 불확실성이 바뀌지 않았는지 비교한다.
+
+## 완료 조건
+
+- 작성자의 시작점, 발견, 행동과 결과가 보인다.
+- 단순한 객관식 해설이나 결론 목록으로 읽히지 않는다.
+- 필요한 곳에서 `저는`이나 `제가`가 실제 서술 관점을 만든다.
+- 한국인 개발자가 동료에게 설명할 때 쓸 수 있는 문장으로 읽힌다.
+- 기술적 의미와 문서 구조가 그대로 남는다.
@@ -0,0 +1,4 @@
+interface:
+  display_name: "한국어 기술문서 문장 다듬기"
+  short_description: "논리와 근거를 보존하며 한국어 기술문서 문장만 수정"
+  default_prompt: "Use $revising-korean-technical-prose to revise this Korean technical document in place without changing its logic or evidence."
@@ -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처럼 보이기 쉬운 신호
+
+다음 표현을 금지어로 취급하지 않는다. 문단의 구체적인 행동을 대신하고 있을 때만 고친다.
+
+- `관점`, `측면`, `구조`, `주체`, `경계`, `맥락`
+- `이를 통해`, `이러한`, `해당`, `~하는 것이 중요하다`
+- `상황은`, `선택은`, `대안은`, `비용은`, `가드레일은`
+- 실제 순서가 없는 `첫 번째`, `두 번째`, `마지막으로`
+- 같은 길이와 어순으로 반복되는 세 문장
+
+고친 뒤에도 기술적 정확성에 필요한 용어와 구분은 남겨 둔다.