[DONE] 정리 2단계 PR 11 — 에이전트가 처음 읽는 AGENTS.md 에 글투 규칙과 검사 명령 셋이 들어간다

[patternflow-bot]

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

정리 2단계 계획서 표의 PR 11 이다. 에이전트가 맨 먼저 읽는 AGENTS.md 끝에 rfc-cleanup.md §2.10 의 글투 규칙을 낱말 하나 안 바꾸고 붙였고, 「Common commands」에 어긋남 검사(check:drift)·글 잠금(check:human-lock)·글투 검사(check:voice)를 한 줄씩 더했다. 머지하면 이 레포에서 글을 쓰는 에이전트가 첫 장에서 규칙과 돌릴 명령을 함께 만난다.

좋아지는 것: 없음

할 일

• 계획서 표의 PR 11 줄과 k11, docs/rfc-cleanup.md §2.1·§2.9·§2.10·§2.11·§2.13(답 6), docs/voice.md 를 읽는다
• 앞선 PR 9·10 이 dev 에 있는지 본다([DONE] 정리 2단계 PR 9 — 새로 쓴 글에 금지 낱말이나 셋 나열, 「이 문서는」 첫머리, 맺음 요약이 있으면 check:voice 가 줄마다 짚는다 #33 5376b0b, [DONE] 정리 2단계 PR 10 — BOM·묶음만 고친 PR 에서도 어긋남 검사와 직접 쓴 글 잠금이 돈다 #32 1c231e4)
• 먼저 머지된 형제 PR 이 k11 에 남긴 말을 모은다: [DONE] 정리 2단계 PR 8 — 일지·릴리스 노트·README 이야기처럼 직접 쓴 글의 낱말을 바꾼 PR 은 잠금 검사에 걸린다 #27(k8), [DONE] 정리 2단계 PR 10 — BOM·묶음만 고친 PR 에서도 어긋남 검사와 직접 쓴 글 잠금이 돈다 #32(k10), [DONE] 정리 2단계 PR 9 — 새로 쓴 글에 금지 낱말이나 셋 나열, 「이 문서는」 첫머리, 맺음 요약이 있으면 check:voice 가 줄마다 짚는다 #33(k9), [DONE] 정리 2단계 PR 12 — CI 가 무엇을 돌리는지 적은 문서가 지금 CI 와 맞는다 #35(k12)
• 표가 PR 11 에 적은 AGENTS.md 하나만 고친다 (+31 −1)
• 붙인 절이 RFC 블록과 낱말까지 같은지 스크립트로 본다
• §2.1 검사, check_versions.py, 잠금, 글투 검사, doc-map 을 돌린다(CSV 는 되돌린다)
• dev 를 merge 한다(5376b0b 그대로라 이미 최신)
• 이 PR 의 CI(Drift checks, Core knows no features, Docs point at files that exist)가 caa6acd 에서 셋 다 success

한 일

• AGENTS.md 끝(「Documentation entry points」 뒤)에 ## Writing voice (hard rule) 절. §2.10 의 인용 블록에서 > 를 떼고, 문단과 목록 한 항목을 한 줄로 이었다. AGENTS.md 가 원래 그렇게 쓰여 있다. 낱말은 scripts/voice-lint.ts → web/scripts/voice-lint.ts 경로 하나만 다르다.
• 「Common commands」의 웹 빌드 줄 뒤에 세 줄:
  • Drift checks: check:drift 가 web/scripts/drift/ 의 파일을 다 돌리고, check:<name> 은 하나(이름 여덟). check:ci 끝에 있고, drift.yml 이 모든 PR 에서 PF_DRIFT_STRICT=1 로 돌려 책상에선 건너뛰던 쪽이 거기선 실패한다.
  • Locked text: check:human-lock 은 §2.9 의 자리와 docs/.human-written 의 경로에서 낱말이 바뀌면 실패. 마크업과 링크 경로는 바꿔도 되고, 그대로 옮긴 글은 통과하되 옮기는 데 메인테이너 승인이 든다. 오타는 PR 에 적는다. drift.yml 은 PR 의 base 와, 책상에선 origin/dev(없으면 origin/main)와의 merge-base 와 비교한다.
  • Voice lint: check:voice 는 같은 base 뒤로 더한 줄을 읽고 금지 낱말·셋 나열·첫머리·맺음 요약을 file:line 으로 짚는다. 산문을 더한 PR 을 열기 전에 손으로 돌리고, CI 는 안 돌린다. 파일 인자는 통째로, - 는 stdin 의 PR 본문을 읽는다.
• 웹 빌드 줄의 「CI runs all of them」을 「CI runs the ones npm run check:ci chains together」로. check:voice 를 CI 가 안 돌리니 원래 말이 틀리게 된다.

증거

GitHub, 이 PR 의 caa6acd: 「Drift checks / check」(job 116206157672), 「Core knows no features / check」(job 116206126289, AGENTS.md 를 고치면 도는 check_versions.py 포함), 「Docs point at files that exist / check」(job 116206021872) 셋 다 success. Drift 작업은 PF_DRIFT_STRICT=1 로 여덟 검사를 다 통과했다. 로컬에서 건너뛴 roadmap 도 거기선 issue 14개를 읽고 passed roadmap 이다. 잠금은 base: 5376b0b (PF_LOCK_BASE), this diff touches 0 locked files.

로컬, caa6acd, web/, 태그 28개, pdftotext 있음:

$ python3 (RFC §2.10 의 > 줄과 AGENTS.md 의 「## Writing voice」 뒤를 공백만 맞춰 비교, 경로 하나 되돌림)
words identical: True 2165 2165
$ python3 firmware/toolchain/check_versions.py
versions agree: core v3.11.0, audio v0.7.0, performance v0.4.0 - in net_config.h, the overrides, AGENTS.md, the manifest and the /editions cards, images on the shelf; try-out images: clock-v0.1.5, midi-v0.1.0
$ python3 .github/scripts/check_links.py
all 683 relative links resolve
$ npm run typecheck   → exit 0
$ npm run lint        → ✖ 12 problems (0 errors, 12 warnings), exit 0 (원래 있던 src/ 경고)
$ npm run check:drift
passed   bom
passed   bom-schematic
passed   changelog
passed   editions
passed   features
passed   links-absolute
passed   presets
skipped  roadmap      (이 세션은 engmung/Patternflow 를 못 읽는다. CI 는 strict 로 돈다)
$ PF_LOCK_BASE=$(git rev-parse origin/dev) npm run check:human-lock
this diff touches 0 locked files
check:human-lock: no locked words changed
$ npm run check:voice
base: 5376b0b (the merge-base with origin/dev)
read: 31 added lines in 1 file
check:voice: nothing found
$ git fetch --tags && npm run doc-map
1072 links from 214 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve

글투 검사가 새 세 줄을 정말 읽는지 버리는 고침으로 봤다(커밋 전에 되돌림). Locked text 줄의 「fails」 앞에 robustly 를 넣으니 check:voice: 1 finding in 1 file / banned 로 걸렸다. 붙인 「Writing voice」 절은 금지어를 인용하는 자리라 k9 가 일부러 건너뛴다(#33).

doc-map: AGENTS.md 에는 Markdown 링크를 더하지 않았다(경로는 다 백틱 안). 이 편집을 stash 하고 돌린 CSV 와 그대로 돌린 CSV 가 cmp 로 같다. dev 의 커밋된 CSV 와 다른 6행은 앞선 PR 몫이고 k13 이 싣는다. 두 CSV 는 git checkout 으로 되돌렸다.

실행법

git fetch --tags
python3 firmware/toolchain/check_versions.py
cd web && npm ci
npm run check:drift
PF_LOCK_BASE=$(git merge-base HEAD origin/dev) npm run check:human-lock
npm run check:voice

가정

• 기준 브랜치는 dev(머리말). 표가 PR 11 에 적은 AGENTS.md 만 고쳤다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV 는 안 고쳤다. 라벨 cleanup·step-2 는 포크에 없어서 달지 않았다.
• 「as the RFC writes it」은 낱말로 지켰다. 줄바꿈과 > 는 AGENTS.md 꼴(문단 한 줄)에 맞췄다. scripts/voice-lint.ts 는 루트에 scripts/ 가 없어 AGENTS.md 의 다른 경로처럼 루트 기준 web/scripts/voice-lint.ts 로 적었다. §2.1(3)이 잠긴 글에서도 허락하는 링크 경로 고침 꼴이다.
• 절은 「Append」 대로 파일 맨 끝에 두었다. 「Hard rules」 목록의 9번으로 넣지 않은 까닭은 제목 「Writing voice」가 그대로 있어야 k9 의 검사가 그 절을 건너뛰기 때문이다([DONE] 정리 2단계 PR 9 — 새로 쓴 글에 금지 낱말이나 셋 나열, 「이 문서는」 첫머리, 맺음 요약이 있으면 check:voice 가 줄마다 짚는다 #33 의 말).
• 붙인 블록 안의 줄표(—)와 「Note:」 같은 말은 RFC 원문이라 그대로 두었다. 기존 AGENTS.md 문단(줄표가 많다)도 손대지 않았다. 「Reformat an existing human-written paragraph」 금지와 같은 쪽이다.
• 형제 PR 의 말을 따랐다. k8: 그대로 옮김은 통과. k9: 제목 낱말 그대로, -(stdin) 언급. k10: strict 와 PR base. k12: web/ARCHITECTURE 와 같은 말(check:ci 끝, drift.yml 에서 strict).
• 머지 뒤 생기는 일 하나. 이 절은 커밋과 PR 본문에 「Generated by」 줄과 AI 가 썼다는 말을 금한다. 일꾼 세션은 커밋 끝 Co-Authored-By·Claude-Session 줄과 PR 본문 끝 줄을 하네스 규칙대로 붙인다. 이 PR 의 커밋도 다른 2단계 PR 과 같이 그 줄을 달았다. 머지 뒤에 일꾼이 그 줄을 뗄지는 창작자·총괄이 정할 일이다.

Changelog

Docs

• AGENTS.md carries the writing-voice rule and the step 2 check commands. The writing-voice hard rule from docs/rfc-cleanup.md §2.10 is appended as the RFC writes it, and Common commands gains one line each for check:drift, check:human-lock and check:voice, saying where each runs.

Upstream

• What: Append the writing-voice hard rule from docs/rfc-cleanup.md section 2.10 to AGENTS.md as written, and add one Common commands line each for check:drift, check:human-lock and check:voice.
• Checks: npm run typecheck, npm run lint (0 errors), npm run check:drift (8 passed, strict in CI), npm run check:human-lock, npm run check:voice, check_versions.py and check_links.py pass.
• Docs map: none

🤖 Generated with Claude Code

https://claude.ai/code/session_019vN4JUEcXpNwPFfJeKCpo8

---

Generated by Claude Code