當研發團隊開始大規模導入 AI 程式設計助手時，普遍會面臨「成員提示詞水準參差不齊」的協同痛點。資深架構師能夠撰寫出約束嚴謹、邊界清晰的結構化提示詞，而部分團隊成員往往僅輸入「修復這段程式碼」或「寫個單元測試」等模糊指令。這種落差直接導致產出的程式碼品質參差不齊：單元測試斷言風格混亂、測試框架混用、程式碼解釋缺乏架構一致性，且團隊長期沉澱的最佳工程實踐無法有效傳承與復用。
Sourcegraph Cody 提供了在專案根目錄直接將流程標準化的關鍵機制：自訂命令（Custom Commands）。透過在程式庫中納入 .vscode/cody.json 設定檔，工程主管可以將驗證有效的高品質提示詞範本、執行模式以及精確的上下文擷取範圍固化為「程式碼化提示詞（Prompts as Code）」。每位團隊成員複製（Clone）專案後，即可直接取用標準化的斜線命令，從源頭確保程式碼補全、重構與測試生成的品質一致性。
.vscode/cody.json 的架構與運作原理
在 Cody 的設計中，自訂命令區分為個人層級（全域配置於使用者個人設定）與工作區層級（Workspace Level）。將 cody.json 放置於專案根目錄的 .vscode/ 資料夾下，即可讓自訂命令與該專案的技術棧、依賴項與架構準則深度綁定：
repository-root/
├── .vscode/
│ ├── cody.json <-- 團隊專案級自訂命令定義
│ └── settings.json
├── src/
├── tests/
└── package.json
一旦將該檔案提交至 Git 版本控制，團隊成員在 VS Code 中開啟工作區時，Cody 便會自動載入並解析這些命令。開發者除了能透過快捷鍵開啟命令選單（macOS 為 Option + C，Windows/Linux 為 Alt + C）之外，也能在 Cody 聊天輸入框中直接輸入斜線指令（例如 /unit-test）來執行。
JSON 設定結構拆解
.vscode/cody.json 以頂層 commands 物件為核心，每個子鍵名對應一個可觸發的斜線命令識別碼：
{
"commands": {
"command-identifier": {
"prompt": "傳遞給底層大型語言模型的詳細提示詞指令範本。",
"description": "顯示在 Cody 命令面板選單中的簡要功能說明。",
"mode": "ask",
"context": {
"codebase": false,
"selection": true,
"currentDir": false,
"openTabs": false
}
}
}
}
各核心屬性定義如下：
| 欄位 | 型別 | 說明 |
|---|---|---|
prompt | String | 提交給 AI 模型的系統提示詞範本，包含角色設定、邊界限制、測試規範與輸出格式要求。 |
description | String | 顯示在 Cody 命令選單中的輔助說明，協助團隊成員快速理解該命令的適用情境。 |
mode | String | 定義命令執行時的互動模式與輸出結果交付方式，可選值為 ask、edit 或 insert。 |
context | Object | 精確控制 Cody 執行該命令時自動擷取的背景程式碼範圍。 |
執行模式：精確控制交付管道
mode 屬性決定了模型生成的成果如何與開發者編輯器當前的檔案內容進行互動：
-
ask（交談檢視與審查模式）：- 將生成結果輸出至側邊欄的 Cody Chat 面板。
- 適合程式碼架構審閱、資安弱點掃描、演算法邏輯推演或 PR 摘要生成等需要開發者先行確認決策的場景。
-
edit（就地編輯與即時重構模式）：- 直接以生成結果替換編輯器中目前選取的程式碼區塊。
- 適合確定性的程式碼重構工作，例如收緊 TypeScript 型別定義、消除巢狀三元運算子、改善程式碼異味（Code Smells）或套用不可變資料結構。
-
insert（針對性插入模式）：- 將生成內容直接插入至目前游標所在位置或選取範圍上方。
- 適用於為現有函式插入標準化 TSDoc/JSDoc 註解、或在空白測試檔案中插入標準測試框架骨架。
上下文範圍擷取：平衡品質與延遲
在 AI 輔助開發中，缺乏上下文會導致模型產生幻覺，而盲目引入過多非必要檔案則會增加 Token 消耗與延遲，並干擾模型的注意力焦點。.vscode/cody.json 的 context 提供了精準的調整開關：
selection（布林值）： 是否擷取編輯器中目前反白標記的程式碼。針對單一函式重構或特定區塊註解，啟用此項可確保模型專注於目標程式碼。codebase（布林值）： 是否觸發 Sourcegraph 針對整體程式庫的語意搜尋與索引檢索。開啟後，Cody 能自動尋找全專案共用的測試工具、公用函式庫與領域模型；但對於無須跨檔案關聯的區域重構，建議保持關閉以避免網路查詢延遲。currentDir（布林值）： 是否納入目前作用中檔案同層目錄下的其他檔案。若專案採用依功能模組劃分的目錄架構，同層檔案往往包含相鄰的介面定義或模擬資料，開啟後有助於生成更協調的程式碼。openTabs（布林值）： 是否引入編輯器中其他已開啟分頁的內容。跨檔案協同開發時雖具便利性，但在獨立任務中建議關閉，避免背景分頁混入無關雜訊。
團隊級生產環境實戰範例
以下展示適用於現代 TypeScript 與 React 專案的 .vscode/cody.json 標準配置，內含四個針對團隊協作痛點打造的命令：
{
"commands": {
"unit-test": {
"description": "依據團隊 Vitest 規範為選取程式碼產生包含邊界條件與 Mock 的測試套件",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": true,
"openTabs": false
},
"prompt": "你是一名資深測試自動化工程師。請為選取的程式碼產生基於 Vitest 與 @testing-library/react 的完整測試套件。\n\n嚴格遵守以下準則：\n1. 統一採用 AAA（Arrange-Act-Assert）三段式架構編排測試案例。\n2. 優先沿用程式碼庫中既有的測試 fixtures 與 mock 慣例。\n3. 完整涵蓋標準情境、邊界極值、空值防護以及非同步 Promise 拒絕（Rejection）。\n4. 嚴禁引用專案未核准的第三方 Mock 套件，一律使用 Vitest 原生的 vi.fn() 與 vi.spyOn()。\n5. 輸出完整且可直接執行的程式碼，禁止出現 '// 請自行實作' 等佔位符註解。"
},
"refactor-clean": {
"description": "以嚴謹 TypeScript 規範與純函式不可變模式就地重構選取程式碼",
"mode": "edit",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "請依照簡潔架構與嚴格 TypeScript 標準重構選取的程式碼區塊：\n1. 保持既有公開 API 簽章、函式參數合約與執行期行為完全一致。\n2. 將寬鬆的 any 或 unknown 型別收緊為精確的標記聯集（Discriminated Unions）或泛型約束。\n3. 將可變異操作替換為純函式與不可變狀態更新語法。\n4. 將深層巢狀條件判斷式重構成清晰的提早回傳（Early Return / Guard Clauses）。\n5. 僅輸出重構後的乾淨程式碼，不要包含任何 markdown 說明或額外字元。"
},
"security-audit": {
"description": "掃描選取區塊潛在的 OWASP Top 10 安全風險與機密資訊洩漏",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": false,
"openTabs": false
},
"prompt": "請對選取的程式碼段落執行嚴格的資安與合規性審查。\n\n著重檢核下列風險維度：\n1. 注入式攻擊弱點（包含 SQL Injection、指令注入、XSS 與範本注入）。\n2. 越權存取漏洞、未授權存取風險與權限檢查疏漏。\n3. 不安全的直接物件參照（IDOR）與未經清洗的使用者輸入。\n4. 硬編碼金鑰、API 憑證或日誌記錄中未脫敏的個人識別資訊（PII）。\n5. 未處理的例外流程導致呼叫堆疊暴露。\n\n輸出格式固定為：[嚴重程度: 高/中/低] | [弱點類型] | [問題行號] | [改善建議與修復Diff]。"
},
"doc-api": {
"description": "在函式或介面上方插入符合團隊規格的 TSDoc/JSDoc 結構化註解",
"mode": "insert",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "為選取的函式或介面產生高品質的 TSDoc 結構化註解區塊：\n1. 首行提供精練的功能摘要，隨後說明核心運作邏輯與使用限制。\n2. 詳細宣告所有 @param 標籤，明確交代參數型別與語意。\n3. 宣告 @returns 明確指出回傳值型別與條件。\n4. 宣告 @throws 詳列所有可能引發的例外狀況與觸發機制。\n5. 附帶一個符合日常呼叫情境的 @example 範例。\n6. 輸出格式必須為完整的 JSDoc/TSDoc 區塊，以便直接插入於程式碼上方。"
}
}
}
團隊治理機制與演進策略
為了讓 .vscode/cody.json 長期發揮效能，團隊應建立相應的管理流程：
1. 貫徹「提示詞即程式碼（Prompts as Code）」理念
.vscode/cody.json 屬於團隊的核心工程資產。所有提示詞的新增、修改或調整，都應遵循常規的 Pull Request 機制，透過同儕審查（Peer Review）確保指令品質，並在 CI 流程中加入 JSON Schema 檢查，防止語法錯誤導致擴充套件無法載入。
2. 審慎評估全域 Codebase 上下文的使用成本
不少團隊容易在所有指令中一律設定 "codebase": true。但對於純粹的邏輯簡化或行內重構，啟用全專案搜尋只會增加網路等待時間並可能混入無關檔案。應嚴格限制全庫上下文的啟用時機，將局部轉換集中在 "selection": true。
3. 平滑過渡至 Sourcegraph Prompt Library
當工程團隊規模擴展至數十個微服務專案時，分散維護多份 .vscode/cody.json 可能面臨版本不同步的問題。Sourcegraph 在 Enterprise 版本與 Cody v1.30+ 中推出了網頁端 Prompt Library（提示詞庫）。
團隊可以先藉由 .vscode/cody.json 在特定專案中快速迭代提示詞；驗證成效卓越後，再由架構師將其遷移至企業級 Prompt Library。結合標籤管理（Tags）、官方推薦（Promoted Prompts）以及動態 @selection、@file、@repo 引用機制，便能輕鬆實現跨多 IDE（VS Code 與 JetBrains）的全組織規模化共享。