這不是一個「叫 AI 幫我寫幾段程式碼」的系列，是一次從零開始，把大型語言模型、程式碼搜尋、結構化索引、評估與安全限制組合成工程工具的實作旅程。

在開始之前

接手一個陌生專案時，最常出現的不是「我不會寫 Python」，而是**「我不知道該先看哪裡」**。

設定可能藏在某個不起眼的模組、函式名稱在多個檔案中重複出現，一個看似簡單的修改，卻可能影響好幾層呼叫鏈。這種時候，我們通常會先用全文搜尋，再開很多檔案來回比對，最後憑經驗猜測修改範圍。

小型專案還能靠記憶處理，但 Repository 一大，這個方法很快就會失效。程式碼每天都在改，文件不一定同步，聊天型 AI 也不可能永遠記住整個專案的最新狀態。即使把一段程式碼貼給模型，它也可能因為缺少上下文，不知道這個函式在哪裡被呼叫，更不知道修改後會不會影響其他模組。

所以我想做一個不同方向的工具：讓 AI 不只是回答問題，而是能夠自己查詢 Codebase、找出定義、整理證據，並在修改前提醒可能受影響的地方。 這就是這個 30 天專案的起點。

我想打造的是什麼？

最後的成果是一個 Codebase Intelligence Agent。它的定位不是取代工程師做決策，而是協助工程師更快理解程式碼。

使用者可以用自然語言提問，例如：

• 「COLLECTION_NAME 定義在哪裡？」
• 「哪些檔案直接 import rag_common？」
• 「build_index 會呼叫哪些函式？」
• 「如果修改這個模組，可能影響哪些 caller？」
• 「和 Qdrant path 有關的程式碼有哪些？」

Agent 收到問題後，不應該只靠模型的模糊記憶回答，而是要先選擇適合的工具，再把查到的檔案路徑、行號與程式片段整理出來。回答可以由模型生成，但證據必須來自實際 Repository。

為什麼不直接使用一般聊天型 AI？

一般 LLM 很適合解釋一小段程式碼，也很適合協助產生範例，但面對完整 Codebase 時有三個明顯限制：

1. 不知道本機檔案目前的最新狀態
2. 不會自動理解所有模組之間的依賴與呼叫關係
3. 當上下文不完整時，容易幻覺（Hallucination）出看似合理的錯誤答案

這不是模型不夠聰明，而是資料取得方式不對。要回答「誰使用了這個函式」，系統必須真的掃描 Repository；要回答「改動會影響什麼」，系統必須建立符號、import 與呼叫關係。光靠一個超長 Prompt，並不能取代索引與分析工具。

這不只是一個 RAG 專案

這個系列會使用 RAG 的概念，但 Codebase Agent 和一般「文件問答」有很大的差異。

文件 RAG 通常把文章切成段落（Chunk），找出相似內容後交給模型摘要；但程式碼擁有 函式、類別、方法、Import、呼叫關係與檔案路徑 等嚴謹結構。如果只把整個 .py 檔切成幾段純文字，可能找得到關鍵字，卻不一定知道那是「定義」、「使用位置」還是「註解」。

因此這 30 天會逐步加入結構化能力：

• 先做文字搜尋
• 再用 Python AST 找出 Symbol
• 接著建立 Import 索引與程式碼 Chunk
• 加入本地 Embedding 和 Hybrid Search
• 最後建立跨檔案呼叫圖（Call Graph），讓系統能從被修改的函式往回追蹤 Caller

30 天會學到什麼？

1. 程式碼結構理解
   透過 AST 找出 module、class、function、method、import 與 call，並保留檔案路徑和行號。讓搜尋結果不再只是相似字串，而是可以回到原始程式碼驗證的具體證據。

2. 混合搜尋與 RAG（Hybrid Search）
   結合關鍵字搜尋與語意向量搜尋。關鍵字適合精準尋找設定名稱，語意搜尋則處理不知道實際變數名稱的提問。兩者合併後，再用 Deterministic Rerank 或本地 LLM 做第二階段排序。

3. Agent 架構設計與控制
   根據問題動態選擇工具、嚴格限制工具權限、處理失敗邊界情況，並在沒有證據時停止回答。這些工程規則會比 Prompt 更接近真正的系統控制。

4. 客觀評估機制
   搜尋結果不能只靠感性判斷。我們將建立評估資料集，使用 Hit@k、MRR 與 Precision@k 量化比較不同搜尋策略，確保更換 Chunk、Embedding 或 Reranker 後確實有所提升。

5. 安全 Guardrails 與邊界防護
   第一版 Agent 採用嚴格唯讀機制：不直接修改檔案、不任意執行 Shell、沒有證據就不給予肯定答案。針對模型出錯的情況，建立 Timeout、格式檢查與安全 Fallback 機制。

讀者最後會得到什麼？

完成這 30 天後，你將會獲得：

• 一套可以實際執行的 Codebase Intelligence Agent
• 一套完整程式碼索引與搜尋流程
• 一份可重複執行的評估資料集
• 一個跨檔案影響分析工具與完整的單元測試

更重要的是，你會深刻理解一個真正的 Agent 系統絕不只有 LLM，還涵蓋了資料取得、工具設計、檢索品質、錯誤處理、權限邊界與驗證方法。

從會用 AI，到會打造 AI 工具
這 30 天真正想練習的，不是把模型包裝成聊天視窗，而是學會把模型、工具、資料、索引、測試和限制組合成一個可維護的工程系統。當 Agent 能回答問題也能拿出證據、不知道答案時能坦白承認、模型失敗時程式仍能安全退回，這才是一個「可用」系統的起點。

明日預告：我們會先弄清楚為什麼我們需要一個 Codebase Intelligence Agent。