[VibeCoding] AI Vibecoding 的地基（上）：大型專案導入前的準備筆記
這篇文章記錄我在一個真實的大型 monorepo（後端數千支服務、前端數百個元件的 .NET + Vue 3 專案） 導入 AI 輔助開發的完整過程——蓋了什麼、為什麼蓋、踩過哪些坑、以及先後順序該怎麼排。 為了不洩漏真實業務內容，範例一律改寫成大家熟悉的 NorthWind（北風貿易） 資料庫情境，路徑也改成通用寫法，但架構、順序、數字都是真實測過的。
在大型專案放手讓 AI 改程式碼之前，需要先蓋五層基礎建設： ①靜態地圖（讓 AI 找得到東西）→ ②閱讀紀律（教 AI 怎麼查地圖，而不是整包讀）→ ③風格範本（讓 AI 寫出來的東西像自己人）→ ④事實庫（記錄程式碼本身回答不了的單一業務真相）→ ⑤深度研究筆記（累積子系統級的來龍去脈，但要有防發散設計）。 前兩層先蓋、成本最低效益最高；後三層要等真實需求出現才動手，不要預先猜測。
起 沒有地圖的 AI，只會用最笨的方法找路
先講一個真實測過的失敗案例。任務是：「幫我追一支 API，看看改動它會影響前後端哪些地方」。 天真的作法是讓 AI 直接對整個 repo 下關鍵字搜尋、讀完相關檔案——聽起來合理，實際跑起來完全不是那回事。
同一個搜尋，因為沒有排除建置產物目錄，回傳結果裡混進了壓縮過的前端 bundle （單行超過五萬字元），總輸出超過 30 萬字元，跑了 兩分鐘還沒結束。 而真正相關的命中，其實只有 5 個檔案、不到一千字。
問題不是 AI 不夠聰明，是它跟人一樣——沒有地圖，只能把整座城市走一遍。專案規模一旦到了 數千支後端檔案、數百個前端元件，「讀完所有相關程式碼再回答」這個策略，成本會直接爆炸。 這篇文章的主張很簡單：在把 AI 放進大型專案之前，要先做的不是寫更好的 prompt，是把整個 codebase 壓縮成一份 AI 可以「按需查詢」的地圖。
承 蓋地圖：把整個專案壓成一份可以按需查詢的索引
地圖長什麼樣子
地圖放在專案根目錄的一個固定資料夾裡（例如 <repo>/.ai/maps/），
由一支腳本一次全量重建。以「前後端函式對照表」這份最常用的分冊為例，實際內容長這樣（一行對應一支 API）：
| 前端函式 | 方法 | URL | 後端 Controller.Action | |---|---|---|---| | getReorderLevel | GET | api/Catalog/Product/GetReorderLevel | ProductController.GetReorderLevel |
除此之外，還有好幾份各司其職的檔案：
| 分冊 | 回答什麼問題 |
|---|---|
| PROJECT_MAP | 專案總覽 + 「該查哪一本分冊」的檢索指南 |
| FEATURE_SLICES | 要改「商品查詢頁」，一次列出前後端所有相關檔案 |
| backend-di | 哪個 Service 用什麼生命週期、註冊在哪個檔案 |
| backend-entities | 資料表欄位對應到哪個 Entity 檔案（查到路徑後只讀那一個檔） |
| component-usage-map.json | 前端元件被哪些畫面用到（反向索引） |
| import-usage-map.json | 某支 store/模組被哪些檔案 import（反向索引） |
| store-api-schema.json | 前端 Store 的 state/actions、API 檔匯出了哪些函式 |
三份 JSON 反向索引長這樣（節錄，實際檔案是完整清單）：
// component-usage-map.json
"ProductBadge": {
"def": "src/components/badge/ProductBadge.vue",
"usedBy": ["src/views/Catalog/ProductList.vue",
"src/views/Ordering/OrderDetail.vue"] // 實際可能有上百筆
}
// store-api-schema.json
"views/Ordering/stores/order.js": {
"storeName": "useOrderStore",
"state": ["header", "lines", "status"],
"actions": ["getOrder", "getReorderLevel", "submitOrder"]
}
重點是這些全部可以重新產生、丟了也不心疼——寫一支產生器，跑一次全量重建， 每份檔案開頭帶上目前的 commit / branch 當時間戳，過期了就重跑，完全不需要人工維護。
為什麼分這麼多份，不做成一份大文件
這是 token 經濟的考量。每份檔案依大小分級對待：幾 KB 的可以整份丟給 AI 讀； 幾十 KB 以上的規則是「先關鍵字定位行號，再取那一段」；結構化的原始資料 （完整依賴圖，體積可能逼近 1 MB）永遠不整包讀，只用程式化查詢單一個 key。
套用到「追一支 API 前後端影響範圍」這個任務，實際查詢配方長這樣：
1. grep crossmap，一行就知道對應到哪個 Controller Action 2. grep 定位到該 Controller 段落，取那 20 幾行（不整檔讀） 3. 查 JSON key，反查前端哪支 store 提供這個函式 4. 查 JSON key，反查這支 store 被哪些畫面 import（爆炸半徑） 5. grep 縮小到「真正呼叫」的檔案 6. grep 該 Service 的註冊生命週期
照這個配方走完整份影響範圍分析，大約只需要 3,000 多個 token； 沒有地圖、土法煉鋼要 十幾萬 token，還可能因為讀到編譯產物直接卡住—— 落差超過 40 倍。差別不是 AI 換了更聰明的版本，是多了一層地圖。
光有地圖還不夠——要教 AI 怎麼讀地圖
地圖越詳細，AI 越容易手滑整包讀進去，反而更貴。所以「怎麼讀」要明文寫成規則， 放進 AI 每次啟動都會自動載入的專案說明書，不能指望它自己猜。核心就三條：
- 不要為了找路由去讀總覽文件——路由表直接寫在說明書裡，照著走。
- 超過一個門檻大小的文件，一律「先 grep 定位行號，再取那一段」，不要整檔 Read。
- 結構化資料（JSON）一律程式化查詢單一個 key，永遠不整包讀；體積最大的原始資料完全禁止讀取。
轉 蓋好地圖不代表萬事OK——三個真正的轉折
地基蓋好之後，以為可以收工了，結果遇到三個沒預料到的轉折——這三個才是整個導入過程裡最值得記下來的部分。
轉折一：自動掃描一定有盲區，第一版一定是錯的
地圖蓋完後，想確認「這張圖到底準不準」，挑了一個自己已經知道答案的案例去驗證——
掃描工具回報「這個元件沒人用」，但我明明知道它在某個畫面上正在用。往下查才發現，
前端框架把某個資料夾底下的元件全部自動註冊成全域元件，
使用端完全不寫 import 語句，樣板裡直接打標籤就能用。傳統「掃 import 語句」的作法，
對這種框架魔法完全失效。第二個盲區是模組內部常用「統一匯出檔」包裝元件，
樣板裡用的又是烤肉串命名法（product-badge），
不是檔名的駝峰式命名——單純字串比對兩層都解不開，通不過就會誤判成「沒人用」。
某個核心元件實測被用在數百個地方，第一版掃描工具卻回報使用數是 0。
任何自動化掃描工具的第一版都假設是錯的。一定要挑幾個「自己已經知道答案」的案例去驗證， 抓到落差再回頭補規則——不要蓋完就直接信它。
轉折二：有些事實，程式碼本身回答不了，而且不只一種形狀
地圖能告訴你「程式碼在哪裡」，但回答不了「這個業務概念，實際的權威資料源頭是哪一個」——
因為常常有不只一個「看起來合理」的候選來源，只有真正測試過的人才知道哪個是真的。
改寫成 NorthWind 情境：商品的「安全庫存」，需求文件可能把它跟訂單明細的歷史出貨匯總混著講；
但實測後發現，真正的權威來源其實是商品資料表本身的 ReorderLevel
欄位。這個結論翻遍程式碼任何角落都推不出來，只有真的跑過一次才有答案。
往下追蹤更多案例後發現，這種「程式碼答不了、只有測試過才知道」的事實其實有三種不同形狀， 對應到三個不同的技術層：
| 形狀 | NorthWind 範例 |
|---|---|
| 後端邏輯：資料真正的根源表 | 安全庫存來自 Products.ReorderLevel，不是訂單匯總 |
| 後端設定：業務條件藏在設定檔哪個 key | 通知信只有正式環境設定值 = "Live" 才會真的寄給客戶，其餘一律攔截給管理者 |
| 前端：畫面看起來的卡控不是真卡控 | 訂單操作按鈕的 v-if 只是顯示過濾，真正的角色/狀態檢查在後端 |
三種形狀的「事實」值得分開存放，而不是塞進一份大檔案——後端邏輯層的事實一般追到 Repository 方法為止，後端設定層追到設定檔的 key 為止，前端層追到 store state 或 API 函式為止。三份檔案格式一致，都是「一句話鏈路 + 路徑」：
// ground-truth-backend-logic.md ### 商品安全庫存（Reorder Level） => Products 資料表 > `IProductRepository.GetReorderLevelAsync(productId)` （<repo>/backend/libs/Database/Catalog/Product/IProductRepository.cs） // ground-truth-backend-setting.md ### 正式環境通知信收件對象 => `_sysCfg.NotifyMode` 設定值 > `NotifyService.BuildMessage()` 判斷 例外：只認字串 "Live"，其餘（含空值、拼錯字）一律攔截給管理者 // ground-truth-frontend.md ### 訂單操作按鈕的真正卡控位置 => `OrderSummary.vue` 的 `v-if` 只是顯示過濾，不是真正卡控 真正卡控一律在後端（狀態 + 角色 + 權限三重檢查），新增動作時前後端都要補
格式設計也走過一段彎路。一開始想寫成「常見誤解 + 正確答案」的對照敘述，很快發現每一筆都要交代「為什麼會誤解」，檔案膨脹得很快；後來收斂成只記錄正確答案本身，需要分支條件才加一行「例外：」，需要長篇解釋才用一行「詳見：」連到別的文件，不整段塞進來。
這份事實只記到「需要測試才能確定」的那一層為止——不記「現在是哪個 Service 在消費它」，因為後者隨時可以用一次搜尋重新查出來，寫死了反而會過期、沒人記得回來更新。 分辨「需要人驗證才知道」跟「機器隨時能重新算出來」，前者才值得手寫留存， 後者交給工具現查就好。
轉折三：敘事型的深度筆記，會讓 AI 自己迷路
團隊另外維護了一個獨立於 repo 之外的「深度研究筆記」資料夾，依日期＋主題分類——每次真的 踩到一個複雜子系統的雷（狀態機、鎖定機制、通知信邏輯…），就請 AI 幫忙 trace 一次， 把過程沉澱成一份文件。這批文件比事實庫豐富得多，一份動輒 1~3 萬字，適合拿來理解 「一整個子系統為什麼這樣設計」，而不是查單一事實。
問題出在把這批筆記接進主專案的閱讀規則時。原本以為「叫 AI 只開需要的那一份就好」已經夠了， 結果實測發現：這些敘事文件彼此常常在內文用文字提到其他子系統的名稱—— 不是自動載入的連結，純粹是行文帶到。AI 讀到一半看到「這個機制跟訂單鎖定的做法類似」， 很自然就想「順手」點開那份訂單鎖定的文件確認——一份接一份，範圍越滾越大。
另外還發現，這批筆記自己的導覽索引檔也早就過期了——維護規則寫著「新增文件後要回來補索引」， 但實際盤點下來，有將近一半的新主題資料夾從來沒被補進去。索引檔本身不可靠，若 AI 為了 找路徑而去讀那份索引，看到的還是全系統總覽加上一長串規則，範圍限制形同虛設。
解法是在主專案這邊，另外維護一份「重新掃描過的、精確到檔案」的本地索引，並且把防發散寫成硬規則，不能只靠常識期待 AI 自己收斂：
// research-notes-index.md（節錄） 1. 只開下表指定的那一份文件，讀完就停。文件內文提到其他主題， 那是行文帶到，不是路標——除非任務明確也需要，不要跟著點開。 2. 絕不直接開外部知識庫自己的總覽文件：一開就是全系統概述＋全部規則＋ 全部主題清單，範圍限制形同虛設。 3. 單一任務最多開 2 份文件。需要開第 3 份，代表範圍可能跑掉了， 先停下來確認，不要自己擴大。 | 主題 | 文件 | 大小 | 讀法 | |-----------------|----------------------------------------|------:|---------------| | 訂單狀態機與鎖定 | 2026XXXX_訂單狀態變更邏輯/分析.md | 10 KB | 可整讀 | | 後端三層架構指南 | 2026XXXX_後端架構/建立指南.md | 27 KB | 先 grep 再取段落 |
敘事型文件的發散風險，往往不是 AI 主動亂逛，是文件內文自己夾帶了「順手看一下這個」的線索。 光講「開一份就好」不夠用，要疊三層防線：索引精確到檔案、明文禁止跟隨文內提及、 加一個「開到第 3 份就要停下來確認」的數量上限——任何一條單獨存在都不夠，疊在一起才頂用。
合 整合起來：完整架構、順序、和一個很重要的分寸感
現在把散落的東西收攏成一張完整的五層架構：
先後順序：準備動手的人，照這個排
- 先做 Layer 1（地圖）——地基，成本最低、最快看到效果，沒有這層後面都做不了。
- 緊接著做 Layer 0（閱讀紀律）——地圖蓋好的當下就要寫，不要事後補，不然地圖越詳細越幫倒忙。
- Layer 2（風格範本）等真的出現「這件事會重複做」的訊號才動手，不要一開始就預判有哪些模式。
- Layer 3（事實庫）永遠是事後累積——不要坐下來預先猜測有哪些地雷，等真的測出一次「文件寫錯」的案例才記一筆，庫存量小，才能一直維持在「可以整篇讀完」的規模。
- Layer 4（深度研究筆記）出現得最晚、也最容易失控——先累積個幾份文件再回頭設計索引與防發散規則，不要一開始就想著要建一套完整的知識庫系統。
輕重緩急：資源有限的小團隊，怎麼取捨
| 層級 | 優先度 | 原因 |
|---|---|---|
| Layer 1 地圖 | 必做 | 投資報酬率最高，純粹一次性腳本投資 |
| Layer 0 閱讀紀律 | 必做 | 成本幾乎是零，沒做等於前面白蓋 |
| Layer 2 風格範本 | 看情況 | 小團隊可以先「人工丟一段現成程式碼當範例」，不急著做自動化 |
| Layer 3 事實庫 | 必做，但成本極低 | 只是要養成「踩雷後隨手記一筆」的習慣 |
| Layer 4 深度研究筆記 | 看情況 | 價值高但風險也高，沒有防發散設計寧可先不接進主流程 |
這整套東西的分寸感很重要——不是規模越大越好、規則越多越好。一個三、五人的團隊， 套上大公司那種層層審批的治理框架，只會拖慢自己；反過來，一個上百人的團隊如果連地圖都沒有， AI 只會變成一個很貴的亂猜產生器。先蓋地圖，再教規矩，等真的重複發生再做範本， 遇到雷才記事實，筆記多了才設計索引——這個順序，比任何單一工具或框架都重要。
說到底，這整件事是把「codebase」當成一個需要先編譯出一份 AI 看得懂、查得快的索引， 才能真正放手讓 agent 動手改的基礎建設——不是錦上添花，是大型專案上 AI vibecoding 能不能穩定跑起來的前提。五層架構講完了，下篇會把每一層實際怎麼下 prompt 攤開來， 照抄就能用。
留言
張貼留言