AGENTS.md：让 AI 读懂你的项目

为什么 AI 总是给出"差不多但不对"的代码？

你有没有遇到过这样的情况：向 AI 编程助手提问，它的回答技术上正确，但风格完全不像你的项目——用了 qDebug() 而你的团队统一用 USE_LOG_XXX，写了裸指针而你们规定用智能指针，或者生成的 QML 文件没有 pragma ComponentBehavior: Bound？

这不是 AI 不够聪明，而是它缺乏项目上下文。AI 每次会话都从零开始，它不知道你的技术栈、命名规范、架构约定，甚至不知道该用 C++20 还是 C++11。

AGENTS.md 就是为了解决这个问题而生的。

---

什么是 AGENTS.md？

AGENTS.md 是一个放置在项目根目录的普通 Markdown 文件，专门写给 AI 编程助手读取的"项目说明书"。

当 AI 工具（GitHub Copilot、Claude、Cursor 等）进入你的工作空间时，它会自动检索根目录下的这个文件，将其内容注入到自身的上下文中，从此你的项目规范就成了 AI 的"内置知识"。

你可以把它理解为：给新来的 AI 员工写的入职手册，只不过这个员工每次重启都会忘记一切，所以手册必须始终在场。

类似的文件还有 .cursorrules（Cursor 专用）、.github/copilot-instructions.md（GitHub Copilot 专用），而 AGENTS.md 因命名更通用、语义更明确，正在成为多工具兼容的事实标准。

---

它能做什么？

一份写得好的 AGENTS.md 能让 AI 做到：

没有 AGENTS.md	有 AGENTS.md
生成 qDebug()	使用项目约定的 USE_LOG_XXX 宏
随意选择 Qt 5 / Qt 6 API	明确使用 Qt 6.8 特性
用 SIGNAL()/SLOT() 宏连接信号	使用函数指针语法
忘记加 pragma ComponentBehavior: Bound	每个 QML 文件顶部自动添加
在 QML 里硬编码颜色 #1e1e2e	引用 GlobalSet.qml 中的颜色常量
在模型层直接写 SQL	提示应封装到 Database/ 目录

简言之，AGENTS.md 将团队共识转化为 AI 的行为约束。

---

核心原理

理解 AGENTS.md 的工作原理，有助于写出真正有效的内容。

上下文窗口注入

现代大语言模型通过"上下文窗口"理解任务。AI 工具在处理你的问题之前，会将 AGENTS.md 的内容与你的提问一起送入模型。这意味着：

• 文件越长，占用的上下文越多，留给代码和对话的空间越少
• 精简优于详尽——每一行都有成本

规则的覆盖优先级

通常情况下，规则的生效优先级为：

用户临时指令 > 项目 AGENTS.md > 模型默认行为

这意味着 AGENTS.md 是项目级别的默认值，用户可以在对话中随时覆盖它，但它提供了一个可靠的"基准线"。

AI 识别的信号词

AI 对某些结构天然敏感——清晰的标题、表格、代码块、"必须/禁止/优先"等强语气词。使用这些结构能让规则被更可靠地识别和遵守。

---

编写原则

原则一：面向 AI，而非面向人类

AGENTS.md 和 README.md 不一样。README 是给人读的，可以讲故事；AGENTS.md 是给 AI 读的，应该写指令。

❌ 不好的写法（叙述式）：

本项目历史上曾经使用过 Qt 5，后来迁移到了 Qt 6，因此部分老代码可能还有 Qt 5 的写法，但我们正在逐步更新…

✅ 好的写法（指令式）：

Qt 版本：Qt 6.8。禁用 Qt 5 API，所有新代码使用 Qt 6 风格。

原则二：写"AI 猜不到"的规范

AI 已经从数亿行代码中学习了通用的 C++ 和 Qt 最佳实践。AGENTS.md 的价值在于覆盖那些项目特有的、与通用规范有偏差的约定。

问自己：“如果 AI 不看这条规则，它会做什么？”

• 如果它大概率会做对 → 不用写
• 如果它可能做错 → 必须写

原则三：结论先行，越短越好

每条规则用一句话说清核心，具体示例放在次要位置。AI 对"优先考虑 X，原因是 Y"的结构响应最好。

原则四：强弱语气要分明

用不同的措辞表达约束强度：

强度	措辞示例
强制	禁止、必须、不可
推荐	优先、建议、应该
参考	通常、一般、倾向于

原则五：定期维护

代码会演进，AGENTS.md 也应该随之更新。过时的规则比没有规则更危险——它会让 AI 生成符合旧规范的代码，从而引入隐蔽的一致性问题。

---

文件结构建议

一个完整的 AGENTS.md 通常包含以下几个部分：

# 项目名称 AI 编码指南

## 项目定位
（一段话说清项目是什么、用于什么场景、AI 应扮演什么角色）

## 技术栈
（语言版本、框架版本、核心依赖——越精确越好）

## 架构概览
（目录结构、模块职责、关键数据流向）

## C++ 编码规范
（命名、智能指针、信号槽风格、头文件约定等）

## QML 编码规范
（如有 UI 层）

## 构建与测试
（构建命令、测试方法——AI 需要知道如何验证自己的改动）

## 关键约定
（所有"坑"，项目特有的禁区和强制规则）

---

真实案例解析

以下是一个真实项目（Qt6/QML 嵌入式+桌面融合应用）的 AGENTS.md 片段及分析：

技术栈表格：

| 层次 | 技术 |
|------|------|
| 语言 | C++20、QML（Qt Quick） |
| Qt 版本 | Qt 6.8（`qt_standard_project_setup(REQUIRES 6.8)`） |
| 构建系统 | CMake ≥ 3.16，AUTOMOC/AUTORCC 开启 |

用表格而非散文，AI 解析更精准。连 CMake 函数名都写进去，消除一切歧义。

强制约束区：

- 信号槽：优先使用新式函数指针语法，避免 SIGNAL()/SLOT() 宏
- 命名：类名 PascalCase，成员变量 camelCase_（后缀下划线）
- 颜色/主题：颜色值集中定义在 GlobalSet.qml 中，禁止在业务组件里硬编码颜色值

每条规则具体到操作层面，没有"尽量"、"大概"这类模糊词。

强制编译验证（对 AI 的行为约束）：

> **强制要求**：每次修改 C++ 或 QML 文件后，必须对所在子项目执行一次编译测试，
> 确认无编译错误后方可提交或结束任务。

这条规则不是针对人类程序员，而是指示 AI 自主执行编译来验证代码——这是 AGENTS.md 与 README 最本质的区别之一。

变更输出格式（规范化 AI 的输出）：

> **变更总结要求**：每次任务结束后，必须以如下格式输出本次变更摘要：
> | 文件 | 改动内容 | 改动原因 |

让 AI 输出结构化的变更摘要，便于 Code Review，这是将 AI 纳入工程流程的关键一步。

---

从零开始写你的 AGENTS.md

Step 1：列出你最常需要纠正 AI 的问题

回想最近一个月，你在 AI 生成的代码里改过什么？每一次纠正都是一条潜在规则。

Step 2：写最小可用版本

先写 50 行以内的核心规则，上线验证效果，再逐步扩充。不要追求一次写完。

Step 3：让 AI 帮你写初稿

这是一个绝妙的 bootstrap：把你的 README.md、主要头文件、CMakeLists.txt 喂给 AI，让它生成一份 AGENTS.md 草稿，然后你来修订。

Step 4：团队评审

AGENTS.md 本质上是团队编码规范的可执行化，它的内容应该经过团队讨论，像代码一样 Code Review，像代码一样版本管理。

---

常见误区

误区 1：越详细越好
AGENTS.md 占用上下文窗口。写 2000 行详细规范，不如写 200 行精准规则。

误区 2：只写规范，不写架构
架构信息（目录结构、模块职责）对 AI 的帮助往往大于编码规范。AI 最需要的是"这段代码应该放哪里"。

误区 3：一劳永逸
项目在演进，AGENTS.md 也要定期更新。建议每个 Sprint 或重大重构后做一次 review。

误区 4：认为 AI 会 100% 遵守
AGENTS.md 是提升 AI 一致性的工具，不是银弹。复杂规则仍需在对话中显式提醒，尤其是安全相关的约束。

---

总结

AGENTS.md 是人与 AI 协作的契约文件。它将散落在代码评审、口头约定、Wiki 页面中的团队规范，浓缩成一份 AI 可读、可执行的项目宪法。

写好它，你得到的不只是一个更听话的 AI 助手，而是一个真正融入你团队文化的编程伙伴——它知道你们的禁区，理解你们的架构，说你们的语言。

投入 30 分钟写好一份 AGENTS.md，可以节省你未来几百次"不对，我们项目不这么做"的纠正。

---

参考工具：GitHub Copilot、Claude (Anthropic)、Cursor；参考规范：OpenAI AGENTS.md 标准、.cursorrules 社区实践