AI代理Markdown文件综合指南
但CLAUDE.md只是整个生态系统中的一个文件。还有AGENTS.md、.cursorrules、copilot-instructions.md、CLAUDE.local.md，现在还有Claude的自动内存系统。您的仓库最终可能看起来像一个用于困惑机器人的markdown博物馆。
AI编程/Vibe Coding 遇到问题需要帮助的，联系微信 ezpoda，免费咨询。
一个文件。在每次对话之前加载。这就是将无状态的AI编码助手转变为实际记住项目如何工作的方法所需的全部。
我通过艰难的方式发现了这一点。在生产代码库上使用Claude Code三个月后，我仍然在每个会话中纠正相同的错误。"不，我们使用pnpm，不是npm。""不，测试命令是make test-integration，不是pytest。""不，我们不在这里使用默认导出。"每次更正在会话结束时都会消失。
然后我创建了一个CLAUDE.md文件。40行的项目上下文。更正一夜之间停止了。
但CLAUDE.md只是整个生态系统中的一个文件。还有AGENTS.md、.cursorrules、copilot-instructions.md、CLAUDE.local.md，现在还有Claude的自动内存系统。您的仓库最终可能看起来像一个用于困惑机器人的markdown博物馆。
本指南涵盖了所有这些文件。每个文件的作用、它的位置，以及（最重要的是）您实际需要哪些。
1、问题：每个工具都想要自己的文件
如果您使用不止一个AI编码助手（而且如果您读了我的AI代理框架的诚实层级列表，您就知道为什么会这样），您可能已经注意到了混乱。Claude想要CLAUDE.md。Cursor想要.cursorrules（或.cursor/rules/）。GitHub Copilot想要.github/copilot-instructions.md。Windsurf想要.windsurf/rules。Google的Jules想要JULES.md。
所有这些文件的内容几乎完全相同。您的编码标准、您的构建命令、您的测试设置、您的架构模式。但您正在将相同的指令复制和粘贴到五个不同的文件中。
这是AGENTS.md创建要解决的碎片化问题。稍后会详细介绍。
首先，让我们了解每个文件实际做什么。
2、CLAUDE.md：开创一切的文件
CLAUDE.md是Claude Code的内存文件。将其放在项目根目录，Claude在每个会话开始时读取它。把它想象成一份为患有健忘症的新团队成员准备的简报。
它所在的位置（层次结构很重要）：
~/.claude/projects/<project>/CLAUDE.md # 全局Claude规则（所有项目）
~/.claude/projects/<project>/<repo>/CLAUDE.md # 特定于仓库
<repo>/CLAUDE.md # 项目根目录（覆盖仓库）
<repo>/src/CLAUDE.md # 子目录（覆盖根目录）
层次结构从下到上加载。企业策略首先加载，然后是您的个人偏好，然后是项目级，最后是子目录级。更具体的指令覆盖更广泛的指令。
实际上属于其中的内容：
/init命令根据您的项目结构生成一个起始文件。这是反直觉的部分：删除它生成的大部分内容。默认文件包括显而易见的内容（是的，Claude，这是一个TypeScript项目，我可以从package.json看到这一点）。CLAUDE.md中的每一行都与实际工作争夺注意力。（如果您曾经想知道为什么大多数AI代理在生产环境中失败，糟糕的上下文管理是答案的一半。）
目标：300行以下。专注于如果没有该文件Claude会出错的内容。
一个好的CLAUDE.md有四个部分：
- 项目上下文。 一行。"带有Stripe集成和Postgres的Next.js电商应用。"
- 代码风格偏好。 不是"正确格式化代码"而是"使用ES模块，首选命名导出，2空格缩进。"
- 命令。 确切字符串：
pnpm test:integration、make build-docker、npm run lint:fix。Claude逐字使用这些。 - 架构决策。 "API路由在/src/api/[resource]/route.ts中。我们使用存储库模式进行数据库访问。"
其他所有内容？将其移动到单独的文件并使用@imports。
@imports系统：
CLAUDE.md支持使用@path/to/file语法导入其他文件：
See @README.md for project overview
See @docs/api-patterns.md for API conventions
See @package.json for available npm scripts
导入可以递归（引用的文件可以引用其他文件，最多5层深度）。这解决了"一个巨大文件"的问题。保持CLAUDE.md精简，将详细指导移至单独的文件。
对于团队来说，这很强大。前端团队拥有docs/frontend-rules.md。安全团队拥有docs/security.md。CLAUDE.md只是导入它们所有。
诚实的限制： CLAUDE.md仅限Claude。如果您的团队与Claude Code一起使用Cursor或Copilot，它们不会读取此文件。这就是AGENTS.md发挥作用的地方。
3、AGENTS.md：通用标准
AGENTS.md于2025年中从Sourcegraph、OpenAI、Google、Cursor和其他公司之间的合作中诞生。它现在由Linux Foundation下的Agentic AI Foundation维护。这个提议很简单：一个文件，任何代理。
它受到Claude Code、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Aider、Zed、Warp、RooCode和不断增长的其他列表的支持。
它的工作原理：
在项目根目录放置一个AGENTS.md。它是标准Markdown，没有特殊模式，不需要YAML前言。离被编辑文件最近的AGENTS.md优先，并且明确的用户提示词覆盖所有内容。
# AGENTS.md
## Project Overview
E-commerce platform built with Next.js 14, Postgres, and Stripe.
## Build & Test
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint:fix`
## Code Standards
- Use TypeScript strict mode
- Prefer named exports over default exports
- API routes follow REST conventions in /src/api/
## Testing Requirements
- All PRs must include tests
- Use vitest for unit tests, playwright for e2e
AGENTS.md vs CLAUDE.md vs README：
它们是互补的，不是竞争的。README是给人类看的，AGENTS.md是通用代理简报，CLAUDE.md在顶部添加Claude特定指令。
我的建议： 如果您使用多个AI工具，将共享指令放在AGENTS.md中，并保留CLAUDE.md用于Claude特定功能，如@imports和/init工作流。如果您只使用Claude Code，单独使用CLAUDE.md就可以了。
4、其他内存文件（快速参考）
并非每个工具都采用了AGENTS.md，有些功能超出了AGENTS.md涵盖的范围。
.cursorrules / .cursor/rules/*.mdc： Cursor的本机格式。较新的.mdc格式支持带有激活模式（Always、Auto Attached、Agent Requested、Manual）的YAML前言。比AGENTS.md更细粒度，但仅限Cursor。Cursor也读取AGENTS.md，所以您可以同时使用两者。将共享规则放在AGENTS.md中，特定于Cursor的行为放在.cursor/rules/中。
.github/copilot-instructions.md： GitHub Copilot的指令文件。位于.github文件夹中。Copilot现在也读取AGENTS.md，所以您可能不需要两者。
.windsurfrules： Windsurf的格式。具有global_rules.md用于工作区范围指令的双重结构。Windsurf也支持AGENTS.md。
CLAUDE.local.md： 您个人的、项目特定的偏好，不会提交到git。自动添加到.gitignore。将其用于诸如您的沙箱URL、首选测试数据或个人工作流怪癖之类的内容。（您的队友不需要知道您总是使用用户名"butts123"进行测试。）
5、Claude的自动内存：自己记笔记的AI
这是最新的补充，也是最有趣的一个。Claude Code现在有一个自动内存系统，Claude在您的会话期间向自己写笔记。
它位于~/.claude/projects/<project>/memory/中：
memory/
├── MEMORY.md # Index file, loaded every session
├── debugging.md # Notes on debugging patterns
├── api-conventions.md # API design decisions
└── ...
与CLAUDE.md的关键区别：您编写CLAUDE.md，Claude编写MEMORY.md。您提供指令。Claude捕获学习内容。
只有MEMORY.md的前200行自动加载。主题文件（debugging.md等）在Claude需要时按需加载。
实用工作流：
当Claude发现有关您的项目的内容时（"哦，这个代码库使用自定义ORM包装器"），它将其保存到自动内存中。下次会话时，它已经知道了。不再重复自己。
您也可以手动触发此操作。在富有成效的会话结束时，问Claude："用您今天对我们代码库学到的内容更新您的内存文件。"学习内容会持久化。
要查看或编辑Claude保存的内容，在任何会话期间运行/memory。
诚实的限制： 自动内存仍在推出中。如果您看不到它，请在您的环境中设置CLAUDE_CODE_DISABLE_AUTO_MEMORY=0。而且由于Claude编写这些笔记，质量会有所不同。定期审查它们，就像您审查任何文档一样。
/init然后删除工作流
这是为任何新项目引导内存文件的最快方法。
- 在项目目录中运行
/init- Claude根据您的项目结构和检测到的技术栈生成一个起始CLAUDE.md - 删除您不需要的内容
第3步是大多数人出错的地方。生成的文件是一个起点，而不是成品。它通常包含不增加价值的填充内容（"这个项目使用JavaScript。"谢谢，Claude。我可以看到package.json。）
先删除的方法比从头开始写更快。您正在从一个合理的草稿向下编辑，而不是盯着一个空白文件。
初始设置后，有机地构建您的内存文件。当Claude做出错误的假设时（在我的情况下，它不断从已弃用的内部包导入），不要只纠正一次。告诉Claude："添加到我的CLAUDE.md中：总是从@company/utils-v2导入，而不是@company/utils。"该指令在未来的会话中持久存在。
每隔几周，请Claude审查和优化您的CLAUDE.md。指令会累积，有些变得冗余，其他指令会冲突。快速清理使事情保持敏锐。
6、我实际使用的设置
在从文档问答系统到不断幻觉公司政策的内部代理等项目上尝试了所有这些之后，这就是我确定的内容：
AGENTS.md在项目根目录中，包含共享指令（构建命令、代码标准、测试要求）。这涵盖了我的团队使用的任何AI工具。
CLAUDE.md带有@imports用于Claude特定行为。保持精简，100行以下，主要指向docs/文件。
CLAUDE.local.md用于我的个人怪癖（我首选的测试数据、沙箱URL、我不断使用的快捷命令）。
自动内存已启用。我让Claude自己记笔记，每月审查一次。
其他所有内容（.cursorrules、copilot-instructions.md）我已用指向AGENTS.md的符号链接替换。一个真正的来源。
# Symlink setup for multi-tool consistency
ln -sfn AGENTS.md .github/copilot-instructions.md
mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc
（这优雅吗？不。它是否防止跨工具的指令漂移？是的。）
7、快速决策指南
六个月前，五个不同的工具需要五个不同的文件。今天，大多数工具读取AGENTS.md。碎片化问题没有解决，但正在改善。
我的赌注：AGENTS.md成为README.md那样的标准方式。不是因为它在技术上更优越，而是因为Linux Foundation支持和广泛的工具支持创造了足够的引力将生态系统拉到一起。CLAUDE.md、.cursorrules和其他东西将因工具特定功能而存在，但共享上下文将存在于一个地方。
在那之前，符号链接黑客技术工作得很好。而且坦白说，拥有一个内存文件已经让您领先于大多数开发者。我写了整个关于使用LangGraph构建AI代理的指南，人们遇到的头号问题不是框架。而是Claude在会话之间忘记了他们的项目设置。每个会话的"Claude，我们使用pnpm"和"Claude已经知道"之间的区别是工具和队友的区别。
原文链接: The Complete Guide to AI Agent Memory Files (CLAUDE.md, AGENTS.md, and Beyond)
汇智网翻译整理，转载请标明出处
