🌏 Read this article in English
團隊開始用 AI 寫程式了
上週，一個 PR 兩小時就交了。
500 行，邏輯完整，看起來沒問題。
Review 的時候，發現風格跟專案不一致、型別定義缺一半、有幾段邏輯跟現有模組重複但寫法不同。
改完這些，整體時間跟預期有落差。
另一個專案，想用 AI 幫忙重構 legacy code。
AI 改完了，邏輯確實更清楚。
上線後，三個看起來無關的功能壞了。
這不是 AI 不好用。
是 codebase 還沒準備好讓 AI 進來幫忙。
⚡ 3 秒重點
- 核心問題：AI 產出品質的天花板 = codebase 成熟度
- 判斷框架：5 層工程地基模型（L1-L5）
- 適用對象：想導入 AI coding 工具的團隊、評估 AI 效益的主管
- 不適用：純粹想學 AI 工具操作的人（這篇談的是「環境準備」）
Part B：為什麼 AI 不是魔法
AI 工具的天花板，不是 AI 本身
2025 年，85% 的開發者已經在用 AI 工具寫程式。
但根據 Gartner 調查，43% 的企業因「技術成熟度不足」而放棄 AI 專案。
S&P Global 的數據更直接：2025 年有 42% 的企業放棄了大部分 AI 計畫，比 2024 年的 17% 暴增一倍多。
關鍵不在工具本身。
關鍵在：你的 codebase 能承受多少自動化？
類比一下：
再好的廚師，食材爛也做不出好菜。
再強的 AI，codebase 狀態不一致，也寫不出好 code。
兩個案例的真正問題
回到開頭的兩個場景：
| 現象 | 表面問題 | 真正問題 |
|---|---|---|
| PR 被打槍更多 | AI 寫的 code 品質差？ | codebase 沒有統一風格、缺型別定義 |
| 重構改一爆三 | AI 不懂業務邏輯？ | codebase 技術債太多、沒有測試保護 |
AI 只是照著它「看到的」來寫。
如果它看到的是混亂，它產出的就是混亂。
工程成熟度金字塔
這不是新概念。軟體工程早就有「成熟度模型」來描述一個 codebase 的治理程度。
套用到 AI 導入的情境，可以分成 5 層：
L5: 架構漂移修正
↑ AI 能做系統級重構
L4: 技術債清理
↑ AI 改動不會連鎖爆炸
L3: 依賴更新、安全修補
↑ AI 產出能安全上線
L2: 型別、文件
↑ AI 能正確推理意圖
L1: 格式化、import 整理
↑ AI 產出風格一致每一層都是下一層的前置條件。
Key Insight: AI 工具的天花板，不是 AI 本身的能力，而是你的 codebase 能承受多少自動化。
Part A：5 層導入路線圖
L1：格式化、整理 import
目標：讓 codebase 看起來像「一個人寫的」
作法：
- 導入 Prettier / ESLint / gofmt / black
- CI 強制 lint，PR 不過不能 merge
- 移除 unused imports
完成指標：
lint error = 0- 新 PR 不會因為格式被打回
AI 能做到什麼：
- 產出風格一致的 code
- 不會因為「這裡用 tab、那裡用 space」被 review 打槍
L2：型別、文件
目標：讓 AI 能「讀懂」你的 code
作法：
- TypeScript / Python typing
- 關鍵函式加 docstring
- API 文件補齊
完成指標：
- Type coverage ≥ 80%
- 核心模組有文件
AI 能做到什麼：
- 正確推理函式的輸入輸出
- 不會亂猜型別、產出 runtime error
這一層特別重要。
AI 要做自動化修改或理解程式碼，最依賴型別與文件。沒有這些，AI 的推論會非常不穩。
L3：依賴更新、安全修補
目標：降低已知漏洞與版本風險
作法：
- 導入 Dependabot / Renovate
- CVE 掃描、SBOM 管理
- 定期更新依賴
完成指標：
- CVE high/critical = 0
- 依賴版本不超過 2 個 major version
AI 能做到什麼：
- 產出的 code 不會引入已知漏洞
- 自動升級 PR 能安全 merge
L4：技術債清理
目標：讓 AI 改動不會「牽一髮動全身」
作法：
- 建立 refactoring roadmap
- 補齊測試（至少核心路徑）
- 模組化拆分
完成指標：
- Test coverage ≥ 60%（核心路徑 ≥ 80%）
- 模組間依賴清晰
AI 能做到什麼：
- 做局部重構不會連鎖爆炸
- 改動範圍可預測、可驗證
這一層是 AI 能「真正提升生產力」的門檻。
技術債越多，AI 產出的修改越容易出錯，影響範圍越不可控。
L5：架構漂移修正
目標：讓系統架構回到可維運的狀態
作法：
- 重新對齊架構原則
- Domain boundary 重新切分
- 系統級重構
完成指標：
- 模組邊界清晰
- 架構文件與實作一致
AI 能做到什麼：
- 協助分析依賴圖
- 建議模組邊界
- 產出系統級重構 PR（但需要強 guardrail）
跳級時常見的情況
| 跳過 | 常見的情況 |
|---|---|
| L1 | AI 產出風格混亂，review 時間變長 |
| L2 | AI 亂猜型別，runtime error 增加 |
| L3 | AI 引入有漏洞的依賴，上線後被打 |
| L4 | AI 改一個地方，爆三個地方 |
| L5 | AI 越改越亂，最後整個系統失控 |
Key Insight: 每一層都是下一層的前置條件。跳級會出問題。
Part C：團隊怎麼分工
誰該負責哪一層？
| 角色 | 負責層級 | 具體任務 |
|---|---|---|
| Junior | L1-L2 | lint 設定、type 補齊、基礎文件 |
| Mid-level | L2-L3 | 複雜型別、依賴更新、安全掃描 |
| Senior | L3-L4 | 安全架構、技術債優先級、測試策略 |
| Architect | L4-L5 | 架構治理、模組邊界、系統重構 |
這個分層有兩個好處：
- Junior 有明確的成長路徑——從 L1 做到 L2，就是在累積基礎功
- Senior 不用花時間在格式問題——這些應該在 L1 就被 CI 擋掉
主管該看什麼指標？
不需要懂技術細節，看這些數字就夠：
L1：Lint error count（程式碼格式錯誤數）
| 項目 | 說明 |
|---|---|
| 意義 | 程式碼風格不一致的地方有幾處 |
| 健康值 | = 0 |
| 警示值 | > 50（團隊沒在管格式） |
| 常見情況 | 老專案剛導入 lint 時，通常 200-500+ |
| 怎麼看 | CI 報告，或跑 npm run lint |
L2：Type coverage（型別覆蓋率）
| 項目 | 說明 |
|---|---|
| 意義 | 有多少程式碼有明確的型別定義（讓 AI 能推理） |
| 健康值 | ≥ 80% |
| 警示值 | < 50%（AI 會亂猜型別） |
| 常見情況 | JavaScript 專案轉 TypeScript 初期約 30-50% |
| 怎麼看 | npx type-coverage，或 IDE 內建 |
L3：CVE high/critical（高風險漏洞數）
| 項目 | 說明 |
|---|---|
| 意義 | 依賴的套件有幾個已知的高風險安全漏洞 |
| 健康值 | = 0 |
| 警示值 | > 0（有已知漏洞沒修） |
| 常見情況 | 半年沒更新的專案通常 5-20 個 |
| 怎麼看 | npm audit、snyk test、GitHub Dependabot |
L4：Test coverage（測試覆蓋率）
| 項目 | 說明 |
|---|---|
| 意義 | 有多少程式碼被自動化測試保護 |
| 健康值 | ≥ 60%（核心路徑 ≥ 80%） |
| 警示值 | < 30%（改 code 像拆炸彈） |
| 常見情況 | 沒刻意維護的專案約 10-30% |
| 怎麼看 | jest --coverage、SonarQube |
L5：模組耦合度
| 項目 | 說明 |
|---|---|
| 意義 | 模組之間的依賴關係有多複雜 |
| 健康值 | 依專案定義（越低越好） |
| 警示值 | 單一模組被 > 10 個其他模組依賴 |
| 常見情況 | 老專案常有「God module」被 30+ 模組依賴 |
| 怎麼看 | madge --circular、SonarQube、依賴圖工具 |
如果團隊說「AI 工具沒效果」，先看這些數字。
數字不到位，關鍵不在 AI。
漸進式導入建議
不是一次做完 L1-L5，而是：
- 先做 L1——最簡單、最快見效
- L1 穩了再做 L2——型別補齊需要時間
- 每次 PR 讓 codebase 好一點——Boy Scout Rule
時間預估（中型專案）：
| 層級 | 預估週期 |
|---|---|
| L1 | 1-2 週 |
| L2 | 1-3 個月 |
| L3 | 持續進行 |
| L4 | 3-6 個月 |
| L5 | 視架構複雜度 |
Key Insight: 成熟度越高，AI 才能從「輔助」變成「自動化」。
下一步行動
5 問自評：你的團隊在哪一層？
- L1：PR 會不會因為「格式問題」被打回？
- L2：AI 產出的 code 型別正確嗎？還是常常要手動修？
- L3：上次更新依賴是什麼時候？有沒有已知漏洞？
- L4：敢讓 AI 做重構嗎？還是怕改一個爆三個？
- L5：系統架構跟文件一致嗎？還是早就各走各的？
Checklist：每層的完成指標
□ L1：Lint error = 0，CI 強制檢查
□ L2：Type coverage ≥ 80%，核心函式有文件
□ L3：CVE high/critical = 0，依賴定期更新
□ L4：Test coverage ≥ 60%，核心路徑 ≥ 80%
□ L5：架構文件與實作一致Sources
AI 專案失敗率
- Gartner: Lack of AI-Ready Data Puts AI Projects at Risk (2025) | Archive
43% 企業因技術成熟度不足放棄 AI 專案；預測到 2026 年，60% 的 AI 專案將因缺乏 AI-ready data 而被放棄。
AI 專案失敗根因
- RAND: The Root Causes of Failure for Artificial Intelligence Projects (2024) | Archive
80% AI 專案失敗，是非 AI 專案失敗率的兩倍。主因：資料品質、技術成熟度不足、技能短缺。
AI 工具採用現況
- Jellyfish: 2025 AI Metrics in Review | Archive
90% 團隊使用 AI 工具（2024 年僅 61%）；Cursor 市佔從年初 20% 成長到 40%，正在追趕 Copilot。