来自 Builder.io 创始人 Steve 的分享，讲了一个简单但超级实用的方法：通过在项目根目录创建一个 AGENTS. md 文件，告诉 AI 编程工具你的项目规则和偏好，让 AI 输出的代码更符合你的需求，减少修改的麻烦。作者分享了他用 AGENTS. md 提升 AI 代码质量的经验和最佳实践，特别适合那些觉得 AI 代码“又聪明又蠢”的开发者。
什么是 AGENTS. md？
AGENTS. md 就像是给 AI 工具的一个“项目说明书”。它是一个 Markdown 文件，放在项目根目录，告诉 AI 你的代码规范、项目结构、偏好设置等。这样，AI 不需要每次都从零开始猜你的项目规则，省时省力，代码质量也更高。
相比每个 AI 工具用单独的配置文件（比如 .cursorrules），AGENTS.md 是一个通用的标准，多个工具都能读，减少文件杂乱。
为什么需要 AGENTS. md？
作者举了个例子：他把 Figma 设计丢给 Builder.io 的 AI 工具，要求生成一个应用全局的 Tab 组件。结果呢？代码看起来不错，但细节问题一堆：
· 用错了 MUI 版本，样式有点跑偏。
· 用了 emotion CSS，但格式不符合团队习惯。
· 状态管理选了 useState，而不是团队偏爱的 Mobx。
· 图表用 ApexCharts，但生成了不必要的 HTML 字符串。
· 暗模式下有些设计 token 没用对。
这些问题不致命，但修起来烦人。AGENTS. md 就是用来解决这些“差一点”的问题，让 AI 直接生成更贴合你需求的代码。
怎么写一个好的 AGENTS. md？
文章提供了一套清晰的结构和建议，帮你打造一个高效的 AGENTS. md 文件。几个关键部分：
- 明确“该做”和“不该做”
列出你的代码规范，比如用哪个库、版本、格式，禁止硬编码颜色或引入不必要的依赖。例子：
Do
· 用 MUI v3，确保代码兼容
· 用 emotion 的 css={{}} 格式
· 用 Mobx 和 useLocalStore 管理状态
· 所有样式从 DynamicStyles.tsx 取设计 token
· 图表用 ApexCharts，别写自定义 HTML
· 组件尽量小而专注
· 修改尽量小，避免改动整个项目
Don't
· 不要硬编码颜色
· 不要用 div 替代现有组件
· 未经许可不要加新依赖
这些规则让 AI 少犯错，比如不会用错版本或格式，生成的代码更符合你的标准。
- 指定文件级别的命令
AI 常跑全项目构建，耗时又浪费资源。告诉它如何针对单个文件跑检查、格式化或测试，效率更高：
# 类型检查单文件
npm run tsc --noEmit path/to/file.tsx
# 格式化单文件
npm run prettier --write path/to/file.tsx
# 单元测试
npm run vitest run path/to/file.test.tsx
# 仅在明确要求时跑全项目构建
npm run build:app
单文件命令更快、更省资源，AI 可以快速验证代码，减少出错。
- 设置安全和权限规则
明确 AI 可以直接做什么（比如读文件、跑单文件检查），哪些需要确认（比如装新包、删除文件）：
### Safety and permissions
允许直接操作：
- 读文件、列出文件
- 单文件 tsc、prettier、eslint、vitest
需先询问：
- 安装新包
- git push
- 删除文件或修改权限
- 跑全项目构建或端到端测试
避免 AI 擅自干危险的事，比如偷偷装包或推代码。
- 提供项目结构指引
给 AI 一个“地图”，告诉它关键文件的位置，比如路由、组件、设计 token 在哪：
### Project structure
- 路由看 App.tsx
- 侧边栏看 AppSideBar.tsx
- 组件在 app/components
- 设计 token 在 app/lib/theme/tokens.ts
AI 不需要每次都重新搜索项目，生成代码时能更快找到正确上下文。
- 用具体例子教 AI
指明“好”的代码示例和“坏”的代码，避免 AI 学错：
### Good and bad examples
- 不要用类组件（如 Admin.tsx）
- 用函数组件和 hooks（如 Projects.tsx）
- 表单参考 app/components/DashForm.tsx
- 图表参考 app/components/Charts/Bar.tsx
- 数据层用 app/api/client.ts，别在组件里直接 fetch
示例让 AI 模仿你最好的代码模式，避开老旧或不规范的代码。
- 指向 API 文档
如果项目有 API，告诉 AI 文档和客户端代码在哪：
### API docs
- 文档在 ./api/docs/*.md
- 获取项目列表：GET /api/projects，用 app/api/client.ts
- 更新项目名：PATCH /api/projects/:id，用 client.projects.update
AI 能直接用正确的 API 和客户端，生成的代码更贴近真实数据。
- 支持嵌套的 AGENTS. md
大项目可以给不同子目录加自己的 AGENTS. md，适配不同技术栈（比如老模块用 React 17，新模块用 React 18）。
- 定义 PR 检查清单
明确提交代码前的要求，比如标题格式、测试通过、diff 尽量小：
### PR checklist
- 标题格式：feat(scope): 简短描述
- 格式化、类型检查、单元测试全通过
- diff 小而专注，附上变更总结
统一标准，减少 review 时的来回修改。
- 当 AI 卡住时
让 AI 在不确定时提问或提计划，而不是瞎猜：
### When stuck
- 提个问题、建议个计划，或开个带注释的草稿 PR
- 别未经确认就推大改动
避免 AI 走错路，省去大修的麻烦。
- 测试优先模式（可选）
对于复杂任务，要求 AI 先写测试，再写代码：
### Test first mode
- 新功能先写/更新单元测试，再写代码到测试通过
- UI 状态变化优先写组件测试
测试先行能锁住行为，减少 bug。
- 设计系统指引
如果有独立的设计系统，告诉 AI 组件和 token 的用法：
### Design system
- 用 @ acme/ui 组件，文档在 ./design-system-index/*.md
- token 从 @ acme/ui/tokens 取
确保 UI 代码高保真，少改动就能匹配设计。
效果怎么样？
作者重新用 AGENTS. md 跑了之前的 Tab 组件任务，结果：
· UI 更准确，暗模式 token 用对了。
· 代码更简洁，符合团队规范。
· 再试加一个表格，效果也很棒。
额外小贴士
· 非开发者的福音：像 Builder.io 这样被设计师和产品经理用的工具，AGENTS. md 能确保他们生成的代码也符合开发规范。
· 兼容性：不是所有工具都支持 AGENTS. md，但可以让工具读它，比如在 CLAUDE. md 里写“严格遵循 ./AGENTS. md”。
· 保持简洁：从简单的 dos 和 don’ts 开始，边用边加规则。清晰比长篇大论重要。
· 持续改进：每次 AI 出错，就把反馈加到 AGENTS. md，让它越来越聪明。
总结
AGENTS. md 就像给 AI 的一份“作弊小抄”，让它少走弯路，直接生成符合你习惯的代码。核心是：
· 写清楚规则（dos 和 don’ts）。
· 提供具体示例和文件路径。
· 用单文件命令提效。
· 迭代完善，保持简洁。
原文地址：
https://www.builder.io/blog/agents-md?utm\_source=x&utm\_campaign=agents-md&utm\_content=ss
信息卡提示词：