明智的開發者不會「先寫程式碼再碰運氣」。他們把新專案推進到頭腦風暴、團隊討論、原型、圖表、提案、ADR、MR/PR 與 GitOps——並由 Review Bot 自動生成 PR 評論，讓人類把時間花在真正重要的事上。這就是生產級手冊。FDE 可以搭建這套體系；若你要設計併為之辯護，Claude Architect Certification 值得追求。
1. 新專案上的「明智」意味著什麼
明智不是更多會議。而是儘早進行低成本學習，並讓晚期的高代價錯誤變得罕見。下列順序使每一步都縮小下一步的爆炸半徑：
Brainstorm → Discuss → Prototype → Diagram → Propose → ADR
→ Implement in small slices → MR/PR + Review Bot → Merge
→ GitOps promote (dev → staging → prod) → Observe → Iterate
僅在有意時跳過步驟（例如單行配置修復）。任何可能進入生產的變更都不要跳過 Review Bot + CI。
2. 頭腦風暴（先獨自，再結構化）
在佔用任何人時間之前，先獨自花 30–90 分鐘：
- 結果： 完成時必須成立的使用者/業務變化是什麼？
- 約束： 時間、預算、合規、現有平臺、團隊技能。
- 非目標： v1 不會構建什麼（保護範圍）。
- 風險： 資料、安全、效能、供應商鎖定、運維負擔。
- 成功指標： 延遲、錯誤率、採用度、成本——選兩個真正重要的。
記成短筆記（Notion/Confluence/倉庫中 docs/ideas/ 下的 markdown）。沒有書面產物的頭腦風暴只是會蒸發的對話。
3. 與同事討論
邀請最小有用圈層：一位將與你一起實現的同伴、一位相鄰系統負責人，以及（需要時）安全或 SRE。保持明智的規則：
- 限時 （25–45 分鐘）。以決策或開放問題結束——不是 vibe。
- 對選項異議，不對人。 強制「方案 A vs B vs 推遲。」
- 指定記錄員。 筆記成為提案的種子。
- 禁止沉默否決。 若有人不安，稍後在 ADR 中把顧慮寫成風險。
非同步也行：短 RFC 評論串往往勝過會議——但仍需有人閉環。
4. 原型（帶到期日的 spike）
不確定性高時做原型：新 API、不熟悉的雲服務、效能問題，或 AI/代理行為。明智規則：
- 在工單中命名為 spike；設定日曆截止（通常 1–3 天）。
- 程式碼放在一次性分支或
spikes/資料夾；不要打磨。 - 用 10 條要點寫下所學——尤其是失敗之處。
- 決定：晉級（重構進產品）、重寫或放棄。
沒有 ADR 就悄悄變成生產的原型，是團隊繼承意外架構的方式。
5. 圖表（足以爭論）
不需要 UML 長篇。優先三張各佔一屏的草圖：
| 圖表 | 回答 |
|---|---|
| 上下文（C4 L1） | 誰與誰通訊？信任邊界？ |
| 序列 | 快樂路徑 + 一條失敗路徑 |
| 部署 | 執行位置；配置與金鑰如何流動 |
把 Mermaid 或圖片存在提案旁（docs/architecture/）。ADR 變更時更新圖表——過時圖片比沒有更糟。
6. 提案（輕量 RFC）
好提案一到三頁：
- 問題與為何現在
- 考慮的選項（至少兩個）
- 推薦及理由
- 影響：安全、成本、運維、遷移
- 釋出與回滾
- 開放問題
請評審並給出明確截止日期。批准（或帶修訂批准）後，把決策寫成 ADR——不要把「真相來源」留在聊天裡。
7. ADR — Architecture Decision Records
ADR 是按約定不可變的短決策記錄。模板：
# ADR-00XX: Title Status: Proposed | Accepted | Superseded by ADR-00YY Date: YYYY-MM-DD Deciders: @alice @bob ## Context What forces are in play? ## Decision What we will do. ## Consequences Positive, negative, and follow-ups. ## Alternatives considered Option A — why not Option B — why not
把 ADR 放在 git（docs/adr/）。從 PR 連結它們。用 supersede 而非改寫歷史——未來的你需要軌跡。
8. MR 與 PR — 交付單元
MR（Merge Request，GitLab）與 PR（Pull Request，GitHub/Bitbucket）是同一概念：可評審的變更集。明智習慣：
- 小： 理想情況下有意義 diff <400 行；按垂直切片拆分。
- 單一意圖： 一個功能、修復或雜務——不是「雜項」。
- 描述： 為何、如何測試、截圖/日誌、風險、回滾。
- 連結： 工單 + ADR + 設計圖。
- 先 Draft 想要早期反饋且不暗示「已可合併」時。
- 絕不強制合併 繞過紅色 CI 或未解決的高嚴重度 bot 發現，除非有書面例外。
示例 PR 正文清單
## Summary - … ## Test plan - [ ] Unit tests - [ ] Manual path … - [ ] Feature flag / config … ## Risk & rollback - Risk: … - Rollback: revert this PR / GitOps revert commit … ## References - ADR-00XX - Ticket ABC-123
9. Review Bot 用法 — 自動生成的 PR 評論
Review Bot 是在每個 MR/PR 上釋出行內評論與摘要的自動化審查者。它不替代人類；它前置乏味與危險事項。
9.1 Bot 應評論什麼
- 安全：注入、授權缺口、金鑰洩漏、不安全預設值
- 正確性：空路徑、競態、損壞的遷移
- 測試：新分支缺覆蓋、濫用快照
- API/契約：破壞性變更未升版本
- 運維：缺超時、無冪等、無限重試
- 風格僅當逃過 formatter/linter（避免噪聲）
9.2 如何簡化開發者生活
- 作者開啟 PR → bot 在數秒到數分鐘內執行。
- 作者在請求人類前先修復或回覆 bot 執行緒。
- 人類審查者閱讀 bot 摘要，並聚焦設計與產品風險。
- 更少「nit」輪次；更快合併；更少因漏掉陷阱導致的週五晚事故。
9.3 典型設定選項
| 方法 | 說明 |
|---|---|
| SaaS Review Bot（如 CodeRabbit、廠商 bot） | 啟用快；調整嚴重度與路徑過濾 |
| Cursor Bugbot / IDE 關聯審查 | 在以 Cursor 為中心的團隊中對 PR diff 很強 |
| 自定義 GitHub Action + Claude / LLM | 完全控制；需要提示詞 + 策略 + 成本上限 |
| 分層流水線（lint → SAST → LLM） | 最佳生產姿態——見 AI 程式碼審查流水線指南 |
9.4 讓 bot 保持有用的策略
- 嚴重度標籤：blocker / should-fix / nit —— nit 不得阻塞合併。
- 忽略生成路徑（
vendor/、lockfile 噪聲、protobuf dumps）。 - 安全敏感路徑（
auth/、infra/、IAM）需要人類批准。 - 記錄誤報；每月反饋進忽略規則。
- 切勿讓 bot 成為生產關鍵服務的唯一審查者。
9.5 最小 GitHub Action 草圖
# .github/workflows/review-bot.yml
name: review-bot
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Review Bot
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
run: |
# Fetch diff, call your review CLI, post review comments via gh api
./scripts/review-bot.sh
實現 review-bot.sh：計算 PR diff，用嚴格 system prompt（安全 + 正確性優先）呼叫模型，並透過 GitHub/GitLab API 發表評論。限制 token；若成本敏感可跳過 draft。
10. 面向生產級質量的 GitOps 最佳實踐
GitOps 意味著：期望狀態存在於 git；協調器（Argo CD、Flux 等）使叢集匹配；晉級是一次 merge；回滾是一次 revert。
- 分離應用程式碼與環境配置 （或清晰目錄：
apps/vsenvs/dev|staging|prod）。 - 不以 kubectl apply 到 prod 作為快樂路徑——僅 break-glass 且可審計。
- 漸進交付： dev 自動同步；prod 手動或門控同步。
- 映象 digest 優於 prod 清單中的可變標籤。
- Policy as code： 用 OPA/Kyverno 約束許可權、倉庫、資源限制。
- 簽名提交 / 出處 在威脅模型要求時啟用。
- 同步後觀察： 健康檢查、錯誤預算、就緒時的自動回滾鉤子。
程式碼質量不只是「乾淨函式」。也是變更如何進入生產。GitOps 使該路徑可審查、可逆、可重複。
11. 端到端質量門（為生產最佳化）
Local: pre-commit (fmt, lint, secrets) + unit tests PR open: CI (build, test, SAST) + Review Bot comments PR merge: human approve + branch protection + required checks Main: build immutable artifact (image digest) GitOps: update env repo / overlay → sync → verify Prod: SLOs + alerts + runbook linked from ADR/PR
12. FDE 角色 — 誰搭建這套系統
Forward Deployed Engineer（前線部署工程師）非常適合在真實團隊中安裝明智開發者體系：
- 倉庫模板：
docs/adr/、PR 模板、CODEOWNERS、分支保護 - Review Bot + secrets + 成本控制
- CI 必過檢查與環境保護
- GitOps 應用（dev/staging/prod）與晉級文件
- 兩週輔導：首個 ADR、首個 bot 調優 PR、首次 GitOps 回滾演練
FDE 主導單個產品倉庫賦能的參考日曆：腳手架與 bot 策略 1–2 周；GitOps 晉級路徑與幹跑回滾再 +1–2 周。文化變革更久——衡量合併時間與逃逸缺陷，而非工具安裝數。
13. Claude Architect Certification — 值得追求
若你設計人類與 AI 代理共同編寫程式碼的系統，Claude Architect Certification 值得追求。它表明你能夠：
- 架構 AI 輔助交付，且不把模型當作絕對正確
- 為代理工作流規定審查策略、護欄與評估
- 向干係人溝通權衡（延遲、成本、隱私、準確性）
- 在 AI 工具旁輔導團隊的 ADR、PR 紀律與生產門
把證書與真實交付配對：搭建 Review Bot、寫三份 ADR、跑一次 GitOps 回滾演練。沒有實踐的紙面不能讓你明智；實踐加上共同語言可以。
14. 反模式（不明智的樣子）
- 巨型 PR 寫著「WIP please approve ASAP」
- 架構只在 Slack 決定，從不進 ADR
- 無測試的原型合入生產
- 因「太囉嗦」而關閉 Review Bot
- 在 GitOps 外熱修生產且無回退計劃
- 人類重複 bot 已抓住的 formatter nits
15. 新專案可複製啟動清單
- 建立
docs/ideas/、docs/architecture/、docs/adr/ - 新增 PR/MR 模板 + CODEOWNERS
- 啟用 pre-commit + CI 必過檢查
- 安裝 Review Bot；調整路徑過濾與嚴重度
- 寫 ADR-0001：「We use GitOps for deploy」
- 定義環境與晉級規則
- 安排 30 分鐘回滾 game day
- 為第一個月輔導預約 FDE 時間；考慮給負責人考 Claude Architect Certification
16. 結語
明智的開發者把新專案當作一串學習產物——筆記、圖表、提案、ADR——再透過 Review Bot 守護、GitOps 晉級的小型 MR/PR交付。這就是在不讓團隊陷入無盡 nit 的前提下，把程式碼質量最佳化到生產級的方式。讓 FDE 鋪好軌道；讓認證架構師在 AI 加速寫碼速度時，讓系統保持誠實。
釋出方 Workstation.
