如果你最近同时在用两三个 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.md | AGENTS.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 或 Windows（Windows 下建议使用 PowerShell 或 Windows Terminal）。
- Node.js：LTS 版本，具体以官方文档要求为准。
- 包管理器：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 用户服务 API，Express + 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 install |
| AI 不读取 AGENTS.md | Claude 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.md，Claude Code 专属内容放在CLAUDE.md，Wiki 里只保留文档链接。宁可文件里写“详见 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 目录的构建方式，以及团队层面的提示词模板管理。
