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

name, description

name	description
revising-korean-technical-prose	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

핵심 원칙

기술 사실을 설명문으로 나열하지 말고, 서술자가 코드를 만들고 판단했거나 직접 확인한 과정으로 쓴다. 먼저 서술자가 코드의 작성자인지 외부 분석자인지 확정한다. 논리와 근거는 그대로 두고 서술 관점과 문장 형식만 고친다.

문장 패턴을 처음부터 끝까지 읽은 뒤 수정한다.

서술자의 위치부터 고정하기

사용자가 자신이 만든 코드라고 밝혔다면 작성자 관점으로 쓴다. 처음 저장소를 열었습니다, 코드를 따라가 보니, 모듈을 훑어봤습니다, 확인해 보니 이런 구조였습니다처럼 다른 사람의 코드를 분석하는 표현을 쓰지 않는다.

작성자 관점에서는 다음 내용을 앞에 둔다.

• 만들 때 해결하려 한 문제
• 당시 정한 기준과 선택
• 그 선택을 코드와 빌드에 옮긴 방법
• 구현을 끝낸 범위와 아직 연결하지 않은 범위
• 선택하면서 받아들인 비용

예를 들어 처음 코드를 열었을 때 19개 모듈이 보였습니다가 아니라 코어의 클래스패스를 제한하고 선택형 어댑터를 분리하면서 19개 모듈로 만들었습니다라고 쓴다. 소유 관계가 확인되지 않았다면 작성자 경험을 만들어 내지 않는다.

경험담 문체

문서의 시작과 주요 전환에서는 저는이나 제가를 사용한다. 모든 문장에 반복하지는 않는다. 다음 흐름으로 문단 전체를 다시 쓴다.

1. 처음 마주한 코드, 화면, 요청 또는 만들 때 해결하려 한 문제를 보여 준다.
2. 당시의 예상이나 처음 보인 인상을 짧게 적는다.
3. 그런데 뒤에 실제 실행이나 코드 추적에서 발견한 차이를 둔다.
4. 낯선 용어는 그때 이해한 내용처럼 바로 풀어 쓴다.
5. 그 차이 때문에 무엇을 확인하고 선택하거나 바꿨는지 적는다.
6. 결과와 함께 새로 생긴 비용이나 남은 문제를 적는다.

여섯 요소의 이름은 출력하지 않고 필요한 요소만 쓴다. 독자가 작성자의 판단과 확인 순서를 따라가게 하며, 기준 문단이 ~했습니다를 사용하면 같은 높임말을 유지한다.

첫 번째 제약이다를 지우거나 호출 주체를 구성요소 이름으로 바꾸는 것만으로는 교정이 끝나지 않는다. 경험의 흐름도 서술자의 위치에 맞춰야 한다. 외부 분석자는 처음에는, 그런데 확인해 보니로 쓸 수 있지만, 작성자는 만들 때, 구현하면서, 그래서 …로 나눴습니다, 그 결과로 자신의 판단과 작업을 설명한다.

문장 종결을 문서 전체에서 맞추기

사용자가 ~했습니다 문체를 예시로 주었거나 기준 문서가 높임말이면, 제목·표의 명사구·인용문·코드 블록을 제외한 독자용 본문 전체를 다음 어투로 쓴다.

• 직접 확인하거나 수행한 일: 확인했습니다, 따라갔습니다, 생각했습니다
• 현재 동작과 기술 설명: 사용합니다, 호출합니다, 막습니다
• 상태와 판단: 있습니다, 없습니다, 입니다, 아닙니다
• 부정: 다루지 않습니다, 보장하지 않습니다

한 문단만 저는 확인했습니다로 열고 뒤에서 있다, 한다, 아니다, 다루지 않는다로 돌아가면 교정이 끝난 것이 아니다. 수정이 끝나면 fenced code를 제외한 본문에서 평서형 종결이 남았는지 따로 검색한다. 원문 코드, 직접 인용, 명령 출력은 어투를 바꾸지 않는다.

한국어 말하기 검사

소리 내어 읽고 한국인 개발자가 동료에게 할 말인지 확인한다. 번역은 맞지만 실제로 말하지 않을 표현이면 다시 쓴다.

대조할 때는 겉으로 보이는 것 → 실제 동작을 바로 연결한다.

화면에서 보이는 이름은 같지만 실제 검증 방식은 다릅니다.

이름을 믿는 이유, 위치와 모양, 의미와 관점처럼 추상적인 말을 대조의 결론으로 두지 않는다. 실제로는 뒤에 JWT 검증, header 확인, token 저장처럼 코드에서 일어나는 차이를 쓴다. 같지만, 달랐습니다, 이유를 금지어로 찾지 말고 문장이 실제 대상을 바로 말하는지 확인한다.

경험과 사실의 경계

코드 작성, 코드 비교, 실행, 요청 추적처럼 실제로 수행한 작업은 1인칭으로 서술할 수 있다. 사용자가 경험담 문체를 요구했다면 이 관점을 제거하지 않는다. 다만 코드를 만든 경험을 저장소를 처음 분석한 경험으로 바꾸지 않는다.

다만 근거에 없는 감정, 대화, 조언, 실패, 성과, 작업 기간은 만들지 않는다. 놀랐습니다, 누군가 조언했습니다, 며칠이 걸렸습니다처럼 확인할 수 없는 경험은 추가하지 않는다. 기술 선택의 이유도 새로 만들지 않는다.

다음 항목은 그대로 보존한다.

• 제목과 절의 순서, 주장, 선택 이유, 대안, 비용, 가드레일, 근거 범위
• 숫자, 버전, 식별자, 코드, 명령, 표, 링크, 다이어그램, 의도한 분량
• 현재 동작, 테스트가 확인한 동작, 아직 확인하지 않은 동작의 차이

문장 순서와 문단 구분은 경험의 흐름을 만들기 위해 조정할 수 있다. 논리, 사실성, 분량, 다이어그램과 정보 구조는 다시 평가하지 않는다.

수정 절차

1. 사용자 요청과 문서에서 코드 소유 관계를 확인하고 서술자를 작성자 또는 외부 분석자로 고정한다.
2. 앞뒤 문단까지 읽고 작성자가 실제로 구현하거나 확인한 코드, 실행 결과와 판단을 찾는다.
3. 독자가 경험을 따라갈 시작점과 그런데 뒤에 놓을 발견을 고른다.
4. 주요 절을 1인칭 경험으로 열고, 기술 동작은 구체적인 구성요소와 동사로 설명한다.
5. 낯선 용어를 처음 필요한 문장 옆에서 풀어 쓴다.
6. 대조 문장은 소리 내어 읽고 실제로는 무엇이 다른가에 바로 답하는지 확인한다.
7. 파일을 직접 수정한 뒤 사실, 조건, 불확실성이 바뀌지 않았는지 비교한다.

완료 조건

• 작성자의 시작점, 발견, 행동과 결과가 보인다.
• 코드 작성자의 문서가 외부 분석자의 저장소 검토처럼 읽히지 않는다.
• 단순한 객관식 해설이나 결론 목록으로 읽히지 않는다.
• 필요한 곳에서 저는이나 제가가 실제 서술 관점을 만든다.
• 사용자 예시와 같은 높임말이 독자용 본문 전체에서 유지된다.
• 한국인 개발자가 동료에게 설명할 때 쓸 수 있는 문장으로 읽힌다.
• 기술적 의미와 문서 구조가 그대로 남는다.