> ## Content Index > Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt > Use this file to discover other available public pages before exploring further. # AI代理Markdown文件综合指南 - URL: https://www.hubwiz.com/blog/ai-agent-markdown-files-comprehensive-guide/ - Published: 2026-03-03T11:54:06.000Z - Updated: 2026-03-03T11:54:06.000Z - Description: 但CLAUDE.md只是整个生态系统中的一个文件。还有AGENTS.md、.cursorrules、copilot-instructions.md、CLAUDE.local.md，现在还有Claude的自动内存系统。您的仓库最终可能看起来像一个用于困惑机器人的markdown博物馆。 - Author: admin - Tags: AGENT, #Import 2026-10-14 14:41 一个文件。在每次对话之前加载。这就是将无状态的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代理框架的诚实层级列表](https://claude.ai/your-article-slug-agent-frameworks?ref=hubwiz.com)，您就知道为什么会这样），您可能已经注意到了混乱。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//CLAUDE.md # 全局Claude规则（所有项目） ~/.claude/projects///CLAUDE.md # 特定于仓库 /CLAUDE.md # 项目根目录（覆盖仓库） /src/CLAUDE.md # 子目录（覆盖根目录） ``` 层次结构从下到上加载。企业策略首先加载，然后是您的个人偏好，然后是项目级，最后是子目录级。更具体的指令覆盖更广泛的指令。 **实际上属于其中的内容：** /init命令根据您的项目结构生成一个起始文件。这是反直觉的部分：**删除它生成的大部分内容**。默认文件包括显而易见的内容（是的，Claude，这是一个TypeScript项目，我可以从package.json看到这一点）。CLAUDE.md中的每一行都与实际工作争夺注意力。（如果您曾经想知道[为什么大多数AI代理在生产环境中失败](https://medium.com/p/f6f604bcd075?ref=hubwiz.com)，糟糕的上下文管理是答案的一半。） 目标：300行以下。专注于如果没有该文件Claude会出错的内容。 一个好的CLAUDE.md有四个部分： 1. **项目上下文。** 一行。"带有Stripe集成和Postgres的Next.js电商应用。" 2. **代码风格偏好。** 不是"正确格式化代码"而是"使用ES模块，首选命名导出，2空格缩进。" 3. **命令。** 确切字符串：`pnpm test:integration`、`make build-docker`、`npm run lint:fix`。Claude逐字使用这些。 4. **架构决策。** "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和[不断增长的其他列表](https://agents.md/?ref=hubwiz.com)的支持。 **它的工作原理：** 在项目根目录放置一个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//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然后删除工作流 这是为任何新项目引导内存文件的最快方法。 1. 在项目目录中运行`/init`\- Claude根据您的项目结构和检测到的技术栈生成一个起始CLAUDE.md 2. **删除您不需要的内容** 第3步是大多数人出错的地方。生成的文件是一个起点，而不是成品。它通常包含不增加价值的填充内容（"这个项目使用JavaScript。"谢谢，Claude。我可以看到package.json。） 先删除的方法比从头开始写更快。您正在从一个合理的草稿向下编辑，而不是盯着一个空白文件。 初始设置后，有机地构建您的内存文件。当Claude做出错误的假设时（在我的情况下，它不断从已弃用的内部包导入），不要只纠正一次。告诉Claude："添加到我的CLAUDE.md中：总是从@company/utils-v2导入，而不是@company/utils。"该指令在未来的会话中持久存在。 每隔几周，请Claude审查和优化您的CLAUDE.md。指令会累积，有些变得冗余，其他指令会冲突。快速清理使事情保持敏锐。 ## 6、我实际使用的设置 在从文档问答系统到[不断幻觉公司政策的内部代理](https://medium.com/p/f6f604bcd075?ref=hubwiz.com)等项目上尝试了所有这些之后，这就是我确定的内容： **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代理](https://medium.com/p/c87f376c84b2?ref=hubwiz.com)的指南，人们遇到的头号问题不是框架。而是Claude在会话之间忘记了他们的项目设置。每个会话的"Claude，我们使用pnpm"和"Claude已经知道"之间的区别是工具和队友的区别。 --- 原文链接: [The Complete Guide to AI Agent Memory Files (CLAUDE.md, AGENTS.md, and Beyond)](https://medium.com/data-science-collective/the-complete-guide-to-ai-agent-memory-files-claude-md-agents-md-and-beyond-49ea0df5c5a9?ref=hubwiz.com) 汇智网翻译整理，转载请标明出处