在本地开发环境中使用 Claude Code 时，许多开发者发现尽管已经创建了 AGENTS.md 文件，但 CLI 工具并未按预期加载自定义指令，或者启动时报错退出。这通常不是工具本身的故障，而是由于文件路径、权限设置或环境变量配置不当所致。本文将针对这一常见问题，提供一套系统化的排查与修复方案，帮助你快速恢复 Claude Code 的高级功能。
检查文件位置与命名规范
Claude Code 对 AGENTS.md 的识别依赖于严格的路径规则。首先，请确认该文件是否位于当前工作目录的根目录下，或者位于项目根目录中。如果文件嵌套在子文件夹中且未被正确引用，工具将无法自动发现它。此外，文件名必须严格为 AGENTS.md（区分大小写），任何拼写错误如 agents.md 或 AGENT.md 都会导致加载失败。
对于多项目用户，建议将全局默认指令放置在用户主目录下的 .claude/AGENTS.md 路径中。这样，无论你在哪个项目目录下启动 Claude Code，它都会优先读取这个全局配置文件。若你希望特定项目拥有独立的行为准则，则必须在该项目根目录创建同名文件，以确保优先级覆盖全局设置。
验证文件格式与内容语法
即使文件位置和名称正确，内容格式的错误也会导致解析失败。AGENTS.md 本质上是一个 Markdown 文件，因此请确保其编码为 UTF-8，避免使用特殊的不可见字符。在编写内容时，建议使用清晰的标题层级和列表结构，以便模型更好地理解指令权重。
常见的错误包括在文件头部混入了非 Markdown 格式的乱码，或者使用了不支持的特殊符号。你可以尝试创建一个最小化的测试文件，仅包含一行简单的指令，例如："你是一个专业的 Python 助手，请始终先解释代码逻辑再给出实现。" 然后重新启动 Claude Code。如果此时工具能正常响应并遵循指令，说明之前的复杂内容可能存在语法冲突或过长导致解析超时。
排查环境变量与权限问题
在某些操作系统（特别是 macOS 和 Linux）中，文件权限可能阻止了 Claude Code 读取 AGENTS.md。请检查文件的读写权限，确保当前用户拥有对该文件的读取权。你可以使用命令 ls -l AGENTS.md 查看权限状态，必要时使用 chmod 644 AGENTS.md 进行调整。
此外，如果你通过脚本或集成开发环境（IDE）插件调用 Claude Code，需确认环境变量 CLAUDE_CODE_DISABLE_AGENT 未被意外设置为 true。某些调试模式可能会禁用 Agent 行为，从而导致 AGENTS.md 被忽略。最后，检查终端日志输出，寻找类似 "Failed to load AGENTS.md" 的具体错误信息，这能帮助你精准定位是网络请求失败、API 密钥无效还是本地文件解析错误。通过以上步骤逐一排除，绝大多数 AGENTS.md 无法运行的问题都能得到解决。
本文链接：https://jianli-bf.com.cn/doubao/claude-code-agents-md-pzbdhwfyx-pcyxfzn/
