🎯 什麼情境該想到我
當你「明明跟 agent 說了用最新寫法，它還是產出三年前的程式碼」的時候。
⚙️ 怎麼用（步驟 / 公式）
先分清楚是哪一種病——這兩種原因的解法完全不同：
| 病因 | 症狀 | 解法 |
|---|---|---|
| 訓練資料落後 | 模型根本沒看過這個 API | 只能餵它——把新特性的簽章與範例放進 context |
| 頻率偏誤 | 模型知道新寫法，但舊寫法在訓練語料裡更常見，所以輸出還是舊的 | 給明確的「舊 → 新」對照表。光說「請用最新寫法」沒有用 |
第二種是多數人沒意識到、卻更常見的那個。模型的輸出跟隨訓練語料的分布，不是新穎度或品質——它不會因為「知道」就改變偏好。
- 列一份「舊 → 新」對照表，不要只寫規則。每條給：舊寫法程式碼、新寫法程式碼、最低版本需求。
對照具體到能直接比對，模型才有東西可以照著換。 - 標上影響程度，讓 agent 有優先順序。可以用「幾乎每個專案都有數十處／每專案 5–20 處／1–5 處／罕見」這種可判斷的分級，而不是「重要／次要」。
- ⭐ 要求它先偵測專案的版本（
go.mod／package.json／pyproject.toml／*.csproj…），只用到該版本為止可用的特性。
少了這步，你會拿到編不過的程式碼——這比舊寫法更糟。 - 放在 agent 讀得到的地方：skill／plugin／
CLAUDE.md。對照表放在很少被讀的檔案裡等於沒寫。 - 跟既有的自動化工具分工：多數生態都有「把舊碼自動升級」的工具（Go 的
modernize、JS 的 codemod、Python 的pyupgrade）。
那些管既有程式碼，對照表管新產出的程式碼——兩邊目標相同、時機不同。
🧪 我實際套用的紀錄
- 2026-08-28：（待填）
⚠️ 注意 / 什麼時候不適用
- 「新的」不等於「該用的」。有些新 API 有效能或語義上的取捨，別把對照表寫成無條件替換；有疑慮的條目要註明適用條件。
- 對照表會過期，而且它自己就是一份要維護的東西。與其自己寫，先找官方或社群維護的版本。
- 版本偵測是硬需求，不是加分項。沒有它，這套會把「過時但能編」變成「先進但編不過」。
- 這解決不了設計品質。它讓寫法現代化，但架構爛還是爛——那是另一回事。
- 同樣的心法可以反過來用：如果專案刻意要停在舊版本（相容性需求），也要明講，否則 agent 會自作主張用新語法。
🔗 相關工具
- 工具-把重複的prompt包成skill —— 這種對照表就是典型該固化成 skill 的東西：規格清楚、會重複用、跟專案無關
- 工具-提示工程 —— 這張是「模型知道但不用」的專門解法，比通用的 prompt 技巧更對症