最近 Claude Code 的热度又上来了。不少团队开始把它接入日常开发流程但很多人卡在同一个地方Agent 生成的代码风格不稳定、上下文记不住项目规范、想植入自己的系统提示词又不知道改哪里。其实这些问题很多都和一个配置体系有关——AGENTS.md与系统提示词。本文会围绕 Claude Code 对AGENTS.md的支持、系统提示词修改方式、以及配套的Skills机制做一次完整梳理。内容包含环境安装、配置编写、模型供应商切换、常见报错排查和工程化建议。无论你是刚接触 Claude Code 的新手还是在团队里推广 AI 编程助手的开发者都能从里面找到可以直接落地的方案。1. Claude Code、Agents.MD 与系统提示词先搞清楚这三件事1.1 Claude Code 是什么Claude Code 是 Anthropic 推出的命令行 AI 编程工具。它不是一个传统的 IDE 插件而是运行在终端里的智能助手可以直接读取项目目录、修改文件、执行命令、运行测试并基于当前仓库的上下文给出代码改动建议。你可以把它理解为“住在终端里的结对编程伙伴”。它和 IDE 插件最大的区别是它不依赖图形界面可以在 SSH 远程服务器、容器、CI/CD 环境里运行并且能通过命令行参数和配置文件实现较高程度的自动化。实际开发中Claude Code 的典型使用场景包括阅读并解释陌生项目的代码结构。根据需求描述生成完整功能模块。修改多个文件并保持接口一致性。运行测试、定位失败用例、修复 Bug。执行批量重构并配合git diff做代码审查。它的价值不只是“生成代码”而是“在真实项目上下文里完成开发任务”。这也是为什么AGENTS.md和系统提示词变得如此重要你提供的上下文越准确Agent 的产出质量越高。1.2 什么是 Agents.MDAGENTS.md是一种约定俗成的项目指令文件。它通常放在仓库根目录或者.claude目录下用来向 AI 编程助手描述项目的技术栈、目录结构、代码规范、构建命令、测试方式等信息。这个名字的用意很直接给“Agent”看的 Markdown 文件。相当于你给新同事写一份“项目入职手册”只不过读者是 AI。在 Claude Code 中AGENTS.md会被作为项目级上下文自动读取。当 Claude Code 启动并进入某个项目目录时它会扫描该目录下的指令文件把里面的内容注入到模型上下文中。这样Agent 不需要从零猜测项目规则而是直接按照文件里的约定来工作。一个典型的AGENTS.md内容会包含项目简介与技术栈。代码目录结构说明。代码风格与命名规范。构建、测试、Lint 命令。常见注意事项与禁止操作。团队约定例如提交信息格式、分支命名规则。1.3 系统提示词是什么和用户提示词有什么区别系统提示词System Prompt是对话或 AI 任务中最底层的指令它定义了 AI 的角色、行为边界、输出格式和全局规则。在 Claude Code 中系统提示词决定了 Agent 的“人设”和“工作方式”比如如何规划任务、如何调用工具、何时停下来向用户确认。用户提示词User Prompt则是你每次输入给 AI 的具体指令。比如“请帮我写一个登录接口”就是用户提示词。两者的区别可以这样理解对比项系统提示词用户提示词作用范围全局每次请求都会生效单次任务内容性质角色定义、规则约束、工作流程具体需求、上下文、目标生命周期配置后持续生效当前对话/任务结束后失效修改方式配置文件、CLI 参数每次对话直接输入优先级较高通常不被用户对话覆盖低于系统提示词但可提供细节在实际使用中如果你想让 Claude Code“始终遵循某些开发规范”应该把它们写进系统提示词或项目指令文件如果你只是想让它在某一次任务里做某件事直接在对话里说明即可。1.4 这次“支持”意味着什么网上关于“Claude Code 将支持 Agents.MD 与系统提示词修改”的讨论核心信息是Claude Code 更进一步完善了AGENTS.md机制并且允许开发者通过配置文件修改系统提示词。这对开发者意味着两件事项目级规范可以沉淀成文件团队可以在仓库里维护AGENTS.md让所有使用 Claude Code 的成员获得一致的 AI 行为约束。系统提示词不再黑盒你可以调整模型的行为边界例如限制 Agent 只能修改某些目录、强制它先写测试再写实现、要求它在执行危险命令前必须二次确认。当然不同版本的 Claude Code 对AGENTS.md的支持深度不同具体配置项也可能有差异。下面我会先讲环境准备再给出一套可复制的配置方案。2. 环境准备把 Claude Code 装起来2.1 前置条件与版本说明Claude Code 主要依赖 Node.js 运行时。安装之前先确认你的机器满足以下条件操作系统macOS、Linux、WindowsWindows 建议使用 WSL 2 或 Git Bash。Node.js建议使用 18.0 或更高版本。npm 或 yarn 等包管理器。一个可用的 Claude 账号或可用的 API Key。终端工具例如 macOS 的 Terminal、Windows 的 PowerShell 或 Windows Terminal。不同的 Claude Code 版本配置文件格式可能略有差异。本文的示例以常见稳定版本为准重点演示配置思路你实际操作时如果遇到参数不识别可以先查看当前版本的帮助文档claude --help2.2 Node.js 环境准备如果你的机器还没有安装 Node.js推荐使用nvm或官方安装包安装。下面以 nvm 为例# 安装 nvmmacOS / Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重启终端后安装并使用 Node.js 18 nvm install 18 nvm use 18 # 检查版本 node -v npm -v安装完成后看到类似v18.20.4和10.7.0的输出说明 Node.js 环境正常。2.3 安装 Claude Code 的三种方式Claude Code 的安装方式比较灵活常见的有三种。第一种是使用 npm 全局安装npm install -g anthropic-ai/claude-code这种方式适合习惯命令行的开发者。安装完成后直接在任意终端执行claude即可启动。第二种是使用桌面端应用。Claude Code 官方也提供了桌面版客户端适合不习惯纯命令行的用户。桌面端和 CLI 的配置目录通常是共享的你在桌面端修改的配置在 CLI 里同样可以读取。下载地址可以关注官方发布页面但无论是 CLI 还是桌面端底层遵循的配置逻辑是相同的。第三种是 VS Code 插件。在 VS Code 扩展市场搜索 “Claude Code” 即可找到官方插件。安装插件后可以直接在编辑器里打开 Claude Code 的面板实现“边看代码边操作 Agent”的体验。不管采用哪种方式安装完成后建议先确认版本claude --version如果输出版本号说明安装成功。2.4 初始化与登录安装完成后第一次运行需要完成认证。在终端中执行claude首次启动时Claude Code 会引导你登录 Claude 账号或者配置 API Key。如果你是通过订阅账号使用直接按提示完成授权登录如果是通过第三方模型服务需要配置 API Key通常把 Key 写入环境变量或配置文件中。常见的环境变量配置方式如下export ANTHROPIC_API_KEY你的 API Key如果你使用的是第三方兼容服务还可以配置自定义接口地址。下面是一个常见的示例export ANTHROPIC_BASE_URLhttps://你的服务地址 export ANTHROPIC_API_KEY你的 API Key配置完成后再次运行claude看到交互式终端界面就说明环境已经就绪。3. 核心机制拆解Agents.MD、Skills、系统提示词怎么写3.1 AGENTS.md 的基础写法AGENTS.md的核心作用是让 Agent 在开始工作前就了解项目的“规则”。它的语法就是 Markdown你可以按团队习惯组织内容但有几个关键模块建议保留。先来看一个最简单的示例# AGENTS.md ## 项目简介 这是一个基于 Next.js 14 的博客系统使用 TypeScript 开发。 ## 技术栈 - 框架Next.js 14 - 语言TypeScript - 样式Tailwind CSS - 数据库PostgreSQL Prisma ## 常用命令 - 安装依赖npm install - 启动开发服务npm run dev - 执行测试npm test - 代码检查npm run lint ## 代码规范 1. 组件使用函数式组件禁止使用 class 组件。 2. 所有 props 必须定义 TypeScript 类型。 3. 样式优先使用 Tailwind不要写纯 CSS 文件。 4. API 路由统一放在 src/app/api 目录下。 ## 注意事项 1. 不要修改数据库表结构除非用户明确要求。 2. 提交信息格式为type(scope): description例如 feat(auth): add login api。 3. 涉及破坏性变更时必须先向用户说明。把上面的内容保存到项目根目录命名为AGENTS.md再次启动 Claude Code 时它就会自动读取这些规则。你可以验证一下让 Claude Code 生成一个新的接口文件看它是否遵守了命名规范和目录约定。这里有一个容易忽略的点AGENTS.md的读取顺序和优先级。通常 Claude Code 会先读取用户级配置再读取项目级配置项目级配置会覆盖或补充用户级配置。如果你的项目里有多个层级的AGENTS.md要注意避免规则冲突。3.2 Skills 机制把常用能力封装成“技能”除了AGENTS.mdClaude Code 还支持Skills机制。你可以把Skills理解成“可复用的能力包”一个 Skill 通常包含一个SKILL.md描述文件以及可能附带的一些脚本、模板或参考文档。例如你想让 Claude Code 在生成 React 组件时保持统一风格就可以定义一个react-component技能skills/ └── react-component/ └── SKILL.mdSKILL.md的内容类似这样--- name: react-component description: 根据需求生成一个 React 函数式组件使用 TypeScript 和 Tailwind CSS。 --- # React 组件生成规范 1. 使用函数式组件和 Hooks禁止使用 class 组件。 2. 文件命名使用 PascalCase例如 UserCard.tsx。 3. 组件 Props 必须定义 interface并使用 export 导出。 4. 样式使用 Tailwind CSS 类名禁止使用内联 style。 5. 必须导出默认组件同时导出 Props 类型。当你在对话中提到相关需求时Claude Code 会读取这个 Skill 的内容并按照其中的规则生成代码。Skills和AGENTS.md的区别在于AGENTS.md是全局项目规范而Skills是“按需加载”的能力模板适合封装高频、固定模式的任务。3.3 修改系统提示词的常见方式在 Claude Code 中修改系统提示词通常有两种方式配置文件修改和 CLI 参数修改。配置文件方式是在用户级或项目级配置目录中添加settings.json。Claude Code 的配置文件通常位于用户级~/.claude/settings.json项目级.claude/settings.json示例配置{ permissions: { allow: [ Bash(npm run lint), Bash(npm test) ], deny: [ Bash(rm -rf *) ] }, model: claude-sonnet-4-20250514 }上面这段配置的作用是限制 Agent 只能执行允许列表中的命令禁止执行危险命令并指定默认模型。如果你需要修改系统提示词本身不同版本支持的方式不同。有些版本支持通过环境变量注入额外的系统指令有些版本则内置了CLAUDE.md这样的文件来补充系统级指令。更常见的做法是把行为规范写入用户级或项目级的CLAUDE.md文件让 Claude Code 在每次对话前自动加载。例如在~/.claude/CLAUDE.md中写入# 全局行为准则 1. 回答技术问题使用中文。 2. 生成代码时必须附上代码注释注释使用中文。 3. 执行删除、覆盖等危险操作前必须先向用户确认。 4. 优先阅读项目文档不要凭空猜测技术方案。 5. 输出内容使用 Markdown 格式代码块标注语言类型。这样无论你在哪个项目中使用 Claude Code模型都会遵守这些全局规则。项目级规则写在项目根目录的CLAUDE.md或.claude/CLAUDE.md中优先级高于用户级规则。3.4 容易混淆的三个概念很多新手容易把AGENTS.md、CLAUDE.md、System Prompt这三个概念搞混这里做一个简单区分文件/概念作用范围典型使用场景AGENTS.md项目级跨工具通用描述项目技术栈、构建命令、代码规范CLAUDE.mdClaude Code 专属定义 Claude Code 的行为准则、交互偏好System Prompt模型请求级定义模型角色、输出格式、工具调用规则简单来说AGENTS.md偏向“项目说明书”CLAUDE.md偏向“Claude 专属操作手册”System Prompt是更底层的“大脑指令”。它们之间可以互相补充但不要把它们完全混为一谈。4. 完整实战从项目指令到模型配置4.1 设计一个示例项目为了演示完整流程我们搭建一个简单的 Node.js API 项目。假设项目名为ai-blog-api目录结构如下ai-blog-api/ ├── src/ │ ├── index.ts │ └── routes/ │ └── post.ts ├── package.json ├── tsconfig.json ├── AGENTS.md └── .claude/ ├── settings.json └── CLAUDE.md这个项目使用 TypeScript 和 Express提供博客文章的基础 CRUD 接口。我们将通过AGENTS.md和CLAUDE.md让 Claude Code 按照团队规范开发。4.2 编写项目级 AGENTS.md在项目根目录创建AGENTS.md内容如下# AGENTS.md ## 项目简介 ai-blog-api 是一个基于 Node.js TypeScript 的博客后端服务。 ## 技术栈 - 运行时Node.js 18 - 语言TypeScript - Web 框架Express 4 - 数据库SQLite开发环境 - ORMPrisma ## 常用命令 - 安装依赖npm install - 启动开发服务npm run dev - 构建npm run build - 测试npm test ## 代码规范 1. 路由文件统一放在 src/routes 目录下。 2. Controller 层负责参数校验和响应Service 层负责业务逻辑。 3. 接口返回格式统一为 { code: number, message: string, data: any }。 4. 所有异步错误必须使用 try-catch 处理禁止出现未捕获的 Promise rejection。 ## 安全要求 1. 禁止将 API Key、数据库密码等敏感信息硬编码到代码中。 2. 涉及用户输入时必须进行校验。 3. 删除类操作必须实现软删除不直接删除数据库记录。保存后启动 Claude Code 并输入一个简单任务例如请帮我实现一个“创建文章”的接口。你会发现 Claude Code 会按照AGENTS.md中定义的目录结构、返回格式、错误处理方式来生成代码而不是随意发挥。4.3 添加项目级 CLAUDE.md接下来在.claude/CLAUDE.md中添加 Claude Code 专属行为规则# Claude Code 项目规则 1. 每次完成代码修改后必须运行 npm run build 确认没有类型错误。 2. 输出代码时所有注释使用中文。 3. 如果涉及数据库变更必须先说明变更内容和影响再执行操作。 4. 新增依赖时需要说明新增依赖的用途并给出替代方案。 5. 重要操作删除、覆盖、批量修改执行前必须向用户二次确认。CLAUDE.md的优先级在项目范围内高于用户级配置。如果你设置了全局规则但项目内规则希望覆盖它可以在项目级CLAUDE.md中重新声明。4.4 修改系统提示词在 Claude Code 中系统提示词的“修改”更多是“补充”和“约束”。常见做法是通过settings.json和CLAUDE.md组合实现。假设我们希望 Claude Code 在生成代码时始终保持中文注释、禁止直接修改 lock 文件、只允许运行安全的 npm 命令。可以在.claude/settings.json中添加{ permissions: { allow: [ Bash(npm run dev), Bash(npm run build), Bash(npm test), Bash(git status), Bash(git diff) ], deny: [ Bash(rm -rf *), Bash(npm install *), Bash(npx prisma migrate reset) ] }, hooks: { PostToolUse: [ { matcher: Bash, command: node .claude/scripts/check-dangerous-commands.js } ] } }这段配置做了三件事allow限制了 Agent 可以自动执行的命令范围。deny禁止了高风险命令。hooks在每次工具调用后执行一个检查脚本用于捕捉危险命令。如果你想更直接地自定义模型行为也可以尝试在启动时通过命令行参数传入额外指令不过不同类型的模型对系统提示词的支持程度不同建议先阅读当前版本的帮助文档。4.5 通过 CC Switch 切换模型供应商很多开发者使用 Claude Code 时并不直接使用 Anthropic 官方服务而是希望通过第三方兼容接口接入其他模型例如 DeepSeek。这时就需要借助配置切换工具社区中比较常见的是 CC Switch。CC Switch 的定位是“Claude Code 配置切换器”它主要用于管理不同的 API 配置方便你在多个模型供应商之间快速切换。基本思路如下安装 CC Switch可以通过 npm 或桌面端使用。在 CC Switch 中添加配置填写接口地址、API Key、模型名称。将配置应用为 Claude Code 的当前环境。启动 Claude Code 时自动读取对应配置。CC Switch 本质上是帮你管理环境变量或配置文件而不是修改 Claude Code 本身。因此你在切换配置时要注意确认目标模型是否兼容 Claude Code 的接口协议。确认模型名称是否在当前版本支持的列表中。如果出现 “model is not a model this version of claude code recognizes” 之类的报错说明模型名称不匹配需要更换为兼容名称或调整配置。4.6 运行与验证完成配置后运行claude进入交互界面后输入请查看项目结构并说明你接下来会如何实现“创建文章”接口。如果配置正确Claude Code 应该会先读取AGENTS.md了解项目规范。读取CLAUDE.md掌握工作方式。输出项目结构分析并给出符合规范的实现计划。在生成代码时遵守中文注释、统一返回格式等规则。你可以把生成结果和规范对照一下确认是否完全匹配。如果不匹配多半是规则写得不够具体或者配置文件路径不正确。5. 常见问题与排查思路Claude Code 的安装和使用过程中容易遇到一些问题。下面整理了几个高频场景及排查方案。问题现象常见原因解决思路安装命令执行后提示命令不存在Node.js 版本过低或 npm 全局目录不在 PATH 中升级 Node.js检查 npm global bin 目录并加入 PATH启动时提示 “claude” not found安装不完整或未全局安装重新执行 npm install -g anthropic-ai/claude-code使用订阅账号登录失败组织策略限制或网络问题检查账号权限联系管理员确认 Claude Code 访问权限请求返回 529 错误服务端负载过高或触发了限流稍后重试降低请求频率检查 API Key 额度提示模型名称不被识别模型 ID 不对或版本过旧查看支持的模型列表升级 Claude Code检查配置中的模型名AGENTS.md 不生效文件名大小写不对或放置目录错误确认文件是 AGENTS.md检查是否在项目根目录重启 Claude Code系统提示词修改无效果配置层级优先级不对确认项目级配置是否覆盖了用户级检查 settings.json 格式命令权限被拒绝permissions 配置限制了命令范围检查 allow/deny 列表按需添加白名单通过第三方模型接入时报错接口地址或 API Key 配置错误检查环境变量确认服务商接口协议是否兼容下面挑几个典型报错详细拆解。5.1 安装与启动类问题如果你执行claude提示找不到命令先执行which claude npm config get prefix如果npm config get prefix输出到某个目录而该目录不在PATH中可以手动加入export PATH$(npm config get prefix)/bin:$PATH这个问题的根源通常是 npm 全局安装路径未被终端识别和 Claude Code 本身关系不大。5.2 登录与订阅类问题收到类似 “your organization has disabled claude subscription access for claude code” 的提示时说明组织管理员关闭了 Claude Code 的订阅访问权限。这种情况属于账号策略限制处理方法很简单联系组织管理员确认权限或者使用个人账号授权。如果你使用的是个人账号可以检查是否切换到了错误的组织工作区。5.3 模型识别与接口类问题报错信息类似deepseek-v4-pro is not a model this version of claude code recognizes这说明当前版本识别不了你配置的模型名称。原因可能是模型 ID 写错也可能这个模型本来就只支持部分版本的 Claude Code。处理方式是到服务商文档里核对模型 ID然后修改环境变量或配置文件中的model字段。5.4 配置不生效类问题AGENTS.md或CLAUDE.md修改后不生效最常见的原因是文件路径不对或者没有重启 Claude Code。Claude Code 通常在启动时读取配置如果你在对话进行中修改了文件需要重启会话才能加载新配置。另外要注意文件编码建议统一使用 UTF-8避免中文注释出现乱码。6. 最佳实践与工程建议6.1 提示词与项目指令的版本管理AGENTS.md、CLAUDE.md、settings.json这些文件都应该纳入版本控制和项目代码一起管理。这样当新成员加入时不需要口头讲解规则Agent 和人都能通过文件快速了解项目约定。建议把规则文件放在独立目录中例如.claude/并在这个目录下维护 README说明每个文件的作用和修改流程。团队里可以指定一位“AI 配置负责人”负责评审规则变更避免配置文件被随意修改导致行为漂移。6.2 团队协作中的职责边界Claude Code 适合处理重复性、模板化、局部修改的工作但在涉及架构决策、核心数据模型变更、第三方服务对接时建议由开发者主导判断。在AGENTS.md中要明确哪些操作是“Agent 可以自动执行”的哪些是“必须询问用户”的。例如## 自动执行 - 生成测试用例 - 编写单元测试 - 重构工具函数 - 修复 ESLint 报错 ## 必须询问 - 删除目录或文件 - 修改数据库表结构 - 升级依赖大版本 - 修改 CI/CD 配置这样能减少 Agent 在危险操作上“先斩后奏”的概率。6.3 API Key 与成本控制如果你使用的是付费 API需要注意成本控制。Claude Code 在处理大型项目时可能会产生大量 Token 消耗建议采取以下措施使用项目级配置限制 Agent 的上下文范围不读取无关目录。在settings.json中设置命令白名单减少无效操作。定时检查 API 用量和费用账单。不要把多个成员共享同一个 API Key避免单个账号触发限流。对于第三方模型还要注意接口兼容性问题。不同模型对工具调用的支持程度不同建议先在小项目中做测试再推广到核心仓库。6.4 安全与权限边界安全问题是使用 AI 编程工具时最容易忽略的部分。Claude Code 拥有读写文件、执行命令的权限如果不做限制一旦模型被恶意提示词诱导可能执行危险操作。下面几条建议非常重要在settings.json中配置permissions禁止运行高危险命令。对包含敏感信息的目录如.env、config/设置访问限制。涉密项目的代码不要直接交给第三方模型处理优先使用本地部署或私有化接口。定期审查 Claude Code 的执行日志检查是否有异常操作记录。涉及生产环境的变更绝不能由 Agent 自动执行必须经过人工 review 和审批流程。安全原则可以简单概括为最小权限、显式授权、全程审计。7. 总结与下一步学习建议这篇文章从 Claude Code 的基础概念讲起详细介绍了AGENTS.md的写法、Skills机制、系统提示词与用户提示词的区别并给出了一个完整的实战配置示例。同时也整理了安装、登录、模型切换、配置不生效等高频问题的排查方法。如果你是从零开始建议按下面的顺序继续深入先在你的个人项目中写一个精简的AGENTS.md让 Claude Code 帮你生成一个功能模块观察行为变化。尝试创建第一个Skill把团队里最高频的代码生成模板沉淀下来。熟悉settings.json的权限控制学会限制 Agent 的命令范围。如果公司有私有化模型或第三方服务接入需求用 CC Switch 或环境变量做配置管理并对比不同模型在编码任务上的表现。关于系统提示词不要一上来就追求“复杂系统”而是从“约束行为”开始。先保证 Agent 不做危险操作再逐步加入风格偏好、输出格式、任务拆分策略等高级规则。配置文件和提示词规则本身也是代码同样需要维护、评审和迭代。希望这篇文章能帮你少踩一些坑把 Claude Code 真正用起来。