用 AI 讀代碼：快速看懂陌生代碼庫的提問順序與 20 個可複製問題

本文根據 GitHub 官方教學《Using GitHub Copilot to explore a codebase》和 Cursor 官方教學《Understanding your codebase》整理，資料核對於 2026-10-11。方法適用於任何能讀取整個倉庫的 AI 工具。

適用於誰

• 剛入職或剛接手一個項目，面對幾千個文件不知道從哪看起的人；
• 想給開源項目提貢獻，需要先摸清結構的人；
• 搜「ai 讀代碼」「ai 看懂代碼」的人。

結論先說

1. 讓 AI 讀代碼，要用能訪問整個倉庫的工具，而不是把文件一個個貼進聊天框。編輯器裏的智能體（Cursor、Copilot、Trae、Cline）、終端智能體（Claude Code、Codex），以及 github.com/copilot 都可以。
2. 用只讀模式：Cursor 的 Ask 模式、Cline 的 Plan 模式——它只回答、不改文件。
3. 提問從寬到窄：整體概覽 → 入口和構建 → 數據流 → 具體功能 → 具體函數。Cursor 官方的說法是：知道要找什麼就問得具體，探索陌生領域就問得寬。
4. 要求給出處。GitHub 官方的示例提示詞裏反覆出現「Provide evidence」「Provide references」「with a link to the file」——讓它每個結論都指到具體文件，你才能抽查。
5. 讀懂之後再改。沒弄懂就讓 AI 動手，是 Cursor 官方點名的常見失敗模式。

準備：讓 AI 拿到倉庫

私有倉庫、公司代碼，先確認所用工具的數據政策和公司規定，見《AI 編程安全注意事項》。

它是怎麼找到代碼的

了解這一點能幫你把問題問對。Cursor 官方把智能體的搜尋分成兩類：

• 精確搜尋：按確切的字符串找，比如函數名、變量名（底層是 grep 一類的工具）。你問「找出所有 import 了 PaymentService 的文件」，它就會走這條路。
• 按含義搜尋：不知道確切名字時，按意思找相關文件，再用精確搜尋補細節。你問「支付失敗是怎麼處理的」，它會先搜語義再追引用。

所以：記得名字就給名字（函數名、報錯原文、接口路徑、介面上的文字），不記得就描述行為。把介面上看到的一句提示語原樣貼給它，往往是定位功能最快的辦法。

五輪提問

第一輪：整體概覽

text
概述這個倉庫：它是做什麼的、目錄結構、關鍵組件、怎麼運行。
每個結論都指出依據的文件。

第二輪：入口、構建、運行

text
這個項目怎麼構建和啟動？應用的入口在哪些文件？
列出運行它需要的環境變量和外部依賴（數據庫、緩存、第三方服務）。

然後真的照着跑一遍。能跑起來，後面的理解才有地方驗證；跑不起來，把報錯貼回去繼續問。

第三輪：數據怎麼流動

text
描述一次「用戶下單」從前端到數據庫的完整流程：
經過哪些文件和函數、在哪做校驗、在哪寫庫、失敗時怎麼返回。

Cursor 官方的同類示例是：我們的應用怎麼處理支付失敗？從結帳表單到用戶看到的錯誤訊息，帶我走一遍。

第四輪：定位具體功能

text
登入鑑權是在哪裏處理的？哪些接口需要登入、是怎麼判斷的？

text
找出所有調用 sendEmail 的地方，按「觸發場景」分組列出來。

第五輪：畫出來

text
畫一張 Mermaid 圖，展示支付模組的數據流：結帳表單、API 路由、支付服務、第三方支付接口。

Cursor 官方說這類圖對新人上手、寫文檔和設計評審都有用，還能暴露架構問題——比如某個服務依賴了太多其他服務，或者數據流走了一條意料之外的路。

20 個可複製的問題

概覽類（前六條為 GitHub 官方示例的轉述）

1. 根據倉庫裏的代碼，概述代碼庫的架構，並給出依據。
2. 概述這個倉庫：用途、結構、關鍵組件、怎麼運行。
3. 主要入口有哪些？關鍵組件之間是怎麼配合的？
4. 這個倉庫用了哪些語言，各佔多少？
5. 這個倉庫實現了哪些核心算法？
6. 用了哪些設計模式？每種簡要解釋，並給出倉庫裏使用它的代碼示例和文件連結。

定位類

1. 怎麼構建這個項目？（官方）
2. 鑑權是在代碼庫的哪裏處理的？（官方）
3. 描述這個應用裏的數據流。（官方）
4. 用了哪些應用層的安全機制？給出引用。（官方）
5. 找出所有 import 了某某服務的文件，並說明它們各自怎麼處理某某錯誤。（Cursor 官方）
6. 介面上這句提示語「……」是在哪個文件裏輸出的？從那裏往回追到觸發條件。

理解細節類

1. 逐段解釋這個函數：輸入、輸出、副作用、可能拋出的異常。
2. 這個文件裏哪些是歷史遺留的兼容代碼？依據是什麼？
3. 這個配置項在哪些地方被讀取？改掉它會影響什麼？
4. 這兩個模組之間是什麼關係？誰依賴誰？

為動手做準備類

1. 我要給訂單加一個「備註」字段，需要改哪些文件？按順序列出，先不要改。
2. 項目裏已有哪些公共工具函數和校驗器？新代碼應該複用哪些？
3. 這個項目的測試怎麼組織的？怎麼只運行某一個模組的測試？
4. 這個倉庫有哪些不成文的約定（命名、目錄、錯誤處理方式）？從現有代碼裏歸納，並各舉一例。

怎麼判斷它說得對不對

AI 讀代碼會出兩類錯：沒讀到就猜，以及把相似的代碼混在一起。應對辦法：

• 抽查出處。它說「在 auth/middleware.ts 裏校驗」，打開文件看一眼。給不出文件和行號的結論先存疑。
• 反過來問。「你剛才說只有三個地方調用了這個函數，再用精確搜尋確認一遍，列出全部匹配。」
• 用運行結果驗證。加一行日誌、打個斷點、跑一個測試，比讀十遍解釋更可靠。
• 留意它沒讀的部分。大倉庫裏它不會讀完所有文件。問「你讀了哪些文件得出這個結論？」

省上下文的做法

• 讓子智能體去搜。Cursor 內置的 Explore 子智能體在自己的上下文窗口裏運行、用更快的模型，可以並行做大量搜尋，只把結論帶回主對話；Claude Code、Devin Desktop 也有類似的子智能體機制，見《Claude Code Subagents 怎麼用》。
• 一個主題一個對話。弄懂鑑權後，開新對話去看支付。
• 把結論沉澱下來。讓它把這一輪的理解寫成一頁項目說明，或者整理進 AGENTS.md / CLAUDE.md，以後每個會話都能直接用。見《AGENTS.md 怎麼寫》。

text
把我們剛才弄清楚的內容整理成一份新人上手文檔：項目用途、目錄結構、
啟動方式、核心流程、常見坑。控制在一頁內，每一條都標註對應的文件路徑。

常見問題

Q：不會編程，也能用這個辦法看懂一個項目嗎？

可以看懂「它是做什麼的、大致怎麼組成」。從第 2 條問題開始，再追問不懂的術語即可。

Q：倉庫太大，它總是答得很籠統？

縮小範圍：指定目錄、指定功能，或者給它一個具體的入口（某個接口路徑、某句介面文字）讓它順着追。

Q：讀完之後想讓它直接改？

先讓它列出要改的文件和步驟（第 17 條），確認後再切到能修改的模式。之後的流程見《用 AI 重構代碼》和《Cursor Agent 模式怎麼用》。

參考資料

• Using GitHub Copilot to explore a codebase（GitHub 官方教學）：https://docs.github.com/en/copilot/tutorials/explore-a-codebase
• Understanding your codebase（Cursor 官方教學）：https://cursor.com/learn/understanding-your-codebase
• Quickstart（Cursor 官方）：https://cursor.com/docs/get-started/quickstart
• Ask mode（Cursor 官方幫助中心）：https://cursor.com/help/ai-features/ask-mode
• Plan & Act Mode（Cline 官方）：https://docs.cline.bot/core-workflows/plan-and-act