AGENTS.md 和 CLAUDE.md 本质上是 Context Engineering（上下文工程）的核心实现，用于为 AI 编程代理提供稳定、结构化的项目上下文，而非传统 Prompt Engineering 中单次交互的临时指令。二者均属于 Harness Engineering（驾驭工程） 的组成部分，通过系统化约束提升 AI 代理的工程可靠性，核心价值在于将“临时提示”转化为“持久化项目规则”。传统 Prompt Engineering 仅优化单次交互，而 AGENTS.md/CLAUDE.md 解决了多轮会话中上下文碎片化、规则不一致的问题。

一、本质定位：从 Prompt 到 Context 的范式升级

1. 传统 Prompt Engineering 的局限性

• 单次交互导向：仅针对当前任务优化指令措辞，无法跨会话保留项目规则。每次新会话需重复说明技术栈、代码规范等基础信息，导致效率低下。
• 上下文易丢失：对话历史超出模型窗口后，关键规则会被截断，AI 可能“失忆”而违反项目约定（如误改受保护文件）。

2. Context Engineering 的突破

• 持久化项目简报：AGENTS.md/CLAUDE.md 作为项目级上下文文件，在 AI 启动时自动加载，确保所有会话共享统一规则（如构建命令、代码风格）。
• 人机协作标准化：将原本依赖口头沟通的隐性规则（如“不要修改 migration 文件”）显性化，减少沟通成本与歧义。

二、核心差异：AGENTS.md 与 CLAUDE.md 的关键区别

1. 标准归属与兼容性

• AGENTS.md：

  • 由 Linux 基金会下属 Agentic AI Foundation 托管的开放标准，支持 Codex、GitHub Copilot、Cursor 等 25+ 工具，实现“一份文件多平台通用”。
  • 优先级规则：全局配置（~/.codex/AGENTS.md）→ 项目根目录 → 子目录级 AGENTS.md，子目录级规则覆盖上级。

• CLAUDE.md：

  • Anthropic 为 Claude Code 设计的私有格式，仅原生适配 Claude Code，但可通过 @AGENTS.md 导入兼容开放标准。
  • 内容倾向：更适合详细解释性背景（如架构设计原因），但需警惕文件过长导致上下文冗余。

2. 设计哲学差异

• AGENTS.md 强调分层与简洁：
  推崇 “精简规则 + Skills + Hooks” 分层体系，仅包含 AI 无法自主推断的关键约束（如构建命令、禁止修改的目录），避免信息过载。
• CLAUDE.md 侧重解释性上下文：
  允许更详细的项目背景说明（如技术选型原因），适合需要深度理解“为什么”的复杂任务。

三、最佳实践：高效配置的三大原则

1. 内容聚焦：只写 AI 推断不出的信息

• 必须包含：
  • 构建与测试命令（如 pnpm run typecheck），避免 AI 猜测流程。
  • 红线约束（如“禁止修改 migration 文件”“API 修改需同步类型定义”），明确安全边界。
  • 代码风格细节（如“文件名用 kebab-case”“禁用 any 类型”），确保输出一致性。
• 必须避免：
  • 一次性调试日志、历史会议记录等临时性内容。
  • 超过 200 行的冗长描述，高信号密度比信息量更重要。

2. 分层管理：就近原则与 override 机制

• 子目录级覆盖：在模块目录中放置独立 AGENTS.md，定义局部规则（如前端子项目禁用特定库）。
• 动态覆盖：使用 AGENTS.override.md 临时替换规则（如紧急修复时放宽格式检查），无需修改原文件。

3. 与 Prompt Engineering 协同

• Prompt 负责单次任务：针对具体需求设计指令（如“用 TypeScript 重写函数”）。
• AGENTS.md/CLAUDE.md 提供基础框架：确保所有 Prompt 在统一规则下执行（如强制类型检查）。
• 关键互补：Prompt 优化“如何做”，上下文文件定义“什么不能做”，二者结合才能规避 AI 的过度设计或越界行为。

四、与 Prompt Engineering 的层次关系

1. 技术演进路径

• Prompt Engineering：单次交互优化（“如何问得更准”）。
• Context Engineering：构建跨会话稳定上下文（AGENTS.md/CLAUDE.md 的核心价值）。
• Harness Engineering：系统级约束，整合上下文、工具链、验证规则，形成可自迭代的工程系统。

2. 实际影响

• 无 AGENTS.md/CLAUDE.md：AI 退化为“通用助手”，需反复交代项目细节，错误率显著上升。
• 合理配置后：AI 表现为“项目专属工程师”，能自主执行验证、遵守约束，调试时间减少 30% 以上。

关键结论：AGENTS.md 和 CLAUDE.md 并非 Prompt 的替代品，而是将零散提示升维为可持续演进的项目规则体系。其价值不在于文件本身，而在于推动开发者从“临时调教 AI”转向“系统化设计人机协作流程”。