给 AI 写的开发手册：如何在 GitHub 项目中优雅地配置 AGENTS.md
随着 Cursor、Claude Code、Windsurf 以及 OpenClaw 等 AI Coding Agent 深度嵌入日常开发工作流，软件开发正在经历从 “人类编写代码” 到 “人类定义规则，Agent 协作编码” 的转变（Agentic Engineering）。
我们在项目中往往会编写 README.md 面向人类开发者，但很多团队忽视了为 AI Agent 提供一套上下文感知与行为治理规范（Harness Guidelines）。这就是 AGENTS.md（或 AGENT.md / CLAW.md）存在的意义——它是写给 AI Agent 看的“项目运维与开发指南”。
本文以实际项目架构为例，聊聊为什么需要 AGENTS.md 以及如何为你的开源或商业项目定制一份高效的 Agent 治理规范。
一、 为什么传统的 README.md 不够用？
人类开发者阅读 README.md 时，拥有强大的泛化能力和隐式背景知识；但 AI Agent 在读取代码库时，是以 Token 上下文的形式载入信息的。
传统的 README 往往面临以下痛点：
- 信息密度不匹配：包含大量面向用户的推广语言、演示 GIF 或过于冗长的安装介绍，浪费 Agent 有限的 Context Window。
- 缺少隐式约束：Agent 无法从普通 README 中感知“不要在组件里直接写 Raw SQL”、“修改 Schema 后必须生成 Migration”等团队内部约定的代码禁区。
- 缺乏验证门禁：Agent 在修改完代码后，往往不知道调用什么 CLI 命令来进行类型检查（Typecheck）和单元测试，导致提交带有隐式 Bug 的代码。