程式碼風格指南
一句話定義
一份團隊或個人對程式碼書寫風格與結構的成文約定；驗收條件是 Mark-Otto 的 Golden Rule——「每一行程式都看起來像同一個人寫的，無論貢獻者有多少」。
核心要點
元命題：單一作者錯覺
Every line of code should appear to be written by a single person, no matter the number of contributors.
驗收條件不是「規則最完備」，而是讀者讀不出多人協作的痕跡——對位 排版 「好排版『沒有感覺』」的元命題：兩者都用「使用者無感」當終極驗收。
典型涵蓋面（從具體到抽象）
| 層級 | 內容 | 自動化程度 |
|---|---|---|
| 格式層 | 縮排、引號、空白、行尾、換行 | 高（formatter / .editorconfig） |
| 語法層 | 屬性順序、boolean attribute、shorthand 用法 | 中（linter） |
| 命名層 | class / 變數 / 檔案命名規則 | 中（linter rule） |
| 結構層 | 檔案組織、模組切分、宣告順序 | 低（review + 慣例） |
| 判斷層 | 「avoid nesting > 3」「reduce markup」等設計建議 | 低（人類判斷） |
自動化原則：能交給 formatter / linter 的就交給工具，只把不能自動化的部分寫進文件。文件愈短愈可能被讀。
規範的層次
從外向內逐層覆寫：
- 語言 / 平台共識（HTML5 spec 的 case 慣例、PEP 8 對於 Python）
- 生態預設（Prettier 預設、Black 預設）
- 公司風格（覆寫前兩層的差異化決策）
- 專案規範（這個 repo 的特化）
在 Code Review 中的角色
2026-05-06-Google-Code-Review 補上一條重要邊界：在 Code-Review 裡，style guide 是 style issue 的共同裁判；有明文規範就照規範，沒有規範時通常尊重 author 或既有 codebase 一致性。若 reviewer 只是覺得另一種 style 更好，應標示為 Nit:，不應把個人偏好升級成 blocking comment。
跨工法對位：給人類 vs 給 Agent
- 給人類團隊：協作收斂工具——比「哪條規則最對」更重要的是「大家用同一條」。
- 給 LLM / Agent：AI輔助開發 駐留 agent 場景下，
CLAUDE.md/.cursorrules/AGENTS.md等本質就是「寫給 LLM 讀的 style guide」——把專案的特殊約束、命名慣例、不要做的事寫進常駐脈絡，讓 agent 每次 session 啟動自動載入。
公開的代表作
- Mark-Otto Code Guide（HTML / CSS）— 一頁可讀完的精簡範式（vault 內錨點來源）
- Google Style Guides（C++ / Python / Java / Shell / etc.）— 大公司全棧版
- Airbnb JavaScript Style Guide — 社群最廣泛 fork 的 JS 規範
- Prettier / Black — 「無爭議格式化」哲學：用工具消滅風格戰爭
與其他概念的關係
- AI輔助開發 — 駐留 agent 場景下，
CLAUDE.md/.cursorrules本質是「寫給 LLM 讀的 style guide」；style guide 從人類協作工具擴展為 agent 的常駐脈絡。 - 排版 — 共享「沒有感覺 / 像一個人做的」終極驗收元命題：好排版讀者無感、好風格指南讀起來像一個人寫的。
- Context-Engineering — style guide 是長期穩定的低變動 context，由配置層（
CLAUDE.md/.editorconfig/ linter config）一次載入，而非每次 prompt 重述；屬於 context engineering「該說什麼一次說好」的工法。 - Pull-Request / GitHub工作流 — PR 是 style guide 的最後一道把關：再短的指南也需要在 PR review 時被人或 hook 確認；squash-merge 的「main 每個 commit 都正常工作」原則直接對位 Golden Rule「每一行程式都看起來像同一個人寫的」——squash 把多人 / 多次嘗試的雜訊收斂成單一作者外觀，是 Golden Rule 在 commit history 層的具體執行。
- Code-Review — style guide 在 review 中負責把風格爭議從個人偏好轉成共同規則；沒有共同規則時，style comment 多半應是 non-blocking
Nit:。
相關來源
- 2026-05-01-Code-Guide-mdo-HTML-CSS規範 — vault 第一份 style guide 主軸來源；HTML / CSS 篇 + Golden Rule 元命題
- 2026-05-06-Google-Code-Review — 補入 style guide 在 code review 中的權威邊界：style guide > personal preference；未寫入規範的風格建議不應阻擋 CL
備註
Vault 中此概念的初始錨點是 Mark-Otto 的 HTML / CSS 規範。未來累積方向：
- Google / Airbnb / Prettier 等其他代表性 style guide 對位
- linter / formatter 工具層（ESLint / Prettier / Black / Ruff / clippy）
- LLM-target style guide（CLAUDE.md / .cursorrules / AGENTS.md）的成熟工法
- 大型專案的 monorepo style enforcement（pre-commit hook / CI gating）
- Design system 與 code style guide 的交界（Bootstrap / Tailwind / Material 等）