AI Coding Customizations 技术指南

AI Coding Customizations 技术指南随着 AI Coding Agent 的发展越来越多开发工具支持AI Customizations允许开发者根据项目需求定制 AI 行为例如代码规范项目架构自动化工作流外部工具调用当前主流 AI Coding 工具Copilot / Codex / Claude Code基本都支持类似的 customization 体系类型作用init初始化 AI 项目配置instruction持久化编码规则prompt可复用任务命令skill多步骤自动化能力agent专用 AI 角色hook生命周期自动化mcp连接外部工具Copilot官方文档Copilot 的 customization 主要存储在.github目录,一个标准的文repo结构如下:my-monorepo/ # repo root (has .git folder) ├── .github/ │ ├── copilot-instructions.md │ ├── instructions/ │ │ └── style.instructions.md │ ├── prompts/ │ │ └── review.prompt.md │ └── agents/ │ └── reviewer.agent.md ├── packages/ │ └── frontend/ # opened as workspace folder │ └── src/Custom instructions自定义指令允许您定义通用准则和规则这些准则和规则会自动影响 AI 生成代码和处理其他开发任务的方式。您无需在每个聊天提示中手动添加上下文只需在 Markdown 文件中指定自定义指令即可确保 AI 响应与您的编码实践和项目要求保持一致。copilot-instructions.md初始化您的项目 在聊天中输入/init以生成一个.github/copilot-instructions.md文件自动应用于工作区中的所有聊天请求。存储在工作区中*.instructions.md您可以使用*.instructions.mdMarkdown 文件创建基于文件的指令.agent会根据指令文件头中 applyTo 属性指定的文件模式或指令描述与当前任务的语义匹配来确定要应用哪些指令文件。instructions.md format--- name: Python Standards description: Coding conventions for Python files applyTo: **/*.py --- # Python coding standards - Follow the PEP 8 style guide. - Use type hints for all function signatures. - Write docstrings for public functions. - Use 4 spaces for indentation.Instructions file locationsScopeDefault file locationWorkspace.github/instructionsfolderUser profile~/.copilot/instructions, instructions folder of the current VS Code profileprompt files提示文件也称为斜杠命令可以将常见任务的提示简化为独立的 Markdown 文件您可以直接在聊天中调用这些文件。每个提示文件都包含特定于任务的上下文以及关于如何执行该任务的指南。Prompt files, agents, or skills?对于轻量级、单任务提示请使用Prompt files。当您需要具有自身工具限制和交接的持久角色时请使用agents 。当您需要具有脚本和资源的便携式多文件功能时请使用skill 。Prompt file locationsScopeDefault file locationWorkspace.github/promptsfolderUser profile/Users/**/Library/Application Support/Code/User/prompts/xxx.mdPrompt file format提示文件是扩展名为 .prompt.md 的 Markdown 文件。可选的 YAML frontmatter 头部用于配置提示的行为FieldRequiredDescriptiondescriptionNo提示的简要描述。nameNo提示名称在聊天中输入/后显示。如果未指定则使用文件名。argument-hintNo聊天输入框中的提示文本用于指导用户如何使用该 prompt。agentNo用于运行 prompt 的 agentask、agent、plan或自定义 agent 名称。默认使用当前 agent如果指定tools默认 agent 为agent。modelNo运行 prompt 时使用的模型。如果未指定则使用当前模型选择器中的模型。toolsNo该 prompt 可用的工具或工具集列表可以是内置工具、工具集、MCP 工具或扩展提供的工具。若要包含某个 MCP server 的全部工具可使用server name/*。如果您希望用户提供更多信息可以使用类似${input:variableName},${input:variableName:placeholder}的语法。大多数语言模型都支持这种语法并会提示用户输入这些内容。Custom Agents自定义代理允许您配置 AI使其扮演不同的角色以适应特定的开发角色和任务。例如您可以创建安全审查员、规划员、解决方案架构师或其他专业角色的代理。每个角色都可以拥有自己的行为、可用工具和指令。您还可以使用handoffs(交接功能)在代理之间创建引导式工作流程。只需一次选择即可在不同的专业代理之间无缝切换。例如直接从规划代理切换到实施代理或者将任务移交给代码审查员并提供相关上下文。交接机制有助于协调多步骤工作流程使开发人员能够在进行下一步之前审查和批准每个步骤。例如Planning → Implementation在规划代理中生成计划然后将其移交给实施代理开始编码。Implementation → Review: 完成实施后切换到代码审查代理来检查质量和安全问题。Write Failing Tests → Write Passing Tests: 生成比大型实现更容易审查的失败测试然后通过实现所需的代码更改来使这些测试通过。Custom agent file locationsScopeDefault file locationWorkspace.github/agentsUser profile~/.copilot/agentsCustom agent file structureTLDR.{{PLACE_HOLDER}}Agent Skills代理技能是包含指令、脚本和资源的文件夹GitHub Copilot 可以根据需要加载这些文件夹来执行特定任务。与custom instructions指令不同技能能够实现专业化的功能和工作流程其中可以包含脚本、示例和其他资源。您创建的技能具有可移植性可在任何兼容该技能的代理上运行。Agent Skills file locationsScopeDefault file locationWorkspace.github/skillsUser profile~/.copilot/skillsAgent Skills file structureTLDR.{{PLACE_HOLDER}}MCPMCP server file locationsScopeDefault file locationWorkspace.vscode/mcp.jsonUser profile/Users/**/Library/Application Support/Code/User/mcp.jsonMcp server structure{servers:{github:{type:http,url:https://api.githubcopilot.com/mcp},playwright:{command:npx,args:[-y,microsoft/mcp-server-playwright]}}}Hooks钩子允许您在代理会话期间的关键生命周期节点执行自定义 shell 命令。Hook file locations范围默认文件位置工作区.github/hooks/*.json用户~/.copilot/hooks自定义代理.agent.mdfrontmatter 中的hooks字段插件hooks.json或hooks/hooks.jsonHook lifecycle events钩子事件触发时机常见用例SessionStart用户提交新会话的第一个提示初始化资源记录会话开始验证项目状态UserPromptSubmit用户提交提示审核用户请求注入系统上下文PreToolUse在代理调用任何工具之前阻止危险操作要求批准修改工具输入PostToolUse工具成功完成后运行格式化程序、记录结果、触发后续操作PreCompact在对话上下文被压缩之前导出重要上下文截断前保存状态SubagentStart子代理已生成跟踪嵌套代理的使用情况初始化子代理资源SubagentStop子代理完成汇总结果清理子代理资源Stop代理会话结束生成报告、清理资源、发送通知your first hook{hooks:{PostToolUse:[{type:command,command:npx prettier --write \$TOOL_INPUT_FILE_PATH\}]}}保存此文件后VS Code 会自动加载钩子。下次代理编辑文件时Prettier 会对已更改的文件运行。Agent plugins代理插件是预先打包好的聊天自定义功能包, 可以捆绑以下一种或多种自定义类型Slash commands,Skills,Agents,Hooks,MCP serversAgent plugins structure插件目录结构如下所示my-testing-plugin/ plugin.json # Plugin metadata and configuration skills/ test-runner/ SKILL.md # Testing skill instructions run-tests.sh # Supporting script agents/ test-reviewer.agent.md # Code review agent hooks/ hooks.json # Hook configuration scripts/ validate-tests.sh # Hook script .mcp.json # MCP server definitionsClaude code扩展 Claude CodeClaude Code 结合了一个能够推理代码的模型和内置工具用于文件操作、搜索、执行和网络访问。内置工具涵盖了大多数编码任务。功能概览功能作用何时使用示例CLAUDE.md每次对话加载的持久上下文项目约定、“始终执行 X” 规则“使用 pnpm而不是 npm。提交前运行测试。”SkillClaude 可以使用的说明、知识和工作流可复用内容、参考文档、可重复的任务/deploy运行部署清单包含端点模式的 API 文档 SkillSubagent返回摘要结果的隔离执行上下文上下文隔离、并行任务、专门的工作者读取大量文件但只返回关键结论的研究任务Agent teams协调多个独立的 Claude Code 会话并行研究、新功能开发、使用竞争假设进行调试生成多个审查者同时检查安全性、性能和测试MCP连接到外部服务需要访问外部数据或执行外部操作查询数据库、发布到 Slack、控制浏览器Hook在事件触发时运行的确定性脚本需要可预测的自动化流程不涉及 LLM每次文件编辑后运行 ESLintPlugins是打包层。Plugin 将 skills、hooks、subagents 和 MCP servers 捆绑到单个可安装单元中。Plugin skills 是命名空间的如 /my-plugin:review因此多个 plugins 可以共存相似的功能对比Skill vs SubagentSkills 和 subagents 解决不同的问题Skills 是可重用的内容您可以将其加载到任何上下文中Subagents 是与您的主对话分开运行的隔离工作者CLAUDE.md vs Skill两者都存储说明但它们的加载方式和用途不同。如果 Claude应该始终知道它请将其放在 CLAUDE.md 中编码约定、构建命令、项目结构、“永远不要执行 X” 规则。如果它是 Claude 有时需要的参考材料API 文档、风格指南或您使用/name触发的工作流部署、审查、发布请将其放在 skill 中。经验法则:保持 CLAUDE.md 在 200 行以下。如果它在增长将参考内容移到 skills 或拆分为.claude/rules/文件。CLAUDE.md vs Rules vs Skills方面CLAUDE.md.claude/rules/Skill加载每个会话每个会话或当打开匹配的文件时按需加载当被调用或相关时范围整个项目可以限定到特定文件路径特定任务最适合核心约定和构建命令特定语言或目录的开发指南参考资料、可重复的工作流Subagent vs Agent team当您需要一个快速、专注的工作者时使用 subagent研究一个问题、验证一个声明、审查一个文件。Subagent 完成工作并返回摘要。您的主对话保持清洁。当队友需要共享发现、相互质疑和独立协调时使用 agent team。Agent teams 最适合具有竞争假设的研究、并行代码审查以及每个队友拥有单独部分的新功能开发。MCP vs SkillMCP 给予 Claude与外部系统交互的能力。没有 MCPClaude 无法查询您的数据库或发布到 Slack。Skills 给予 Claude 关于如何有效使用这些工具的知识以及您可以使用/name触发的工作流。Skill 可能包括您团队的数据库架构和查询模式或带有您团队消息格式规则的 /post-to-slack 工作流。CLAUDE.mdCLAUDE.md 文件是 markdown 文件为项目、你的个人工作流或整个组织为 Claude 提供持久指令。Claude 在每个会话开始时读取它们。运行/init自动生成起始 CLAUDE.md,Claude 分析你的代码库并创建一个包含构建命令、测试指令和它发现的项目约定的文件。如果 CLAUDE.md 已存在/init 会建议改进而不是覆盖它。CLAUDE.md 文件的位置CLAUDE.md 文件可以位于多个位置每个位置有不同的范围。更具体的位置优先于更广泛的位置。范围位置目的用例示例共享对象托管策略macOS:/Library/Application Support/ClaudeCode/CLAUDE.md由 IT / DevOps 管理的组织范围指令公司编码标准、安全策略、合规要求组织中的所有用户项目指令./CLAUDE.md或./.claude/CLAUDE.md项目的团队共享指令项目架构、编码标准、常见工作流程通过源代码管理共享的团队成员用户指令~/.claude/CLAUDE.md所有项目的个人偏好代码风格偏好、个人工具快捷方式仅当前用户适用于所有项目rulesCLAUDE.md 文件在每个会话开始时加载到上下文窗口中与你的对话一起消耗令牌。每个 CLAUDE.md 文件目标在 200 行以下。如果你的指令变得很大使用path/to/import或.claude/rules/文件进行分割。.claude/rules/ 组织规则your-project/ ├── .claude/ │ ├── CLAUDE.md # 主项目指令 │ └── rules/ │ ├── code-style.md # 代码样式指南 │ ├── testing.md # 测试约定 │ └── security.md # 安全要求AGENTS.mdClaude Code 读取 CLAUDE.md而不是 AGENTS.md。如果你的存储库已经为其他编码代理使用 AGENTS.md创建一个导入它的 CLAUDE.md这样两个工具都可以读取相同的指令而无需重复。你也可以在导入下方添加 Claude 特定的指令。Claude 在会话开始时加载导入的文件然后附加其余部分AGENTS.md ## Claude Code 对 src/billing/ 下的更改使用 plan mode。SkillsSkills 的位置位置路径适用于企业请参阅托管设置你的组织中的所有用户个人~/.claude/skills/skill-name/SKILL.md你的所有项目项目.claude/skills/skill-name/SKILL.md仅当前项目插件plugin/skills/skill-name/SKILL.md启用该插件的位置subagentsSubagents 是处理特定类型任务的专门 AI 助手。每个 subagent 在自己的 context window 中运行具有自定义系统提示、特定的工具访问权限和独立的权限。当 Claude 遇到与 subagent 描述相匹配的任务时它会委托给该 subagent该 subagent 独立工作并返回结果。subagent 范围Subagents 是带有 YAML frontmatter 的 Markdown 文件。根据范围将它们存储在不同的位置。位置作用范围优先级如何创建--agentsCLI 参数当前会话1最高启动 Claude Code 时传递 JSON.claude/agents/当前项目2交互式创建或手动创建~/.claude/agents/所有项目3交互式创建或手动创建插件的agents/目录启用该插件的位置4最低随插件一起安装agent teamsAgent teams 让你协调多个 Claude Code 实例一起工作。一个会话充当团队负责人协调工作、分配任务和综合结果。队友独立工作每个都在自己的 context window 中并直接相互通信。McpMCP 安装范围本地范围Local本地范围的服务器代表默认配置级别存储在您项目路径下的.claude/settings.local.json中。claude mcp add --transport http stripe --scope local https://mcp.stripe.com项目范围(Project)项目范围的服务器通过在项目根目录中存储配置在.mcp.json文件中来启用团队协作。claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp生成的 **.mcp.json **文件遵循标准化格式{mcpServers:{shared-server:{command:/path/to/server,args:[],env:{}}}}用户范围(user)用户范围的服务器存储在~/.claude.json中并提供跨项目可访问性使其在您机器上的所有项目中可用同时对您的用户帐户保持私密。claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropicHooks当 Claude Code 编辑文件、完成任务或需要输入时自动运行 shell 命令。配置 hook 位置位置范围是否可共享~/.claude/settings.json所有项目否仅本机可用.claude/settings.json单个项目是可提交到代码仓库.claude/settings.local.json单个项目否通常被.gitignore忽略托管策略设置组织范围是由管理员统一控制插件hooks/hooks.json启用插件时是与插件一起分发Skill 或 Agent 的 frontmatter当 Skill 或 Agent 激活时是在组件文件中定义设置你的第一个 hook打开~/.claude/settings.json并添加一个 Notification hook。{hooks:{Notification:[{matcher:,hooks:[{type:command,command:osascript -e display notification \Claude Code needs your attention\ with title \Claude Code\}]}]}}Plugins创建自定义插件以使用skills、agents、hooks 和 MCP servers扩展 Claude Code。何时使用插件与独立配置Claude Code 支持两种方式来添加自定义 skills、agents 和 hooks方法Skill 名称最适合独立.claude/ 目录/hello个人工作流、项目特定的自定义、快速实验插件包含 .claude-plugin/plugin.json 的目录/plugin-name:hello与团队成员共享、分发到社区、版本化发布、跨项目重用/commands (legacy)推荐使用skills/prompt files (legacy)推荐使用skillscodex官方文档Codex configuration filebasic优先级顺序配置来源文件位置说明1Profile values--profile name通过 CLI 指定的 profile 配置2Project config files.codex/config.toml从项目根目录到当前工作目录逐级查找越靠近当前目录优先级越高仅限 trusted projects3User config~/.codex/config.toml用户级全局配置4System config/etc/codex/config.toml(Unix)系统级配置如果存在Custom instructions with AGENTS.mdCodex 会在执行任何操作之前读取 AGENTS.md 文件。通过将全局指导与项目特定的覆盖规则相结合无论您打开哪个代码库都可以确保每个任务都基于一致的预期。位置作用范围说明~/.codex/AGENTS.md个人级仅当前用户可用repo-root/AGENTS.md项目级仅当前项目可用MCP编辑config.toml[mcp_servers.figma] url https://mcp.figma.com/mcp bearer_token_env_var FIGMA_OAUTH_TOKEN http_headers { X-Figma-Region us-east-1 }SubagentsCodex 可以通过并行生成多个专用代理来运行子代理工作流然后将它们的结果汇总到一个响应中。这对于高度并行的复杂任务例如代码库探索或实施多步骤功能规划尤其有用。CODEX Subagent 配置要定义自定义代理可以在以下目录中添加独立的TOML 文件位置作用范围说明~/.codex/agents/个人级仅当前用户可用适用于个人代理.codex/agents/项目级仅当前项目可用可随项目代码一起管理Skills使用代理技能可以为 Codex 扩展特定任务的功能。技能包含指令、资源和可选脚本使 Codex 能够可靠地执行工作流程。Where to save skills技能范围位置建议用途仓库$CWD/.agents/skills如果在代码仓库或代码环境中团队可以提交与当前工作文件夹相关的技能例如仅适用于某个微服务或模块的技能。仓库$CWD/../.agents/skills当在 Git 仓库中启动 Codex 且存在嵌套目录时可以在父目录中存放共享区域相关的技能。仓库$REPO_ROOT/.agents/skills当仓库包含嵌套目录时可在仓库根目录提交对整个仓库所有用户有用的技能这些技能可被仓库中的任何子目录使用。用户$HOME/.agents/skills用于存放用户个人技能这些技能适用于用户参与的所有代码仓库。管理员/etc/codex/skills用于 SDK 脚本、自动化任务以及提供给机器上所有用户的默认管理员技能。系统随 Codex 一起提供面向广泛用户的通用技能例如技能创建或计划相关技能所有用户启动 Codex 时即可使用。pluginshooks~/.codex/hooks.jsonrepo/.codex/hooks.jsonRules./codex/rules/: 例如~/.codex/rules/default.rules