最近一段时间终端 AI 编程工具的热度一直没降。Claude Code 作为其中的代表产品凭借直接在终端里读写文件、执行命令的 agent 能力很快成为很多开发者日常工作流的一部分。围绕 Claude Code 支持 AGENTS.MD、系统提示词修改、Skills 配置的讨论也越来越多说明大家已经不满足于“让 AI 写一段代码”而是希望它真正理解项目的规则和边界。这篇文章就围绕 Claude Code 的 AGENTS.MD 与系统提示词修改展开。先讲清楚 AGENTS.MD 是什么、怎么写再区分系统提示词和用户提示词最后给出从安装、配置到接入第三方模型的完整实操流程。新手能照着搭建自己的 AI 编程环境已经在用 Claude Code 的开发者也能从中找到优化工作流的思路。1. 背景与核心概念1.1 Claude Code 是什么Claude Code 是 Anthropic 推出的命令行 AI 编程工具。它不是一个普通的聊天窗口而是运行在终端里的 agent 程序能够直接读取项目文件、修改代码、执行终端命令、运行测试并在多轮对话中持续完成任务。简单理解传统 AI 编程助手更像“你在编辑器里复制代码给它看它给你返回结果”Claude Code 则更像是“你给它一个目标它在项目目录里自己看代码、自己改代码、自己跑命令验证”。它的典型应用场景包括新项目脚手架生成。跨文件重构。根据测试失败信息定位 Bug。批量修改接口调用。自动补充单元测试和文档。通过项目规则文件理解团队代码规范。也是因为这种“agent 形态”的工作方式Claude Code 对项目上下文的理解非常重要。AGENTS.MD、CLAUDE.md 这类规则文件就是用来帮它快速理解项目的。1.2 AGENTS.MD 是什么AGENTS.MD 是一种 Markdown 格式的项目说明文件目的是给 AI 智能体提供项目的“工作手册”。当 AI 进入项目时会优先读取这个文件从而了解技术栈、常用命令、代码风格、约束条件等关键信息。需要注意的是AGENTS.MD 并不是 Claude Code 独有的概念。OpenAI Codex、Cursor 等 AI 编程工具也在支持或推进类似机制。也就是说AGENTS.MD 正在成为一种“跨工具的项目记忆标准”。那它解决什么问题呢很多开发者的直观感受是AI 刚进入一个项目时往往不知道项目结构、不知道构建命令、不知道代码规范。你每次都口头交代一遍效率很低不交代AI 就可能生成完全不符合项目风格的代码。AGENTS.MD 相当于把“项目入职培训手册”写成一个文件放进仓库。AI 一进来先读手册自然就知道该怎么做。1.3 系统提示词与用户提示词先分清概念很多人会问扣子工作流里系统提示词和用户提示词有什么区别这个问题放在 Claude Code 中同样成立。系统提示词System Prompt由开发者预先设置的指令决定了 AI 的角色、行为规则、知识边界和输出格式。它在整个会话过程中持续生效相当于“员工手册”。用户提示词User Prompt用户在每一轮对话中提出的具体请求相当于“你临时跟同事说帮我把这个接口改一下”。在 Claude Code 中系统提示词并不是只有一个。它内部有一套完整的提示词体系内置基础系统提示词定义 Claude Code 自身身份、工具调用方式、安全限制。项目级指令通过 CLAUDE.md、AGENTS.md 注入告诉 Claude Code 这个项目有什么约定。用户级指令通过用户主目录下的 CLAUDE.md 注入对所有项目生效。Skills 指令通过特定任务的 SKILL.md 文件注入当相关任务被触发时加载。所以“修改系统提示词”这件事在实际操作中并不是直接改 Claude Code 内置的那段文本而是通过配置层、规则文件、Skills 等方式把自定义指令注入到它的系统上下文中。2. 环境准备与安装2.1 安装方式对比Claude Code 目前常见的安装方式有三种安装方式适合场景特点npm CLI最常用跨平台终端直接使用适合脚本化、自动化VSCode 插件编辑器内使用可视化交互适合日常开发桌面版不想碰命令行的用户独立窗口操作门槛更低不同安装方式之间并不冲突。你可以一边用 npm 安装 CLI一边在 VSCode 里使用插件两者共享同一套登录凭证。2.2 npm 安装 Claude CodeCLI 方式安装最简单。先确认本机有 Node.js 环境一般建议 Node.js 18 或更高版本。然后在终端执行npm install -g anthropic-ai/claude-code安装完成后验证是否成功claude --version如果显示版本号说明安装成功。如果提示claude命令找不到通常是 npm 全局 bin 目录没有加入 PATH。可以执行npm config get prefix查看全局安装路径再把对应目录加入系统 PATH。2.3 登录与 API Key 配置首次运行claude会进入登录流程。Claude Code 支持两种授权方式使用 Claude 订阅账号登录。使用 Anthropic API Key。如果使用 API Key可以通过环境变量或配置文件指定。示例export ANTHROPIC_API_KEYsk-ant-xxxx export ANTHROPIC_MODELclaude-sonnet-4-5 claude这里要注意环境变量是临时生效的关闭终端后失效。如果想长期使用可以写入 shell 配置文件或者使用 Claude Code 自己的配置命令。2.4 VSCode 插件配置VSCode 用户可以安装 Claude Code 官方扩展。安装后在左侧活动栏会出现 Claude Code 图标打开一个项目文件夹后可以直接在面板中开始对话。插件模式和 CLI 模式共享登录状态。我的建议是先在终端里跑通claude确认登录没问题再打开 VSCode 插件。这样如果插件连接失败能更快定位是登录问题还是插件问题。3. AGENTS.MD 编写与项目接入3.1 AGENTS.MD 文件位置AGENTS.MD 通常放在项目根目录文件名严格区分大小写。项目根目录/ ├── AGENTS.md ├── src/ ├── package.json └── ...除了根目录AGENTS.MD 也可以放在子目录中。AI 在不同目录工作时会优先读取该目录下的规则。比如项目根目录/ ├── AGENTS.md ├── frontend/ │ ├── AGENTS.md │ └── ... ├── backend/ │ ├── AGENTS.md │ └── ...根目录的 AGENTS.md 定义全局规则子目录的 AGENTS.md 定义局部规则。3.2 AGENTS.MD 怎么写下面给一个可以直接套用的结构示例。# AGENTS.md ## 项目简介 这是一个基于 Next.js 14 TypeScript 的后台管理系统提供用户管理、权限管理和数据报表功能。 ## 技术栈 - 前端React 18、Next.js 14、Ant Design 5 - 后端Node.js、Express - 数据库PostgreSQL、Prisma ORM - 部署Docker、GitHub Actions ## 常用命令 - 安装依赖npm install - 启动开发npm run dev - 构建生产npm run build - 运行测试npm test - 代码检查npm run lint ## 目录结构 - src/api/接口请求封装 - src/components/公共组件 - src/pages/页面路由 - src/utils/工具函数 - prisma/数据库模型和迁移文件 ## 代码规范 - React 组件统一使用函数组件并使用 TypeScript。 - 组件文件使用 PascalCase 命名工具文件使用 camelCase 命名。 - API 请求统一放在 src/api/ 目录禁止在页面直接写 fetch。 - 禁止在组件中使用 document.getElementById 操作 DOM。 - 新增依赖需要说明用途避免随意引入第三方库。 ## AI 工作约定 - 修改代码之前先说明影响范围。 - 新建文件必须附带必要的类型定义。 - 代码注释使用中文关键逻辑必须解释为什么。 - 提交信息遵循 Conventional Commits 格式。这个文件的核心价值是“把团队里口口相传的约定沉淀下来”。AI 每次进入项目都会读取它相当于默认携带了项目背景知识。3.3 AGENTS.MD 与 CLAUDE.md 的区别CLAUDE.md 是 Anthropic 产品体系里的概念而 AGENTS.MD 是更偏向跨工具的通用标准。对很多项目来说两者可以同时存在。文件定位适用工具AGENTS.md通用的项目规则说明书Claude Code、OpenAI Codex、Cursor 等CLAUDE.mdClaude 产品专属的指令文件Claude Code、Claude 桌面应用实际项目中我建议这样分配AGENTS.md 放通用信息技术栈、命令、目录结构、代码风格。CLAUDE.md 放针对 Claude 的补充指令比如“优先使用 Claude Code 的 Skills 完成代码审查”“修改文件前先查看相关测试”。两者可以互相引用!-- CLAUDE.md -- # CLAUDE.md 项目通用规则请阅读 AGENTS.md。 本文件补充 Claude 专属约定 1. 使用 Claude Code 时所有重构必须运行 npm test 验证。 2. 涉及数据库变更时先生成 Prisma Migration再修改业务代码。3.4 如何验证 AGENTS.MD 是否生效一个很简单的验证方法在项目根目录创建 AGENTS.md。运行claude进入对话。输入“请根据 AGENTS.md介绍一下这个项目的技术栈和常用命令。”如果 Claude Code 正确回答了 AGENTS.md 中的内容说明文件已经生效。如果回答牛头不对马嘴检查文件名是否真的是AGENTS.md大小写有没有错误。文件是否放在项目根目录。当前对话是否已经加载了项目上下文必要时重启会话。4. 系统提示词修改与全局行为定制4.1 Claude Code 的提示词体系Claude Code 内部有一套固定的系统提示词负责定义工具调用规则和基本行为。用户不能也不应该直接修改这段内置内容但可以通过“叠加”的方式影响最终的系统上下文。从上到下的影响层级大致是内置系统提示词定义 Claude Code 的身份和能力。用户全局配置通过claude config set或配置文件设置默认行为。用户级 CLAUDE.md位于用户主目录的~/.claude/CLAUDE.md对所有项目生效。项目级 CLAUDE.md / AGENTS.md位于项目目录仅对当前项目生效。Skills按需加载的专项指令。用户消息每次对话的具体需求。“修改系统提示词”在实际操作中通常指调整第 2 到第 5 层。4.2 用户级配置Claude Code 提供配置命令可以用它设置模型、权限等偏好。例如# 设置全局默认模型 claude config set --global model claude-sonnet-4-5 # 查看当前配置 claude config list配置会被写入用户目录下的配置文件中。以下是配置文件的一种常见结构具体字段以你安装的版本生成为准{ model: claude-sonnet-4-5, permissions: { allow: [Bash(npm run test)], deny: [WebFetch] }, env: { DISABLE_TELEMETRY: 1 } }权限配置尤其重要。通过 allow 和 deny 列表可以限制 Claude Code 能执行哪些终端命令、能访问哪些网络地址。生产环境项目建议默认拒绝高风险命令只放行测试、构建等安全指令。4.3 用户级与项目级指令文件用户级指令文件位于~/.claude/CLAUDE.md写入的内容会对所有项目生效。适合放通用偏好例如# 全局偏好 - 代码注释使用中文。 - 回答技术问题时先给结论再解释原理。 - 禁止生成没有错误处理的文件读写代码。 - 涉及删除操作时必须先输出影响范围再执行。项目级指令文件就是前面提到的项目根目录CLAUDE.md和AGENTS.md。项目级指令优先级更高适合放与具体项目相关的内容。4.4 Skills 与提示词扩展Claude Code 的 Skills 机制允许开发者把特定任务的指令封装成独立的技能文件。典型目录结构如下项目根目录/ ├── .claude/ │ └── skills/ │ └── code-review/ │ ├── SKILL.md │ └── scripts/ │ └── review.py其中SKILL.md是技能说明文件--- name: code-review description: 对当前代码变更进行系统性审查适用于代码评审场景 --- ## 执行步骤 1. 获取本次变更涉及的文件列表。 2. 检查是否存在调试残留代码例如 console.log。 3. 检查异常处理逻辑是否完整。 4. 检查是否有明显的安全问题例如 SQL 拼接、硬编码密钥。 5. 输出审查结论按严重程度排序。 ## 注意 - 只提可执行的改进建议不输出泛泛而谈的内容。 - 如果发现高危问题必须明确标注。当对话内容触发某个 Skill 的 description 时Claude Code 会加载该 SKILL.md把里面的指令作为系统上下文的一部分。社区里也有很多现成的 Skills 可以下载安装方式就是把技能目录放到项目的.claude/skills/或用户目录的~/.claude/skills/下。4.5 系统提示词修改的边界有一点必须强调修改系统提示词不等于修改模型能力。通过 AGENTS.MD、CLAUDE.md、Skills 注入指令只能调整行为的“倾向”和“约束”不能突破模型本身的能力边界。比如模型不擅长实时数据检索你把系统提示词写成“你拥有最新的股票行情”也没有意义它依然需要工具来获取真实数据。安全边界也不是由提示词保证的而是由权限配置保证。提示词里写“不要删除文件”只是行为约定真要防止破坏性操作必须在权限层禁止对应命令。5. 实战通过 CC Switch 接入 DeepSeek 等第三方模型5.1 为什么会有第三方接入需求Claude Code 默认连接 Anthropic 的服务但实际使用中很多人会遇到两类情况组织账号限制了 Claude Code 的访问需要切换到自己可用的模型服务。希望使用 DeepSeek、Kimi 等国内模型或者通过 OpenRouter 选择更多模型。CC Switch 这类社区工具之所以流行就是因为它解决了“快速切换模型供应商”的痛点。5.2 CC Switch 的本质CC Switch 是一个社区桌面工具本质上做的事情是修改 Claude Code 依赖的环境变量或配置文件把默认的模型请求地址和 API Key 切换到其他供应商。它确实节省了手动改环境变量的时间。但要注意这类工具由社区维护版本更新和数据结构差异都很大使用时要以你下载到的工具实际界面为准。5.3 手动配置 DeepSeek 的思路如果不想安装额外工具也可以通过环境变量手动接入。很多第三方模型平台提供了 Anthropic API 兼容端点配置思路如下export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_API_KEYsk-your-deepseek-key claude其中ANTHROPIC_BASE_URL指向第三方平台的 Anthropic 兼容地址ANTHROPIC_API_KEY换成你在该平台申请的 Key。不同平台的接入地址可能不同一定要以目标平台官方文档为准。比如你看到的 DeepSeek 接入地址、OpenRouter 接入地址都要去对应平台确认。5.4 使用 CC Switch 管理多个供应商CC Switch 的典型使用流程是启动 CC Switch。添加多个模型供应商配置例如 Anthropic、DeepSeek、OpenRouter。为每个供应商填写对应的 API Key 和模型名。一键切换当前 Claude Code 使用的供应商。切换之后在 Claude Code 会话里输入/status通常可以看到当前使用的模型和 API 端点。如果显示的模型仍然不对就需要检查 CC Switch 里的模型名是否填写正确。需要提醒的是使用第三方模型时代码会被发送到对应平台处理。公司项目或敏感项目要评估数据合规问题不要贸然把所有源码交给外部服务。6. 常见问题与排查思路Claude Code 相关的报错信息很多下面整理几个高频问题。问题现象常见原因解决思路安装后 claude 命令找不到npm 全局 bin 目录不在 PATH 中执行 npm config get prefix将对应目录加入 PATH首次运行一直卡在登录网络问题或账号验证失败检查网络确认账号状态或改用 API KeyVSCode 插件无法连接 Claude CodeCLI 登录状态失效先回到终端运行 claude重新登录后再打开插件your organization has disabled claude subscription access for claude code企业订阅策略禁止使用联系公司管理员确认策略或使用个人账号/API Key429 / 529 错误请求过载、账号额度不足等待后重试检查订阅或 API 额度deepseek-v4-pro is not a model this version recognizes模型名输入错误或该模型不在当前版本支持列表到第三方平台核对准确的模型 ID重新配置claude code might not be available in your country所在地区不在官方支持范围参考官方支持地区列表合规使用AGENTS.md 不生效文件名大小写错误或目录位置不对确认文件名为 AGENTS.md放在项目根目录修改 CLAUDE.md 后行为没变化当前会话仍使用旧上下文重启 Claude Code 会话重新加载项目上下文针对“提示词修改后不起作用”的情况排查顺序建议如下确认你修改的是不是正确文件。比如你想做项目级定制却改在了用户全局文件里优先级可能不符合预期。确认会话是否重新加载。Claude Code 通常会在启动时读取规则文件运行中的会话可能不会热更新。确认修改内容是否与内置规则冲突。如果项目规则要求“不要运行测试”而基础系统提示词要求“修改代码后验证结果”可能出现矛盾。确认是否被权限配置拦截。规则文件里要求 AI 做某个操作但如果权限层禁止了对应命令AI 无法执行。7. 最佳实践与工程建议7.1 把 AGENTS.MD 纳入版本管理AGENTS.MD 和 CLAUDE.md 不应只放在本地而应该提交到 Git 仓库跟随代码一起评审和更新。这样新成员、CI 里的 AI 工具、不同开发者的本地 Claude Code 都能读到同一份规则。规则文件本身也需要评审。如果一个项目中 AI 频繁生成风格不统一的代码先看 AGENTS.md 是否写清楚了规范再考虑模型能力问题。7.2 不要把密钥写进提示词文件AGENTS.md 和 CLAUDE.md 会进入 AI 的上下文也可能被其他人看到。API Key、数据库密码、内部地址都不应该写进这些文件。密钥统一走环境变量或密钥管理服务。7.3 权限配置比提示词更可靠提示词属于“软约束”权限配置属于“硬约束”。在共享环境或生产环境中要充分利用 Claude Code 的权限机制对 Bash 命令、网络访问、文件写入做最小化授权。7.4 第三方模型接入先小范围验证接入 DeepSeek、OpenRouter 或其他模型时不要上来就跑全量重构任务。先在一个小项目或一个分支上验证模型是否支持工具调用。是否能正确读取 AGENTS.md。生成代码质量是否满足要求。交付速度和成本是否可接受。不同模型对工具调用的支持差异很大Claude Code 的一些高级功能在第三方模型上可能失效。7.5 关注版本变化Claude Code 迭代速度很快社区里很多文章写完后几天就过时了。遇到问题时优先看官方更新日志和当前版本的行为而不是硬套网上的旧教程。这也包括 AGENTS.MD 的解析规则、Skills 的目录规范、系统提示词注入方式等细节。7.6 记录团队成员的使用经验如果团队里有人已经调教出一套效果不错的 AGENTS.md建议沉淀成团队模板。比如统一的代码风格段落、AI 工作约定段落、命令白名单段落。相比每次让 AI 随机发挥一份结构稳定的规则文件价值更大。8. 总结与后续学习这篇文章围绕 Claude Code 的 AGENTS.MD 与系统提示词修改展开梳理了几个关键点Claude Code 是运行在终端里的 AI agentAGENTS.MD 是它理解项目规则的重要入口。系统提示词和用户提示词是两个层级不同的概念AGENTS.MD、CLAUDE.md、Skills 都是把自定义指令注入系统上下文的合法途径。修改系统提示词的常见方式包括用户级配置、项目级指令文件、Skills 技能包。通过 CC Switch 或环境变量可以接入 DeepSeek 等第三方模型但要注意模型兼容性和数据合规问题。遇到安装、订阅、模型名、规则不生效等问题时按“环境变量 → 会话加载 → 配置层级 → 权限拦截”的顺序排查。下一步建议按这条路线继续深入把自己的个人项目补上一份 AGENTS.md跑一周看看 AI 生成代码的变化。研究 Claude Code 的 Skills 规范把一个高频任务封装成技能。阅读 Claude Code 官方文档中关于配置项和权限的部分把软约束和硬约束配合起来。对比 Codex 和 Claude Code 在同等任务下的表现找到更适合自己工作流的工具。AI 编程工具的战斗力很大程度上取决于你给它多少“上下文”。一份高质量的 AGENTS.md一套合理的系统提示词往往比频繁更换模型更能提升实际效果。先动手把项目规则文件写好你会明显感受到变化。