source-driven-development

源碼驅動開發

概述

每個與框架相關的程式碼決策都必須有官方文件作為依據。不要憑記憶實作——驗證、引用，並讓使用者看到你的來源。訓練資料會過時，API 會被棄用，最佳實務會演進。這個技能確保使用者獲得可以信賴的程式碼，因為每個模式都可以追溯到可查證的權威來源。

使用時機

• 使用者想要遵循特定框架當前最佳實務的程式碼
• 建立專案中會複製使用的樣板、起始程式碼或模式
• 使用者明確要求有文件、可驗證或「正確」的實作
• 實作框架建議方法很重要的功能（表單、路由、資料擷取、狀態管理、認證）
• 審查或改進使用框架特定模式的程式碼
• 任何時候你即將憑記憶撰寫框架特定程式碼

何時不使用：

• 正確性不依賴特定版本（重新命名變數、修正錯字、移動檔案）
• 在所有版本中運作方式相同的純邏輯（迴圈、條件判斷、資料結構）
• 使用者明確要求速度優先於驗證（「趕快做就好」）

流程

偵測 ──→ 擷取 ──→ 實作 ──→ 引用
  │          │           │            │
  ▼          ▼           ▼            ▼
 什麼       取得相關   遵循文件    顯示你的
 技術堆疊？ 文件       中的模式    來源

步驟 1：偵測技術堆疊與版本

讀取專案的相依性檔案以識別確切版本：

package.json    → Node/React/Vue/Angular/Svelte
composer.json   → PHP/Symfony/Laravel
requirements.txt / pyproject.toml → Python/Django/Flask
go.mod          → Go
Cargo.toml      → Rust
Gemfile         → Ruby/Rails

明確說明你找到的內容：

偵測到技術堆疊：
- React 19.1.0（來自 package.json）
- Vite 6.2.0
- Tailwind CSS 4.0.3
→ 正在擷取相關模式的官方文件。

如果版本遺失或不明確，詢問使用者。不要猜測——版本決定哪些模式是正確的。

步驟 2：擷取官方文件

擷取你要實作功能的特定文件頁面。不是首頁，不是完整文件——而是相關頁面。

來源層級（依權威性排序）：

優先級	來源	範例
1	官方文件	react.dev, docs.djangoproject.com, symfony.com/doc
2	官方部落格 / 更新日誌	react.dev/blog, nextjs.org/blog
3	網頁標準參考	MDN, web.dev, html.spec.whatwg.org
4	瀏覽器/執行環境相容性	caniuse.com, node.green

不具權威性——切勿引用為主要來源：

• Stack Overflow 回答
• 部落格文章或教學（即使很受歡迎）
• AI 生成的文件或摘要
• 你自己的訓練資料（這正是重點——驗證它）

精確指定你要擷取的內容：

不好：擷取 React 首頁
好：擷取 react.dev/reference/react/useActionState

不好：搜尋「django authentication best practices」
好：擷取 docs.djangoproject.com/en/6.0/topics/auth/

擷取後，提取關鍵模式，並注意任何棄用警告或遷移指南。

當官方來源彼此衝突時（例如遷移指南與 API 參考矛盾），向使用者揭露差異，並驗證哪個模式實際上適用於偵測到的版本。

步驟 3：遵循文件中的模式進行實作

撰寫與文件顯示相符的程式碼：

• 使用文件中的 API 簽章，而非憑記憶
• 如果文件顯示新的做法，就使用新做法
• 如果文件棄用某個模式，就不要使用已棄用的版本
• 如果文件未涵蓋某個部分，將其標記為未驗證

當文件與現有專案程式碼衝突時：

偵測到衝突：
現有程式碼庫使用 useState 處理表單載入狀態，
但 React 19 文件建議使用 useActionState 處理此模式。
（來源：react.dev/reference/react/useActionState）

選項：
A) 使用現代模式（useActionState）——與當前文件一致
B) 比照現有程式碼（useState）——與程式碼庫一致
→ 你偏好哪種做法？

揭露衝突。不要默默選擇其中一個。

步驟 4：引用你的來源

每個與框架相關的模式都必須有引用。使用者必須能夠驗證每個決策。

在程式碼註解中：

// React 19 表單處理使用 useActionState
// 來源：https://react.dev/reference/react/useActionState#usage
const [state, formAction, isPending] = useActionState(submitOrder, initialState);

在對話中：

我使用 useActionState 而非手動的 useState 來處理表單提交狀態。
React 19 用這個 hook 取代了手動的 isPending/setIsPending 模式。

來源：https://react.dev/blog/2024/12/05/react-19#actions
「useTransition 現在支援非同步函式 [...] 自動處理待處理狀態」

引用規則：

• 使用完整網址，不要縮短
• 盡可能使用帶有錨點的深層連結（例如 /useActionState#usage 優於 /useActionState）——錨點比頂層頁面更能承受文件重構
• 當引用支援非顯而易見的決策時，引用相關段落
• 在推薦平台功能時，包含瀏覽器/執行環境相容性資料
• 如果你找不到某個模式的文件，明確說明：

未驗證：我找不到此模式的官方文件。這是基於訓練資料，可能已過時。
在生產環境使用前請先驗證。

誠實說明你無法驗證的部分，比虛假的信心更有價值。

常見的合理化藉口

合理化藉口	現實
「我對這個 API 很有信心」	信心不是證據。訓練資料包含看似正確但與當前版本衝突的過時模式。請驗證。
「擷取文件浪費 token」	幻想出一個 API 浪費更多。使用者除錯一小時，然後發現函式簽章已經改變。一次擷取可以避免數小時的重工。
「文件不會有我需要的內容」	如果文件沒有涵蓋，那是有價值的資訊——該模式可能不是官方推薦的。
「我只要提一下它可能過時就好」	免責聲明沒有幫助。要嘛驗證並引用，要嘛清楚標記為未驗證。含糊其辭是最糟的選項。
「這是簡單的任務，不需要檢查」	使用錯誤模式的簡單任務會變成模板。使用者將你棄用的表單處理器複製到十個元件中，才發現現代做法存在。

紅旗警示

• 未檢查該版本的官方文件就撰寫框架特定程式碼
• 使用「我相信」或「我認為」來描述 API，而非引用來源
• 實作模式時不知道它適用於哪個版本
• 引用 Stack Overflow 或部落格文章而非官方文件
• 使用已棄用的 API，因為它們出現在訓練資料中
• 在實作前未讀取 package.json / 相依性檔案
• 交付的程式碼中，框架特定決策沒有來源引用
• 只擷取一個相關頁面時，卻擷取整個文件網站

驗證

使用源碼驅動開發實作後：

• [ ] 從相依性檔案中識別出框架和函式庫版本
• [ ] 為框架特定模式擷取了官方文件
• [ ] 所有來源都是官方文件，而非部落格文章或訓練資料
• [ ] 程式碼遵循當前版本文件顯示的模式
• [ ] 非顯而易見的決策包含帶有完整網址的來源引用
• [ ] 未使用已棄用的 API（已對照遷移指南檢查）
• [ ] 文件與現有程式碼之間的衝突已向使用者揭露
• [ ] 任何無法驗證的內容都已明確標記為未驗證