[DONE] 메인 README 한 번 더 — 독자별 비판 검토부터 하고 다시 다듬는다

[patternflow-bot]

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

메인 README 를 처음 온 사람·빌드하려는 사람·구경 온 사람·편집자·사실 검사의 눈으로 두 바퀴 비판받은 뒤 다시 썼습니다. 머지하면 첫 화면이 매니페스토의 고정 문구와 「브라우저에서 해 보기·만들기·완제품 받기」 세 갈래로 열리고, First light 는 빌드 뒤로 가서 빠졌던 단계를 채우고, 낡은 사실(캠페인·에디션·타임라인)이 레포에 맞게 바로잡힙니다.

위 셋: 폰 첫 화면 전(왼쪽)·후(오른쪽) · 데스크톱 후 · 데스크톱 전. 모두 GitHub 가 그 커밋의 README 를 렌더한 HTML 그대로입니다(이 샌드박스에서 github.githubassets.com 이 막혀 있어 github-markdown-css 로 스타일만 입혔습니다).

체크리스트

• 포크 dev 최신(caaf2c1)에서 시작, 원래 레포 engmung/Patternflow main(511e776) merge — 새 커밋 둘은 이미 dev 에 내용이 들어 있어 파일 변화 없음
• 독자별 비판 1회차 5명(처음 온 사람 · 빌드하려는 사람 · 구경 온 사람 · 편집자 · 사실/규칙 검사) → 고쳐 쓰기 (f1186ca)
• 비판 2회차 4명(처음 온 사람 · 빌드하려는 사람 · 구경 온 사람과 매니페스토 · 잃은 것/사실 검사) → 반영 (34a14d9)
• 마지막 적대적 검사 1명 → 반영 (e5a81cc)
• 사실은 레포로 확인(펌웨어, 가이드 copy, BUILD_GUIDE, BOM, 빌드 지도 데이터, 저널, CHANGELOG), 규칙 지킴(J4 전원만, 브랜드 표기, MIT/CC BY-SA 분리, BUILD_GUIDE §10 은 가리키기만)
• check_links.py 통과, 페이지 안 앵커 6개와 다른 파일로 가는 앵커 확인
• 전·후 첫 화면 스크린샷(GitHub 렌더)과 바꾼 까닭

What — 바꾼 것과 까닭

절 순서 — 전: First light → Where it began → The community responded → Make it yours → Quick facts → Playing it → Editions → How it's built → Repository & documentation → Contributing → Story so far → License
후: Where it began → The community responded → Make it yours (Patterns → The device) → First light → Playing it → MIDI, OSC, MQTT & audio-react → Quick facts → How it's built → Repository & documentation → What's new → Contributing → Story so far → License

1. 첫 화면을 매니페스토의 고정 문구로. 태그라인은 L1 + L2, 경고 다음 첫 문장은 L3 굵게, 백남준(L5)은 「Where it began」 끝에 글자 그대로. 까닭: docs/manifesto.md §11 「README opening — L1 + L2 + L3, with L5 in the section explaining the idea」, §3 「짧은 소개엔 부품 이름을 빼라(ESP32-S3)」. 전 판은 L5 와 칩 이름으로 열렸습니다(처음 온 사람·구경 온 사람·편집자 셋이 짚음).
2. 배지 위에 세 갈래 링크 — Try one in your browser · Build one · Get one assembled. 까닭: 하드웨어 없이 해 볼 수 있는 Live Editor 가 폰으로 7화면쯤 아래에서야 처음 나왔고, 사는 길은 배지 하나뿐이었습니다. 「Play」 는 가이드 이름이라 Live Editor 쪽은 매니페스토 §10 의 「Try」.
3. 광과민 경고를 §13 원문 그대로 — 빠져 있던 「Viewer discretion is advised.」 복원.
4. 배지 6 → 5. 레포 자신을 가리키던 Open Source Hardware 배지를 빼서 폰에서 3줄 → 2줄. Crowd Supply 「Campaign Live」 → 「Funded」(저널 good-but 09-13: 132% 달성, maybe-this-will-work·the-30th-entry: 펀딩은 10월 초 마감).
5. 문 네 개 2×2 표 → 가이드 허브 문구(copy/hub.ts)의 목록, 각 줄에 글 가이드. 까닭: 폰에서 표가 한 화면을 다 차지했고 화살표가 줄바꿈됐습니다. Make 는 「하드웨어 있든 없든」(copy/make.ts: 연습용 커뮤니티·AI 로 함).
6. First light 를 맨 위에서 빌드 뒤로. 까닭: 첫 H2 가 BOOT·RST 절차라 구경 온 사람이 거기서 나갑니다(세 명이 짚음). 내용도 웹 가이드(copy.ts 01 Flash·03 Patterns, copy/build.ts 06)와 BUILD_GUIDE §7·§9 에 맞춰 고쳤습니다: J4 규칙을 단계 위 상자로(빨강 +5V, 검정 GND; DevKit 의 USB-C 는 기판 밖에서 굽기용), 지우는 단계 전에 「이미 쓰는 보드·완제품은 5단계부터」, 컴퓨터에서 빼고 보조배터리도 뺀 채 꽂기, 성공 신호(빨간 네모 패턴 = Origin, 하나뿐인 게 정상), 15초 기다린 뒤 K2, 폰의 「인터넷 없음」 안심, 왼쪽 포트여야 하는 까닭, 빈 스캔, 같은 와이파이로 돌아와 Basics, Format storage 확인, patternflow.local 과 안드로이드 Device address, 패널이 안 켜질 때 볼 것, §9 로 마무리. BUILD_GUIDE §8 은 같은 절차로 내세우지 않습니다(아직 옛 순서).
7. 커뮤니티를 구체적으로, 사람 이름으로. 빌드 지도의 실제 핀(멕시코시티 나무 케이스, 키이우 가로 케이스, 독일 석고 셸), 매니페스토 §5 「한 사람이 한 일이면 누군지 말하라」에 따라 Simone Majocchi(.pfm 모듈, CHANGELOG 3.2.0)와 Martin Lopez(커뮤니티 패턴 최다, builds.ts). 「보드에서 소리, TouchDesigner 작업 중」 문단은 이미 에디션으로 나온 일이라 지금 열린 자리(integrations/)로 바꿈. 손그림 지도 at-a-glance.png 는 뺌 — Crowd Supply 를 「구독, 2026 Q4」로, 창작자가 09-14(eb512b8) README 에서 뺀 Workshop 을 「이야기가 모이는 곳」으로 그리고 있습니다.
8. Make it yours 안에서 Patterns 를 장치보다 먼저(「You don't need hardware to start」), 49% 스크린샷 두 장 → 100% 한 장씩(폰에서 글자가 안 읽혔음).
9. The device: 부품 도착 2주(매니페스토 §8 「지루한 부분도 말하라」), 「BOM 이 링크한 패널을 사라」와 까닭, BUILD_GUIDE §10 링크(전엔 README 어디에도 없었음), v2.x 줄.
10. 틀린 사실 고침: v3.10.5 「다섯 요청」 → 넷(CHANGELOG: 1 + 3), v3.8.0 Audio 내용(네트워크 MIDI 는 3.9.0 — 그 줄 추가), K4 「롱프레스로 불러오기」 → 멈추면 재생(3.11.0), Brain = ESP32-S3-DevKitC-1 N16R8(BOM), 슬립을 MQTT 로 깨우는 건 Performance 에서만, 로컬 빌드가 필요한 경우(드라이버 프로필), make_pack.py 는 묶기만, Ctrl-M 은 Ableton Live 것, 라이선스(코드에 tools·integrations 포함, CONTRIBUTING 과 어긋나던 「패턴을 PR·디스코드로 보내면」 줄 정리, 예전 MIT·CC0 패턴).
11. 낱말: 매니페스토 §9 금지어(drive, visuals, authors, control, generate, backers) → play, look, people, make. 고정 문장은 글자 그대로(L5, 「share it on Community」).
12. Story so far: 9월 「펀딩 성공을 향해」 → 목표 달성, 손 조립 계획; 10월 줄 추가(v3.11.0, Audio 가이드, Anbu, USER EXPERIENCE); 날짜 있는 이정표(Live Editor·Pattern Lab, Nath 의 첫 커뮤니티 빌드, v3.0 보드, 패턴 모듈, Pattern Community, CAN); Mixmag → Mixmag Asia(roadmap-data); 「my first work」(§5 의 예문 그대로).
13. 제목: Repository & documentation 살림, 새 「What's new」 아래 Moving fast. 그대로(RELEASING.md 와 release.py 가 이름으로 부름).
14. CHANGELOG [Unreleased] 의 README 줄 하나를 이 README 에 맞게(아래 가정 참고).

길이: 접힌 것 빼고 보이는 낱말 3,396 → 3,750. First light 를 정확하게 채우고 사람 이름을 넣은 만큼 늘었습니다. 줄인 곳: 첫 화면의 칩·스펙 줄, 표, 반복된 가이드 링크, 낡은 생태계 문단과 손그림 지도.

Tested

• python3 .github/scripts/check_links.py README.md CHANGELOG.md → all 92 relative links resolve · 레포 전체 python3 .github/scripts/check_links.py → all 622 relative links resolve
• 앵커: 페이지 안 6개(#first-light #playing-it #power--runtime #midi-osc-mqtt--audio-react #contributing #license)와 다른 파일로 가는 것(BUILD_GUIDE.md#1-bill-of-materials-bom #off-the-board #9-final-checks #10-known-issues--design-notes, 가이드 #flash #flash-5 #patterns)이 실제 제목·id 와 맞음. 루트 README 의 옛 앵커를 가리키는 파일은 레포에 없음(grep).
• grep -c "—" README.md → 0 (README 의 em dash 없는 관례 유지)
• 렌더: 커밋마다 github.com/…/blob/<SHA>/README.md 를 headless Chromium 으로 열어 GitHub 가 만든 article.markdown-body 를 1280 폭(README 상자 880)·390 폭(폰)에서 찍고, 전체 페이지를 내려 보며 표·목록·그림이 깨지지 않는지 확인.
• 비판 기록: 1회차 5명, 2회차 4명, 마지막 1명. 지적은 레포 파일로 다시 확인한 것만 반영했습니다.
• 이 포크는 GitHub Actions 가 돌지 않아 PR 체크가 없습니다([DONE] 웹 가이드 펌웨어 굽기·와이파이를 BOOT+RST 기본으로 고치고, 메인 README·문서를 정리한다 #7 과 같음).

First light 를 폰에서 렌더한 모습:

실행법

이 브랜치의 README 를 GitHub 에서 열면 됩니다(폰으로도): https://github.com/Patternflow-lab/Patternflow/blob/claude/studio-readme-polish-as2xvs/README.md · 링크 검사 python3 .github/scripts/check_links.py README.md CHANGELOG.md

Which row

CONTRIBUTING 표의 「A fix to a guide, a README or a spec」.

가정

• 「다른 문서는 안 건드림」: README 만 고쳤고 예외 하나 — CHANGELOG [Unreleased] 의 README 줄. [DONE] 웹 가이드 펌웨어 굽기·와이파이를 BOOT+RST 기본으로 고치고, 메인 README·문서를 정리한다 #7 이 쓴 그 줄은 이 PR 로 바뀌는 README(표와 First light 가 맨 위)를 적고 있어서, 두면 다음 릴리스에 틀린 기록으로 나갑니다.
• 히어로(릴과 필름 썸네일, 「400k+ views」 캡션)는 창작자가 만든 그대로입니다. 썸네일은 OXt-yg_7qdk(사이트 히어로 루프), 링크는 BPMhTChY9vg 로 서로 다른 영상입니다 — 의도인지 확인 부탁드립니다(여기선 YouTube 에 닿지 않음).
• Crowd Supply: 배지 「Funded」는 저널로 확인. 「Get one assembled」는 사이트 히어로도 Crowd Supply 로 「Get One」을 앞세워 그대로 두었지만, 지금 주문이 열려 있는지는 여기서 Crowd Supply 에 닿지 않아 확인하지 못했습니다. 키트는 적지 않았습니다(copy/hub.ts 「There are no kits」; 8월 로드맵엔 DIY 키트가 있었음). 지금 파는 것을 알려 주시면 맞추겠습니다.
• docs/media/at-a-glance.png 는 README 에서만 뺐고 파일은 그대로입니다(이제 아무 데서도 안 씀). 다시 쓰려면 at-a-glance.py 를 고쳐 그려야 합니다.
• BUILD_GUIDE §7.4·§8.1 은 아직 옛 순서(먼저 꽂고 굽기, BOOT+RST 는 포트가 안 보일 때만)라 README·웹 가이드와 다릅니다. 이번엔 README 만이라 손대지 않았고, README 가 §8 을 같은 절차로 내세우지 않게만 했습니다. 따로 맞추면 좋겠습니다.
• 레포에 근거가 없어 README 에 넣지 않은 것: 보조배터리 칸의 크기, USB-C 포트만 있는 보조배터리에 자른 C-to-C 선을 꽂으면 5 V 가 안 나올 수 있다는 점(Type-C 전원은 CC 풀다운이 있어야 켜짐).
• 맨 위 한 줄 「Started by media artist SeungHun Lee (@engmung) in Seoul」은 builds.ts·타임라인에서 왔습니다. Azmano 는 저널에서 한 사람으로 쓰여 「collective」라는 말을 뺐고, 사람에게 대명사는 쓰지 않았습니다.
• 창작자가 쓴 문장(Every first-timer…, stainless steel, Sponsor, Moving fast, 타임라인의 숫자, Instagram almost daily)은 지우지 않았습니다.
• 증거 그림은 .github/pr-evidence/pr-8/ 에 올렸다가 다음 커밋에서 뺐습니다([DONE] hardware+web: mbchars' horizontal desktop case (upstream #488) is the fourth case in the /build 3D preview #5·[DONE] 웹 가이드 펌웨어 굽기·와이파이를 BOOT+RST 기본으로 고치고, 메인 README·문서를 정리한다 #7 과 같은 방식, 그림은 a55acbd 에 남음).

🤖 Generated with Claude Code

https://claude.ai/code/session_01RanQkiT18dbS2eF7LVnjuo