1 语法最佳实践
1.1 标题创建
同的Markdown解析器处理 # 和标题之间的空格方式并不一致。为了兼容考虑，请用一个空格在 # 和标题之间进行分隔。
1.2 段落用法
不要用空格（spaces）或制表符（ tabs）缩进段落。
1.3 换行
几乎每个Markdown解析器都支持两个或多个空格进行换行 ，称为结尾空格（trailing whitespace) 的方式，但这是有争议的，因为很难在编辑器中直接看到空格，并且很多人在每个句子后面都会有意或无意地添加两个空格。由于这个原因，你可能要使用除结尾空格以外的其它方式来换行。幸运的是，几乎每个Markdown应用程序都支持另一种换行方式：HTML 的 <br> 标签。
1.4 粗体
要加粗文本，请在单词或短语的前后各添加两个星号（asterisks）或下划线（underscores）。Markdown解析器在如何处理单词或短语中间的下划线上并不一致。为兼容考虑，在单词或短语中间部分加粗的话，请使用星号（asterisks）。
1.5 斜体
要用斜体显示文本，请在单词或短语前后添加一个星号（asterisk）或下划线（underscore）。为兼容考虑，在单词或短语中间部分用斜体显示的话，请使用星号（asterisks）。
1.6 粗体+斜体
要同时用粗体和斜体突出显示文本，请在单词或短语的前后各添加三个星号或下划线。Markdown解析器在处理单词或短语中间添加的下划线上并不一致。为了实现兼容性，请使用星号将单词或短语的中间部分加粗并以斜体显示，以示重要。
1.7 无序表
要创建无序列表，请在每个列表项前面添加破折号 (-)、星号 (*) 或加号 (+) 。Markdown解析器在处理同一列表中的不同分隔符时存在分歧。为了保持兼容性，请不要在同一列表中混用不同的分隔符，而应选择一种并坚持使用。
1.8 有序表
要创建有序列表，请在每个列表项前添加数字 并紧跟一个英文句点 。数字不必按数学顺序排列 ，但是列表应当以数字 1 起始。
CommonMark和其他一些轻量级标记语言允许使用括号 ）作为分隔符，例如，1) First item），但并非所有Markdown解析器都支持这一点，因此从兼容性的角度来看，这并非一个很好的选择。为了兼容性，请仅使用句点，且保持数字序号的连贯性。
1.9 分割线
要创建分隔线，请在单独一行上使用三个或多个星号 (***)、破折号 (---) 或下划线 (___) ，并且不能包含其他内容。为了兼容性，请在分隔线的前后均添加空白行。
1.10 链接
不同的Markdown解析器处理URL中间的空格 方式不一样。为了兼容性，请尽量使用**%20代替**空格。
1.11 HTML 用法
出于安全原因，并非所有Markdown解析器都支持在Markdown文档中添加 HTML。如有疑问，请查看相应Markdown解析器的手册。某些应用程序只支持HTML标签的子集。
对于HTML的块级元素 <div>、<table>、<pre> 和 <p>，请在其前后使用空行（blank lines）与其它内容进行分隔。尽量不要使用制表符（tabs）或空格（spaces）对 HTML 标签做缩进，否则将影响格式。
在HTML块级标签内不能使用Markdown语法。例如 <p>italic and **bold**</p> 将不起作用。
2 工程最佳实践
2.1 聚焦重要事件
添加有助于智能体有效处理项目的章节，热门选择包括：
- 项目概述
- 构建和测试命令
- 编码风格指南
- 测试指令
- 安全事项
2.2 添加额外指令
代码提交信息或拉取请求指南、安全陷阱、大型数据集、部署步骤。任何你想告诉新队友的内容也放这里。
2.3 针对子项目使用嵌套的AGENTS.md文件
在每个包中再放一份AGENTS.md文件，即每个代码包都有属于自己的AGENTS.md，而非整个项目只用一个根目录的AGENTS.md。
智能体会自动读取目录树中最靠近的文件，即与编译和测试代码最近的AGENTS.md。因此，最近的AGENTS.md文件具有优先权，每个子项目都可以推出定制指令。例如，OpenAI的主仓库中有88个AGENTS.md文件。
2.4 统一AGENTS.md编写的最佳实践
为了保持整个团队AGENTS.md文件编写的一致性，要求团队成员编写AGENTS.md文件时，需要遵循"语法最佳实践"章节中的写法，并将其作为文档编写规范化的检查项之一。