如果你最近同时在用两三个 AI 编程工具大概率经历过一个尴尬场景在 Claude Code 里反复交代好的项目规范、构建命令、代码风格换到另一个工具后它一概不知道只能重新讲一遍。更麻烦的是每个工具都有自己的“记忆文件”Claude Code 认CLAUDE.md别的工具可能认别的格式项目知识被拆散在不同地方。AGENTS.md就是为了解决这个痛点而出现的项目级约定文件。它把“这个项目怎么构建、怎么测试、有什么禁忌”写进项目根目录的一个 Markdown 文件让 AI 代理启动时自动读取。Claude Code 正在逐步支持AGENTS.md并进一步开放系统提示词修改能力这件事的真正的价值不是多了一个配置项而是让提示词资产开始标准化、可复用、可交给团队管理。这篇文章不会停留在新闻解读层面。我会从开发效率出发讲清楚AGENTS.md和系统提示词修改到底改变了什么然后给出一份可以直接照做的写法、配置、验证方式和排错清单。无论你已经在用 Claude Code还是刚从 VS Code 插件、桌面端或 CLI 开始接触都可以通过这篇文章把项目上下文管理这件事一次做对。1. 为什么 AGENTS.md 比一次性提示词更重要先解释一个高频误区很多人觉得给 AI 编程工具交代背景只要在对话框里写一段“你现在是一个资深工程师请按照以下规范开发……”就够了。这在单次会话里确实有效但换一个会话、换一个开发者、换一台机器这段提示词就消失了。AGENTS.md的出现是把“一次性对话里的项目背景”变成“项目仓库里的持久化文件”。它解决的问题非常具体第一上下文不再靠记忆。AI 编程工具每次启动时自动读取项目根目录的AGENTS.md相当于把整个项目的“操作手册”装进了模型上下文。开发者不需要每次会话都重新介绍项目。第二团队可以共同维护。把项目说明放在仓库里团队成员都能 review、更新而不是某个人私藏一段提示词。新成员接手项目时AI 工具也能读取同一份说明降低交接成本。第三跨工具复用。AGENTS.md正在成为多个 AI 编程工具共同认可的约定。如果你今天在 Claude Code 里维护好了一份AGENTS.md未来切到其他支持该约定的工具时这份文件仍然有效不需要重写。这里真正容易踩坑的地方是很多人会把AGENTS.md写成“给 AI 的一句话简介”比如“这是一个电商项目”。这种内容几乎没有价值。真正有效的AGENTS.md应该像一份给新同事看的项目交接文档包含可执行的命令、明确的目录结构、必须遵守的规范和安全边界。2. CLAUDE.md 与 AGENTS.md有什么关系有什么区别Claude Code 之前已经有自己的约定文件机制CLAUDE.md。它分为全局配置和项目级配置Claude Code 启动时会读取这些文件把内容附加到对话上下文中。很多老用户已经用CLAUDE.md管理项目规范所以当AGENTS.md出现时一个自然的问题是两者会不会冲突从设计目标看两者解决的问题类似但定位不同。可以参考下面这张表对比项CLAUDE.mdAGENTS.md诞生背景Anthropic Claude Code 专用约定面向多工具的跨平台项目约定存放位置项目根目录或~/.claude/全局目录通常放在项目根目录自动读取Claude Code 启动时读取支持该约定的工具启动时读取通用性较低绑定 Claude Code较高适合多工具场景内容倾向可包含 Claude 特有指令、工具权限、Skill 说明更通用的项目说明、构建命令、编码规范当两者同时存在时不同版本的 Claude Code 可能有不同处理策略。从社区讨论来看更稳妥的理解是CLAUDE.md是 Claude Code 的第一优先上下文AGENTS.md是补充参考如果两者内容冲突通常以CLAUDE.md为准。这个细节依赖具体版本建议你在升级后通过日志或让 AI 复述规则来确认实际行为。我的建议是不要同时维护两份内容重复的文件。如果团队工具链相对固定可以在CLAUDE.md中写 Claude 特有配置在AGENTS.md中写通用项目说明并通过引用方式避免重复。例如AGENTS.md负责项目概览和构建命令CLAUDE.md只补充工具权限、网络访问限制等专属内容。3. 系统提示词修改从“黑盒”到“可配置”“系统提示词修改”是标题里另一个关键能力。要理解它先得明白系统提示词在 Claude Code 里扮演什么角色。每一次你向 Claude Code 提问模型并不是只看到你输入的那句话。它的上下文里还有一段系统级提示词这段提示词定义了模型的基础行为它是什么工具、能调用哪些能力、遇到不确定时该怎么做、输出时应该遵守什么格式。这段内容通常由 Anthropic 预设普通用户接触不到。Claude Code 开放系统提示词修改意味着你可以在这段基础指令上追加自己的规则。典型的追加内容包括要求模型始终使用中文回复指定必须使用某个测试框架禁止运行删除类命令除非用户明确确认要求生成代码时附带单元测试规定错误处理方式和日志输出格式。这里需要特别提醒官方开放的能力通常是“追加”而不是“整体替换”。直接覆盖整套系统提示词非常危险因为默认提示词中包含安全约束、工具调用规范和权限边界一旦删掉模型可能在某些场景下表现出不符合预期的行为。正确的姿势是只在原有基础上追加项目约束。从工程效率来看系统提示词修改的价值在于它把团队的“开发纪律”从口头约定变成了模型每次任务都会遵守的硬约束。比如你希望提交代码前必须先跑测试这条规则如果只写在文档里AI 不一定记得写入系统提示词后它会在每次任务中强制执行。4. 环境准备与前置条件开始实操之前先确认环境。Claude Code 是终端运行的工具通常通过 npm 安装因此需要 Node.js 环境。不同版本对 Node.js 版本要求可能不同建议使用当前 LTS 版本。环境清单如下操作系统macOS、Linux 或 WindowsWindows 下建议使用 PowerShell 或 Windows Terminal。Node.jsLTS 版本具体以官方文档要求为准。包管理器npm 或 pnpm/yarn。Claude Code CLI建议升级到最近版本因为AGENTS.md和系统提示词修改属于新特性旧版本可能不支持。认证Anthropic API Key 或 Claude 订阅账号。组织策略可能限制某些账号使用 Claude Code如果遇到提示your organization has disabled Claude subscription access需要联系项目管理员处理。安装命令通常是npm install -g anthropic-ai/claude-code安装完成后执行claude --version如果能输出版本号说明安装成功。如果提示命令不存在优先检查 npm 全局 bin 目录是否在PATH中而不是急着重新安装。本文后面所有示例都假设你使用的 Claude Code 版本已经支持AGENTS.md。如果你安装的版本还没有该功能可以使用CLAUDE.md配合系统提示词追加来获得等效效果区别只是文件名不同。5. 编写 AGENTS.md完整示例与结构拆解我以一个常见的 Node.js TypeScript 项目为例演示一份可落地的AGENTS.md。这个项目是典型的后端服务包含build、test、lint三个核心脚本使用 Express 框架数据库通过 Prisma 管理。首先在项目根目录创建AGENTS.md# AGENTS.md ## Project Overview 这是一个基于 Express TypeScript 的用户服务 API提供用户注册、登录、资料查询接口。数据库使用 PostgreSQL通过 Prisma ORM 访问。 ## Development Commands - 安装依赖npm install - 启动开发服务npm run dev - 构建生产版本npm run build - 运行单元测试npm test - 运行代码检查npm run lint ## Project Structure - src/routes路由定义按业务模块拆分 - src/services业务逻辑层 - src/repositories数据库访问层 - prisma/schema.prisma数据库模型定义 - tests单元测试与集成测试目录 ## Coding Conventions 1. 函数命名使用 camelCase常量使用 UPPER_SNAKE_CASE 2. 接口返回统一使用 { code, data, message } 结构 3. 数据库查询必须通过 repository 层禁止在路由层直接调用 Prisma 4. 新增接口时需要同时补充测试用例 5. 错误处理统一使用自定义 ApiError禁止在 controller 中直接抛出原始异常 ## Workflow Constraints - 修改数据库模型后必须执行 npx prisma generate 并提交迁移文件 - 提交代码前必须通过 npm run lint 和 npm test - 禁止将 .env 文件提交到版本库 - 删除生产数据前必须向用户确认这段文件的核心逻辑是每一条规则都必须可执行、可验证。比如“禁止在路由层直接调用 Prisma”比“要注意代码分层”更有约束力提交代码前必须通过 npm test比“保证代码质量”更明确。再对比一下CLAUDE.md。如果你已经在用 Claude Code文件内容可能是这样的# CLAUDE.md ## Project 用户服务 APIExpress TypeScript Prisma。 ## Commands - npm run dev启动开发服务 - npm test运行测试 - npm run lint代码检查 ## Rules - 不在路由层直接访问数据库 - 修改 Prisma 模型后需要执行 generate - 提交前必须通过测试两相比较AGENTS.md更像是“团队新同事入职手册”而CLAUDE.md是 Claude Code 的专属操作手册。理想情况下把通用项目知识放在AGENTS.md把 Claude 特有的工具权限和 Skill 说明放在CLAUDE.md。完成AGENTS.md后不要忘记提交到版本库。它和README.md一样应该被团队共同维护而不是成为某个人的私人文件。6. 修改系统提示词配置示例与代码实现完成了AGENTS.md下一步是体验系统提示词修改。Claude Code 提供了多种方式向系统提示词追加内容下面给出三种常用方法。6.1 通过设置文件追加系统提示词Claude Code 的全局设置文件通常位于用户目录下的.claude文件夹中文件名可能是settings.json。如果你本地没有这个文件可以先创建对应目录。在设置文件中追加appendSystemPrompt字段{ appendSystemPrompt: 请始终使用中文回复。在运行任何可能删除文件的命令前必须先向用户确认并列出将被删除的文件列表。 }这种方式的优点是持久生效适合团队统一规范。缺点是需要修改全局文件不同开发者之间的同步需要额外管理。6.2 通过启动参数追加系统提示词如果你只是想在当前会话中临时添加约束可以使用启动参数。在终端进入项目目录后执行claude --append-system-prompt 请始终使用中文回复。在运行任何可能删除文件的命令前必须先向用户确认。这种方式适合临时任务不会污染全局配置。注意参数名在不同版本中可能有差异可以用claude --help查看当前版本支持的参数。6.3 通过项目的 CLAUDE.md 向上下文注入内容对于已经使用 Claude Code 的用户CLAUDE.md本质上也是一种“向系统提示词追加内容”的机制。我们可以把项目规范写进CLAUDE.md并注明这些内容会被自动注入## Explicit Constraints - 所有回复默认使用中文 - 在删除或覆盖文件前必须输出将要执行的操作列表供用户确认 - 生成新路由时必须同步生成对应的测试文件这种方式和settings.json的区别在于CLAUDE.md随项目仓库走不同项目可以有不同的规则settings.json是全局的对所有项目生效。在实际项目中推荐的分层策略是AGENTS.md存放通用项目说明、构建命令、编码规范CLAUDE.md存放 Claude Code 专属权限、工具配置、任务执行规则settings.json或启动参数存放跨项目通用的个人偏好和团队纪律。7. 运行验证与效果检查配置写完后不能只停留在“文件存在”层面必须验证 Claude Code 是否真的读取到了这些内容。推荐按下面几步操作。7.1 验证 AGENTS.md 被读取在项目根目录启动 Claude Code输入一个依赖项目上下文才能回答的问题claude -p 根据 AGENTS.md 的说明这个项目的测试命令是什么如果 AI 回答的是npm test或包含你写在文件中的命令说明AGENTS.md已经被成功读取。如果 AI 说“我不知道”或者给出了项目无关的回答先检查文件是否在项目根目录以及 Claude Code 版本是否支持该特性。7.2 验证系统提示词追加生效先启动一个交互会话再直接询问 你当前需要遵守哪些额外规则请列出我在设置文件中追加的内容。如果 AI 能复述出你追加的中文回复或删除确认规则说明系统提示词修改已经生效。如果它完全不知道检查settings.json路径是否正确以及字段名是否与当前版本匹配。7.3 用行为测试替代口头验证更可靠的验证方式是行为测试。比如你追加了“删除文件前必须确认”那么可以在测试目录里建一个临时文件要求 AI 删除它观察 AI 是否会先列出删除计划并征求确认。口头复述有时会有偏差行为测试才是最终标准。touch tmp-delete-test.txt claude 请删除项目根目录的 tmp-delete-test.txt预期结果是 AI 先提示将要删除的文件路径并询问是否继续而不是直接执行删除。如果直接删除成功说明追加规则没有被正确加载需要检查配置。8. 常见问题与排查思路问题现象可能原因排查方式解决方案启动 Claude Code 时命令不存在npm 全局 bin 目录不在 PATH 中执行node -v、npm -v再执行which claude将 npm 全局目录加入 PATH或重新执行 npm installAI 不读取 AGENTS.mdClaude Code 版本过旧执行claude --version查看版本升级 Claude Code 到最新版本CLAUDE.md 和 AGENTS.md 同时存在导致规则冲突两份文件内容重复或矛盾让 AI 复述当前读取到的规则对比两份文件确定优先级避免重复维护同一份规范追加系统提示词后 AI 行为异常覆盖或替换了默认安全指令恢复默认配置改用追加方式只追加项目约束不修改核心系统提示词组织账号提示无法访问 Claude Code组织策略限制订阅使用联系项目管理员确认权限使用个人账号或让管理员开放 Claude Code 使用权限修改 settings.json 后不生效文件路径错误或字段名不匹配确认配置文件位置执行claude --help查看参数按当前版本文档调整字段名提示 “model not recognized”配置了当前版本不支持的模型标识查看官方支持模型列表修改模型配置或升级版本如果问题一时无法定位建议直接执行claude --help和claude --version把输出与官方文档对照多数 CLI 工具问题都能从这两条命令里找到线索。9. 最佳实践与工程建议AGENTS.md和系统提示词修改看起来只是两个配置文件但它们本质上属于团队工程规范的一部分。从实际项目经验来看有几个点值得特别注意。第一单一事实来源。不要同时维护AGENTS.md、CLAUDE.md、团队 Wiki 三份内容重叠的文档。我的建议是通用项目规范放在AGENTS.mdClaude Code 专属内容放在CLAUDE.mdWiki 里只保留文档链接。宁可文件里写“详见 AGENTS.md”也不要复制粘贴。第二AGENTS.md 要像代码一样被 review。它会影响 AI 的每一个操作所以内容修改应该走代码审查流程。尤其要警惕外部贡献者在 PR 中偷偷修改AGENTS.md诱导 AI 执行恶意命令。这是提示词注入攻击的一种形态团队应该在 CI 中增加对AGENTS.md变更的审查。第三命令必须可执行。不要写“运行测试”这种模糊表述要写npm test。AI 编程工具的优势在于能执行命令所以你的文件里应该给出生效命令而不是描述性文字。第四敏感信息不要写入 AGENTS.md。AI 可能把文件内容复述到对话中如果文件中包含密钥、内网地址、数据库连接信息存在泄露风险。数据库密码等敏感信息应该通过环境变量管理而不是写进项目说明书。第五系统提示词尽量用追加不要整体替换。默认系统提示词包含安全边界覆盖它们很可能让工具在某些场景下出现不可控行为。如果确实需要测试自定义系统提示词先在一个隔离的测试项目里验证不要直接在生产仓库中尝试。第六配合 Skill 使用。Claude Code 的 Skill 机制可以把专业技能打包成目录结构每个 Skill 包含描述文件和调用说明。AGENTS.md负责项目级上下文Skill 负责可复用的专业能力两者结合可以实现“项目知道自己在做什么AI 知道该怎么调用能力”的效果。10. 总结下一步建议Claude Code 支持AGENTS.md与系统提示词修改说明 AI 编程助手正在从“对话工具”走向“项目级协作工具”。AGENTS.md解决的是项目知识的标准化和复用系统提示词修改解决的是行为约束的持久化。对团队来说这两件事真正带来的是提示词资产沉淀项目越复杂沉淀下来的规范越有价值。如果你现在只做一件事我的建议是打开项目根目录把 README 里散落的“如何构建、如何测试、架构说明、代码规范”抽出来整理成一份AGENTS.md提交到版本库。然后升级 Claude Code在项目里跑一次“测试命令是什么”的验证。完成这一步你就已经比大多数停留在“对话式编程”的开发者更接近下一代 AI 工作流。后续可以继续研究CLAUDE.md与AGENTS.md的优先级细节、Skill 目录的构建方式以及团队层面的提示词模板管理。