当研发团队开始规模化引入 AI 编程助手时，普遍会遭遇“提示词能力参差不齐”的协同痛点。资深架构师能写出约束严密、边界清晰的结构化提示词，而不少团队成员往往只输入“修复这段代码”或“写个单元测试”等模糊语句。这种差异直接导致生成的代码质量千差万别：单元测试断言风格混乱、框架混用、代码解释缺乏架构一致性，且团队长期沉淀的最佳工程实践无法有效复用。
Sourcegraph Cody 提供了在仓库根目录直接规范化这一过程的核心机制：自定义命令（Custom Commands）。通过在代码库中提交 .vscode/cody.json 配置文件，团队负责人可以将高质量提示词模板、执行模式以及精准的上下文抓取范围固化为“代码化提示词（Prompts as Code）”。每位团队成员拉取仓库后，即可直接使用标准化的斜杠命令，从源头上统一代码补全、重构与测试生成的质量水位。
.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 | 提交给大模型的系统提示词模板，包含角色设定、业务约束、测试规范与格式输出要求。 |
description | String | 显示在 Cody 命令列表中的功能说明，辅助团队成员快速识别命令用途。 |
mode | String | 指定命令的执行行为与结果交付方式，可选 ask、edit 或 insert。 |
context | Object | 精确控制 Cody 执行该命令时自动摄取的代码上下文信息范围。 |
执行模式：精准控制代码交付路径
mode 参数决定了模型生成内容如何与开发者的编辑器交互：
-
ask（交互问答与审查模式）：- 将生成结果输出至侧边栏的 Cody Chat 窗口。
- 适用于代码架构审阅、安全合规扫描、算法逻辑解释或生成 PR 摘要等需要开发者先行审查推演的场景。
-
edit（就地代码重构模式）：- 将当前选中的代码直接替换为大模型生成的新代码。
- 适用于确定性重构任务，例如规范 TypeScript 类型定义、消除嵌套三元表达式、修正代码坏味道或应用不可变数据模式。
-
insert（定向插入模式）：- 将生成内容直接插入到当前光标所在位置或选区上方。
- 适用于为现有函数生成标准化文档注释（如 JSDoc/TSDoc）、在空白测试文件中插入完整测试套件框架等场景。
上下文捕获范围：平衡质量与延迟
在 AI 代码生成过程中，缺乏上下文会导致模型幻觉，而注入过多杂乱上下文则会带来高延迟并稀释模型的注意力焦点。.vscode/cody.json 中的 context 提供了细粒度的控制开关：
selection（布尔值）： 是否抓取当前编辑器中高亮选中的代码块。对于代码局部重构或针对单函数的文档编写，开启此项能确保大模型聚焦于明确的目标范围。codebase（布尔值）： 是否调用 Sourcegraph 的语义搜索与代码图谱索引抓取全仓库上下文。开启后，模型能自动识别仓库内共享的测试工具类、通用模型与断言辅助函数。但在执行无需全局知识的局部逻辑重构时建议关闭，以减少检索耗时和 token 浪费。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. 优先复用代码库中现有的测试 fixture 和 mock 机制。\n3. 覆盖正常流程、边界条件、空值异常及异步 reject 场景。\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 类型重构为精确的可辨识联合类型或泛型约束。\n3. 将可变操作替换为纯函数与不可变数据流更新。\n4. 将深层嵌套条件或三元表达式提取为卫语句（Early Return）。\n5. 仅输出替换后的代码本身，不要包含任何 markdown 解释或额外包裹字符。"
},
"security-audit": {
"description": "扫描选区潜在的 OWASP Top 10 安全漏洞与敏感信息泄露",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": false,
"openTabs": false
},
"prompt": "请对选中的代码逻辑进行严密的代码安全与合规审计。\n\n重点检查以下安全风险：\n1. 注入漏洞（SQL 注入、命令注入、XSS 或模板注入）。\n2. 越权风险、权限校验缺失与身份验证绕过。\n3. 敏感数据暴露：是否存在硬编码的密钥、Token 或未脱敏打印的个人隐私数据（PII）。\n4. 异常处理疏漏：是否存在导致调用栈或内部实现信息泄露给前端的未捕获错误。\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 流程，通过代码评审确保指令设计符合团队最新技术架构演进，并在 CI 流水线中进行 JSON 格式语法校验，防止配置损坏。
2. 严控全局代码库上下文的使用成本
很多团队初次配置时倾向于为所有命令无脑开启 "codebase": true。但对于单纯的代码美化或局部重构命令，启用全库语义检索只会徒增网络延迟并引入过多无关依赖干扰。合理分配上下文范围是保证 AI 交互流畅度的关键。
3. 向 Sourcegraph Prompt Library 的自然演进
当工程团队规模扩大至跨数十个微服务仓库时，在每个仓库维护一份 .vscode/cody.json 可能会面临多库同步问题。Sourcegraph 在 Enterprise 版本和 Cody v1.30+ 中推出了集中式的 Prompt Library（提示词库）。
团队可以先在单仓库的 .vscode/cody.json 中孵化并打磨提示词模板。一旦验证有效，便可由管理员将其晋升至企业 Prompt Library 中，通过标签（Tags）、推荐提示词（Promoted Prompts）以及 @selection、@file 等动态上下文标记，实现全企业多 IDE（包括 VS Code 与 JetBrains）的无缝跨仓库共享。