AGENTS.md：我试图统一AI编码工具的配置，然后…

📁 项目地址: https://github.com/YaBoom/agents-md-zyt

说实话，第一次看到AGENTS.md这个名词，是在刷Twitter的时候。当时Cursor官方转了一条推文，说AGENTS.md现在被多少多少工具支持。我心想：又来一个标准？真的假的？

但后来仔细一看，发现这事儿还真有点意思。

为什么我开始关注这个

我现在的开发工作流里同时用着好几个AI工具：

• 主力编辑器是Cursor
• 偶尔用GitHub Copilot CLI
• 听说Windsurf也不错想试试
• 还有Claude Code在终端里

然后你就发现一个问题：每个工具都有自己的"教它怎么写代码"的配置文件。

.cursorrules        ← Cursor的
.github/copilot-instructions.md  ← Copilot的  
CLAUDE.md           ← Claude的
.windsurf/rules.md  ← Windsurf的
...

这什么啊？我一个项目要维护四五个不同的规则文件？而且内容90%都是重复的——“用TypeScript严格模式”、“单引号不要分号”、“测试覆盖率80%”…

所以当看到AGENTS.md说"一个文件，所有工具都能读"的时候，我确实是眼睛亮了一下。

AGENTS.md是什么

简单来说，它就是一个放在项目根目录的Markdown文件，专门给AI编码工具看的。

官方的说法是：README是给人类看的，AGENTS.md是给AI看的。

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev: `pnpm dev`
- Test: `pnpm test`

## Code style
- TypeScript严格模式
- 单引号，不要分号
- 函数式优先

## Testing
- 提交前跑测试
- 新功能要有测试

就这么简单。没有复杂的格式，就是Markdown。

但关键是——Cursor、Windsurf、GitHub Copilot、Zed、Pulumi Neo，现在都能自动读取这个文件。据说已经有60,000多个开源项目在用。

而且这玩意儿是开放标准，由Agentic AI Foundation在Linux Foundation下面管。不是某个公司的私货。

我决定动手试试

看到这里我就手痒了。想写一个解析器，看看这个格式到底有多简单（或者说多复杂）。

于是就有了这个项目：https://github.com/YaBoom/agents-md-zyt

第一次尝试：正则表达式 ❌

我一开始的想法很简单：用正则匹配/^#{1,6}\s+(.+)$/gm，把标题和内容分离不就行了？

结果马上踩坑。

## Setup Commands
```bash
# 安装依赖  ← 这里！
npm install

代码块里的`#`也会被正则匹配到。这就乱了。

我当时还没想到怎么处理代码块，就先把这版代码扔到了`experiments/attempt1-regex.ts`，当个反面教材。

### 第二次尝试：逐行解析 ✅

换了种思路：逐行读取，维护一个"是否在代码块内"的状态。

```typescript
let inCodeBlock = false;

for (const line of lines) {
  if (line.trim().startsWith('```')) {
    inCodeBlock = !inCodeBlock;
  }
  
  if (!inCodeBlock) {
    // 现在可以安全地解析标题了
  }
}

这版基本能用了。我实现了：

• 解析sections（标题+内容）
• 简单的验证（检查有没有setup/style/test相关内容）
• 查找最近的AGENTS.md（支持嵌套项目）

但说实话，代码还是挺糙的。比如：

• 没有处理YAML frontmatter（SKILL.md格式会用到）
• findNearestAgentsMd没有真正递归，只是硬编码了几个路径
• 错误处理很粗暴，直接throw Error

不过这本来就是个实验项目，README里也写清楚了——这只是探索代码。

运行效果

$ node dist/index.js

🔍 AGENTS.md Parser - 实验版本

📄 找到: /home/project/AGENTS.md

📊 解析结果:
   - 共 6 个section

1. 项目概述
   这是一个AGENTS.md解析器的实验项目...

2. 安装依赖
   pnpm install

...

🔍 验证结果:
   ⚠️  建议:
      - 建议添加 security 相关内容

能用。不是生产级，但证明了概念。

我的一些想法

1. 这个标准为什么能成

我觉得AGENTS.md能火起来，不是因为它技术多牛逼，而是因为它解决了一个真实的痛点：配置碎片化。

以前你要用5个AI工具，就得维护5份配置。现在一份就够了。而且格式简单，就是Markdown，没有学习成本。

2. 和Agent Skills的关系

Anthropic还推了一个叫Agent Skills的标准，是SKILL.md格式，带YAML frontmatter的。这个更复杂一些，可以定义更结构化的能力。

AGENTS.md是项目级别的配置，Agent Skills是更细粒度的能力定义。两者可能会融合，也可能会并行存在。我好奇的是未来会不会有一个统一的标准。

3. 实际用起来的感受

我在这个项目里写了一个真正的AGENTS.md，然后让Cursor基于它来生成代码。感觉确实有区别——AI会更"懂"项目结构，不会随便推荐不匹配的命令。

但也不是银弹。如果AGENTS.md写得不清楚，AI还是会懵。而且不同工具对AGENTS.md的支持程度不一样，有些可能只是简单地读取，没有深度集成。

踩过的坑

1. Markdown解析比想象中复杂

   • 代码块、嵌套列表、表格…要考虑的边界情况很多
   • 真要健壮的话，还是得用marked这种成熟库

2. 嵌套AGENTS.md的优先级

   • 官方说"最近的AGENTS.md优先"
   • 但在monorepo里怎么定义"最近"？需要想清楚路径解析逻辑

3. 验证规则不好定

   • 什么样的AGENTS.md算"好"的？
   • 我现在的验证只是检查有没有常见sections，但这太主观了

下一步想做的

• 用真实的大项目测试（比如openai/openai-python这种有AGENTS.md的）
• 支持SKILL.md格式的YAML frontmatter解析
• 写一个VS Code插件，可以可视化编辑AGENTS.md
• 看看能不能和MCP（Model Context Protocol）结合

总结

AGENTS.md这个标准我觉得是靠谱的。它足够简单，又解决真实问题，而且有主流工具支持。

我的实验项目只是一个开始，代码很糙，但验证了想法。如果你想试试，可以去GitHub看完整代码：https://github.com/YaBoom/agents-md-zyt

话说回来，你们现在用AI编码工具的时候，是怎么管理项目规则的？是各自用各自的配置文件，还是已经在尝试AGENTS.md了？

---

参考链接:

• AGENTS.md官方规范: https://agents.md/
• Pulumi Neo的AGENTS.md支持: https://www.pulumi.com/blog/pulumi-neo-now-supports-agentsmd/
• Agent Skills标准: https://agentskills.io/