让AI代理像开发者一样入职

当新开发者加入项目时，有人会带他们了解惯例——代码存放位置、团队规则、需要运行的命令。AI代理却没有这些待遇。每次会话开始时它们没有上下文，如果找不到指令，它们不会询问，而是直接猜测。最近的调查显示，大多数工程师现在同时使用2-4个AI工具。如果你有超过几个开发者，无论你是否有意为之，你的仓库实际上已经是一个多代理环境。所以问题不是要不要为代理写入职文档——而是写哪些，因为它们会读取不同的文件。 --- **第一级——强制要求。** 两个文件： - **AGENTS.md** —— 跨工具标准，自2025年12月起由Linux基金会托管，被Codex、Copilot的编程代理、Cursor、Windsurf以及大约二十多个其他工具原生读取。内容：技术栈、命令、硬性规则、指向更详细文档的链接。保持在约200行以内。 - **CLAUDE.md** —— 单独存在是因为Claude Code（最新调查中使用最多的代理）是唯一一个不读取AGENTS.md的主流工具。Anthropic推荐的桥接方案：第一行为 '@AGENTS.md'（Claude Code在会话启动时展开该导入），下方添加Claude特定说明。 因此强制设置是两个文件，其中一个是指针。 如果你有值得传授的多步骤工作流（发布流程、脚手架模板），添加技能：SKILL.md格式在Anthropic开放规范后已跨供应商使用，现在相同的文件夹可在Claude Code、Codex、VS Code和Gemini CLI中加载。唯一的小问题：Claude Code在 .claude/skills/ 中查找，Codex在 .agents/skills/ 中查找——将两者互相镜像即可。 **第二级——如果这些工具在组织内实际使用则执行。** Copilot和Cursor都读取AGENTS.md，因此这一级带来的是优化而非覆盖： - **Copilot** —— .github/copilot-instructions.md 用于编辑器内聊天；.github/instructions/*.instructions.md 用于 applyTo 作用域规则。 - **Cursor** —— .cursor/rules：按glob自动附加规则类型是其真正特性。约定仅在适用处加载。 没有Copilot席位，没有Cursor用户→完全跳过这一级。 **第三级——锦上添花。** - **MCP服务器** —— 如果你有机可读的资产（令牌、注册表、模式），代理可以查询实时数据，而不是搜索过时的文本。 - **Gemini CLI** —— 默认读取GEMINI.md，但签入的 .gemini/settings.json 可以将 context.fileName 指向 AGENTS.md（配置优于另一个markdown文件）。 - **可移植的系统提示文档** —— 用于原始API调用者和评估框架；从AGENTS.md派生。 --- 真正重要的部分：不要手动维护这些文件。它们会漂移，错误的指令文件比没有更糟糕，因为代理信任它而从不复核。从一个真实源生成所有表面文件，使用愚蠢的确定性模板脚本（构建中不涉及LLM），这样重新运行时字节稳定——CI重新生成所有内容并在任何差异时失败。 不过，这整个事情都是偶然的复杂性。现在有两个真正的标准：用于上下文的AGENTS.md，用于工作流的SKILL.md。大多数针对特定工具的文件之所以存在，只是因为供应商在达成一致之前各自发布了文件名。