# AI 写代码总不合规范？根目录放一份 AGENTS.md 就够了

> **引言**：不是 AI 不够强，是它每次对话都像**第一天入职**——根目录一份 AGENTS.md，把团队规矩写进它的「长期记忆」。

用 Cursor 写前端，常见场景：让它装依赖跑 npm，你们用 pnpm；让它调接口，组件里裸 fetch；让它写样式，随手 inline style。代码能跑，Review 必被打回。

解决办法是项目根目录一份 **AGENTS.md**：把技术栈、目录、命令、Never 规则写进去，Cursor / Copilot 开聊先读它。60～100 行就够，提交 Git、团队共享。

## 📌 本文看点

| 序号 | 主题 | 说明 |
|------|------|------|
| 01 | 概念边界 | vs Prompt / Rules |
| 02 | 代码对比 | ❌ vs ✅ 三场景 |
| 03 | 逐章 + 模板 | 六章写法 · 完整示例 |
| 04 | 接入维护 | 工具配置 · 自查清单 |

---

## 01 · CONCEPT — AGENTS.md 是什么？和 Prompt / Rules / Skill 差在哪

| 概念 | 作用域 | 典型用途 |
|------|--------|----------|
| Prompt | 单次对话 | 「帮我写个按钮」——用完即丢 |
| Rules / SKILL.md | IDE 或任务级 | 管「别乱来」或「某类任务怎么做」 |
| MCP | 外部工具 | 给 AI 连接数据库、浏览器、Figma 的「手」 |
| **AGENTS.md** | **项目级** | **本仓库怎么写、怎么跑、绝对不能碰什么** |

---

## 02 · COMPARE — 三个场景：有 / 没有 AGENTS.md 的代码差距

### 场景 1：写一个复制按钮

**❌ 没有 AGENTS.md**

```tsx
// ❌ 没有 AGENTS.md 时 AI 常写的代码
export default function CopyBtn({ text }: any) {
  return (
    <button style={{ color: 'blue', padding: '4px 8px' }}
      onClick={() => navigator.clipboard.writeText(text)}>
      Copy
    </button>
  )
}
```

**✅ 有 AGENTS.md**

```tsx
// ✅ 有 AGENTS.md 后 → src/components/CopyButton/index.tsx
import React, { useCallback } from 'react'
import { message } from 'antd'
import styles from './index.less'
interface CopyButtonProps { text: string; onSuccess?: () => void }
const CopyButton: React.FC<CopyButtonProps> = ({ text, onSuccess }) => {
  const handleCopy = useCallback(async () => {
    await navigator.clipboard.writeText(text)
    message.success('已复制'); onSuccess?.()
  }, [text, onSuccess])
  return <button className={styles['copy-button']} onClick={handleCopy}>复制</button>
}
export default CopyButton
```

### 场景 2：调用 API 接口

**❌ 没有 AGENTS.md**

```tsx
// ❌ 组件里裸 fetch，无类型、无 loading、无错误处理
const [data, setData] = useState(null)
useEffect(() => {
  fetch('/api/customers').then(r=>r.json()).then(setData)
}, [])
```

**✅ 有 AGENTS.md**

```tsx
// ✅ src/services/customer.ts
import { request } from '@/utils/request'
export async function fetchCustomerList(params: API.CustomerListParams) {
  return request('/api/customers', { params })
}
// 组件中：const { data, loading } = useRequest(fetchCustomerList)
```

### 场景 3：提交代码

**❌ 没有 AGENTS.md**

```bash
git commit -m "fix button"
```

**✅ 有 AGENTS.md**

```bash
git commit -m "fix(components): 修复 CopyButton 在 Safari 下复制失败的问题"
```

Commit 规范看起来小事，但在 CI 自动生成 Changelog、按 scope 分配 Reviewer 的团队里，不规范的 commit 会直接卡住流水线。

---

## 03 · DEEP DIVE — 逐章详解：模板里每一块为什么这么写

下面按模板章节顺序，解释「写什么、怎么写、常见坑」。你可以对照后面的完整模板一起看。

**1. 这是什么（项目背景）**  
3 行以内说清楚：技术栈 + 业务场景 + 核心模块。要写版本号——React 18 和 19 写法不同；要写包管理器——否则 AI 默认 `npm install`。不要写「这是一个优秀的项目」这种废话。

**2. 仓库结构（Project Structure）**  
只列一级目录 + 注释说明用途和命名规范。太深 AI 反而困惑。关键是告诉 AI「新组件放哪、API 放哪、类型放哪」。路径别名 `@/*` 也要写，否则 AI 会用相对路径 `../../../` 乱 import。

**3. 构建与测试命令**  
AI 会原样执行这些命令——必须精确。写 `pnpm dev` 就不要写「启动开发服务器（具体命令见 README）」。提交前必须跑通的检查也写在这里，AI 改完代码会主动跑 lint/test。

**4. 代码规范（Coding Style）**  
越具体越好。不要写「遵循最佳实践」，要写「Props 用 interface 不用 type」「样式 import styles from ./index.less」。最好给一行正确用法示例——AI 读示例比读规则更准。

**5. Never 规则（价值最高）**  
告诉 AI「绝对不能做什么」，比「应该怎么做」更有效。因为 AI 犯错的成本远高于人类——它会认真改完 `src/.umi/`，然后你下次构建直接炸。每条 Never 最好对应一次真实踩坑。

**6. Commit 规范**  
给格式 + 类型枚举 + 一个真实示例。AI 生成 commit message 时会直接套用。

**7. 常见任务入口**  
告诉 AI「加页面 / 加组件 / 修 Bug」分别从哪一步开始。降低 AI 乱猜路径的概率。

**8. 更多细节（渐进式披露）**  
指向 `docs/ARCHITECTURE.md`、`DESIGN.md` 等深层文档。AGENTS.md 是入口，不是终点。

> **⚠ Never 规则为什么这么重要？**  
> 人类改错 `.umi/` 目录，很快意识到「哦不该改这个」。AI 不会——它会把自动生成的路由配置改得「更合理」，然后构建失败。建议养成习惯：AI 每犯一次你不希望犯的错，就往 Never 里加一条，并记一行原因（演进日志）。三个月后你会有一份从真实踩坑沉淀出来的规则手册。

---

## 04 · STRUCTURE — 四个模块 + 六条写作原则（带正反例）

好用的 AGENTS.md 有一个反直觉原则：写少比写多好。LLM 能可靠执行的指令有上限——堆太多不是忽略后半段，而是全局质量一起下降。

| 模块 | 写什么 | 为什么重要 |
|------|--------|------------|
| 项目背景 | 技术栈 + 业务场景 | 帮 AI 选对框架 API 和组件库 |
| 精确命令 | install / dev / test / build | AI 调试时会原样执行，不能含糊 |
| 代码规范 | 目录、命名、类型、样式 | 决定 AI 输出代码的「团队味」 |
| 容易踩错 | Never 规则 + 踩坑沉淀 | 防止灾难性误操作，价值最高 |

### 六条写作原则（每条都有正反例）

1. **当目录用，不当百科**  
   ❌ 在 AGENTS.md 里写 50 行架构说明 → ✅ 写 3 行概述 + 指向 `docs/ARCHITECTURE.md`。AI 可以自己读文件，你只需要告诉它文件在哪。

2. **写规则，不写建议**  
   ❌ 「建议使用 CSS Modules」→ ✅ 「禁止内联 `style={{}}`，必须使用 `import styles from './index.less'`」。规则可机械执行，建议只能「尽量遵守」。

3. **把「为什么」写上**  
   ❌ 「禁止修改 .umi/」→ ✅ 「禁止修改 .umi/（框架自动生成，改了会导致路由配置丢失）」。AI 在边界情况推理时会更守规矩。

4. **指向 lint / CI**  
   ❌ 「代码要有良好日志」→ ✅ 「使用结构化日志（见 eslint rule custom/structured-logging）」。如果 lint 已经在检查，直接指向它。

5. **渐进式披露**  
   AGENTS.md(100行) → docs/ARCHITECTURE.md → docs/domains/XXX.md → 代码注释。每一层更具体，但不一次性全塞给 AI。

6. **持续演进，不要一次性写完**  
   AI 犯同样错两次 → 加一条 Never。三个月后你会有一份真正懂这个项目的规则手册。

---

## 05 · TEMPLATE — 完整 AGENTS.md 模板

下面是一份约 80 行的团队项目模板。复制到项目根目录，按你的技术栈改参数即可。

`DESIGN.md` 管「UI 长什么样」——品牌色、间距、文字色。有了它，AI 写样式时不会随手 `color: blue`。

**DESIGN.md · 片段示例**

```markdown
## 品牌色
- 主色：#1677FF
- 主色悬浮：#4096FF
## 间距系统
- 基础单位：8px；组件间距：16px / 24px
```

**AGENTS.local.md · 个人偏好（不入库）**

```markdown
# 加入 .gitignore
- 回复语言：中文
- 代码注释：中文
- 复杂任务先说明思路再动手
- 信息不足立即停下，不要猜测
- 删文件 / 推远程 / 改 CI 须二次确认
```

---

## 06 · SETUP — 各工具如何接入 + 三种规模怎么写

### 主流工具接入方式

- **Cursor**：Settings → Rules → 添加 Rule，内容写「Always follow AGENTS.md in project root」；或在 `.cursor/rules` 中 `@import AGENTS.md`
- **Claude Code**：项目根目录 AGENTS.md 自动读取；也可在 CLAUDE.md 中写 `@AGENTS.md` 引用
- **GitHub Copilot**：`.github/copilot-instructions.md` 中引用或同步 AGENTS.md 内容
- **Windsurf**：`.windsurfrules` 或 Rules 面板引用项目 AGENTS.md

核心思路：AGENTS.md 是统一规范源文件，不同工具通过各自的 Rules 入口接入，内容保持一致。

### 三种规模，三种写法

| 规模 | 行数 | 写法 |
|------|------|------|
| **A 个人项目** | 10～30 行 | 技术栈 + dev/test 命令 + 3 条 Never + 指向 README |
| **B 团队项目** | 60～100 行 | 用本文完整模板：目录结构、精确命令、Never 规则、常见任务入口 |
| **C 企业级** | 100 行 + 配套文档 | AGENTS.md 仍然 100 行，配套 docs/ARCHITECTURE.md、自定义 lint、doc-gardening |

老项目最快启动：让 AI 读一遍代码库，问「这个项目有什么值得写进 AGENTS.md 的规范？」——它会给初稿。然后删掉 AI 看代码就能知道的废话，只留真正需要的约定。

---

## 07 · DATA — 效果数据 + 研究结论

以下数据来自实际项目 3 周、50+ 次 AI 生成代码的人工抽检（不同项目会有差异）：

| 指标 | 没有 | 有 AGENTS.md | 变化 |
|------|------|--------------|------|
| 规范遵循率 | ~60% | **95%+** | ↑35% |
| 一次通过率 | ~40% | **80%+** | ↑40% |
| 每次手动修正 | ~8 分钟 | **~1 分钟** | ↓87% |
| 新人上手 | 3～5 天 | **约 1 天** | ↓70% |

最后一项容易被忽略：AGENTS.md 对人也有用。它是项目开发规范的浓缩版——新人 5 分钟能摸清技术栈、目录、规范和禁止事项。
---

## 08 · CHECKLIST — 自查清单 + 常见问题

写完后用这张清单过一遍。任何一项不通过，回去改 AGENTS.md，不要带着问题开聊。

- [ ] 不超过 100 行？（超过就删废话，指向 docs/）
- [ ] 一句话说清项目是什么 + 技术栈版本？
- [ ] 构建 / 测试 / lint 命令精确可执行？
- [ ] 3～8 条 Never 硬约束写出来了？
- [ ] 每条 Never 对应一次真实踩坑（或潜在灾难）？
- [ ] 常见任务（加页面 / 修 Bug）有入口指引？
- [ ] 指向了 docs/ARCHITECTURE.md 等深层文档？
- [ ] 规则指向了对应的 lint / CI 检查？
- [ ] 有定期维护机制（AI 犯两次错就加一条）？

### FAQ

| 问题 | 回答 |
|------|------|
| 放哪里？ | 项目根目录，与 package.json 同级。全局个人偏好可放用户目录，通过工具配置引用。 |
| 要提交 Git 吗？ | AGENTS.md 必须提交，团队共享。AGENTS.local.md 加入 .gitignore。 |
| 和 .cursorrules 冲突吗？ | 不冲突。建议 AGENTS.md 作唯一规范源，Cursor Rules 只做引用，避免两处维护不一致。 |
| 写多长合适？ | 最小 30 行可用，推荐 60～100 行，不建议超过 200 行。 |
| 老项目怎么加？ | 根目录新建文件，复制模板改参数，5 分钟提交。不需要改任何业务代码。 |
| 多久维护一次？ | 不是定期维护，是事件驱动——AI 犯你不希望犯的错，就加一条 Never。每月 Review 一次有没有过时规则即可。 |

---

## 写在最后

2026 年 AI 编程最值钱的两件事：认知升级（知道 Agent 是「员工」不是「补全工具」）+ 工具配置（用 AGENTS.md 把上下文持久化）。

> 与其每次手动修正 AI 写的代码，不如花 20 分钟写一份精简的入职手册。100 行 Markdown，左右 Agent 每天的工作方式。





引言：不是 AI 不够强，是它每次对话都像第一天入职——根目录一份 AGENTS.md，把团队规矩写进它的「长期记忆」。

告别 AI 乱写代码，AGENTS.md 提升代码输出质量

人工智能

在项目根目录添加AGENTS.md，可有效解决AI编程不合规范问题。该文件将技术栈、目录结构、精确命令、代码规范及Never规则写入AI的“长期记忆”，使Cursor、Copilot等工具遵守团队约定。实测显示，规范遵循率提升至95%，一次通过率提高40%，代码修正时间减少87%，新人上手效率提升70%。模板约80行，含提交规范与踩坑记录，是提升AI协作质量的关键配置。

包管理器

代码解释

服务器

数据库

AI编程

路由

Agent

ReAct 

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

在项目根目录添加AGENTS.md，可有效解决AI编程不合规范问题。该文件将技术栈、目录结构、精确命令、代码规范及Never规则写入AI的“长期记忆”，使Cursor、Copilot等工具遵守团队约定。实测显示，规范遵循率提升至95%，一次通过率提高40%，代码修正时间减少87%，新人上手效率提升70%。模板约80行，...

告别 AI 乱写代码，AGENTS.md 提升代码输出质量-腾讯云开发者社区-腾讯云

告别 AI 乱写代码，AGENTS.md 提升代码输出质量

告别 AI 乱写代码，AGENTS.md 提升代码输出质量

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐