Coding Standard · 編碼規範

---
doc_type: "coding-standard"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["pr-comment-samples", "linter-config"]
  optional: ["existing-style-guide"]
---

# Coding Standard: <language-and-framework>

**Status:** Draft v0.X · **Owner:** <Dev Lead name> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 3, 5, 10, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每條規則行內加 `（依據：PR comment §X / lint rule id）`；每條規則帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造；輕量版規則上限 **15 條**（超過代表沒取捨）；無法被 linter 偵測且嚴重度 < high 的不入規範。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行，新人 30 秒讀完。內容：本 standard 涵蓋什麼語言+框架、共 N 條規則、最常違反的 top 3 -->

<3-5 行說明>

> **TL;DR:** <一句話：這份 standard 解決什麼具體的 review 口水戰>

---

## 2. Language Scope

<!-- ai-rule: 必含語言版本 + 主要框架。版本太舊（>2 年）要在 confidence 標 L 並列升級風險 -->

| Item | Value | Confidence |
|---|---|---|
| Language | <e.g. TypeScript 5.4> | **[H]** |
| Frameworks | <e.g. React 18, Next.js 14> | **[H]** |
| Linter | <e.g. ESLint 9 + typescript-eslint> | **[H]** |
| Formatter | <e.g. Prettier 3> | **[H]** |

---

## 3. Rules（top 10-15）

<!-- ai-rule: 每條規則必含 good/bad 對照 + linter rule id（或 TODO 找對應）+ enforcement 層級。Severity 三級：error / warning / info -->

### CS-001 · Severity **error** · Enforcement **lint** · **[H]**

- **Rule:** <一句話描述>
- **Rationale:** <為何重要 + 從哪個 PR comment 歸納>
- **Linter rule id:** `@typescript-eslint/no-explicit-any`
- **Source:** PR comment §XX (出現 8 次)

**Good:**
```ts
function fetch<T>(url: string): Promise<T> { ... }
```

**Bad:**
```ts
function fetch(url: any): any { ... }
```

### CS-002 · Severity **warning** · Enforcement **pre-commit** · **[M]**

...

---

## 5. Enforcement Matrix

<!-- ai-rule: 每條規則都要有 enforcement 落點 — lint / pre-commit / review / doc-only 之一，無落點視為純廢話 -->

| Layer | Tool | Fail policy | Notes |
|---|---|---|---|
| **CI lint** | <ESLint job name> | fail on error | block merge |
| **Pre-commit** | husky / lefthook | fail on error | local-only |
| **Review** | code-review-checklist | reviewer 判斷 | nit 可拒絕 |
| **Doc-only** | this file | reviewer 引用 | 無自動擋 |

---

## 10. Decision Log（key 2-3 條）

<!-- ai-rule: 每條必含 chosen + 至少 1 個 rejected + 拒絕原因 -->

| Date | Decision | Options | Chosen | Rejected why | Confidence |
|---|---|---|---|---|---|
| YYYY-MM-DD | Formatter 選擇 | Prettier / Biome | Prettier | Biome 工具鏈太新、IDE 整合不足 | **[H]** |

---

## 12. Confidence & Sources & TODO

- **整份 standard 最低 confidence 規則：** <列出所有 [L] 與 [M] 規則>
- **Fabricated assumptions（推測但 input 未明說）：**
  - <假設 1>
- **Highest-value next input:** <下一份最該補的 PR comment 主題 / production incident 史>

### TODO（缺資料）

- _TODO: 需要 CS-007 對應 linter rule id_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 3, 5, 10, 12，刻意不連號）
> - [ ] 規則數量 ≤ 15（超過代表沒取捨）
> - [ ] 每條規則帶 inline `[H/M/L]` badge + good/bad 對照 + linter rule id
> - [ ] 每條規則有 enforcement 層級（不是純文件建議）
> - [ ] Decision Log ≥ 1 條，每條有 rejected reason
> - [ ] 無 YAML / JSON schema 輸出（standard 是給人讀的 markdown）