korean-rewrite
한국어를 session에서 처음 쓰기 전에 부르고, 같은 session에서 이미 불렀으면 다시 부르지 않습니다. 다만 대화를 압축한 뒤 context에 이 skill의 본문이 없으면 다시 부릅니다. 답변, 문서, README, 코드 주석, 사용자에게 보이는 메시지, commit 메시지, PR 설명, 번역에 모두 적용합니다. 처음부터 한국어로 생각해 업무 문서처럼 격식 있는 문어체로 쓰고 번역투와 AI가 자주 쓰는 표현을 걸러 냅니다. 직접 쓰는 글에서는 독자에게 필요한 내용만 고릅니다.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- korean-rewrite
- description
- 한국어를 session에서 처음 쓰기 전에 부르고, 같은 session에서 이미 불렀으면 다시 부르지 않습니다. 다만 대화를 압축한 뒤 context에 이 skill의 본문이 없으면 다시 부릅니다. 답변, 문서, README, 코드 주석, 사용자에게 보이는 메시지, commit 메시지, PR 설명, 번역에 모두 적용합니다. 처음부터 한국어로 생각해 업무 문서처럼 격식 있는 문어체로 쓰고 번역투와 AI가 자주 쓰는 표현을 걸러 냅니다. 직접 쓰는 글에서는 독자에게 필요한 내용만 고릅니다.
03 SKILL.md 正文
한국어 작성 규칙
이 프로젝트의 hook은 Claude가 한국어를 쓰기 전에 이 session에서 이 skill을 불렀는지 확인합니다. 한 번 부르면 같은 session에서 쓰는 답변, 파일, 메시지, commit에 모두 적용합니다. 대화를 압축한 뒤 context에 이 skill의 본문이 없으면 다시 부릅니다. 다 쓴 글만 보여 주고, 이 skill이나 검사를 거쳤다는 말은 하지 않습니다.
<!-- register:begin -->
말투: 합니다체. 서술은 ~합니다로, 요청은 ~해 주십시오로 끝냅니다. ~해요, ~하세요 같은 해요체를 섞지 않습니다. 예: cache 무효화 후 재deploy 필요 → cache를 무효화한 뒤 다시 deploy해야 합니다.
<!-- register:end -->
번역투
번역투는 외국어(주로 영어와 일본어) 원문의 낱말, 문장 구조, 표현 방식을 그대로 따라 쓴 표현입니다. 같은 뜻의 자연스러운 한국어 표현이 있는데도 원문의 흔적이 드러납니다. 번역투는 쓰지 않습니다.
- 판단 기준은 같은 뜻의 더 자연스러운 한국어 표현이 있는지입니다. 있으면 번역투로 보고 고칩니다.
- 사전에 오른 정상 용법으로 관계와 뜻을 밝히는 표현은 번역투가 아닙니다. 외국어에서 왔다는 이유만으로 고치지 않습니다.
- 정상 용법을 피하려고 명사를 나열하거나 뜻을 흐리지 않습니다. 고칠 표현은 아래 '고칠 표현' 절에 있고 그대로 둘 표현은 그 절의 '번역투가 아닌 표현'에 있습니다.
처음부터 한국어로 생각하는 원칙
- 요청을 읽는 순간부터 한국어로 생각합니다. 무엇을 쓸지 정하는 생각도 한국어로 합니다. 영어로 계획을 세운 뒤 문장마다 옮기면 영어 문장 구조가 그대로 남습니다.
- 영어 자료, 코드, log를 읽었어도 요점을 한국어로 정리한 뒤 씁니다.
- 프로젝트가 영어로 이름 붙인 내부 개념은 독자가 화면에서 보는 말로 풀어 씁니다. IT 용어의 표기는 아래 '용어 표기' 절을 따릅니다.
내용 선정
Claude가 무엇을 쓸지 정하는 글에 적용합니다. 사용자가 준 글을 옮기거나 다듬을 때는 내용을 빼거나 덧붙이지 않습니다.
- 독자와 목적부터 정합니다. 누가 어디서 이 글을 읽는지, 읽은 뒤에 무엇을 알거나 할 수 있어야 하는지 정합니다. 웹 페이지 방문자, 앱 이용자, 공개 repository에 처음 온 사람은 프로젝트 내부 사정을 모르고 알 필요도 없습니다.
- 독자에게 필요한 내용만 고릅니다. 대화, CLAUDE.md, 설정 파일, commit 기록, 작업 메모에서 알게 된 사실은 글감일 뿐입니다. 문장마다 그 문장이 없으면 독자가 무엇을 모르게 되거나 못 하게 되는지 따져 보고 잃는 것이 없으면 그 문장을 지웁니다. 글쓴이나 사이트 주인 소개, 작업 경위, 내부 구성, 누가 무엇을 정했는지는 독자가 찾는 내용일 때만 씁니다. 고르면서 뺀 내용을 설명하는 문단은 덧붙이지 않습니다.
- 독자가 이해하는 데 필요한 설명은 채웁니다. 메모나 요점을 주고 블로그 글, 안내서, 소개 글처럼 독자가 배우는 글을 써 달라고 요청하면 메모를 문장으로 옮기는 데서 끝내지 않습니다. 메모의 사실마다 독자가 알아야 할 배경, 원리, 결과의 의미를 일반 지식으로 풀어 씁니다. 예를 들어 메모에 환율이 올라 수입 원가가 늘었다고 적혀 있으면 환율이 원가에 왜 영향을 주는지 설명합니다. 이런 설명은 지어낸 사실이 아닙니다. 메모에 없는 수치, 날짜, 사람, 실제 코드와 설정, 팀의 결정과 계획은 지어내지 않습니다. 메모의 수치로 계산한 값은 씁니다. 판매량이 200개에서 250개로 늘었으면 25% 늘었다고 씁니다. 설명하려고 만든 예는 실제 사례가 아니라고 밝힙니다. 짧게 써 달라고 하면 되풀이한 내용을 줄이고 독자가 이해하는 데 필요한 설명은 남깁니다.
- 공개하는 글에는 내부 정보와 개인 정보를 넣지 않습니다. 공개하는 글은 웹 페이지, 공개 repository의 문서와 commit 메시지, release note, 앱 스토어 설명, 이용자 공지입니다. 이런 글에는 개발 server와 staging server의 주소, 내부 host 이름과 IP, 클라우드 계정과 bucket 이름을 쓰지 않습니다. Local 경로, 사내 채널과 사내 issue 번호, 비공개 프로젝트 이름, 비밀번호 관리 도구의 항목 이름, 사내 담당자 이름도 쓰지 않습니다. 사용자나 사이트 주인의 실명, 직업, 소개도 사용자가 넣으라고 하지 않았으면 쓰지 않습니다. 빠짐없이 쓰려고 내부 사정을 드러내지 않습니다. 개발 server에도 같은 분석 도구가 켜져 있다는 사실은 방문자가 읽는 처리방침에 들어갈 내용이 아닙니다.
- 글 종류마다 정해진 형식과 용어를 따릅니다. 개인정보 처리방침처럼 법령과 기관 지침이 항목을 정한 글은 그 항목 이름과 용어를 씁니다. Release note, 공지, README처럼 관례가 있는 글은 아래 '글 종류별 관례'를 따릅니다.
- 두 언어로 쓰는 글은 언어마다 따로 씁니다. 영어 문단과 한국어 문단을 나란히 두는 글에서도 한국어 문단은 영어 문장을 옮기지 않고 정한 내용으로 처음부터 씁니다. 두 문단에 담긴 사실만 같으면 되고 문장 수와 순서는 맞추지 않습니다.
개인 웹사이트의 개인정보 처리방침 첫 문단을 고친 예입니다.
example.com은 홍길동의 개인 profile page이며 회원 가입과 입력 양식이 없습니다. 오류를 찾고 page를 어떻게 쓰는지 알아보려고 아래 두 도구로 방문 기록을 모읍니다. 시험용 사본인 dev.example.com도 같은 방식으로 기록합니다. → 이 사이트에는 회원 가입과 입력 양식이 없습니다. 오류를 찾고 방문자가 페이지를 어떻게 이용하는지 알아보려고 아래 두 도구로 방문 기록을 모읍니다.
방문자는 처리방침 첫머리에서 사이트 주인 소개를 찾지 않고 개발 server가 있는지도 궁금해하지 않습니다. 개발 server 주소는 공개하면 안 되는 정보입니다. 시험용 사본은 test copy를 낱말마다 옮긴 말입니다. 처리방침은 일반 독자가 읽는 글이므로 page는 페이지로 씁니다.
격식 있는 문어체
답변을 포함한 모든 글을 업무 문서처럼 격식 있는 문어체로 씁니다. 채팅 답변도 동료에게 말하듯 쓰지 않고 같은 문체로 씁니다. 문장 끝만 위 말투 문구를 따릅니다. 해요체로 쓸 때도 낱말과 문장 구조는 이 절을 따릅니다.
- 일상 한자어는 그대로 씁니다.
변경,동일,현재,해당,기존,확인,제공,진행,완료,유지,적용,재시작,이후,이전을 고유어나 구어로 바꾸지 않습니다.설정을 바꾼 뒤에도 나머지 값은 지금과 같습니다.→설정을 변경한 뒤에도 나머지 값은 현재와 동일합니다. 추가하다,측정하다,호출하다,제거하다처럼 개발 문서에서 흔히 쓰는 한자어 동사는 그대로 씁니다. 고유어로 바꾸면test를 더하다,효과를 재다처럼 목적어와 맞지 않는 말이 되기 쉽습니다.- 한자 관형사와 어려운 한자어는 쓰지 않습니다.
본 PR→이 PR,타 모듈→다른 module,동 함수→같은 함수,제고→높이다,향후→앞으로,익일→다음 날,금번→이번,상이→다르다,당해→해당,제반→모든,소정의→정해진,의거→따라.본 PR은 타 모듈의 동 함수 호출을 제거하여 성능을 제고합니다→이 PR은 다른 module에서 같은 함수를 호출하던 코드를 제거하여 성능을 높입니다. - 구어 표현은 쓰지 않습니다.
-구요,-길래,되게,좀,근데, 접속 부사그러니까가 여기에 듭니다. 접속 부사로는하지만보다그러나를 권합니다. 일반 어휘를 외국어 음차로 쓰지 않습니다.컨펌 부탁드립니다→확인해 주십시오. - 고유어를 한자어로 바꿀 때는 뜻과 앞뒤 말에 어울리는지 확인합니다.
현재는 구어 표현과 어울리지 않으므로지금 바로 server를 재시작해 주십시오의지금을현재로 바꾸지 않습니다. 이외와외는관계자 이외처럼 앞에 꾸미는 체언이 있을 때 씁니다. 꾸미는 말이 없으면그 밖의를 씁니다. 예:기존 model ID에 대한 요청은 model만 변경되고 그 밖의 처리 조건은 현재와 동일합니다.- 사람이 하는 일은 능동형으로 쓰고 시스템의 상태가 바뀌는 일은
-되다로 씁니다.파일이 저장됩니다,model만 변경되고처럼 씁니다. ~하는 바입니다,~할지어다같은 예스러운 말투는 쓰지 않습니다.
용어 표기
개발자가 읽는 글에서는 IT와 공학 용어를 영어 원어로 씁니다. 답변, 개발 문서, README, commit 메시지, PR, issue, 코드 주석, 검사기와 hook이 출력하는 메시지가 여기에 듭니다. 음차(커밋, 머지, 리포지토리)와 번역어(저장소, 병합, 배포)를 모두 쓰지 않습니다.
- 영어로 쓰는 용어 가운데 자주 나오는 것은 다음과 같습니다. 목록에 없는 IT와 공학 용어도 영어로 씁니다. 제품 이름, 고유명사, 약어가 아니면 소문자 원형으로 쓰고 복수형으로 바꾸지 않습니다.
- Git과 협업:
repository,repo,commit,branch,push,pull,merge,rebase,clone,fork,pull request,PR,issue,review,code review,patch,tag,release - Build와 deploy:
build,bundle,compile,deploy,rollback,rollout,pipeline,workflow,artifact,script,staging,production,migration - Test:
test,회귀 test,fixture,mock,mocking,coverage,lint,linter,debugging - 실행 환경:
server,client,process,thread,event,handler,callback,queue,worker,scheduler,trigger,step,job,container,image,cluster,node,instance,region,network,proxy,endpoint,port,domain,certificate,secret,runtime,timeout,storage,snapshot,backup - Data:
data,database,schema,query,record,table,cache,caching,log,logging,monitoring,metric,dashboard,alarm,payload,connection pool - 코드 구성:
directory,folder,package,library,module,dependency,framework,component,interface,template,resource,target,architecture,rendering,frontend,backend,refactoring,option,flag,parameter,argument - 도구:
console,terminal,shell,hook,skill,agent,subagent,plugin,model,prompt,session,token,context,browser,cookie,login,logout,output style,transcript
- Git과 협업:
- 문장, 제목, 목록 항목, 표 칸이 영어 낱말로 시작하면 그 낱말의 첫 글자를 대문자로 씁니다. 굵은 글씨로 쓴 항목 이름 바로 뒤에 오는 낱말도 같습니다.
commit하기 전에 test를 실행합니다→Commit하기 전에 test를 실행합니다,bug와 제안은 Issues에 남겨 주십시오. pull request를 환영합니다.→Bug와 제안은 Issues에 남겨 주십시오. Pull request를 환영합니다.,## skill 목록→## Skill 목록처럼 고칩니다. 문장 가운데에서는 소문자 원형으로 씁니다. 코드, 명령, 경로, 파일 이름은 백틱으로 감싸 원문 그대로 둡니다.npm,macOS,iOS처럼 공식 표기가 소문자로 시작하는 이름도 첫머리에서 그대로 둡니다. 풀은 pull,분기는 branch,이미지는 container image,테이블은 database table,잡은 job을 뜻할 때만 영어로 바꿉니다.정규식은regex나정규 표현식으로 씁니다.- 일반 어휘는 한국어로 씁니다. 확인, 검증, 검사, 요청, 응답, 설정, 알림, 조건, 설치, 실행, 출력, 입력, 명령, 경로, 환경 변수, 규칙, 문서, 답변, 질문이 여기에 듭니다.
- 완전히 정착한 일반어는 한글로 둡니다. 파일, 프로젝트, 버전, 클라우드, 메시지, 프로그램, 컴퓨터, 인터넷, 이메일, 앱, 웹, 메뉴, 버튼, 화면이 여기에 듭니다.
- 제품 이름, 고유명사, 약어, 코드, 명령, 경로, 설정 키, 환경 변수는 원문 그대로 둡니다. GitHub, Claude Code, Node.js, PR, API, CI,
npm run gate가 여기에 듭니다. - 조사는 그 용어를 한글로 읽은 소리에 맞춥니다.
commit을,cache를,model로,hook을,test를,server를,data를처럼 씁니다. -하다와-되다는 붙여 씁니다.deploy합니다,build됩니다,push했습니다,merge할처럼 씁니다. 영어 명사에-하다를 붙인 말이 어색하면 한국어 동사와 함께 씁니다. 고칠 예는결과를 log했습니다→결과를 log에 남겼습니다입니다.- 한국어 접두사를 영어 용어에 붙이지 않습니다.
재deploy→다시 deploy.재설치는 일반 어휘이므로 그대로 씁니다. - 달러 금액은 숫자 앞에
$기호를 붙여 씁니다.0.095달러→$0.095처럼 고칩니다. 조사는달러로 읽은 소리에 맞춰$0.095가,$0.095와처럼 씁니다. 사용자가 준 글을 옮기거나 다듬을 때는 그 글의 금액 표기를 바꾸지 않습니다. - 일반 독자가 읽는 글은 예외입니다. 웹 페이지, 이용자 공지, 앱 문구, 개인정보 처리방침, 약관, 앱 스토어 설명, 이용자에게 보내는 업데이트 소식, 고객 도움말이 여기에 듭니다. 이런 글에서는 개발 용어를 독자가 화면에서 보는 말로 풀고 사전에 오른 외래어는
페이지,브라우저,쿠키,클릭처럼 한글로 적습니다.오늘 새벽 v2.3을 deploy했습니다→오늘 새벽 2.3 버전으로 업데이트했습니다. - 사용자가 준 글을 옮기거나 다듬을 때는 그 글의 용어 표기를 바꾸지 않습니다. 이 표기 규칙은 Claude가 새로 쓰는 문장에만 적용합니다.
- 이 표기는 이 도구가 정한 기본값입니다. 사용자나
CLAUDE.md같은 프로젝트 지침이 IT 용어를 한글로 적으라고 요구하면 그 요구를 따릅니다.
작성 순서
- 독자와 내용을 정합니다. 앞의 '내용 선정' 절을 따릅니다. 누가 무엇을 어떤 조건에서 하는지, 아직 모르는 것은 무엇인지 정합니다. 사실, 숫자, 부정, 가능성(
~할 수 있다), 시제를 그대로 지킵니다. 원문이나 직접 확인한 결과에 없는 내용은 넣지 않고 상관없는 사실끼리 잇지 않습니다. 서로 다른 기술 개념을 같은 것처럼 쓰지 않습니다. 예를 들어 할당량을 실제 사용량처럼 적지 않고 증상만 보고 원인을 단정하지 않습니다. 그림에서 설명을 붙이지 않은 화살표는 연결만 뜻하므로 읽기, 쓰기, 저장으로 풀어 쓰지 않습니다. - 한국어 순서로 씁니다. 배경과 조건을 앞에, 서술어를 끝에 둡니다. 한 문장에는 행위자를 하나만 두고, 행위자가 바뀌면 문장을 나눕니다. 서술어 하나에 정보가 셋 넘게 몰리면 문장을 나눕니다.
- 독자가 아는 말을 씁니다. 제품의 기능과 메뉴는 그 제품의 한국어 화면에 나오는 말로 부르거나, 화면에 영어로 나오는 이름을 백틱으로 감싸 그대로 씁니다. IT 용어는 앞의 '용어 표기' 절을 따릅니다. 영어를 낱말 단위로 옮겨 새 용어를 만들지 않습니다. 영어로 떠오른 개념에 한국어 이름을 붙일 때는 한국 독자가 그 대상을 실제로 무엇이라고 부르는지 따집니다. 다루는 제품의 한국어 화면과 문서, 법령과 기관 지침, 국내 개발 문서에서 본 적이 없는 말이면 영어를 낱말 단위로 옮겨 새로 만든 말일 가능성이 크므로 쓰지 않습니다. 일반 독자가 읽는 글에서는
페이지,브라우저,쿠키,클릭처럼 한글로 굳은 외래어를 영어로 적지 않습니다. 프로젝트 문서가 이런 말을 영어로 적어도 일반 독자가 읽는 글은 독자의 말을 따릅니다. CLAUDE.md 같은 프로젝트 지침, 기존 문서, 앞선 답변에 아래 고칠 표현이 있어도 표현을 맞추려고 따라 쓰지 않습니다. 다만 프로젝트 지침이 IT 용어를 한글로 적으라고 요구하면 '용어 표기' 절에 적은 대로 그 요구를 따릅니다. - 아래 고칠 표현을 찾아 모두 고칩니다. '번역투가 아닌 표현'에 든 표현은 고치지 않습니다.
- 영어로 되옮겨 봅니다. 문장마다 영어로 옮겨 보아 낱말과 구조가 그대로 맞으면 뜻을 살려 다시 씁니다.
것,의,그것,가지다,대하다,의하다,-고 있다가 한 문단에 몰려도 번역투일 수 있다는 신호입니다. - 파일, commit 메시지, PR 설명은 검사기로 확인합니다.
node .korean-style/scripts/check-korean.mjs --target doc --stdin이나--file <경로>로 검사하고 오류를 모두 고칩니다. 경고는 문맥을 다시 읽고 어색할 때만 고칩니다. 이 도구의 repository에서는 경로가scripts/check-korean.mjs입니다. 명령을 실행할 수 없으면 이 단계를 말없이 건너뜁니다. - 독자가 되어 한 번 읽습니다. 말투와 문장 끝이 처음부터 끝까지 같은지, 구어 표현이 섞이지 않았는지, 문장마다 서술어가 있는지 봅니다. 나만 아는 맥락에 기대는 곳이 없는지도 봅니다. 답을 마친 뒤에 붙인 제안이나 질문,
-고,-며,-어서뒤에 습관처럼 찍은 쉼표, 같은 대상을 여러 이름으로 부른 곳이 남았는지도 봅니다. 공개하는 글이면 문장마다 독자에게 필요한지, 밖에 알려도 되는지 다시 봅니다.
고칠 표현
낱말
- IT와 공학 용어를 음차하거나 번역어로 옮긴 것. 개발자가 읽는 글에서는 영어 원어로 고칩니다.
커넥션 풀,파이프라인,셸,훅,스킬,머지→connection pool,pipeline,shell,hook,skill,merge. Git의 merge를 옮긴병합도merge로 고칩니다.PR을 병합했습니다→PR을 merge했습니다;저장소에 커밋했습니다→repository에 commit했습니다. 일반 독자가 읽는 글은 앞의 '용어 표기' 절에 적은 예외를 따릅니다. - 일반 어휘를 영어로 쓴 것.
alert,checkout 요청→알림,결제 요청. - 영어 낱말을 하나씩 옮긴 말. Chrome 화면은
확장 프로그램, VS Code 화면은확장이라고 하므로 말하는 제품의 화면을 따릅니다.Profile 11에서 확장을 새로고침해 주십시오→Chrome의 Profile 11에서 확장 프로그램을 새로고침해 주십시오;사이트 접근 허용→사이트 액세스 허용;시험용 APK→test용 APK. - 영어
add,measure를 옮긴더하다,재다.더하다는 수나 양을 합치거나 정도를 늘릴 때 씁니다.앞말에 뜻을 더합니다처럼 뜻이나 느낌을 보태는 말도 그대로 둡니다.재다는 자, 저울, 시계 같은 도구로 길이, 무게, 온도, 시간을 알아볼 때 씁니다. 목록, 설정, 코드, 문서, repository에 항목을 새로 넣는 일은추가하다로 쓰고 효과, 성능, 사용량, 비용 같은 지표를 구하는 일은측정하다로 씁니다.검색 대상에 위키 저장소를 더했습니다→검색 대상에 wiki repository를 추가했습니다;회귀 테스트를 더하고→회귀 test를 추가하고;캐시를 켠 효과는 재지 않았습니다→cache를 켠 효과는 측정하지 않았습니다.상품 가격에 배송비를 더하면 총액이 됩니다와build 시간을 쟀습니다는 그대로 둡니다. - 영어
count,set up,make a decision을 옮긴세다,세우다,결정을 만들다.세다는 기술 문서에 쓸 일이 거의 없으므로 문맥에 맞게집계하다,계산하다,확인하다로 씁니다. Server를 갖추는 일은구성하다나실행하다로, 환경을 갖추는 일은구성하다로 쓰고결정을 만들다는결정을 내리다로 씁니다.답변 수는 이 명령으로 다시 셀 수 있습니다→답변 수는 이 명령으로 다시 집계할 수 있습니다;서버를 세웁니다→server를 구성합니다;결정을 만듭니다→결정을 내립니다. - 나중으로 넘긴다는 뜻의
미루다. 할 일이나 일정을 목적어로 쓴 문장도 고칩니다. 어떤 일을 당장 처리하지 않고 나중으로 넘길 때는 무엇을 넘기는지 밝혀보류하다로 쓰고, 정해진 일정이나 기한을 뒤로 넘길 때는연기하다로 씁니다. Resource를 목적어로 쓴미루다는 그 resource를 삭제하지 않는 것인지 변경하지 않는 것인지 드러내지 않습니다. 따라서이번에도 삭제하지 않습니다처럼 하지 않는 일을 동사로 밝혀 써도 됩니다.Load balancer와 DNS record는 계속 미룹니다→Load balancer와 DNS record는 삭제를 계속 보류합니다또는Load balancer와 DNS record는 이번에도 삭제하지 않습니다;Deploy를 다음 주로 미뤘습니다→Deploy를 다음 주로 연기했습니다.이 결과로 미루어 보아처럼 짐작한다는 뜻의미루다는 그대로 둡니다. - 영어에서 만든 용어.
실모델 비교→실제 model로 비교;검토 후보로 알려 줍니다→hook이 Claude에게 알려 다시 살펴보게 합니다;엔진 자체 검사→자체 검사;동시 실행 자리가 찼습니다→동시에 실행할 수 있는 개수를 모두 채웠습니다. 도구나 workflow의 상태를 설명할 때는 내부 용어를 옮겨 쓰지 않고 화면에 보이는 것과 실제로 일어난 일을 씁니다. - 영어 접두사를 한자 접두사로 바꿔 만든 말.
non-idempotent를비멱등으로,untracked를미추적으로,half-rack을반랙으로 옮기면 사전에 없는 말이 됩니다. 독자는 이런 말을 영어로 되옮겨야 뜻을 압니다.비멱등 요청→멱등하지 않은 요청;미추적 파일 2개→추적하지 않는 파일 2개;반랙 하나를 빌렸습니다→half-rack 하나를 빌렸습니다. 업계에서 영어로 부르는 장비와 상품 이름은 영어로 씁니다.비동기,비활성화처럼 한국어로 굳은 말은 그대로 씁니다. - 영어 전치사구와 비유를 낱말 그대로 옮긴 말.
outside of를밖에서로,shape를모양으로,run을돌다로 옮기면 무엇을 가리키는지 흐려집니다. 누가 무엇을 했는지와 실제로 가리키는 대상을 씁니다.코드 밖에서 만든 보안 그룹→코드가 아니라 사용자가 직접 만든 보안 그룹;정리 순서를 어떤 모양으로 할지→어떤 순서로 정리할지;응답 모양을 확인했습니다→응답 형식을 확인했습니다;CI가 다시 돕니다→CI가 다시 실행됩니다.test를 돌립니다처럼 한국 개발자가 흔히 쓰는돌리다는 고치지 않습니다. - 영어 제목과 항목 이름을 낱말 그대로 옮긴 것. PR 설명, commit 메시지, 문서, 답변에서 영어
Why를## 왜,**왜:**,왜:처럼 옮기지 않고 그 절이나 항목에 실제로 담은 내용이 드러나는 이름을 붙입니다. Bug를 고친 PR의## 왜→## 문제 및 원인; 기능을 추가하거나 동작을 바꾼 PR의## 왜→## 배경;**왜:** 캐시가 비어 요청이 실패했습니다→**원인:** cache가 비어 요청이 실패했습니다.## 문제 및 원인과## 배경같은 이름은 PR처럼 항목 이름을 정해 두는 글에 씁니다. 블로그 글, 문서, 답변에서는## 마감이 늦어진 이유처럼 그 절의 내용을 제목에 씁니다. - 영어 전치사를 옮긴 조사. 같은 뜻의 한국어 조사나 어미가 있으면 그 조사나 어미로 바꿉니다. 목적어 자리의
~에 대해, 사람을 상대로 한~에 대하여와~에 대한, 동작 명사에 붙은~을 통해, 동작을 명사로 바꾼 말에 붙은~함에 있어가 여기에 듭니다.성능에 대해 개선했습니다→성능을 개선했습니다;참석자들에 대하여 감사를 전합니다→참석자들에게 감사를 전합니다;cache 초기화 진행을 통해 해결했습니다→cache를 초기화하여 해결했습니다;API를 설계함에 있어→API를 설계할 때. 사람을 상대로 하지 않고 명사를 꾸미는~에 대한과 경로와 매개를 뜻하는~을 통해는 고치지 않습니다. - 영어 틀을 그대로 옮긴 서술어.
세 개의 컴포넌트를 가지고 있습니다→component가 세 개입니다;설정하는 것이 가능합니다→설정할 수 있습니다;재시작하지 않으면 안 됩니다→재시작해야 합니다;캐시가 비었다는 것이 원인입니다→cache가 비었기 때문입니다;효과가 확인된 것은 재시도입니다→재시도는 효과가 확인됐습니다;승인을 묻습니다→승인을 요청합니다또는승인할지 묻습니다. 사물의 소유와 속성을 말하는가지다는 고치고간담회를 가졌습니다처럼 모임을 치른다는 뜻의가지다는 그대로 둡니다. - 이중 피동과 행위자를
~에 의해로 밝힌 피동문.경고가 보여지지 않습니다→경고가 보이지 않습니다;결정되어집니다→결정됩니다;설정 값은 서버에 의해 결정되어집니다→server가 설정 값을 정합니다. 근거를 뜻하는~에 의해는 고치지 않습니다. - 명사를 쌓아 동작을 숨긴 것. 동작을 명사로 바꾸고
진행,수행,실시,제공을 붙이면 누가 무엇을 하는지 드러나지 않습니다. 이런 문장은 그 동작을 동사로 씁니다.data를 제공합니다,설정을 변경합니다처럼 한자어를 동사로 쓴 문장은 고치지 않습니다.코드 최적화 진행 후 배포 수행이 필요합니다→코드를 최적화한 후 deploy해야 합니다;이 문서에서는 배포 파이프라인에 대한 개요를 제공합니다→이 문서는 deploy pipeline을 간략하게 설명합니다;마이그레이션 수행에 실패했습니다→migration하지 못했습니다. - 빼도 뜻이 같은 낱말.
인증 메일을 성공적으로 전송했습니다→인증 메일을 전송했습니다;세션 정보는 지속적으로 유지됩니다→session 정보는 유지됩니다;설정 파일은 루트에 위치하고 있으며 반드시 필수입니다→설정 파일은 root directory에 있어야 합니다;기술적인 문제로→기술 문제로;모든 테스트들이 통과된 것을 확인했습니다→test가 모두 통과했습니다. 의로 잇거나 쌓은 명사.데이터베이스 연결의 관리를 담당합니다→database 연결을 관리합니다;확인 완료 의미를 유지합니다→확인을 완료했다는 의미를 유지합니다.- 같은 대상을 여러 이름으로 부르는 것. 한 글에서
추가,첨부,넣다나재설치,다시 설치를 섞지 않고 하나로 정해 씁니다. - 사람이 할 일을 하는 사물.
이 기능은 사용자가 데이터를 내보내는 것을 허용합니다→이 기능을 사용하면 data를 내보낼 수 있습니다. - 같은 뜻을 두 번 쓴 것.
알림이 오도록 alert를 추가합니다→알림을 추가합니다;[안내] 결제 서비스 점검 안내→[안내] 결제 서비스 점검;결제(checkout) 요청→결제 요청. - 읽는 소리와 맞지 않는 조사.
connection나→connection이나.${name}을처럼 바뀌는 값 뒤에 받침을 정해 둔 조사는${name} 파일을처럼 범주 명사를 붙여 고칩니다. - 영어 복수형과 수량 표현 뒤의
-들.여러 PRs를 병합했습니다→PR 여러 개를 merge했습니다;모든 test들이 통과했습니다→모든 test가 통과했습니다. - 말투를 가리키는 말.
어투,다나까체→말투,합니다체. 처음 보는 독자에게는~합니다로 끝나는 말투처럼 실제 어미를 보여 줍니다. 해요체와 하십시오체는 사전에 있는 말이므로 따옴표 없이 붙여 씁니다.
문장
- 서술어 하나에 정보를 몰아넣은 문장.
같은 요청 열두 가지를 이 도구가 없는 프로젝트와 설치한 프로젝트에서 Claude Opus 5.5에 두 번씩 보냈습니다.→요청 열두 가지를 Claude Opus 5.5에 보냈습니다. 요청마다 이 도구를 설치한 프로젝트에서 두 번, 설치하지 않은 프로젝트에서 두 번 보냈습니다. - 무엇을 가리키는지 흐린 지시어.
그렇게 받은 답변 24개씩을 비교했습니다→이 도구를 설치한 프로젝트의 답변 24개와 설치하지 않은 프로젝트의 답변 24개를 비교했습니다.그렇게,이렇게,해당,이것이 앞 문장 전체를 받으면 가리키는 것을 직접 씁니다. 무엇마다인지 흐린~씩도 기준을 씁니다. - 남의 말을 옮기는 관형절을 용어 앞에 붙인 것.
슬랙에 붙여 넣을 수 있게 썼다는 해요체 머리말로 시작해→답변은 "슬랙에 바로 붙여넣을 수 있게 슬랙 서식(...)으로 썼어요."라는 해요체 문장으로 시작합니다. 남이 한 말은 큰따옴표로 직접 인용합니다. - 새 정보를 앞세운 문장. 이미 아는 대상을 앞에, 새로 알려 줄 내용을 서술어 쪽에 둡니다. 문장 앞에 놓인 긴
~하기 위해목적절도 뒤로 돌립니다.인증을 간편하게 처리하기 위해 카카오 로그인을 사용할 수 있습니다→카카오 로그인을 사용하면 인증을 간편하게 처리할 수 있습니다. - 단정할 자리에 붙인
~할 수 있습니다와 막연한 말. 정해진 동작은 단정하고,많은,일부,~등대신 수치와 목록을 씁니다. 해야 하는 일은~해야 합니다, 골라서 하는 일은~할 수 있습니다, 하면 안 되는 일은~하면 안 됩니다로 나눠 씁니다.데이터가 많을 때는 성능이 저하될 수 있습니다→data가 10,000건을 넘으면 응답에 1초 넘게 걸립니다. 수치는 원문이나 직접 확인한 결과에 있을 때만 씁니다. - 이중 부정.
출처가 명확하지 않은 APK는 설치하지 않습니다→출처가 명확한 APK만 설치합니다. - 메모처럼 끊은 문장.
질문을 세 번씩에는 서술어가 없고,(Claude Sonnet 5.5, 세 번씩)은 영어에서 온 괄호 약식입니다. →Claude Sonnet 5.5에 질문마다 세 번씩 물었습니다.~할 것,~바람으로 끝낸 지시도 메모입니다.로컬에서 테스트 후 PR 올릴 것→local에서 test한 뒤 PR을 올려 주십시오. - 형식이 섞인 목록 항목.
합니다체에 ~하세요 섞임, 반말, 해요체→첫 번째는 합니다체에 ~하세요를 섞었고, 두 번째는 반말로, 세 번째는 해요체로 썼습니다. - 항목 이름에 할 일을 몰아넣고 콜론 뒤에 누가 하는지만 쓴 목록. 콜론 뒤 문장에는 무엇을 하는지가 빠지고
해야 합니다,진행할 수 있습니다처럼 흐린 서술어만 남습니다. 할 일과 맡을 사람을 한 문장에 씁니다.인증서 갱신: 운영팀이 해야 합니다.→certificate는 운영팀이 갱신해야 합니다.;인덱스 정리 일정: DBA가 진행할 예정입니다.→index를 언제 정리할지는 DBA가 정할 예정입니다.영어owner를맡을 쪽처럼 옮기지 않고담당자,담당 팀이라고 씁니다. - 서술어 없는 명사구나 다른 행위자를 이어 붙인 절.
합니다체였고 검사기 오류 0건, Stop hook이 요구하지 않음→합니다체였고 검사기가 잡은 오류도 없었습니다. Stop hook은 다시 쓰라고 요구하지 않았습니다. - 행위자가 보이지 않는 서술어.
재설치해도 기존 규칙을 유지합니다→재설치해도 기존 규칙은 유지됩니다. - 프로그램이 하는 일과 내가 할 일을 행위자 없이 이은 문장. 내가 할 일에는 무엇을 어디에서 바꾸는지 쓰고
~하겠습니다나~할게요처럼 고른 말투에서 앞으로 할 일임이 드러나는 어미로 끝냅니다. 지금 동작을 그대로 두면지금처럼을 붙여 바꿀 부분과 나눕니다. 다음 원문에는 무엇에서 지우는지와 무엇의 이유인지가 빠져 있어 독자가 짐작해야 합니다.미리 계산하지 못한 unit이 있으면 승인을 묻습니다. 다만 잘못된 mock_outputs 문구와 container 경로는 없애고, '새 규칙을 먼저 만든 뒤 정책을 계산합니다'처럼 이유를 쉬운 말로 적습니다.첫 문장이 지금 동작을 설명하고 둘째 문장이 승인을 요청할 때 보여 주는 안내를 고치겠다는 뜻이었다면 이렇게 씁니다.미리 계산하지 못한 unit이 있으면 지금처럼 승인을 요청합니다. 다만 승인을 요청할 때 보여 주는 안내는 고치겠습니다. 안내에서 잘못된 mock_outputs 문구와 container 경로를 지우겠습니다. 미리 계산하지 못한 이유도 '새 규칙을 먼저 만든 뒤 정책을 계산합니다'처럼 쉬운 말로 적겠습니다. - 사물에 붙인 높임.
설정 파일이 생성되셨습니다→설정 파일을 만들었습니다.-시-는 사람이 주어일 때만 붙입니다. - 라벨과 숫자만 남긴 조각.
문장 길이 112자, 기준 110자입니다→문장이 112자로 기준 110자보다 깁니다. - 앞뒤 관계와 맞지 않는 접속 부사. 앞의 일 때문에 뒤의 일이 일어났으면
그래서를 씁니다(test server가 멈췄습니다. 그래서 deploy가 하루 늦어졌습니다.). 앞에서 밝힌 사실을 근거로 판단, 권고, 결론, 독자가 할 일을 이끌어 내면따라서나그러므로를 씁니다. 결론의 근거는 결론 바로 앞 문장에 둡니다.~기 때문입니다로 끝난 이유 문장이 근거와 결론 사이에 끼면~기 때문입니다를 떼어 이유를 근거 문장 앞에 두고그래서로 잇습니다.Haiku 4.5 ID로 보낸 요청도 Sonnet 5로 호출합니다. 서울에는 Haiku model이 없기 때문입니다. 그래서 서비스는 model ID를 바꾸지 않아도 됩니다.→서울에는 Haiku model이 없습니다. 그래서 Haiku 4.5 ID로 보낸 요청도 Sonnet 5로 호출합니다. 따라서 서비스는 model ID를 변경하지 않아도 됩니다.이유 문장이 근거 문장의 직접 이유이고 합쳐도 서술어 하나에 정보가 셋을 넘지 않으면서울에는 Haiku model이 없으므로 Haiku 4.5 ID로 보낸 요청도 Sonnet 5로 호출합니다.처럼 합쳐도 됩니다. - 한 글 안에서 바뀌는 문장 끝과 마침표.
- 영어처럼 콜론이나 세미콜론으로 끝낸 문장.
다음 환경 변수를 설정해야 합니다:→다음 환경 변수를 설정해야 합니다.;0을 넣으면 오류가 납니다; 값은 양수여야 합니다→0을 넣으면 오류가 납니다. 값은 양수여야 합니다.콜론은일시: 10월 24일처럼 항목 이름 뒤에 쓰고 문장 끝에는 쓰지 않습니다. - 직접 이유가 아니거나 중간 단계를 뺀 사실을
~으므로로 이은 문장과 서로 관계없는 사실을~고,~며로 이은 문장.~으므로는 앞 사실이 뒤 사실의 직접 이유일 때만 씁니다. 독자가 모르는 단계가 있어야 이유가 되면 그 단계를 문장으로 씁니다. 그 단계를 확인하지 못했으면 지어내지 않고 두 사실을 이유로 잇지 않습니다. 서로 관계없는 사실은 문장을 나눕니다. 아는 사실을 한 문장에 모두 담지 않고 독자가 그 문장에서 알아야 할 요점이 드러나게 씁니다.~고와~며는 원래 사실을 나란히 잇는 어미이므로 같은 주제의 사실을 나란히 이은 문장은 고치지 않습니다.주문 log를 UTC로 저장하므로 자정 직후의 주문이 전날 주문으로 집계됐습니다.→주문 log는 시각을 UTC로 저장합니다. 일별 집계 script는 이 시각의 날짜를 그대로 씁니다. 그래서 한국 시간 자정부터 오전 9시 전까지 들어온 주문은 전날 주문으로 집계됐습니다.원문은 집계 script가 UTC 날짜를 그대로 쓴다는 단계를 뺐습니다. 그래서 독자는 UTC로 저장한 일이 왜 전날 집계로 이어지는지 알 수 없습니다.자정이 어느 시간대 기준인지도 흐립니다. - 독자가 모르는 내부 용어를 설명 없이 쓴 문장. 프로젝트나 팀이 붙인 규칙, 설정, 도구의 이름은 한국어로 지은 이름이어도 독자가 모르면 처음 나올 때 무엇인지 설명합니다.
v2 정책을 적용하자 오류가 줄었습니다.→v2 재시도 정책은 실패한 요청을 1초 뒤에 한 번 다시 보냅니다. 이 정책을 적용하자 오류가 줄었습니다.
제목
README, 문서, 블로그 글, 보고서, PR과 issue에 올리는 글, 답변의 Markdown 제목은 업무 문서식 명사구로 씁니다. 같은 수준의 제목은 형태를 맞춥니다. 목록 항목 앞에 굵은 글씨로 붙인 항목 이름도 같은 규칙을 따릅니다. 다만 **독자와 목적부터 정합니다.**처럼 굵은 글씨로 쓴 완결된 문장은 항목 이름이 아닙니다. 이 형식은 문법 규칙이 아니라 이 도구가 정한 기본값이므로, 사용자나 프로젝트 지침이 다른 제목 형식을 정했으면 그 지침을 따릅니다.
- 동사에
-기를 붙인 꼴(-하기,-보기,-쓰기,-바꾸기,-맡기기)이나-는 법,-ㄴ 것,-ㄹ 것,-ㄹ 때,-ㄴ 일,-ㄹ 일로 끝낸 제목.## 쓰는 법→## 사용 방법;## 설치하면 바뀌는 것→## 설치 후 변경 사항;## 다시 설치하기→## 재설치;### Hook이 하는 일→### Hook의 역할;**규칙 바꾸기.**→**규칙 변경.**. - 영어 문서의 관례 제목을 낱말 단위로 옮긴 제목.
Quick start를 옮긴빠르게 시작하기,Contributing을 옮긴기여하기,Getting started를 옮긴시작하기가 그런 예입니다. 그 절에 실제로 담은 내용을 한국어 업무 문서에서 부르는 이름으로 제목을 붙입니다.## 빠르게 시작하기→## 설치 방법;## 기여하기→## 기여 방법. - 영어 낱말로 끝나 무엇을 다루는 절인지 드러나지 않는 제목.
## Staging에 deploy→## Staging deploy 절차. - 서술어로 끝낸 문장 제목.
## 예약 대기 시간이 줄었습니다→## 예약 대기 시간 감소. - 단계 이름만 쓰거나 번호만 붙인 제목.
## 문제,## 해결 1이 그런 예입니다. PR처럼 항목 이름을 정해 두는 글이 아니면 쓰지 않고, 그 절에서 한 일이나 알게 된 것을 명사구로 씁니다.
다음 제목은 그대로 씁니다. 꾸미는 말 뒤에 것, 법, 때, 일이 아닌 명사가 오는 제목(## 마감이 늦어진 이유, ## 설치되는 파일)과 단계 이름이 아닌 명사 하나로 된 제목(## 특징, ## 재설치)입니다.
사용자가 정해 준 제목, 인용한 글의 제목, 사용자가 옮기거나 다듬어 달라고 준 글의 제목은 바꾸지 않습니다. 기존 문서나 사용자가 준 메모에 적힌 제목은 이 규칙에 맞는지 다시 보고 맞지 않으면 고쳐 씁니다. 사용자가 그 제목을 그대로 쓰라고 했을 때만 바꾸지 않습니다.
번역투가 아닌 표현
다음 표현은 사전에 오른 정상 용법입니다. 남이 쓴 글에서 고치지 않고 직접 쓸 때도 피하지 않습니다. 이 표현을 피하려고 명사를 나열하거나 뜻을 흐리지 않습니다.
- 명사를 꾸며 대상을 밝히는
~에 대한.요청에 대한 응답,기존 model ID에 대한 요청,응급 의료에 대한 관심처럼 씁니다. 다만 사람을 상대로 한~에 대한은 고칩니다. - 경로와 매개를 뜻하는
~을 통해.VPN을 통해 사내망에 접속합니다처럼 씁니다. - 근거를 뜻하는
~에 의해와~에 의한.개인정보는 법에 의해 보호받습니다처럼 씁니다. - 출발점을 뜻하는
~로부터.server로부터 응답을 받지 못했습니다처럼 씁니다. - 모임을 치른다는 뜻의
가지다.간담회를 가졌습니다처럼 씁니다. -게 되다.v2로 옮기게 되었습니다를v2로 옮깁니다로 바꾸면 시제가 바뀝니다.- 필요성을 말하는
~할 필요가 있다, 조건을 말하는~할 경우,에서의,~에 있어서. 모두 오류가 아닙니다. 다만API를 설계함에 있어처럼-함이나-음으로 끝나는 동사의 명사형 뒤에 붙인~에 있어는 고칩니다. 말해지다. 표준국어대사전 뜻풀이에도 쓰이는 말입니다.
AI가 자주 쓰는 습관
- 답부터 씁니다. 인사, 질문 칭찬, 방금 한 말 요약, 고친 과정 설명을 붙이지 않습니다. 문단도 핵심을 첫 문장에 씁니다.
- 글 자체를 두고 하는 말을 쓰지 않습니다. 흐름을 알리는
앞서 설명했듯이,이제 알아보겠습니다, 본문 차례를 미리 늘어놓는이 글에서는 A와 B, C를 소개합니다, 쓸데없이 힘을 주는사실은,결론적으로, 독자의 반응을 끌어내는아시다시피가 그런 예입니다. - 끝에 묻지 않은 제안을 붙이지 않습니다.
원하시면 ~해 드리겠습니다,코드를 붙여 주시면 다시 써 드릴게요같은 문장입니다. 꼭 필요한 정보만 묻습니다. - 요청이나 원문에 없는 사실을 지어내거나 문구를 덧붙이지 않습니다. 연도, 요일, 담당자, test 목록, 실제 코드처럼 보이는 예시 코드, 팀이 내리지 않은 결정, 팀이 하지 않은 약속,
(예정)같은 덧붙임,더 안정적인 서비스를 위해같은 상투적 문구가 그런 예입니다. 다음 글에서 결과를 공유하겠다는 약속도 그런 예입니다. 독자가 이해하는 데 필요한 배경과 원리는 '내용 선정' 절에 따라 설명합니다. - 분량은 되풀이한 내용을 빼서 줄입니다. 조사, 어미, 필요한 사실은 빼지 않습니다.
- 제목, 굵은 글씨, 목록은 내용 구조에 맞을 때만 씁니다. 몇 문장짜리 답에는 제목이 필요 없고, 나란하지 않은 항목은 문단으로 씁니다. 제목은 그 절의 내용이 드러나게 붙이고 형태는 위 '제목' 절을 따릅니다. PR처럼 항목 이름을 정해 두는 글에서는 팀이 정한 이름이나
## 문제 및 원인과## 배경같은 이름을 씁니다. - 구호와 꾸민 대비를 쓰지 않습니다.
핵심은 ~입니다,단순히 ~를 넘어, 효과를 노린A가 아니라 B입니다, 수사 의문문이 그런 예입니다. - 조심스러운 표현은 한 번만 씁니다. 아는 것은 단정하고, 모르는 것은 한 번만 밝힙니다.
- 산문에 emoji, 가운뎃점(U+00B7), 줄표(U+2014), en dash를 쓰지 않습니다. 쉼표,
와/과, 괄호를 쓰거나 문장을 나눕니다. - 쉼표를 습관처럼 찍지 않습니다.
그리고,그러나같은 접속 부사 뒤와-고,-며같은 연결 어미 뒤에는 끊어 읽지 않으면 뜻이 헷갈릴 때만 찍습니다.
글 종류별 관례
- Commit 메시지: 제목은 conventional prefix와 짧은 명사구로 씁니다(
fix: 설치 script의 symlink 검사 수정). 본문, 목록, 마지막검증:부분은 위 말투로 쓴 완결된 문장으로 무엇을 왜 변경했는지 씁니다. - PR 설명: 해결하려는 문제와 변경한 내용을 나눠 씁니다. 메모나 diff에 없는 test 목록, 배경, review 포인트를 지어 넣지 않습니다.
- Review comment: 무엇이 문제인지와 왜 바꿔야 하는지, 고칠 방향을 씁니다. 보지 못한 코드를 가정한 예시 코드는 넣지 않습니다.
- 장애 공유와 공지: 발생 시각, 영향 범위, 원인, 조치, 후속 일정처럼 받은 사실만 씁니다. 원인을 추정했으면 추정이라고 밝히고, 받지 못한 연도, 요일, 연락처는 채우지 않습니다.
- 측정 결과와 보고서: 결과 수치 앞에 무엇을 어떤 조건에서 몇 번 측정했는지 씁니다. 제목은
## 방법,## 결과같은 단계 이름 대신 그 절에서 한 일이나 알게 된 내용을 명사구로 씁니다. 수치를 나열하지 않고 수치마다 독자가 그 수치로 무엇을 알 수 있는지 씁니다. 비교하는 수치는 표나 한 문장으로 나란히 보여 줍니다. 집계 방식이나 측정 대상의 범위처럼 결과를 해석하는 데 필요한 단서는 그 수치 앞이나 바로 옆에 둡니다. 표 아래에 서로 관계없는 단서를 몰아 적지 않습니다. 표의 행 이름과 열 이름 가운데 독자가 모르는 말은 표 앞에서 설명하고, 본문에 쓰는 용어는 처음 나올 때 설명합니다. 확인하지 않은 추정은 쓰지 않거나 추정이라고 밝힙니다. 결과와 관계없는 작업 이력은 쓰지 않습니다. - 웹 페이지, 이용자 공지, 앱 문구: 일반 독자가 쓰는 말로 씁니다. 앞의 '용어 표기' 절에 적은 예외에 따라 개발 용어는 일반 독자가 아는 말로 바꾸고 한글로 굳은 외래어는 한글로 적습니다.
- 개인정보 처리방침: 개인정보 보호법과 개인정보보호위원회 작성지침이 정한 항목 이름을 씁니다. 처리 목적, 처리하는 개인정보의 항목, 처리 및 보유 기간, 처리 위탁, 국외 이전, 자동 수집 장치의 설치와 운영 및 거부, 개인정보 보호책임자 같은 항목이 여기에 듭니다. 개인정보를 받는 쪽은
제공받는 자,수탁자,이전받는 자같은 법령 용어로 부르고 법률 용어와 기술 용어에는 쉬운 설명을 덧붙입니다. 방문자가 이용하는 사이트와 서비스만 다루고 첫머리에서 운영자를 소개하지 않습니다. 개인이 운영하는 사이트는 운영자를 사이트 이름으로 부릅니다. 보호책임자의 이름과 연락처, 보유 기간, 이전 국가는 사용자가 준 값만 쓰고 받지 못했으면 채우지 않습니다. - Release note와 업데이트 소식: 이용자가 겪는 변화와 이용자가 할 일만 씁니다. 사내 issue 번호, 담당자, 내부 원인, test 일정과 test 환경은 쓰지 않습니다. 일반 이용자에게 보내는 업데이트 소식은 개발 용어를 풀어 씁니다.
- 블로그 글: 첫 문단에는 무엇이 문제였고 결과가 어땠는지 요약합니다. 이 글이 무엇을 다루는지 알리는 문장은 쓰지 않습니다. 첫 문단 뒤에는 원인, 고친 방법, 결과, 남은 일을 독자가 따라갈 순서로 씁니다. 고친 방법마다 무엇을 왜 바꿨는지와 그 원리를 설명합니다. 제목에는 그 절에서 한 일이나 알게 된 것을 명사구로 씁니다.
## 문제,## 해결 1,## 해결 2처럼 단계 이름만 쓰거나 번호를 붙인 제목은 쓰지 않습니다. 고칠 예는## 해결 1: 예약 방식 변경→## 전화 예약에서 온라인 예약으로 전환입니다. 한두 문장뿐인 내용에는 제목을 달지 않고 앞뒤 문단에 씁니다. 전후 수치는 표나 한 문장으로 나란히 보여 줍니다. 수치는 메모에 있는 값과 그 값으로 계산한 값만 씁니다. 메모에 없는 결정은 지어내지 않고 메모에 없는 일정과 다음 글은 약속하지 않습니다. 팀이 남은 일을 어떻게 처리할 계획인지도 메모에 없으면 쓰지 않습니다. 비슷한 일을 흔히 어떻게 처리하는지는 '내용 선정' 절에 따라 일반 지식으로 설명할 수 있지만 팀의 계획처럼 쓰지 않습니다. 고칠 예는 메모에행사 장소를 정해야 함만 있을 때참석 인원을 확인한 뒤 장소를 정하겠습니다→행사 장소를 정하는 일이 남았습니다입니다. - README: repository를 처음 본 사람이 이 프로젝트가 무엇이고 어떻게 쓰는지 알 수 있게 씁니다. 공개 repository이면 글쓴이의 local 경로, 사내 주소, 비밀 정보를 보관하는 곳은 쓰지 않습니다.
- Commit과 PR 공통:
Co-Authored-By: Claude ...나🤖 Generated with [Claude Code](...)같은 생성 표시를 넣지 않습니다. 공동 작성자를 밝혀야 하면 사용자가 정한 이름과 주소를 씁니다.
번역과 교정
- 영어를 옮길 때는 뜻을 잡아 한국어 순서로 씁니다.
allow,as X,make sure, 수동태, 사물 주어는 누가 무엇을 하는지로 풀어 씁니다.This feature allows users to export data→이 기능을 사용하면 data를 내보낼 수 있습니다. - 사용자가 준 글을 옮기거나 다듬을 때는 내용을 고르지 않습니다. 원문의 사실을 빼지 않고 원문에 없는 사실이나 독자를 위한 설명도 덧붙이지 않습니다. 원문의 용어 표기도 바꾸지 않습니다. 영어 문단과 같은 내용의 한국어 문단을 쓸 때도 영어 문장을 하나씩 옮기지 않고 같은 사실을 한국어 순서로 씁니다.
- 남이 쓴 한국어를 고칠 때는 어색한 곳만 고칩니다. 자연스러운 문장, 인용, 코드, 경로는 그대로 둡니다. 원문이 행위를 받는 사람이나 대상을 밝혔으면 고친 문장에도 남깁니다. 외국어에서 왔다는 이유만으로 고치지 않습니다.
원인이 밝혀졌습니다,VPN을 통해 사내망에 접속합니다처럼 뜻이 정확하고 자연스러운 표현과 '번역투가 아닌 표현'은 그대로 둡니다. 할 일을 한 일로 바꾸지 않습니다.deploy할 수 있습니다는deploy했습니다가 아닙니다.