AI-First Coding：如何讓 AI 更有效率地幫你寫 Code
現在的軟體開發方式正在發生根本性的轉變。
以前我們思考的核心問題是：
「怎麼把程式碼寫得最漂亮、最容易讓人維護？」
但如果現在主要由 AI 協助，甚至直接產生 Code，問題應該改成：
「怎麼讓 AI 下一次修改這份 Code 時，需要理解的 Context 最少？」
這兩件事情並不完全相同。
對 AI Coding 而言，真正昂貴的不是 Code 行數，而是：
- AI 需要讀多少 Code
- AI 需要理解多少關聯
- AI 需要跨多少檔案
- AI 需要猜多少隱藏規則
- 修改後需要重新測試多少功能
- 一次修改產生多少 Diff
因此，AI-first 的程式設計原則應該從「程式碼漂亮」轉向：Low Context、Low Coupling、Small Diff、Small Regression Scope。
一、AI Coding 最重要的不是「少寫 Code」，而是「少讀 Code」
人類工程師可以花半小時閱讀一個專案。
AI 則會受到 Context Window、Token 成本以及推理成本的影響。
舉例來說：
需求：修改 Landing Page 的 B12 流程步驟
做法 A（傳統寫法）：
LandingPageSchema.php
B02
B03
B04
B06
B07
B08
B09
B10
B11
B12
B13
B14
B15
B16AI 必須先理解大量無關的 Block。
更好的架構是讓 AI 可以快速定位：
B12 → b12Steps()然後只理解：
protected static function b12Steps(): Block
{
...
}這就是 AI-first 的核心：
不是讓 Code 最小，而是讓 AI 每次修改時需要理解的 Context 最小。
二、不要過度拆檔案
傳統工程習慣很容易變成：
LandingPage/
├── B02.php
├── B03.php
├── B04.php
├── B06.php
├── B07.php
├── B08.php
├── B09.php
├── B10.php
├── B11.php
├── B12.php
├── B13.php
├── B14.php
├── B15.php
└── B16.php看起來很乾淨，但 AI 修改 B12 時可能需要：
找到 B12 → 找到 Registry → 找到引用 → 找到 Base Schema → 找到 Helper → 找到相關設定
Context 反而增加。
因此：不要為了「檔案看起來乾淨」而拆檔。
比較適合 AI 的方式通常是：
LandingPageSchema.php
├── Registry
├── B02
├── B03
├── B04
├── B06
├── ...
├── B16
└── Helpers這種「單檔、功能區塊化」有一個很大的優點：
AI 可以透過命名快速定位功能，同時避免跨檔案理解。
三、功能邊界比檔案數量更重要
AI-first 架構不是「全部塞在一個檔案」。
真正的原則是：一個功能應該有清楚的邏輯邊界。
例如：
protected static function b12Steps(): Block就是非常好的 AI 定位點。
AI 收到：
B12 的步驟標題限制改成 12 字。
可以直接定位：
b12Steps() → 步驟標題 → maxLength()而不是重新理解整個 CMS Builder。
因此，命名本身就是 AI 的 Navigation System。
四、不要讓 AI 猜架構
AI 最容易出錯的情況不是 Code 寫錯，而是它不知道你的專案規則。
例如你的專案可能有：
- SharedFields
- BlockRegistry
- BaseModel
- HasTranslatable
- Permission Convention
- API Transformer
- Cache Convention
如果沒有規則，AI 很容易自己發明：
NewHelper、NewService、NewTrait、NewRepository、NewBaseClass
最後變成：
原本 1 個檔案 → AI 新增 5 個檔案 → 跨檔案依賴增加 → Token 增加 → 維護成本增加
所以 AI Coding 必須有一個非常重要的規則：
Reuse Before Create
先搜尋現有：
Helper、Service、Trait、SharedField、Component、Repository、Enum、Transformer
確認不存在之後，才允許新增。
五、AI 修改 Code 時，Diff 必須最小化
這是 AI Coding 最重要的規則之一。
不要要求 AI：
「順便幫我重構這個檔案。」
除非你真的要重構。
應該要求：
「只修改造成這個問題所必要的程式碼，不要進行其他重構。」
因為 AI 很容易做：
需求：修改 B12 標題長度
AI 實際行為：
- 重構 B12
- 抽出 Helper
- 修改命名
- 整理 imports
- 調整其他 Block
- 順便最佳化 Registry
最後你得到的不是 +1 行，而是 +80 / -120。
這會直接增加 Review 成本、Token 成本、Bug 風險、Regression Scope。
因此應該建立：Minimal Diff Principle。
六、不要為了 AI 未來好維護，現在就做大重構
這是非常重要的原則。
例如目前 B02～B16 已經功能正常、測試完成、Production 穩定。
這時候發現：
「如果拆成多個檔案，AI 以後可能比較好維護。」
不代表現在就應該重構。
因為：重構 → 整體重新測試 → 增加 Regression Risk → 增加開發時間
如果沒有實際需求，收益可能非常低。
更好的方式是：
現在維持現狀 → 下一次修改 B12 時順手改善 B12 → 只測 B12
這叫 Incremental Refactoring，而不是一次性大重構。
七、把「修改範圍」直接告訴 AI
一個好的 AI Prompt 不應該只有：
「幫我修 B12。」
應該明確指定：
修改範圍：
- 僅修改 LandingPageSchema::b12Steps()
- 不修改其他 Block
- 不新增檔案
- 不新增 Helper
- 不修改 SharedFields
- 不修改資料庫
- 不修改 API
- 不修改既有資料結構這會大幅降低 AI 的探索範圍。
八、推薦使用「Think → Locate → Modify → Verify」
不要叫 AI 一開始就寫 Code。
推薦固定使用：
- Think
- Locate
- Modify
- Verify
Prompt 範例：
在修改 Code 前，先執行以下流程：
1. 分析需求的真正原因，不要立即修改。
2. 找出實際負責此功能的 Entry Point。
3. 找出最小必要修改範圍。
4. 優先使用現有的 Helper、Service、Component 與 Convention。
5. 不要建立新的抽象，除非現有架構無法合理支援。
6. 不要修改需求範圍以外的 Code。
7. 不要順便重構、重新命名或格式化無關程式碼。
修改完成後說明：
- 修改了哪個檔案
- 修改了哪個方法
- 為什麼需要修改
- 是否影響其他功能
- 建議測試範圍核心原則：Small Context → Small Diff → Small Test Scope
九、讓 AI 優先搜尋，而不是閱讀整個專案
AI 最有效率的流程不是：
讀整個專案 → 理解全部架構 → 開始修改
而是：
需求 → 搜尋關鍵字 → 找到 Entry Point → 讀附近 Code → 追必要 Dependency → 修改
例如修改 B12：
先搜尋 b12Steps，再搜尋 steps，最後只讀 LandingPageSchema 與 SharedFields 真正需要的部分。
因此你的 Prompt 可以要求：
請採用「由需求反向定位」的方式處理：
1. 先搜尋與需求直接相關的 Class / Method / Field。
2. 找到 Entry Point 後，只追蹤完成需求所必要的 Dependency。
3. 不要為了理解整個專案而讀取無關檔案。
4. 優先使用現有架構。
5. 找不到必要資訊時再擴大搜尋範圍。
目標不是理解整個專案，而是以最小 Context 完成正確修改。十、Prompt 最重要的不是「告訴 AI 怎麼寫」，而是「告訴 AI 不要做什麼」
這是一個非常重要的觀念。
一般 Prompt：
幫我修改 B12。
AI 有非常大的自由度。
好的 Prompt：
只修改 B12。
禁止：
- 修改其他 Block
- 新增檔案
- 新增 Service
- 新增 Helper
- 修改 DB
- 修改 API
- 重構現有 Code
- 修改命名
- 修改無關格式這叫 Negative Constraints。
在 AI Coding 裡面，限制條件往往比需求描述更重要。
十一、建立「AI Coding Contract」
可以把整個專案的規則濃縮成一份 AI-CODING-RULES.md：
# AI Coding Rules
## 1. Core Principle
Think Before Code.
目標不是產生最多 Code，而是以最小 Context、最小 Diff 完成需求。
## 2. Locate Before Modify
修改前必須先找到：
- Entry Point
- 實際負責功能的 Method
- 必要 Dependency
- 現有可重用元件
禁止未定位就直接修改。
## 3. Reuse Before Create
優先使用：
- Existing Helper
- Existing Service
- Existing Trait
- Existing Component
- Existing Convention
除非現有架構無法合理支援，否則不要新增抽象。
## 4. Minimal Diff
只修改完成需求所必要的 Code。
禁止：
- 順便重構
- 順便重新命名
- 順便格式化
- 修改無關功能
- 修改其他 Module
## 5. Minimal Context
不要閱讀整個專案。
採用：Search → Locate → Read Relevant Context → Modify
只有必要時才擴大 Context。
## 6. File Structure
不要為了理論上的 Clean Architecture 過度拆檔。
優先考慮：Feature Boundary > File Count
功能相關的 Schema、Helper 可以在同一個檔案內保持集中。
## 7. No Speculative Architecture
禁止因為「未來可能需要」而新增：
Service、Repository、Trait、Interface、Abstract Class、Helper
除非目前需求已經證明需要。
## 8. Regression Scope
每次修改都應該盡可能縮小測試範圍。
修改單一 Block → 優先測試該 Block。
修改 SharedFields → 才需要測試所有使用該 SharedFields 的功能。
## 9. Refactoring Policy
不要因為 Code 不夠漂亮就主動重構。
只有以下情況才進行重構：
- 已經影響目前需求
- 已經造成重複問題
- 已經造成維護問題
- 使用者明確要求重構
## 10. Final Response
完成修改後，只需要回答：
- 修改檔案
- 修改位置
- 修改原因
- 影響範圍
- 測試建議
不要描述與本次需求無關的架構。十二、真正有效率的 AI Coding Prompt
最後，可以把日常開發 Prompt 簡化成這個：
AI Coding Task
Goal
[描述我要完成什麼]
Scope
只允許修改：
- [檔案 / Class / Method]
Constraints
- 不修改需求範圍以外的 Code
- 不新增檔案，除非確實必要
- 優先使用現有 Helper / Service / Component
- 不進行額外重構
- 不重新命名無關 Code
- 不修改 DB / API / Architecture，除非需求明確要求
Process
1. 先分析 Root Cause。
2. 找出 Entry Point。
3. 找出最小修改範圍。
4. 確認是否存在可重用的既有實作。
5. 執行最小修改。
6. 檢查是否產生不必要 Diff。
7. 說明需要測試的最小範圍。
Output
完成後只回報：
- Root Cause
- Modified Files
- Modified Methods
- What Changed
- Test Scope核心原則：Do not optimize the architecture. Optimize the change.
十三、AI-first 的真正目標
最後可以把整套方法濃縮成一個公式：
AI 開發效率 = 正確率 × Context 效率 × 修改精準度 × 測試範圍控制
而不是：
AI 開發效率 = Code 寫得多快
所以你真正應該追求的是：
需求 → 最小 Context → 最小理解範圍 → 最小 Diff → 最小 Regression Scope
這也是為什麼有時候：
一個 800 行、但功能邊界清楚的檔案，可能比 15 個 50 行的小檔案更適合 AI 維護。
因為 AI 不需要一直跳來跳去。
結論
如果未來幾乎全部 Code 都由 AI 協助完成，那麼我們其實正在從：
Human-readable Architecture
逐漸轉向：
AI-navigable Architecture
好的 AI Code 不一定是最符合傳統 Clean Architecture 的 Code。
而是：
AI 能快速找到、快速理解、快速修改，而且每次修改只影響最小範圍的 Code。
因此真正值得建立的不是「讓 AI 寫更多 Code 的 Prompt」，而是：
讓 AI 少讀 Code、少猜東西、少改 Code、少產生 Diff、少需要重新測試。
這才是 AI-first Software Development。
