[DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다

[patternflow-bot]

studio / https://claude.ai/code/session_01KBjxwhdLKoNyn28YLnUz8x

이번 판은 voice.md 의 한국어 기준을 바꿨다. 웹 조립 가이드의 한국어(번역체)와 일지는 기준에서 뺐고, 공개된 한국어 윤문 스킬 둘과 KatFishNet 연구가 꼽는 번역투 표시를 출처와 함께 적었으며, 가이드 문장 두 줄을 영어 원문, 가이드 한국어, 한국어로 처음 쓴 문장 순으로 나란히 보였다. 머지하면 영어는 README·조립 가이드의 글투, 한국어는 번역체를 피하는 기준이 한 쪽에 적히고, 금지어 21개가 따로 목록으로 남는다.

좋아지는 것: 없음

할 일 (지금 판, v2)

• PR 제목을 [WIP] 로
• 한국어 기준에서 웹 조립 가이드 한국어를 빼고, 그 문장은 「피할 꼴」 예로만 쓰기
• 일지 한국어판도 기준으로 쓰지 않기 (창작자 두 번째 말)
• 웹에서 한국어 윤문 지침·스킬 찾아 근거로 삼고, 출처를 voice.md 에 적기
• 「한국어로 처음 쓴」 예문을 그 기준대로 새로 쓰기
• 한 쪽 안으로 다시 맞추기 (105줄 · 754 낱말)
• 링크 검사 · 문서 지도 · 임시 글투 검사 · 인용 대조
• 기준 브랜치(dev) merge: [DONE] 정리 2단계를 PR 열넷으로 나눈 계획서 — 어느 셋을 같이 맡겨도 파일이 안 겹친다 #19 가 들어와 3761d9e 로 merge, 충돌 없음. 그 뒤 다시 fetch 해 HEAD..origin/dev 0개
• head 81df247 GitHub CI (check, 문서 링크) success

한 일

• docs/voice.md 「Korean」 절을 새로 썼다. 한국어는 그 파일의 어미(해요체·합니다체)를 지키고 처음부터 한국어로 쓴 것처럼 읽혀야 한다고 연다. 일지와 웹 가이드가 기준이 아닌 까닭을 한 문장씩 적었다(일지는 일기, 가이드 한국어는 영어를 문장마다 옮겨 온 글). 그다음 옮겨 온 한국어의 표시를 목록으로 들었다: 영어 전치사를 옮긴 조사(~에 대해·~를 통해·~에 있어서·~에 의해), 사람 아닌 주어에 붙은 영어 동사(「드라이버 IC가 결정해요」 = decides), 가지고 있다·~되어지다, 말하면 될 자리의 ~할 수 있다, 동사 일을 하는 명사(확인을 진행해요), 필요 없는 대명사·-들, 영어 자리마다 찍은 쉼표. 출처는 두 스킬 링크와 KatFishNet(ACL 2025) 링크다.
• 나란히 놓은 예 두 쌍. 가이드의 영어 원문과 한국어를 원문 그대로 두고, 아래에 한국어로 처음 쓴 문장을 놓았다.
  • Its driver IC decides, not “HUB75E” in the title. → 가이드 「제목의 ‘HUB75E’가 아니라 드라이버 IC가 결정해요.」 → 「패널이 켜질지는 제목의 ‘HUB75E’가 아니라 드라이버 IC에 달려 있어요.」
  • Take $100 as the floor, not the estimate → 가이드 「100달러는 예상치가 아니라 바닥이에요.」 → 「100달러는 아무 문제 없이 끝났을 때 드는 돈이에요. 보통은 더 들어요.」
• 영어 절은 그대로 두고 줄였다. 한국어 절이 늘어난 만큼 예 몇 개를 뺐다(「about two minutes / 15 October 2026」, 보조배터리 측정 인용, 「No printer?」, 「The other nouns…」 문장). 맨 앞 문단은 「README·조립 가이드는 영어의 기준, 한국어는 맨 끝에 따로」로 고쳤다. 지난 판에서 해요체 근거로 걸었던 SERVICES.md 링크는 뺐다.
• docs/voice-banned.txt 는 바꾸지 않았다(§2.10 목록 21개).

증거

$ git diff --stat origin/dev
 docs/voice-banned.txt |  34 ++++++++++++++++
 docs/voice.md         | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 139 insertions(+)

$ python3 .github/scripts/check_links.py
all 671 relative links resolve

$ git fetch --tags && (cd web && npm run doc-map)
1059 links from 210 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
$ grep '^docs/voice' docs/investigations/2026-10-doc-map.csv
docs/voice.md,AGENTS.md,relative,,yes
docs/voice.md,BUILD_GUIDE.md,relative,,yes
docs/voice.md,README.md,relative,,yes
docs/voice.md,docs/EDITIONS.md,relative,the-three-words,yes
docs/voice.md,docs/rfc-cleanup.md,relative,210-writing-voice,yes
docs/voice.md,docs/voice-banned.txt,relative,,yes
$ git checkout docs/investigations/        # 지도는 C 갈래가 커밋

# 임시 글투 검사 (스크래치 스크립트, 레포에 안 넣음): 금지어 21개, em dash,
# 「A, B, and C」 나열, 여는/닫는 틀
$ python3 voicecheck.py docs/voice-banned.txt docs/voice.md
entries: 21          # 걸린 줄 없음
$ grep -c '—' docs/voice.md
0

# 인용 대조: 가이드 문장 넷이 web/src/components/guide/copy/build.ts 에 그대로 있다
$ grep -cF "Its driver IC decides, not “HUB75E” in the title." web/src/components/guide/copy/build.ts   → 1
$ grep -cF "제목의 ‘HUB75E’가 아니라 드라이버 IC가 결정해요." …                                      → 1
$ grep -cF 'Take $100 as the floor, not the estimate' …                                            → 1
$ grep -cF "100달러는 예상치가 아니라 바닥이에요." …                                                → 1

# 출처: 아래 셋은 원문을 받아 읽었다 (raw.githubusercontent.com)
#   DaleSeo/korean-skills skills/humanizer/SKILL.md + references/translation-ese-patterns.md 외 3 (MIT)
#   epoko77-ai/im-not-ai README.md 의 분류 체계 A~J (MIT)
#   Shinwoo-Park/KatFishNet README.md 의 abstract: "Korean ... has ... less frequent comma usage compared to English"

• 펌웨어 · web/src 무변경이라 §2.1 의 빌드 · 웹 명령은 해당 없다.

정리 기록 (RFC §2.11)

• 바꾼 것: 새 파일 docs/voice.md, docs/voice-banned.txt
• §2.1 명령: 해당 없음(펌웨어 · web/src 무변경). check_links.py, npm run doc-map 을 돌렸다
• doc-map 행: 새 행 6개(docs/voice.md 에서 나가는 링크), 모두 yes. 들어오는 링크는 아직 없다

for another lane

• AGENTS.md 의 「Writing voice (hard rule)」 덧붙임(§2.10) 은 이 PR 에 없다. AGENTS.md 를 가진 쪽(C3 이나 따로 낸 PR)이 붙인다. §2.10 의 그 글은 한국어를 「해요체 or 합니다체 as the file already uses」로만 말하니, 붙일 때 「Korean: see docs/voice.md」 정도를 같이 두면 이 절이 읽힌다.
• C3: docs/README.md 와 docs/REPOSITORY.md 에 두 파일을 한 줄씩. 제안: 「voice.md: how the docs sound in English and in Korean, with the words that stay out in voice-banned.txt」.
• [DONE] 행동 강령·보안·지원 안내는 .github/ 로, 오디오 가이드는 docs/ 로 옮겨 루트가 한눈에 읽힌다 #16 이 남긴 일: docs/README.md · docs/REPOSITORY.md 의 규칙 문장 다시 쓰기는 이 PR 머지를 기다리고 있었다(답 6).
• 웹 가이드 한국어 다시 쓰기: 창작자가 나중에 고칠 일로 남긴다. voice.md 는 그 글 두 줄을 「피할 꼴」로 인용하므로, 가이드를 고친 뒤에도 인용은 그대로 둬도 된다(당시 글을 보인 예).
• scripts/voice-lint.ts 를 쓸 사람: voice-banned.txt 머리 주석의 맞추는 법을 따르면 된다.

실행법

python3 .github/scripts/check_links.py
git fetch --tags && (cd web && npm ci && npm run doc-map) && git checkout docs/investigations/

읽기는 GitHub 에서 docs/voice.md 를 열면 된다.

가정

• 창작자 말과 총괄 짐작이 어긋난 곳. 첫 판 요청의 가정은 「한국어 기준을 일지 한국어판에서 뽑는다」였지만, 창작자가 곧바로 「저널 한국어판은 … 맞지 않고」라고 고쳤다. 창작자 말을 따라 일지는 기준에도 예에도 쓰지 않았다. 답 6(「It does not quote the journal」)과도 맞는다.
• 웹 조립 가이드 한국어는 「피할 꼴」 예로만, 두 줄을 영어 원문과 함께 원문 그대로 인용했다. 영어를 문장마다 옮겨 온 흔적이 보이게 하려는 배치다. 가이드 문구 자체는 이 PR 범위 밖이라 고치지 않았다.
• 근거로 삼은 것: 웹 검색으로 찾은 공개 한국어 윤문 스킬 둘(DaleSeo/korean-skills 의 humanizer, epoko77-ai/im-not-ai 의 Humanize KR, 둘 다 MIT)과, 첫째가 기대는 KatFishNet(연세대, ACL 2025). 스킬 둘은 원문을 받아 읽었다. KatFishNet 은 이 환경에서 arxiv 가 막혀 abstract 와 코드 저장소 README 만 확인했다. 그래서 「한국어는 영어보다 쉼표를 덜 쓴다」만 적고, 스킬이 이 논문을 들며 인용하는 수치(쉼표 든 문장 61% 대 26%)는 직접 확인 못 해 넣지 않았다. 국립국어원·위키독스 자료는 이 환경의 네트워크 정책으로 열리지 않았다.
• 「한국어로 처음 쓴」 예문 두 줄은 창작자 요청대로 내가 새로 썼다. 위 표시 목록(조사 번역투, 무생물 주어, 할 수 있다, 명사화, 대명사, 쉼표)에 걸리는 말이 없는지 하나씩 대조했다. 처음엔 「보통은 그보다 더 들어요」였는데, 목록이 그 를 들기에 「보통은 더 들어요」로 줄였다.
• voice.md 본문은 영어로 두었다. 레포 문서가 영어이고 원래 레포로 올라갈 글이라서다. 한국어 표시와 예문만 한국어다.
• 한국어 번역투 표시는 voice-banned.txt 에 더하지 않았다. 그 파일의 한국어 줄은 글 어디서나 맞추는데, 그러면 에 있어서 가 「보드 뒤에 있어서」 같은 바른 문장까지 잡는다. 늘 틀린 형태(되어지, 되어진, 되어져)만은 넣어도 오탐이 없다. 더할지는 창작자 몫이라(답 6) 후보로만 적는다.
• 「한 쪽」: 105줄 · 754 낱말. 지난 판(84줄 · 646 낱말)보다 한국어 절만큼 길어서, 영어 절의 예 몇 개를 뺐다(한 일 참고).
• 커밋 제목은 판 요청 규칙대로 한국어 한 줄, 본문은 docs: 로 시작하는 영어다.

Changelog

Docs

• The project's writing voice is written down. docs/voice.md describes, on one page, the voice the README and the build guide already use for English, and a standard for Korean taken from published Korean editing guides: the marks of Korean carried over from English, with two lines from the web guide shown beside a version written in Korean first. docs/voice-banned.txt starts the list of words that stay out of the docs, for the voice check the cleanup adds later.

Upstream

• What: Add docs/voice.md, one page on the voice the README and the build guide use for English and a Korean standard taken from two published Korean editing skills, and docs/voice-banned.txt, starting with the word list in rfc-cleanup.md section 2.10.
• Checks: python3 .github/scripts/check_links.py and npm run doc-map (0 do not resolve); nothing under firmware/ or web/src/ changes, so the build and web commands do not apply.
• Docs map: 6 new rows out of docs/voice.md, all resolving; nothing links to it yet.

지난 판

v1

b835d57. 한국어 기준을 웹 조립 가이드의 한국어 문구(해요체)와 docs/SERVICES.md(합니다체)로 잡고, 가이드 문장 「전부 부품 목록에 있어요. 주문부터 해요. 배송이 제일 오래 걸려요.」를 좋은 예로 썼다. 그림은 없었다.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KBjxwhdLKoNyn28YLnUz8x