從虛假繁榮到真實掌控的開發者指南

第一章　悖論與現實

AI 輔助開發帶來了一個令人不安的矛盾：你越依賴它，越需要人類思考。這不是技術缺陷，而是使用哲學的根本問題。

1.1　數據說的殘酷真相

表面上看，AI 工具的採用率極高，但信任度卻出現了反轉訊號：

Stack Overflow 2025 年調查：84% 開發者正在使用 AI 工具
信任度首次下降：從 2023–2024 年的 70%+ 跌至 60%
METR 研究發現：有經驗的開發者「感覺」快了 20%，客觀測試卻顯示慢了 19%
AI 提供 46% 的程式碼補全，但只有 30% 被開發者接受——70% 遭拒或修改

⚠ 核心警示這不是生產力提升，是虛假繁榮。感知效率與實際效率的落差，正是 Context 工程問題的根源。

1.2　Context 視窗的物理極限

AI 的工作記憶有硬性上限，且性能退化不是漸進的，而是突然崩潰：

Context 達到 32k tokens，大多數模型性能降至 50% 以下
宣稱支援 200k tokens 的模型，通常在 130k 就開始不可靠
Chroma Research 確認：性能退化是突發性的，非線性

更致命的是糾錯的方式。AI 沒有記憶，下一個輸出只受當前 context 影響。
當對話中不斷糾正錯誤，AI 看到的模式是「錯誤→修正→錯誤」，下一個輸出更容易再次出錯。
你越想修正它，它越容易錯——這就是悖論的核心。

第二章　Context 工程原則

HumanLayer 創辦人 Dex Horthy 的核心洞察：AI 寫程式的問題不是模型太笨，是你不懂 Context 工程。Context 工程就是管理 AI 的工作記憶——讓它始終在最佳狀態下推理。

2.1　工作桌比喻

🖥 思考框架把 AI 的工作記憶想像成一張桌子。你丟的東西越多（對話記錄、錯誤訊息、重複資料），桌子越亂，它越難找到重點。 Context 工程的本質，就是讓這張桌子隨時保持整潔。

2.2　幻覺偵測三技法

在長對話中，AI 會用「模式補空白」而非承認不確定。以下三個技巧可以主動偵測幻覺訊號：

技法一
　Anchor Citation（強制引用錨點）

要求 AI 直接引用原始碼片段，而非只給路徑行號。若它給的內容與實際檔案不符，幻覺已經發生。

你說 auth middleware 在 middleware/auth.js:8，請直接複製那幾行的實際程式碼給我。不要改寫，原樣貼出。

技法二
　Contradiction Probe（矛盾探針）

故意給出一個錯誤的前提，測試 AI 是否會順從你的錯誤，還是根據程式碼事實反駁：

你說這個專案用 Sequelize，但我記得是 Prisma，你確定嗎？請再去確認一次 package.json 和 models 目錄。

若 AI 說
「你說得對，應該是 Prisma」——幻覺確認。
若它堅持並附上 package.json 第 12 行證據——可信。

技法三　Uncertainty Forcing（強制承認不確定性）

在 prompt 開頭加入系統性指令，把 AI 的預設行為從「填空」改成「承認空白」：

規則：・如果你不確定某件事，必須說「我不確定，需要確認」・如果你找不到對應的程式碼，必須說「找不到，不要猜測」・禁止用「通常」「一般來說」「應該是」描述這個 codebase 的具體實作・「通常」類的描述只能用在解釋概念，不能用在描述這個專案的程式碼

研究階段結束後的驗證關卡

在進入計畫階段之前，執行以下三清單驗證：

請做一個自我驗證： 1. 列出你「直接從程式碼讀到」的事實（附原文片段） 2. 列出你「推斷或假設」的部分（沒有直接證據） 3. 列出你「不確定」的部分用三個分開的清單呈現。

2.3　幻覺的語言訊號

不需要特別 prompt，閱讀 AI 輸出時留意語言模糊度就能早期偵測：

⚠ 幻覺風險高（模糊語言）	✅ 相對可信（具體語言）
這個檔案可能包含…	routes/users.js 第 45 行的 router.get
通常這類專案會…	package.json dependencies 裡有 sequelize: ^6.0
應該是在…附近	controllers/userController.js:87 的 exports.deleteUser
我建議你可以…	middleware/auth.js:8 的 JWT 驗證邏輯確認如下

第三章　RPI 框架

RPI（Research → Plan → Implement）
是針對中大型、長期運行程式庫的三階段工作法。
核心取捨是：犧牲速度，換取清晰度、可預測性與正確性。

💡 RPI 的根本哲學閱讀 1,000 行 AI 程式碼是低效的。審核 1 頁計畫書，才是 10 倍槓桿。 AI 負責打字，你負責思考——RPI 就是把這兩件事拆開，讓每個角色做自己最擅長的事。

3.1　Research（研究）——只讀，不動

讓 AI 探索 codebase，找到正確檔案，全程禁止修改任何程式碼。這個階段的產出必須通過 FAR 驗證。

FAR 驗證標準

Factual（基於事實）：
發現必須來自實際程式碼，不是假設
Actionable（可行動）：
要指出具體檔案路徑和行號
Relevant（相關）：
只記錄跟任務直接相關的發現

Research Prompt 範本

你的任務是「研究」，不是「實作」。禁止修改任何程式碼。
請探索這個 codebase，回答以下問題：
1. [目標功能] 相關的 routes 在哪些檔案？（路徑 + 行號）
2. 目前有沒有相關邏輯？在哪？
3. 資料庫操作使用什麼 ORM/library？
4. 現有的 auth middleware 怎麼運作？路徑在哪？
5. 測試檔案放在哪個目錄？命名規則是什麼？
回答格式：
・事實（來自實際程式碼，附上檔案路徑:行號）
・不要猜測，不知道就說不知道

3.2　Plan（計畫）——每個步驟都能被稽核

開一個全新的對話視窗，把 Research 的「壓縮事實」帶進來，產出一份可執行的計畫書。每個任務都必須通過 FACTS 驗證。

FACTS 驗證標準

Feasible（可行）：
這任務在當前環境可以完成
Atomic（原子化）：
一次只做一件事，不混雜多個目標
Clear（清晰）：
有明確的檔案名稱、行號片段
Testable（可測試）：
有具體的驗證步驟
Scoped（範圍明確）：
知道這步會改什麼、不改什麼

⚠ 計畫的底線沒有程式碼片段的計畫只是「感覺」，不具備執行力。每個 Step 必須包含：具體檔案路徑、修改位置（行號）、預期程式碼片段、驗證方式。

3.3　Implement（執行）——低壓力精準打擊

再開一個全新的對話視窗，context 保持乾淨，帶入計畫書逐步執行。
每完成一個 Step 就停下來等確認。即使是較弱的模型，在低 context 壓力下也能完成高品質修改。

Git 操作節奏

# 開新 branch，保護 main git checkout -b feature/your-feature # AI 改完每個 Step 後，用 patch mode 逐行確認 git add -p # 不要 git add . git diff routes/users.js # 確認只有預期的改動 # 每個 Step commit 一次 git commit -m "step1: add DELETE route to users.js" # 全部完成後整體 review git diff main

💡 git add -p 是最好的 Review 機制強迫你逐行看 AI 改了什麼。防止 AI 偷偷塞入你沒要求的東西。這個習慣在大型專案中價值遠超任何 AI 工具。

第四章　大型程式庫精準導航

10M+ 程式碼已超出任何 context window 能直接處理的範圍。精準導航需要區分兩種根本不同的查詢需求：

語意查詢：「這個系統的權限控制怎麼實作？」——你不知道在哪，需要搜索
結構查詢：「UserService.deleteUser 的完整呼叫鏈是什麼？」——你知道入口，需要追蹤

兩種需求的工具選擇完全不同。混用會讓你效率低落。

4.1　語意查詢：Code-aware RAG

一般 RAG 用文字 embedding，但程式碼不適合。需要以語意單位（函數、class）而非字數來切塊。

核心工具：Tree-sitter

Tree-sitter 能 parse 任何主流語言的 AST，依函數/class 邊界切塊，每個 chunk 保留 file + line range + function name metadata。

# chunk metadata 範例 { "code": "exports.deleteUser = async (req, res) => { ... }", "file": "controllers/userController.js", "start_line": 87, "end_line": 95, "name": "deleteUser" }

Embedding 模型推薦 voyage-code-2 或 text-embedding-3-large，兩者對程式碼語意的理解遠優於通用模型。
向量資料庫選擇：本地用 Chroma，需要 production scale 用 Qdrant。

4.2　結構查詢：Code Graph

RAG 的盲點是不懂呼叫關係。「deleteUser 會影響哪些地方」這類問題，RAG 只能找語意相似片段，卻不知道 A 呼叫 B 呼叫 C 這條鏈。

建立呼叫圖

# 用 ctags 建符號索引 ctags -R --fields=+n --output-format=json . > tags.json # 用 semgrep 做精準靜態分析 semgrep --config auto --json . > analysis.json # 用 ripgrep 做快速文字搜索（比 grep 快 10 倍） rg "deleteUser" --type ts -n --context 3

更完整的做法是用 Neo4j 存關係圖。
節點：Function、Class、File、Module；
關係：CALLS、IMPORTS、EXTENDS、IMPLEMENTS。
查詢變成「找所有 CALLS deleteUser 的節點，再往上兩層」，精準度遠超 RAG。

4.3　Sub-agents 分片架構

這才是針對 10M+ codebase 的真實架構：讓工具做搜索，讓 AI 做推理，兩者不要混用。

主 Agent（低 context，只做推理）
    │
    ├── RAG Sub-agent
    │     任務：語意搜索，回傳 top-5 相關片段 + 位置
    │     輸出：壓縮摘要，不是原始程式碼
    │
    ├── Graph Sub-agent
    │     任務：追蹤呼叫鏈、依賴關係
    │     輸出：A→B→C 的路徑，附行號
    │
    └── File Reader Sub-agent
          任務：讀取特定檔案的特定行範圍
          輸出：只回傳主 Agent 需要的 50 行，不是整個檔案

💡 Sub-agents 的核心原則 每個 Sub-agent 是獨立的 AI 呼叫，帶著各自精簡的 context，不共享同一個對話視窗。 主 Agent 只收到三份壓縮摘要，context 始終保持輕盈。 一個查詢的 context 消耗從「整個 codebase」縮小到「500 tokens 摘要 + 50 行原始碼」。<

4.4　工具選擇速查表

需求	推薦工具	說明
AST 解析	tree-sitter	支援所有主流語言
本地向量搜索	Chroma + voyage-code-2	Code-aware embedding
符號索引	ctags / ripgrep	快速定位函數位置
呼叫圖	semgrep / Neo4j	靜態分析 + 圖查詢
Sub-agent 框架	LangGraph / Claude API	獨立視窗分片執行
快速文字搜索	ripgrep (rg)	比 grep 快 10 倍

4.5　中間檔策略

不建 RAG 也能運作，但需要建立正確的中間檔索引：

.codebase-index/
  ├── symbols.json          # 所有函數/class 名稱 + 位置（ctags）
  ├── file-summaries/       # 每個檔案的 AI 生成摘要（一次性建立）
  │     ├── routes_users.md
  │     └── controllers_userController.md
  ├── dependency-graph.json # import/require 關係
  └── search-cache.json     # 常用查詢的快取結果

file-summaries 是關鍵。批次建立後，Sub-agent 的查詢流程變成：讀 symbols.json 找函數（毫秒級）→ 讀對應 file-summary 確認相關性（幾百 tokens）→ 才讀實際原始碼的特定行範圍（精準打擊）。

第五章　工具生態現況

5.1　Coding Agent CLI 的 ripgrep 支援

ripgrep 已成為這一代 coding agent CLI 的標配基礎設施。三家主要工具各有不同的實作哲學：

工具	ripgrep 支援	實作方式
Claude Code	✅ 內建 Grep tool	工具層抽象，有 rg 則優先使用
Gemini CLI	✅ 自帶 bundled binary	獨立模組 ripGrep.ts，存於 \~/.gemini/tmp/bin/rg
Codex CLI	✅ 依賴系統安裝	Shell 呼叫，官方建議預先安裝

⚠ 注意事項 ctags 三家均無原生支援。 Call graph 追蹤仍需自行建立索引層，不能依賴 agent 工具層。 Claude Code 系統提示明確禁止直接呼叫 rg 指令，必須使用內建 Grep tool。

5.2　LSP 整合：真正的突破

2025 年最重要的進展是 LSP（Language Server Protocol）與 AI agent 的整合。LSP 是確定性的、極度精準的：它知道一個符號在哪裡定義、被用了幾次、一個變數的真實型別，以及一個改動是否引入了編譯錯誤。

Claude Code 2.0.74 版（2025/12）加入 LSP 支援，涵蓋 11 種程式語言
LSP 導航約 50ms，傳統文字搜索在大型 codebase 需要 45 秒——相差 900 倍
有了 LSP，find references 和 call hierarchy 成為原生能力，不需要自建索引

LSAP：專為 AI Agent 設計的協議

LSAP（Language Server Agent Protocol）把 LSP 的底層原子操作提升成 Agent 能直接理解的認知工具。其 Relation API 可在單一請求中找出兩個函數之間的呼叫路徑，自動處理圖的遍歷、循環偵測和格式化。

💡 架構演進舊架構：ripgrep → ctags → 自建 Neo4j call graph 新架構：LSP（結構 + call graph，確定性）+ AI Agent（推理），透過 LSAP 或 MCP 橋接若使用 Claude Code，開啟 LSP 支援後，10M+ codebase 的定位問題從「工程難題」變成「配置問題」。

第六章　DO / DON'T 速查

6.1　Context 管理

❌ 不要這樣做	✅ 應該這樣做
在同一個對話視窗不斷糾錯	切斷對話，壓縮事實，開新 context
把整個 codebase 丟進 context	用 Sub-agent 過濾，只回傳壓縮摘要
對話超過 20 輪繼續追加	執行意圖壓縮，帶摘要重啟
接受 AI 的「通常…」描述你的專案	要求附上實際程式碼路徑和行號
讓主 Agent 讀 500 萬行 codebase	派 Sub-agent 分片閱讀，主 Agent 只收摘要

6.2　RPI 執行

❌ 不要這樣做	✅ 應該這樣做
直接叫 AI 開始寫程式	先完成 Research 和 Plan，再進入 Implement
在同一視窗做 Research 和 Implement	每個 Phase 開新對話視窗
接受沒有行號的計畫書	要求每個 Step 含檔案路徑、行號、程式碼片段
git add . 接受所有改動	git add -p 逐行確認，只 commit 預期的改動
RPI 一再失敗還繼續硬撐	回到白板，由人類重新梳理邏輯

6.3　幻覺防範

❌ 危險訊號	✅ 應對措施
AI 說「這個檔案可能包含…」	要求引用原始碼片段（Anchor Citation）
AI 順著你的錯誤前提走	已發生幻覺，立刻壓縮重啟
AI 重複犯同樣的錯誤	意圖壓縮，切斷對話，開新 context
AI 給出「一般來說…」描述專案細節	Uncertainty Forcing，禁止使用通用語言
計畫書沒有程式碼片段	打回去重問，要求 FACTS 標準

第七章　立即行動清單

從今天開始，三件事立刻能做：

行動一　用 FAR 標準自問下次用 AI 前，先問自己：・這個問題基於事實嗎？（Factual）・有具體可行動的方向嗎？（Actionable）・跟當前任務直接相關嗎？（Relevant）三問都是「是」，才把問題交給 AI。

行動二　要計畫，不要直接寫程式要求 AI 先產出計畫，不要直接寫程式碼。計畫必須包含：檔案名稱、行號、測試步驟、預期程式碼片段。沒有這些要素的計畫，打回去重問。

行動三　超過 20 輪就壓縮重啟當對話超過 20 輪，立刻執行意圖壓縮：・要求 AI 總結已確認完成的事實・關掉這個對話視窗・帶著摘要開新對話繼續放入更好的內容，才能得到更好的輸出。

結語　思考主權

未來 99% 的程式碼可能由 AI 生成。但頂尖開發者和普通開發者的差距，在於誰懂得在 AI 時代保持思考主權。

AI 最大的價值在於放大。它能放大你已完成的思考，也能放大你缺乏思考的事實。

最後一問你要當那個教 AI 怎麼思考的人，還是被 AI 牽著走的人？

參考來源：HumanLayer / Dex Horthy · METR Research · Stack Overflow 2025 · Chroma Research · IEEE ICSME/SANER

August IceKimo

AI 輔助開發實戰手冊 Context 工程・RPI 框架・大型程式庫精準導航

第一章　悖論與現實

1.1　數據說的殘酷真相

1.2　Context 視窗的物理極限

第二章　Context 工程原則

2.1　工作桌比喻

2.2　幻覺偵測三技法

技法一
　Anchor Citation（強制引用錨點）

技法二
　Contradiction Probe（矛盾探針）

技法三　Uncertainty Forcing（強制承認不確定性）

研究階段結束後的驗證關卡

2.3　幻覺的語言訊號

第三章　RPI 框架

3.1　Research（研究）——只讀，不動

FAR 驗證標準

Research Prompt 範本

3.2　Plan（計畫）——每個步驟都能被稽核

FACTS 驗證標準

3.3　Implement（執行）——低壓力精準打擊

Git 操作節奏

第四章　大型程式庫精準導航

4.1　語意查詢：Code-aware RAG

核心工具：Tree-sitter

4.2　結構查詢：Code Graph

建立呼叫圖

4.3　Sub-agents 分片架構

4.4　工具選擇速查表

4.5　中間檔策略

第五章　工具生態現況

5.1　Coding Agent CLI 的 ripgrep 支援

5.2　LSP 整合：真正的突破

LSAP：專為 AI Agent 設計的協議

第六章　DO / DON'T 速查

6.1　Context 管理

6.2　RPI 執行

6.3　幻覺防範

第七章　立即行動清單

結語　思考主權

AI 輔助開發實戰手冊 Context 工程・RPI 框架・大型程式庫精準導航

第一章 悖論與現實

1.1 數據說的殘酷真相

1.2 Context 視窗的物理極限

第二章 Context 工程原則

2.1 工作桌比喻

2.2 幻覺偵測三技法

技法一 Anchor Citation（強制引用錨點）

技法二 Contradiction Probe（矛盾探針）

技法三 Uncertainty Forcing（強制承認不確定性）

研究階段結束後的驗證關卡

2.3 幻覺的語言訊號

第三章 RPI 框架

3.1 Research（研究）——只讀，不動

FAR 驗證標準

Research Prompt 範本

3.2 Plan（計畫）——每個步驟都能被稽核

FACTS 驗證標準

3.3 Implement（執行）——低壓力精準打擊

Git 操作節奏

第四章 大型程式庫精準導航

4.1 語意查詢：Code-aware RAG

核心工具：Tree-sitter

4.2 結構查詢：Code Graph

建立呼叫圖

4.3 Sub-agents 分片架構

4.4 工具選擇速查表

4.5 中間檔策略

第五章 工具生態現況

5.1 Coding Agent CLI 的 ripgrep 支援

5.2 LSP 整合：真正的突破

LSAP：專為 AI Agent 設計的協議

第六章 DO / DON'T 速查

6.1 Context 管理

6.2 RPI 執行

6.3 幻覺防範

第七章 立即行動清單

結語 思考主權

第一章　悖論與現實

1.1　數據說的殘酷真相

1.2　Context 視窗的物理極限

第二章　Context 工程原則

2.1　工作桌比喻

2.2　幻覺偵測三技法

技法一
　Anchor Citation（強制引用錨點）

技法二
　Contradiction Probe（矛盾探針）

技法三　Uncertainty Forcing（強制承認不確定性）

2.3　幻覺的語言訊號

第三章　RPI 框架

3.1　Research（研究）——只讀，不動

3.2　Plan（計畫）——每個步驟都能被稽核

3.3　Implement（執行）——低壓力精準打擊

第四章　大型程式庫精準導航

4.1　語意查詢：Code-aware RAG

4.2　結構查詢：Code Graph

4.3　Sub-agents 分片架構

4.4　工具選擇速查表

4.5　中間檔策略

第五章　工具生態現況

5.1　Coding Agent CLI 的 ripgrep 支援

5.2　LSP 整合：真正的突破

第六章　DO / DON'T 速查

6.1　Context 管理

6.2　RPI 執行

6.3　幻覺防範

第七章　立即行動清單

結語　思考主權