Claude Code 作为一款面向开发者的命令行 AI 编程工具正在把项目级协作能力作为本次升级的重点。从目前公开的更新方向看支持 Agents.MD 文件与系统提示词修改意味着开发者可以把项目背景、编码规范、架构约束直接注入 Agent 的上下文而不是每次开始新会话时反复解释“这是什么项目、你要遵守什么规则”。这个能力一旦落地Claude Code 就不再只是一个能回答代码问题的终端助手而是一个可以按照团队约定持续工作的项目级 Agent。本文会围绕这条主线展开先解释 Agents.MD 和系统提示词在 Claude Code 工作流中的位置再介绍如何编写文件、修改系统提示词随后给出安装、配置和验证的完整路径最后整理常见问题与排查方法。无论你是在本地个人项目中使用还是在团队仓库里统一维护 AI 协作规范这套思路都可以直接迁移。1. 先看懂 Claude Code 的执行链路Agent、会话上下文与提示词的关系1.1 Claude Code 是什么为什么需要项目级提示词Claude Code 是 Anthropic 推出的命令行 AI 编程工具可以在终端里直接读取文件、执行命令、修改代码并基于当前项目内容生成回答或完成编程任务。与普通聊天窗口不同的是它的输入不只是用户敲入的一条指令而是“用户指令 当前项目上下文 系统提示词”三部分的组合。项目级提示词的价值在于解决一个很常见的问题AI 工具不知道你的项目背景。同一个仓库里可能同时有前端、后端、脚本和文档Agent 如果没有约束可能会在错误目录里改代码也可能按通用规范而不是团队规范来生成内容。有了项目级提示词就可以在目录级别告诉 Claude Code“这是 Java 后端项目接口返回统一使用 Result 结构禁止直接返回 Map”这类规则会随会话自动加载。过去这些约束通常只能写在用户消息里每次开会话都要重复。支持 Agents.MD 和系统提示词修改后项目约束可以固化到文件或配置中Agent 每次启动时自动读取从而使输出更稳定。1.2 Agents.MD 在 Agent 工作流中的位置Agents.MD 的核心思路是给 Agent 一份“项目说明书”。当 Claude Code 进入某个目录时它可以按照规则读取对应目录下的 Agents.MD 文件把其中的内容作为上下文的组成部分。实际使用中文件名更常见的是全大写AGENTS.md。标题里写成 Agents.MD 并不影响理解但在仓库中落地时建议遵循社区更通用的写法避免大小写问题在不同操作系统或未来版本中出现偏差。你可以在项目根目录放一份AGENTS.md也可以在子目录中放更细化的AGENTS.md让 Agent 在不同模块下自动获得不同的上下文。这份文件加载后作用类似于“项目级系统提示词片段”。但它与真正的系统提示词又有区别Agents.MD 主要是项目事实和规则系统提示词则更多描述 Agent 的角色、行为边界和输出格式。两者可以配合使用而不是互相替代。1.3 系统提示词和用户提示词的区别系统提示词System Prompt是设置 Agent 身份和全局行为的提示词通常由工具或开发者预先定义不随每轮对话变化。用户提示词User Prompt则是每一次用户输入的具体指令解决的是“当前这一轮要做什么”。在很多工作流平台上也有类似区分系统提示词负责长期约束用户提示词负责短期任务。Claude Code 对系统提示词的修改能力意味着你可以覆盖默认的角色设定比如默认的“你是 Claude Code 编程助手”可以改写成“你是本团队的资深后端工程师回答问题前必须列出影响到的文件”。注意区分三个概念概念作用范围典型内容修改方式系统提示词全局/会话级角色、行为边界、输出格式环境变量、配置文件、CLI 参数Agents.MD项目/目录级项目结构、技术栈、编码规范在目录中放置文件用户提示词单次请求具体任务、问题描述每次对话输入理解这三者的关系后后面配置时就不会搞混。系统提示词管“你是谁”Agents.MD 管“你在什么项目里”用户提示词管“这一轮做什么”。2. Agents.MD 文件要怎么写格式、作用域与加载规则2.1 Agents.MD 的本质给 Agent 看的项目说明书Agents.MD 不是给人看的完整文档而是给 Agent 看的精简说明书。它不需要像 README 那样面面俱到也不需要像架构文档那样详细。它要回答的是 Agent 在进入项目后最先遇到的几个问题这个项目是做什么的用了什么技术栈代码目录结构是怎样的有哪些硬性约束和常见禁忌自动化命令是什么测试、构建、格式化怎么执行涉及外部服务时有哪些注意事项写作原则是“短句、明确、可执行、无歧义”。不要让 Agent 去猜“尽量不要”而是直接告诉它“不要做 A遇到 B 时按 C 处理”。2.2 一个最小示例假设一个后端项目使用 Java 17、Spring Boot 3、Maven数据库使用 PostgreSQL。可以在项目根目录创建AGENTS.md# AGENTS.md ## 项目目标 这是一个用户订单管理后端服务提供订单创建、查询、取消接口。 ## 技术栈 - Java 17 - Spring Boot 3.2 - Maven 3.9 - PostgreSQL 15 - Redis 7 ## 目录结构 - src/main/java/com/example/order主代码 - src/main/resources配置与 SQL 脚本 - src/test单元测试与集成测试 ## 构建与测试 - 构建mvn clean package - 运行测试mvn test - 启动开发环境mvn spring-boot:run ## 编码规范 - Controller 只做参数接收和响应包装不写业务逻辑。 - 所有接口返回统一结构ResultT。 - 禁止在 Service 层直接返回 Map 或 JSONObject。 - 数据库字段使用下划线命名Java 字段使用驼峰命名。 ## 注意事项 - 涉及金额的字段必须使用 BigDecimal禁止使用 double。 - 删除操作必须做软删除不能执行物理删除。 - 每次改动代码后必须运行 mvn test确认没有破坏已有测试。这个文件虽然只有二十多行但对 Agent 的约束已经非常明确。后续让 Claude Code 添加一个下单接口时它会自动遵循 Result 返回结构、软删除、测试验证等规则。2.3 作用域与优先级Agents.MD 可以分级放置。根目录的AGENTS.md描述全局规则子目录的AGENTS.md描述模块内特殊规则。加载时Claude Code 通常会从当前工作目录向上或向下查找合适的文件具体顺序可能随版本调整但核心原则是“就近优先子目录覆盖或补充根目录”。例如order-service/ ├── AGENTS.md └── src/main/java/com/example/order/ ├── controller/ │ └── AGENTS.md └── service/ └── AGENTS.md根目录的AGENTS.md写全项目规范controller目录下的AGENTS.md补充“所有接口必须做参数校验”等局部规则。这样 Agent 在不同目录时看到的上下文不同既能控制 token 消耗又能保证相关规则不被淹没。优先级设计上建议遵循这样的顺序会话级用户指令 目录级 Agents.MD 根目录 Agents.MD 默认系统提示词。用户明确要求永远应该覆盖项目默认规则项目级规则再覆盖全局默认规则。这样既保留了灵活性也避免 Agent 被死板的文件约束绑住。2.4 常见的错误写法与检查点编写 Agents.MD 时有几类写法会导致效果大打折扣。第一类是写成了论文式长文。Agent 的上下文窗口虽然不小但过多的废话会稀释关键约束。好的做法是每个约束独立成行最多两行说明原因。第二类是规则冲突。例如根目录说“所有接口统一返回 Result”子目录又说“health 接口直接返回 String”。Agent 看到冲突规则时很难判断以哪个为准。建议在冲突时明确“子目录规则优先”或“根目录规则优先”。第三类是只有规则没有验证方式。例如“代码必须经过充分测试”Agent 不知道怎样算充分。更好的写法是“每个新增 public 方法至少要有对应单元测试运行 mvn test 必须全部通过”。写完文件后可以做一个简单验证进入项目目录启动 Claude Code输入“请根据 AGENTS.md 总结这个项目的关键约束”看它能否准确复述。如果复述结果偏离文件内容说明文件可能太长、格式太散或加载路径不对。注意Agents.MD 不是 README 的替代品也不是交给普通用户看的产品手册。它的目标读者只有一个进入这个目录的 AI Agent。3. 系统提示词修改从 CLI 参数、配置文件到会话内指令3.1 为什么要修改系统提示词修改系统提示词能做什么最直接的价值是改变 Agent 的“职业身份”和“工作方式”。默认情况下Claude Code 的定位是通用编程助手回答偏保守操作偏谨慎。在特定项目中你可能希望它更主动地检查代码、更严格地输出格式或者在回答前先列出影响范围。具体场景包括希望 Agent 每一次回答都给出“改动文件列表 影响范围”。希望 Agent 默认使用中文回复而不是中英混杂。希望 Agent 遇到不确定的依赖版本时先查配置文件再回答。希望 Agent 在修改代码前先输出计划等待确认后再动手。这些行为如果靠每次输入用户提示词来维护既浪费 token又容易遗漏。把它们写入系统提示词就可以让每个会话都继承相同的行为基线。3.2 修改系统提示词的入口在 Claude Code 中系统提示词的修改路径通常有三层配置目录、CLI 参数、会话内设置。不同版本支持程度可能不同落地前先确认当前版本的帮助信息。第一层是全局配置文件。常见位置在用户主目录下的.claude目录中例如settings.json。可以在其中设置系统提示词相关字段。第二层是项目级配置放在.claude/settings.json只对当前项目生效。第三层是 CLI 启动参数执行claude时传入自定义提示词。典型的 CLI 形式claude --system-prompt 你是本项目的后端架构师。回答问题时必须先列出受影响的文件再给出具体代码。如果希望更持久可以写入项目级settings.json{ systemPrompt: 你是本项目的后端架构师。回答问题时必须先列出受影响的文件再给出具体代码。所有接口建议使用 ResultT 包装。 }这里要特别提醒不同版本的 Claude Code 对配置字段的命名可能有差异。有的版本使用systemPrompt有的版本可能使用system_prompt或additionalSystemPrompt。配置不生效时优先执行claude --help查看当前版本支持的参数名。3.3 修改后的加载优先级系统提示词修改可能涉及“追加”和“覆盖”两种语义。追加是在默认系统提示词后面加入你的规则风险较低覆盖是替换整个默认系统提示词风险较高因为默认提示词中可能包含工具调用、安全边界等必要逻辑。建议优先采用追加方式。以普通开发者能理解的方式来说默认系统提示词是安全网你的项目规则是在安全网内增加约束而不是把安全网撤掉。如果直接覆盖可能导致 Agent 无法正确调用文件读写、命令执行等核心工具。因此在配置时尽量寻找appendSystemPrompt或类似字段而不是完全替换。例如{ appendSystemPrompt: \n请遵守以下项目规则\n1. 修改代码前先列出影响文件。\n2. 涉及数据库操作时检查是否存在事务注解。 }这样既保留官方默认行为又加入了项目自定义约束。3.4 修改后如何验证生效验证系统提示词是否生效最直接的方法是让 Agent 输出“你当前的角色指令是什么”。如果它能够复述你追加的规则说明配置已经进入上下文。另一种方式是设计一个触发型测试。比如追加规则“每次修改 Java 文件前先检查是否存在于 pom.xml 中的依赖”然后要求 Agent 添加一个使用某依赖的功能。如果它先检查依赖再写代码说明规则生效如果直接写代码且没有提示依赖问题说明配置可能没有加载。还可以通过观察回答风格判断。追加“所有回答使用中文”后Agent 如果仍然优先输出英文需要检查配置文件路径、字段名和启动方式。注意不要只验证程序能启动还要验证输入、输出、异常分支和日志是否符合预期。系统提示词能否生效必须通过实际对话内容来确认。4. 环境准备与安装从 CLI 到桌面端与 VS Code 插件4.1 安装前提安装 Claude Code 前需要确认本机环境满足基本要求。官方支持常见操作系统但具体支持范围以当前版本的官方文档为准。通常需要Node.js 18 或更高版本用于安装 npm 包。能正常访问服务端的网络环境。一个可用的 Claude 账号或 API Key。足够的磁盘空间和内存用于处理代码上下文。建议在安装前检查 Node 版本node -v npm -v如果 Node 版本过低先升级 Node.js。生产环境建议使用固定版本避免升级后依赖不兼容。4.2 安装 Claude Code 的几种方式Claude Code 的安装方式与你的使用场景有关。最常见的三种# 全局安装 CLI 工具 npm install -g anthropic-ai/claude-code # 查看安装后的版本 claude --version如果你更习惯图形界面可以安装桌面端应用。桌面端会把项目目录、会话历史和配置文件统一管理适合不常用终端的开发者。如果你使用 VS Code可以直接在扩展市场搜索 Claude Code 插件。安装后可以在编辑器底部或侧边栏打开会话面板也可以选中代码后右键发送给 Claude Code。插件本质上还是调用本地的 CLI 或服务因此核心配置与 CLI 相同。4.3 首次登录与鉴权安装完成后执行claude进入交互界面会触发登录流程。常见方式有两种订阅账号登录和 API Key 鉴权。订阅账号登录会打开浏览器完成授权完成后 CLI 会保存凭据。API Key 鉴权则通过环境变量或配置文件提供export ANTHROPIC_API_KEY你的 API Key claude如果企业环境要求通过代理接口访问模型服务还可以使用ANTHROPIC_BASE_URL指向兼容的服务地址。不过要注意只有兼容 Anthropic Messages API 的服务才能正常工作否则启动时会出现模型无法识别的报错。4.4 常见安装问题安装阶段遇到最多的问题可以对照下表排查问题现象常见原因检查方式处理建议命令找不到npm 全局目录未加入 PATH执行npm config get prefix将输出路径加入环境变量 PATH安装时报 EACCES 权限错误当前用户无全局写入权限执行npm config get prefix使用 nvm 或设置 npm 前缀到用户目录登录后无法使用账号权限或区域限制查看终端报错信息按官方支持范围和账号状态确认API Key 配置后仍提示未登录环境变量名或值错误执行echo $ANTHROPIC_API_KEY核对变量名不要在值前后加空格启动时模型不识别服务端与客户端模型名不一致查看启动日志中的模型名使用当前版本支持的模型名或更新客户端安装问题大多数发生在环境变量和版本匹配上。不要在多个版本同时存在时盲目升级先固定一套可运行的版本组合。5. 在 VS Code 和桌面端使用项目提示词5.1 工作区配置与项目级 Agents.MD 的放置在 VS Code 中Claude Code 插件通常会读取当前打开工作区的根目录。只要工作区根目录下有AGENTS.mdAgent 就能在会话开始时自动加载。如果你在 VS Code 中打开的是仓库根目录那么配置文件可以分布在根目录和子目录。但要注意如果工作区只打开了某个子目录根目录的AGENTS.md可能不会被读取。因此建议统一从仓库根目录打开工作区。项目级配置.claude/settings.json也应该放在工作区根目录下并提交到版本仓库。这样团队成员 clone 项目后不需要手动配置Claude Code 就会自动读取相同的规则。5.2 VS Code 插件中的常用配置VS Code 插件安装后会读取用户级和项目级配置。一个常见组合是用户级settings.json保存个人偏好比如中文回答、输出详细程度。项目级settings.json保存项目规则比如必须运行测试、禁止改动生成的代码。项目根目录AGENTS.md保存项目事实比如技术栈、目录结构、命名规范。在 VS Code 中你可以通过设置界面搜索 Claude Code 相关配置也可以直接编辑 JSON 文件。注意区分“用户设置”和“工作区设置”。如果项目中已经存在.vscode/settings.jsonClaude Code 插件的配置也可以放在里面但建议独立到.claude/settings.json避免与编辑器通用配置混在一起。5.3 桌面端与 CLI 的同步机制桌面端通常會在底层复用 CLI 的核心逻辑。因此AGENTS.md和.claude/settings.json的读取规则在桌面端、CLI、VS Code 插件之间应当保持一致。不过桌面端可能增加一层“应用配置”用来管理项目列表、会话记录和主题设置。这些应用级配置与项目配置不冲突但如果桌面端缓存了旧的提示词修改文件后可能不会立即生效。遇到这种情况重启桌面端或重新打开项目目录即可。5.4 使用中的注意事项使用图形界面时容易忽略文件路径。桌面端和 VS Code 插件显示的“当前目录”不一定是仓库根目录。如果当前目录是一个深层子目录Agent 读取到的上下文可能缺少根目录规则。建议在每次会话开始时先确认一个问题“当前 Agent 的工作目录在哪里”可以让 Claude Code 执行pwd并列出工作区根目录下的关键文件。如果发现目录不对就用“切换到项目根目录”的指令修正或在图形界面中正确处理打开目录。注意不要在不同工具间重复配置同一套规则。CLI、桌面端、VS Code 插件共用项目文件时只要路径一致规则就会同步。6. 常见问题与排查链路6.1 Agents.MD 不生效现象项目里写了AGENTS.md但 Claude Code 完全像没看到一样回答内容与文件规则无关。按以下顺序排查检查文件名是否完全正确。推荐使用AGENTS.md不要写成agents.md或Agents.md。部分文件系统大小写不敏感但为了跨平台稳定建议统一大写。检查文件是否在当前工作目录或上级目录。Claude Code 的加载规则一般基于工作目录不是基于编辑器打开的任意文件。检查文件编码是否为 UTF-8。包含中文时如果编码混乱Agent 可能无法正确解析。检查是否有其他同名文件冲突。如果根目录和子目录都有AGENTS.md确认是否触发了冲突规则。修复后重新启动会话再测试。6.2 系统提示词被覆盖现象在settings.json中配置了systemPrompt但每次会话表现仍是默认行为。可能原因使用了错误的配置字段名。修改的是用户级配置但当前项目级配置覆盖了它。CLI 启动时没有加载该配置文件。配置文件中 JSON 语法错误导致整体被忽略。检查方法打开终端执行claude --help查看当前版本支持的提示词参数。如果是配置文件检查 JSON 是否可被解析python -m json.tool ~/.claude/settings.json如果解析失败说明 JSON 语法有问题修正后再启动。6.3 模型识别、529 与访问限制类错误使用过程中可能看到类似信息model is not a model this version of Claude Code recognizes客户端版本与模型名不匹配或自定义服务返回的模型名不在支持列表中。529 错误服务端负载过高通常代表瞬时过载可稍后重试或减少并发请求。组织策略错误企业账号可能通过组织策略限制 Claude Code 访问需要联系管理员确认账号权限。这类错误不一定由本地配置引起。先区分是客户端问题还是服务端问题看报错出现在启动阶段还是请求阶段再看完整日志。客户端版本问题时更新到最新版服务端过载时增加重试策略不要频繁重发。6.4 排错清单可以把以下内容作为一份可复用的排错清单检查项操作正常结果工作目录执行pwd路径为项目根目录或预期目录文件命名列出根目录文件存在AGENTS.md大写 M 和 D配置文件查看.claude/settings.jsonJSON 可解析字段名正确环境变量检查ANTHROPIC_API_KEY值不为空无多余空格版本信息执行claude --version版本符合当前使用要求日志输出查看启动日志无解析错误、无模型名报错实际对话让 Agent 复述规则能准确说出项目约束如果以上检查都通过但问题仍在建议查看官方更新日志确认当前版本是否已经支持你配置的字段和能力。有些功能在旧版本中尚不可用升级后即可解决。7. 最佳实践与扩展方向7.1 把提示词纳入版本管理AGENTS.md和.claude/settings.json都应该提交到 Git 仓库。这样提示词的变更可以像代码一样审查、回滚和追溯。团队协作时建议单独开 PR 修改提示词并在描述中说明修改动机。例如“增加禁止使用 double 存储金额的规则避免精度问题”。这比直接在群里发一段文字让每个人手动复制靠谱得多。同时不要把 API Key 或敏感信息写进仓库配置文件。项目级配置只放规则不放密钥。密钥通过环境变量或本地未跟踪文件提供。7.2 分层提示词设计提示词设计可以按照“全局基础规则 - 团队项目规则 - 模块规则 - 单次任务指令”分层。每层只关注自己的职责全局基础规则比如“使用中文回答、先列影响文件”。团队项目规则比如“统一 Result 结构、禁止物理删除”。模块规则比如“controller 层只做参数校验不写业务逻辑”。单次任务指令比如“为 OrderService 添加一个超时取消方法”。分层的好处是不会在根目录文件里堆满所有规则。规则越多Agent 越容易忽略重点。控制每个AGENTS.md的体量超过 50 行就考虑拆分或精简。7.3 与自动化流程配合项目级提示词不止影响交互式会话也能用于自动化场景。例如在 CI 流程中调用 Claude Code 做代码审查时提示词可以规定“重点检查事务边界和异常处理”。这样每次提交代码AI 审查的视角都和团队定义的一致。也可以用 Claude Code 编写项目文档、生成变更日志、补充测试用例。此时AGENTS.md中的“文档目录结构”和“测试命令”会被复用减少重复说明。7.4 扩展方向与后续学习路径从 Claude Code 的这次更新出发可以继续关注几个方向多 Agent 协作一个 Agent 负责分析一个 Agent 负责编码一个 Agent 负责审查通过系统提示词区分各自职责。模型接入通过配置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN可以尝试接入兼容 API 的服务但要注意模型名和版本兼容性。技能包Skills在 Claude Code 中配置自定义技能把常见操作封装成可复用的技能与AGENTS.md的规则形成互补。提示词评估建立一组测试用例定期验证修改提示词后 Agent 的行为是否稳定。实际项目中最值得先做的不是接入更多模型而是把项目级规则梳理清楚。先把AGENTS.md写好让 Agent 在你最熟悉的仓库里稳定工作再逐步扩展到其他项目和团队。7.5 最后留给开发者的实践建议Claude Code 支持 Agents.MD 和系统提示词修改本质上是把“AI 协作规范”从口头交流变成了项目资产。你可以在今天就开始做这三件事在个人项目根目录创建一份AGENTS.md写清技术栈、目录结构和三条最重要的编码规范。在.claude/settings.json中追加一条系统提示词要求 Agent 回答前先列出影响文件。把这两个文件提交到版本仓库然后新建一个会话让 Claude Code 复述规则确认配置生效。完成这三个步骤后再根据实际使用情况迭代提示词。你会发现AI 编程工具能否高质量工作很大程度取决于你给了它什么样的上下文。系统提示词和 Agents.MD 的意义就是把这种上下文从临时输入变成可持续维护的工程资产。