大型 repository 用 Copilot CLI 前，先用 sparse-checkout 縮小工作目錄
大型 repository 啟動 AI coding 工具時，常見的卡點不是 prompt 寫得不夠長，而是工作目錄一次帶進太多檔案。近期 GitHub Copilot CLI 的公開 feature request 提到，希望在建立 session worktree 時支援 sparse-checkout，以避免完整 checkout 在大型專案逾時。這是使用者提出的需求，不是已發布功能；但它指出一個可立即處理的問題：在啟動工具前，先把本機工作目錄縮到真正要修改的範圍。
這篇以 Git 的 sparse-checkout 為主，Copilot CLI 只負責在你選定的目錄中工作。目標不是讓 agent 看得越少越好，而是讓它讀到足以完成任務、又不把無關設定與服務一起納入的最小範圍。
先把「要改哪裡」說成目錄，而不是一句任務
開始前列出三類路徑：本次要改的功能、它必須讀取的共用介面，以及明確不在範圍內的服務。舉例來說，若只要修網站前台，範圍可能是：
要修改：apps/web必要介面：packages/ui、packages/types不在範圍：services/billing、infra/production這份列表同時是 Git 設定與 agent 任務的依據。它比「只修改前端」更可驗證，因為 review 時可以直接比對 diff 是否越過目錄邊界。
用 cone mode 建立可讀的 sparse-checkout
Git 的 sparse-checkout 用來讓工作目錄只保留受關注的 tracked files 子集。官方文件建議一般目錄選取採用 cone mode；它以目錄為單位，較適合大多數 monorepo 的工作流。
請先確認工作樹乾淨，並在獨立 worktree 或可安全實驗的分支操作。以下範例假設 repository 已經 clone 完成：
git status --shortgit sparse-checkout init --conegit sparse-checkout set apps/web packages/ui packages/typesgit sparse-checkout listset 後重新檢查工作目錄，確認必要的根目錄檔案與指定資料夾都在，再開始安裝依賴或執行測試。若任務後來需要另一個目錄，明確追加並記錄原因：
git sparse-checkout add packages/api-clientgit sparse-checkout list不要用手動複製檔案來「補齊」缺少的內容；那會讓工作樹實際狀態與 sparse 規格脫鉤。Git 文件也提醒，某些指令或衝突解決可能暫時讓工作目錄出現規格外檔案，必要時可用 git sparse-checkout reapply 回到設定的範圍。
再啟動 Copilot CLI，並逐項確認信任與路徑權限
Copilot CLI 首次從某個目錄啟動時，會要求確認是否信任該目錄及其下方檔案。預設可存取目前工作目錄、子目錄與系統暫存目錄；額外路徑與工具權限則應按任務需要授權。
因此較安全的順序是：先在 sparse 工作目錄驗證可建置，再從這個目錄啟動 Copilot CLI。不要為了消除提示直接加上允許所有路徑、所有工具或所有網址的選項。若 agent 需要讀取相鄰 repository，先停下來確認那個目錄是否真的屬於本次任務，再透過 CLI 的目錄權限機制加入。
| 檢查點 | 你應該看到的結果 | 失敗時先做什麼 |
|---|---|---|
git sparse-checkout list | 只有本次功能與必要介面 | 補一個明確資料夾，不要改成全量 |
| 專案建置或測試 | 能在縮小後的範圍重現 | 檢查缺少的設定檔或產物是否必需 |
| Copilot CLI 信任提示 | 啟動位置就是預期的 repo/worktree | 不要把家目錄或父層目錄永久設為信任 |
| 工具請求額外路徑 | 有具體檔案與原因 | 人工判斷後才新增路徑授權 |
sparse-checkout 不是權限沙箱
sparse-checkout 主要改變工作目錄中顯示的 tracked files 範圍；它不是安全隔離，也不能取代 Copilot CLI 的工具、路徑與 URL 權限。反過來說，Copilot CLI 的路徑權限也不會替你判斷大型 repository 裡哪些檔案與功能有關。
把兩者組合的價值在於分工：Git 讓工作目錄與 diff 範圍更容易閱讀；Copilot CLI 讓工具使用和額外路徑的授權可以逐次確認。若任務要跨越多個服務，與其一次把根目錄全開，不如拆成數個可建置、可 review 的提交。
不要在有未提交變更的主工作樹直接縮範圍切換 sparse 規格可能影響工作目錄可見檔案。先看
git status --short，有正在進行的變更時，優先建立新的 worktree 或先完成既有工作，再做這類範圍調整。
將「最小範圍」寫進任務完成條件
最後在 prompt 或 PR 描述加入一句可驗證的完成條件：修改限於哪些資料夾、執行了哪些測試、若需要擴大範圍必須先提出理由。這會比要求 agent「小心一點」更有用。
大型 repository 的可控性來自可檢查的邊界：先用 sparse-checkout 選目錄，再確認 Copilot CLI 信任的是哪個工作位置，最後讓測試與 diff 證明沒有跨出範圍。公開 issue 可以提醒我們這是常見摩擦點，但實際的範圍與授權仍要由專案維護者決定。
常見問題
Q: sparse-checkout 會把 repository 的其他檔案刪掉嗎？
A: 不會。它讓工作目錄只保留選定的 tracked files 子集，其他檔案仍由 Git 追蹤。開始前仍應確認工作樹沒有未提交變更，並用 git sparse-checkout list 檢查目前範圍。
Q: 我可以把 sparse-checkout 當成 Copilot CLI 的安全限制嗎？
A: 不可以。它不是權限沙箱。Copilot CLI 的工具、路徑與 URL 存取需要依其權限機制處理；sparse-checkout 的價值是降低工作目錄與 review 的複雜度。
Q: 缺少一個必要目錄時，是否該直接關掉 sparse-checkout？
A: 先用 git sparse-checkout add <directory> 增加具體目錄，並重新執行最小測試。只有任務邊界確實擴大、且已經 review 時，才考慮改回完整工作目錄。
參考資料：
回報錯字、失效連結，或告訴我你想看的延伸主題。