| name | writing-fixer |
| description | Use when the user wants Korean prose cleaned of AI tone, stiff old-fashioned (할아버지/훈장/공문서) tone, translationese, and excessive quotation marks - or asks to "글 다듬어", "자연스럽게", "AI 말투 제거", "할아버지 말투 빼", "deslop 한국어", or "writing-fixer". Removes as many AI and unnatural expressions as possible in one thorough pass while preserving meaning, code, math, and markup. Korean prose only. |
writing-fixer
한국어 산문을 사람이 쓴 글처럼 고친다. 한 패스에 AI 말투와 할아버지(딱딱한 공문서·훈장)체, 번역체, 과도한 따옴표를 최대한 많이, 정확하게 걷어낸다. 목표는 빠뜨리지 않고 한 번에 끝내는 것이다. 뜻과 코드, 수식, 마크업은 절대 바꾸지 않는다.
착지점: 두 극단 사이
고치는 글은 보통 두 방향 중 하나로 어긋나 있다. 둘 다 피하고 가운데로 모은다.
- AI 말투: 매끈한데 영혼이 없다. 상투어, 빈 수식어, 번역체, 스케어쿼트(장식 따옴표), 규칙의 삼, 공허한 비유, 친절 안내조. "겁먹을 거 없다", "이를 통해", "콕 집어 준다" 부류.
- 할아버지 말투: 굳고 예스럽고 훈계조다. 공문서체, 과한 한자어, 권한다/추천한다, 예스러운 어휘(곧장, 가닿다, 가늠하다, 낱말, 한 벌), "본 풀이/본인". "직접 붙잡고 끙끙대 본 다음에 펼쳐 보는 게 훨씬 남는다" 부류.
착지점은 담백한 강의체(하다체) 또는 맥락에 맞는 말투다. 사람이 차분히 설명하듯, 군더더기 없이.
적용 범위
한국어 산문(문서, 슬라이드 텍스트, README, 블로그, 강의자료, 주석)만 고친다.
절대 건드리지 않는다:
- 코드 블록(
```), 인라인 코드(백틱)
- 수식(
$...$, $$...$$) - 토큰 하나도 바꾸지 않는다
- SVG/HTML 태그와 속성(
<rect fill="..."> 등 <...> 전부, 속성 안 따옴표)
- YAML 프런트매터(title/subtitle 등의 따옴표는 문법이라 유지)
- 숫자, 변수명, 함수명, 알고리즘·기술 용어, 사실·주장·인과 관계
- callout 펜스(
::: {.callout-...}), 마크다운 헤딩 속성({background-color="..."})
원뜻 보존이 최우선이다. 애매하면 그대로 둔다. 없는 사실이나 수치를 만들어 넣지 않는다.
작업 순서 (한 패스에 최대치로)
- 문체 확인. 사용자가 이미 말투를 지정했거나 원문에서 분명하면 묻지 않고 바로 간다. 정말 모를 때만 한 번 묻는다(구어체/문어체, 종결어미, 강도). 되묻기를 반복하지 않는다.
- 범위 확정. 대상 파일·문단을 정한다. 지정된 범위 밖으로 나가지 않는다.
- 파일 전체를 처음부터 끝까지 읽는다. grep으로 대신하지 않는다. 이 스킬에서 고칠 것의 대부분은 특정 단어가 아니라 문장의 결이라 패턴 검색으로는 잡히지 않는다. 미묘한 AI 말투, 스케어쿼트, 규칙의 삼, 어색한 리듬, 할아버지체, 구구절절한 군더더기, 라벨과 캡션 남발은 전부 읽어야 보인다. 실제로 앞선 작업에서 마스터 grep이 1500줄짜리 자료에서 세 줄만 잡아냈는데, 정독으로는 수십 군데가 나왔다.
- Read 도구로 파일을 300줄 안팎씩 끊어 읽되 한 줄도 건너뛰지 않는다. 코드 블록과 SVG는 눈으로 지나가고 산문만 본다.
- 제목과 소제목도 본문과 똑같이 검토한다. 헤딩, callout 제목, 표 머리글, 그림 캡션, SVG 안의 라벨 문구까지 포함한다. 헤딩은 놓치기 쉬운데
~에서의 쓰임, ~에 대한 이해, OO 맛보기, -나? 의문형 같은 것이 그대로 남아 있는 경우가 많다.
- 한 덩이를 읽고 바로 고친 뒤 다음 덩이로 간다. 다 읽고 나중에 몰아 고치면 앞부분을 잊는다.
- 삭제 우선. 지워도 뜻이 안 상하는 것부터 지운다. 뻔한 도입·마무리, 빈 수식어, 메타 언급, 불필요한 영어 병기.
- 카테고리별 치환. 아래 카탈로그 순서대로 돈다(상투어 → 번역체 → 할아버지체 → 군더더기 → 구조 패턴).
- 따옴표 축소. 정책(아래)대로 장식 따옴표를 걷어낸다.
- 문법·피동. 전부다→전부이다 류 문법, 이중 피동, -되다 남용, 동사/형용사 종결, 에게/에를 잡는다.
- 리듬·말투 통일. 한 글에서 말투를 하나로, 문장 길이에 변화를 준다.
- 검증. 고친 파일을 처음부터 다시 읽어 어색한 곳이 남았는지 본다. 첫 패스에서 놓친 것이 반드시 나온다. 코드/수식/숫자 보존 확인(아래 체크리스트).
- (.qmd 등) 빌드·배포·커밋. 프로젝트 규칙대로.
도구 규칙: 산문 교정은 Edit로 정밀하게 한다. sed로 산문을 고치지 않는다(맥락을 깨뜨린다). 코드 슬롭(중복·죽은 코드)이 섞여 있으면 그건 별도 패스로 분리한다.
대용량·다파일 병렬 처리
파일이 크거나(수천 줄) 여러 개면 서브에이전트로 병렬 처리하면 빠르다. 단, 품질을 지키려면 스펙을 못 박는다.
- 각 에이전트에 맡은 파일을 처음부터 끝까지 읽으라고 못 박는다. grep으로 훑고 끝내는 것을 명시적으로 금지한다. "산문만, 코드/SVG/수식/숫자/속성 절대 금지, 뜻 불변, 애매하면 그대로" 규칙과 아래 카탈로그를 그대로 준다.
- 중복 내용이 있는 두 파일은 한 에이전트에 묶어 일관성을 지킨다.
- 에이전트가 끝나면 반드시 git diff로 검수한다(리뷰어 패스). 점검 항목: 균형 diff(삽입=삭제), 코드/SVG/수식 줄 변경 0건,
$ 토큰 add==remove, 가능하면 수식 토큰 MD5 일치.
금지 표현 카탈로그
A. AI 상투어 (삭제하거나 바로 본론)
| 금지 | 대체 |
|---|
| 살펴보겠습니다 / 알아보겠습니다 / 자세히 살펴보면 | (삭제, 바로 본론) |
| 이를 통해 / 이를 바탕으로 / 이를 기반으로 | (삭제하거나 "그래서") |
| 결론적으로 / 궁극적으로 / 종합적으로 | (삭제) |
| 주목할 만한 점은 / 흥미로운 점은 / 놀라운 것은 | (삭제, 바로 사실 서술) |
| ~라고 할 수 있다 / ~라고 볼 수 있다 | ~이다 (단정) |
| ~하는 데 있어 / ~의 관점에서 / ~라는 측면에서 | (삭제하거나 풀어서) |
| 핵심: / 정리: / 요약: / 핵심은 / 핵심 아이디어 | (라벨 빼고 바로 서술. 핵심은→중요한 건) |
| 콕 집어 준다 / 짚어 준다 | 정확히 설명한다 / 분명히 적는다 |
| 맛보기 / 살짝 보기 / 엿보기 (제목·헤딩) | 입문 / 기초, 또는 주제명만. (OO 맛보기→OO 입문 또는 OO 기초) |
B. 빈 수식어 (삭제 또는 구체화)
다양한, 폭넓은, 핵심적인, 근본적인, 본질적인, 혁신적인, 획기적인, 선도적인, 심층적으로, 포괄적으로, 체계적으로, 종합적으로, 보다 효과적인/효율적인(→더, 또는 수치), 한눈에(들어온다/보인다/알린다. 대개 지워도 뜻이 같다. 제목·SVG 라벨의 "~ 한눈에"도 삭제).
"다양한 분야에서 중요한 역할을 한다" → 실제로 어디에 쓰이는지 구체적으로. 근거 수치가 원문에 있으면 끌어 올리고, 없으면 비교 주장을 뺀다.
C. 번역체 동사·구문
| 금지 | 대체 | 비고 |
|---|
| 활용하다 (utilize) | 쓰다, 사용하다 | |
| 수행하다 (perform) | 하다, 처리하다 | |
| 제공하다 (provide) | 주다, 내놓다 | |
| 갖는다 / 갖고 있다 (have) | 있다 | "객체에 속성이 세 개 있다" |
| ~를 통해 / ~를 통한 (through) | ~로, ~로써 | "상태 정의로 푸는 탐색" |
| ~에 도달하다 (reach) | 닿다, 다다르다 | |
| 소멸하다 (vanish) | 사라지다, 없어지다 | |
| 존재하다 (exist) | 있다 | |
| 직면하다 (face) | 부딪히다, 겪다 | |
| 각 X에 대해 (for each) | X마다, X별로 | |
| ~에 참여한다 (participate) | ~에 쓸 수 있다, ~이/가 된다 | |
| ~에게 (무정물 to) | ~에 | 컴파일러에/함수에/시스템에 (사람·동물만 에게) |
| ~를 보고 ~한다 (look at and) | ~를 보면 / ~에 따라, 또는 직접 서술 | "결과를 보고 좁힌다"→"결과에 따라 좁힌다". 시험 지문은 "읽고"로 |
| 순서대로 본다 / 차례대로 본다 (in order) | 차례로 다룬다 / 하나씩 본다 | "다섯 가지를 순서대로 본다"→"다섯 가지를 차례로 다룬다" |
D. 할아버지 / 공문서 / 훈장체
| 금지 | 대체 |
|---|
| 본 풀이 / 본 문서 / 본인 | 이 풀이 / 이 문서 / 스스로 |
| 낱말 | 단어 |
| 곧장 | 바로 |
| 가닿다 | 닿다 |
| 가늠한다 | 잡는다, 짐작한다 |
| 한 벌 | 하나 |
| 권한다 / 추천한다 (훈계조) | 읽어 두면 좋다 / ~하는 편이 좋다 |
| 확정된 후 / 확정되면 | 반영된 뒤 / 정해지면 / 끝난 뒤 |
| 훈계조 ("직접 붙잡고 끙끙대 본 다음에 펼쳐 보는 게 훨씬 남는다") | 담백하게 ("먼저 스스로 풀어 본 뒤에 펼쳐 보는 편이 좋다") |
| ~가 갈린다 / ~를 가른다 (분기·결정의 문어 비유) | 무엇이 어떻게 달라지는지 직접 서술이 우선. 그냥 "달라진다"로만 바꾸면 공허한 필러가 남는다. 바로 뒤에 수식·표가 오면 그 사실(점화식·값)로 대체하거나 삭제. 분류·분기 동사로 쓴 것은 "나눈다"로(실행 흐름을 가른다→나눈다, 자료형을 가르는 기준→나누는 기준). "짝수와 홀수를 가르다"처럼 문자 그대로 나누는 용법은 유지 |
| 과한 한자어 일반 | 쉬운 우리말 |
E. 캐주얼 안심조 · 드라마틱 의인화
AI가 흔히 쓰는 입에 발린 안심과 과장된 의인화를 뺀다.
- "겁먹을 거 없다", "걱정 마라", "어렵지 않다" 같은 안심조 → 사실만. ("문제는 9개지만 접근하는 방식은 모두 같다.")
- "코드가 무너진다", "서로 따로 논다", "여기서 죽는다" 같은 과장 의인화 → 담담하게. (코드가 무너지지 않는지→답이 어긋나거나 오류가 생기지 않는지, 서로 따로 놀면 안 된다→서로 맞물려야 한다.)
- "거의 받아쓰기다", "그냥 다 해 보면 된다" 같은 구어 비유 → 강의체. (받아쓰기다→거의 기계적으로 작성한다.)
- "~로 내려가도 된다", "급하면 바로" 같은 친절 안내조 → 사실 서술. (급하면 바로 ...로 내려가도 된다→... 절에 정리해 두었다.)
- "직접 채워 보면", "직접 세 보면", "직접 짜 본다" 같은 "직접 ~해 보면/본다" 훈장 안내조 → "직접"을 빼고 담백하게. (직접 채워 보면 값이 나온다→채워 보면 값이 나온다. 직접 세다 보면→세어 보면.) 단, "직접 만든 스택"처럼 시스템 것과 대비하는 "직접"은 뜻이 있으니 유지한다.
- 안심조 꼬리: 사실을 말한 뒤 "~이니 새로울 것은 없다", "~라고 보면 낯설지 않다", "~에는 이걸로도 된다" 같은 다독임을 덧붙이는 꼬리 → 꼬리를 자르고 사실만. (예전 방식도 마찬가지였으니 새로울 것은 없다→예전 방식도 마찬가지였다. 서로 대응한다고 보면 낯설지 않다→서로 대응한다. 짧은 실험에는 이걸로도 된다→짧은 실험에 알맞다.)
F. 습관적 군더더기
| 금지 | 대체 |
|---|
| 충분하다 (습관적으로 붙는 것) | 된다 / 넉넉하다 / 구체적으로 |
| 안전하다 (막연한 보증) | 구체 결과로: 오류가 나지 않는다, 값이 어긋나지 않는다, 실수를 막는다 |
| 웬만하면 | 대부분 / 특별한 경우가 아니면 |
| 한마디로 | 정리하면 / 즉 (또는 삭제) |
| 또한 / 게다가 / 나아가 / 더욱이 (문장마다) | (절반은 삭제, 접속사 없이 잇기) |
| 초반에는 / 처음에는 충분하다 | "처음에는 이 정도만 알아도 된다" 같은 구체 표현 |
| ~하기 마련이다 (남발) | (줄이기) |
| 첫째로 / 둘째로 / 셋째로, 첫째, / 둘째, (열거) | 번호 목록(1. 2. 3.)이나 "하나는 ~, 다른 하나는 ~", "먼저 ~. 다음으로 ~."로. first/second 직역투 |
| 그러니 / 그러므로 / 따라서 (문단마다 반복) | 절반은 삭제하거나 접속 없이 잇는다. 한 문단에 인과 접속이 두 번 넘으면 과하다 |
G. 구조적 AI 패턴
- 규칙의 삼: 나열을 무조건 셋으로 맞추지 않는다. 둘이면 둘, 넷이면 넷. 원문에 근거 없는 셋째 항목을 지운다.
- 공허한 상징·비유: "관통하는 줄기", "새로운 지평", "이정표", "패러다임의 전환", "여정". 풀어서 사실로. (관통하는 줄기는 두 개다→크게 두 갈래다.)
- 홍보성 어휘: 업계를 선도하는, 강력한, 압도적인, 차세대, 최고 수준의 → 구체 사실/수치 또는 삭제.
- 부정 평행: "효율적일 뿐만 아니라 생산적이기도", "쉽고 간단하다" 같은 동의어 병렬 → 한쪽만.
- 피상적 -하면서/-함으로써: 실제 메커니즘 없이 인과를 얼버무리는 구문 → 진짜 원리로 바꾸거나 삭제.
- 메타 언급: "이 글에서는 ~다룬다", "앞서 말했듯이", "다음 절에서는" → 대부분 삭제해도 본문이 자립한다.
- 대조 캡션("같은 A, B로 C가 달라진다"): "같은 입력, 다른 결과" 식 대비를 명사구로 압축한 슬라이드 캡션투. 풀어서 평범한 문장으로. (같은 재료, 섞는 순서로 결과가 달라진다→섞는 순서에 따라 결과가 달라진다.)
- 모호한 출처: "일부 전문가들은", "연구에 따르면"(출처 없음) → 구체 출처 명시 또는 삭제.
- 과도한 목차(TOC): AI는 짧은 글에도 목차·색인을 붙인다. 한 화면에 들어오는 문서엔 목차를 빼고, 긴 문서도 모든 헤딩을 그대로 베낀 자동 나열식 목차는 줄인다. (프로젝트 규칙이 목차 금지면 그대로 따른다.)
- 정해진 양식(보일러플레이트): 모든 글을 "개요 → 배경 → 본론 → 결론"이나 "## 들어가며 / ## 마치며" 틀에 억지로 끼우지 않는다. 섹션 구조는 내용이 정한다. 본문을 한 번 더 요약만 하는 빈 "## 개요"는 지운다.
- 불필요한 서론·도입부: "이 문서에서는 ~를 다룬다", "## 들어가며", "시작하기 전에", "본격적으로 살펴보기 전에" 같은 도입 단락은 대개 삭제해도 본문이 자립한다. 바로 본론으로 들어간다.
- 쓸데없는 노트·캡션: 표나 섹션 앞뒤에 "이건 ~로 푼다", "학기 중 푼 ~", "여기서는 ~를 본다", "아래 표는 ~" 같은 틀 설명 캡션을 습관적으로 붙이지 않는다. 제목과 내용으로 충분하면 노트를 통째로 뺀다. 구체적 사실·수치·함정·팁이 든 노트만 남긴다.
H. 구구절절한 설명, 라벨 남발, 캡션·주석 과잉
읽는 사람이 이미 아는 것을 다시 말하거나, 내용에 이름표를 붙여 두는 습관이다. 지우면 대개 글이 좋아진다.
- 구구절절한 설명: 한 가지를 말해 놓고 같은 말을 표현만 바꿔 두세 번 더 하는 것. 한 번만 말하고 끝낸다. 예를 들어 "A는 B이다. 즉 A를 하면 B가 된다. 다시 말해 A와 B는 같다"는 첫 문장만 남긴다.
- 뻔한 부연: "즉", "다시 말해", "쉽게 말하면", "정리하면"으로 시작하는 문장이 앞 문장을 되풀이만 하면 지운다. 진짜로 새 정보를 더할 때만 남긴다.
- 과잉 라벨: "핵심:", "정리:", "요약:", "참고:", "주의:", "중요:", "팁:" 같은 이름표를 문장 앞에 붙이지 않는다. 내용으로 드러나게 쓴다. 굵게(
**)로 라벨을 흉내 내는 것도 마찬가지다. **개념 정의**:, **예시**:, **결론**: 전부 뺀다.
- 모든 문단에 굵은 머리말 달기: 목록 항목마다
**...**로 시작하는 라벨을 다는 것은 항목이 실제로 병렬적인 사전 항목일 때만 쓴다. 서술형 문단에는 붙이지 않는다.
- 자명한 캡션: 그림이나 표 바로 옆에 그림이 이미 보여 주는 것을 다시 적지 않는다. "아래 표는 각 알고리즘을 비교한 것이다", "위 그림에서 볼 수 있듯이" 같은 문장은 지운다. 캡션은 그림에 없는 정보(수치의 출처, 읽는 법의 함정)를 담을 때만 쓴다.
- 표·코드 앞뒤의 안내 문장: "다음 표를 보자", "아래 코드는 이를 구현한 것이다", "이제 코드를 살펴본다" 부류. 표와 코드는 스스로 보인다.
- SVG·그림 안의 잔소리: 다이어그램 안에 설명 문구를 여러 줄 넣지 않는다. 그림이 못 담는 한 줄만 남긴다.
- 중복 요약 섹션: 본문을 한 번 더 줄여 놓은 "## 정리", "## 요약", "## 마치며"는 새 정보가 없으면 통째로 지운다.
- 판단 기준: 그 문장을 지웠을 때 독자가 잃는 정보가 있는지 본다. 없으면 뺀다.
I. 문장부호
| 금지 | 대체 |
|---|
| em dash (—) | 쉼표, 괄호, 마침표 |
| en dash (–) | 쉼표, 하이픈(-), "부터/까지" |
| 물결표(~) 범위 표기 | 하이픈(-): 34일→3-4일, 48주→4-8주 (물결표 범위는 한국에서만 통용, 쓰지 않는다) |
| 가운뎃점 (·) | 쉼표, "및", "과/와" (SVG 라벨이라도 가운뎃점은 쉼표로) |
| 둥근 따옴표 (" " ' ') | 곧은 따옴표 (" " ' ') |
| 말줄임표(...) 남용 | 꼭 필요한 곳만 |
| 느낌표(!) 남발 | 꼭 필요할 때만 |
| 쉼표(,) 남발 | 줄인다. 한국어는 영어·AI 번역문보다 쉼표를 훨씬 적게 쓴다. 명사 나열은 와/과/이나/하고로 잇고("무게 w, 가치 v인 물건"→"무게 w와 가치 v를 지닌 물건"), "~하고, ~하며, ~한다"식 긴 연결어미 나열은 문장을 끊어 나눈다. 곧/즉/다시 말해 앞 쉼표는 대개 뺀다. (조건절·종속절 뒤 꼭 필요한 쉼표, 코드·수식·표 안 쉼표는 유지) |
J. 한국어 문법
- 서술격 조사 누락: 받침 있는 명사 뒤는 "이다". 전부다→전부이다, 객체다→객체이다, 함수다→함수이다. (받침 없으면 그대로: 하나다 OK이지만 문어체는 하나이다.)
- 이중 피동(틀림): 되어진다, 읽혀진다, 보여진다, 쓰여진다 → 된다, 읽힌다, 보인다, 쓰인다.
- 불필요한 피동 → 능동: 계산된다→계산한다, 출력된다→출력한다, 저장된다→저장한다, 실행된다→실행한다, 변환된다→바뀐다, 사용된다→쓴다.
- -되다 남용: 추정된다→추정할 수 있다, 요구된다→필요하다, 기대된다→기대할 수 있다.
- 동사/형용사 종결: 동사는 -ㄴ다/-는다(반환한다, 돌아간다, 맞는다), 형용사는 -다(좋다, 빠르다), 있다/없다는 -다.
- 기본형을 문장 끝에 그대로 두지 않는다: 사용하다.→사용한다. / 발생하다.→발생한다.
- 의문문 종결 "-나" → "-는가"(문어체): 자문·수사 의문을 "-나"로 끝내면 구어·예스러운 말투다. 문어체 하다체는 "-는가/-은가/-ㄴ가"가 맞다. 헤딩이든 본문이든, 심지어 SVG/표 라벨의 의문 문구까지 모두 고친다. 잡나→잡는가, 정해지나→정해지는가, 쪼개나→쪼개는가, 어디서 왔나→어디서 왔는가, 무엇을 제출하나→무엇을 제출하는가, 언제 쓰나→언제 쓰는가. (단, 코드 주석 안의 "되나 시도" 같은 단편은 코드라 건드리지 않는다. "가나 마나"처럼 양보의 "-나"도 의문이 아니라 유지.)
따옴표 정책 (중요)
따옴표가 많으면 번역체로 읽힌다. "지나친 인용표현"을 대폭 줄인다. 판단 기준:
- 장식 따옴표(스케어쿼트) - 제거: 평범한 단어·개념·구를 강조하려 감싼 것. 따옴표 두 개만 지우고 조사만 다듬는다. 안의 내용은 절대 삭제하지 않는다.
상태를 "현재 위치"로 둔다 → 상태를 현재 위치로 둔다입력은 "크기 먼저, 데이터 나중" 순서다 → 입력은 크기를 먼저 주고 데이터를 나중에 준다
- 정의·판정 따옴표 - 기본 제거:
x를 "..."라 하면, f(n)은 "..."이다 꼴. 문장이 따옴표 없이도 자연스러우면(대개 그렇다) 따옴표를 뺀다.
이 값을 "지금까지의 최대 합"이라 하면 → 이 값을 지금까지의 최대 합이라 하면- 빼면 진짜로 모호해지는 극히 드문 경우에만 유지한다.
- 항상 유지: 진짜 인용(논문·책 제목, 인물 발언, 규격 문구), 코드·문자열 리터럴 예시(
"Hello", {"수빈": 85}, "({[]})"), 코드/SVG/속성 안 따옴표, YAML 제목.
따옴표도 읽으면서 판단한다. 같은 따옴표라도 인용이면 남기고 강조면 빼야 하므로, 목록으로 뽑아 놓고 일괄로 처리할 수 없다.
검증 체크리스트
교정 뒤 반드시 확인한다.
- 고친 파일을 처음부터 다시 읽는다. 이것이 유일한 실질 검증이다.
git diff --stat → 삽입 수 ≈ 삭제 수(같은 줄 교정이면 균형).- 코드/SVG/수식 보존:
git diff -U0 결과에 코드펜스·<rect|circle|path|svg>·printf가 새로 바뀐 줄이 없어야 한다(허용한 SVG 라벨 가운뎃점 교체 제외).
- 수식 불변: 변경 줄의
$ 개수가 add측과 remove측이 같은지. 더 엄밀히는 $...$ 토큰 MD5 일치.
- 뜻 불변: 수치·고유명사·주어/목적어/동사 역할이 그대로인지.
grep을 쓰지 않는다
이 스킬에는 마스터 grep이 없다. 예전에는 있었는데, 검색이 잡아내는 것이 실제 문제의 극히 일부라서 뺐다. 1500줄짜리 강의 자료에서 grep은 세 줄을 잡았고 정독은 수십 군데를 잡았다.
grep으로 안 잡히는 것들이 정확히 고쳐야 할 것들이다. 같은 말을 두 번 하는 문단, 그림이 이미 보여 주는 캡션, 문장 앞에 붙은 이름표, 앞뒤가 서로 부딪히는 설명, 어색한 리듬, 제목의 번역투. 전부 문맥을 읽어야 보인다.
카탈로그의 표에 있는 단어를 검색해 훑고 싶은 유혹이 들면, 그것은 파일을 읽기 싫다는 뜻이다. 읽는다.
빌드 · 배포 · 커밋 (프로젝트 규칙이 있으면 따른다)
- 프로젝트 루트의
CLAUDE.md(또는 .context/)에 한국어 규칙·예시 이름 풀·빌드 명령이 있으면 그것을 우선한다.
.qmd를 고쳤으면 quarto render로 HTML을 다시 빌드한다. 여러 파일은 개별로 렌더한다(한 명령에 여러 파일을 주면 첫 파일로 합쳐질 수 있다).- PDF가 필요하고 LaTeX가 없으면 Chrome headless로 뽑는다. 멈춤 방지로 워치독(예: 40초 뒤 kill)을 건다. MathJax/SVG 렌더 시간을 위해
--virtual-time-budget을 준다. --run-all-compositor-stages-before-draw가 멈춤을 유발하면 뺀다.
- 정적 배포(예: static.example.com)는 기존 경로(
.deploy-url)를 재사용해 학생 URL을 유지한다. 업로드 전 .apikey가 든 _oj 등 민감 디렉터리를 제외한 임시 사본에서 sync한다.
- 커밋은 세분화(한 영역 한 커밋), 시맨틱 + gitmoji, GPG 서명(
-S), Co-Authored-By 금지. git pull --rebase 후 push. 작업과 무관한 변경(예: NFS 임시 파일 삭제)은 stash로 빼 두고 rebase한다.
좋은 예 / 나쁜 예
좋다: "이 문서의 AI 말투와 과한 따옴표를 다듬어 줘."
좋다: "이 글이 너무 할아버지 같아. 강의체로 자연스럽게."
나쁘다(범위 밖): "이 코드의 중복 로직을 정리해 줘." → 코드 슬롭은 코드 정리 스킬로.
이번 작업에서 검증된 교정 (before → after)
실제로 사람이 OK한 교정들이다. 패턴을 익히는 데 쓴다.
| before | after | 이유 |
|---|
| 문제가 많다고 겁먹을 거 없다. | 문제는 많지만 접근하는 방식은 모두 같다. | 안심조 |
| 코드는 거의 받아쓰기다 | 코드는 거의 기계적으로 작성한다 | 구어 비유 |
| 먼저 직접 붙잡고 끙끙대 본 다음에 펼쳐 보는 게 훨씬 남는다 | 먼저 스스로 풀어 본 뒤에 펼쳐 보는 편이 좋다 | 훈장 훈계조 |
| 문제 풀이만 급하면 바로 "..."로 내려가도 된다 | ... 절에 정리해 두었다 | 친절 안내조 + 따옴표 |
| 이 여섯 개가 서로 따로 놀면 안 된다 | 이 여섯 가지는 서로 맞물려야 한다 | 구어 의인화 |
| 길게 늘어놓으면 오히려 핵심이 묻힌다 | 배경이 길면 무엇을 구하는 문제인지가 잘 드러나지 않는다 | AI 클리셰 |
| 마지막 문장은 출력을 콕 집어 준다 | 마지막 문장에서는 무엇을 출력할지 정확히 설명한다 | 콕 집어→정확히 |
| 입력은 보통 "크기 먼저, 데이터 나중" 순서로 간다 | 입력은 보통 크기를 먼저 주고 데이터를 나중에 준다 | 장식 따옴표 |
| 끝에 줄바꿈 하나 차이로도 오답이 나니까 ... 똑같이 맞춰 둔다 | 공백이나 줄바꿈이 하나만 달라도 오답으로 처리되므로 ... 정확히 같은 형식으로 작성한다 | 장황한 구어 인과 |
| 경계에서 코드가 무너지지 않는지 본다 | 경계에서 답이 어긋나거나 오류가 생기지 않는지 확인한다 | 드라마틱 의인화 |
| 문제들을 관통하는 줄기는 두 개다 | 문제는 크게 두 갈래다 | 공허한 비유 |
| 안쪽 반복문 방향이 전부다 | 안쪽 반복문 방향이 전부이다 | 서술격 조사 |
| 배열로 옮기면 웬만하면 풀린다 | 배열로 옮기면 대부분 풀린다 | AI말투 |
| 어떤 문제든 충분하다 | 어떤 문제든 넉넉하다 | 충분하다 남용 |
| 한 가지 약속만 머릿속에 두면 충분하다 | 한 가지 약속만 기억하면 된다 | 충분하다 남용 |
| 보조 장치도 갖고 있다. 이를 활용한다 | 보조 장치도 있다. 이를 쓴다 | have 직역 + 활용 |
| 이 값을 "최종 점수"라 하면 | 이 값을 최종 점수라 하면 | 정의 따옴표 제거 |
| 한마디로 조건에 맞는 수를 센다 | 정리하면 조건에 맞는 수를 센다 | 군더더기 연결어 |
| 검색을 통한 확인 | 검색으로 하는 확인 | 통한 직역 |
| 옵션 하나로 동작이 갈린다 | 옵션 하나만 바꿔도 동작이 달라진다 | 갈린다 문어 비유 |
| 자료구조 하나로 성격이 갈린다 | 자료구조 하나로 성격이 달라진다 | 갈린다 문어 비유 |
| 표를 직접 채워 보면 값이 나온다 | 표를 채워 보면 값이 나온다 | 직접 훈장 안내조 |
| 결과를 보고 범위를 좁힌다 | 결과에 따라 범위를 좁힌다 | ~를 보고 번역투 |
| 다섯 가지를 순서대로 본다 | 다섯 가지를 차례로 다룬다 | 순서대로 본다 번역투 |
| 영업일 기준 3~4일 내에 답변드립니다 | 영업일 기준 3-4일 내에 답변드립니다 | 범위는 하이픈, 물결표 금지 |
| OO 맛보기 (제목) | OO 입문 | 맛보기 캐주얼 헤딩 |
| 같은 재료, 섞는 순서로 결과가 달라진다 | 섞는 순서에 따라 결과가 달라진다 | 대조 캡션 압축 |
| 왜 통째로 읽나 | 왜 통째로 읽는가 | 의문문 -나→-는가 |
| 어디서 값이 정해지나 | 어디서 값이 정해지는가 | 의문문 -나→-는가 |
| 언제 쓰나 (표 헤더) | 언제 쓰는가 | 의문문 -나→-는가 |
| 설정에 따라 결과가 달라진다 (표·수식 바로 앞) | 어떤 설정이 어떤 결과를 내는지 바로 뒤 표·수식의 사실로 서술하거나 삭제 | 공허한 "달라진다" 필러를 실제 사실로 |
| 예전 방식도 마찬가지였으니 새로울 것은 없다 | 예전 방식도 마찬가지였다 | 안심조 꼬리 |
| 서로 대응한다고 보면 낯설지 않다 | 서로 대응한다 | 안심조 꼬리 |
| 짧은 실험에는 이걸로도 된다 | 짧은 실험에 알맞다 | 안심조 |
| 네 가지 한눈에 (그림 라벨) | 네 가지 | 한눈에 빈 수식어 |
| 무엇을 돌려주는지 한눈에 알린다 | 무엇을 돌려주는지 알린다 | 한눈에 빈 수식어 |
| 실행 흐름을 가른다 | 실행 흐름을 나눈다 | 가른다→나눈다 |
| 없는 키를 건드릴 때 안전하다 | 없는 키를 건드려도 오류가 나지 않는다 | 안전하다→구체 결과 |
