AI Coding 开发常用的规约工具：让 AI 真正听懂你的项目

关键词：AI 编程、Cursor、Claude Code、GitHub Copilot、规约文件、AGENTS.md、Context Engineering

一、为什么需要"规约工具"？

用 AI 写代码最让人崩溃的不是它不会写，而是它每次都像没带过脑子——

• 你团队用 Tailwind，它给你写 CSS Module；
• 你项目里全是 named export，它偏给你 default export；
• 你用 pnpm，它 npm install 一把梭；
• 你数据库用 Prisma，它给你裸 SQL。

根本原因：LLM 在每次对话之间不保留记忆，它不知道你项目的"家规"。“规约工具”（也叫规则文件 / 指令文件 / 上下文文件）就是用来把这套家规持久化地喂给 AI 的——相当于给 AI 配了个入职手册。

这类文件本质是 Context Engineering（上下文工程） 的落地：用一份可版本控制的 Markdown，定义项目的角色、技术栈、编码风格、命令和边界，让 AI 从"通用顾问"变成"懂你项目的老员工"。

下面按工具盘一下当下最主流的几种规约方案，并给出一份规则该写什么的实战模板。

---

二、主流规约工具盘点

1. Claude Code —— CLAUDE.md

Anthropic 的 Claude Code 把规则文件做到了极简且强悍。项目根目录放一个 CLAUDE.md，AI 每次启动都会自动读取。

# CLAUDE.md

本项目是一个 SaaS 应用，技术栈：
- Next.js 15（App Router，不是 Pages Router）
- React 19 + TypeScript（strict 模式）
- Tailwind CSS v4
- Prisma + PostgreSQL

## 编码规范
- 全部使用 async/await，禁止 .then()
- 组件用 named export，禁止 default export
- 错误处理用具体 Error 类型，错误信息要可操作

## 命令
- 安装依赖：pnpm install
- 跑测试：pnpm test
- 构建：pnpm build

特点：写法自由，纯 Markdown，无 frontmatter；同时被 Claude Code、Copilot、Codex 等多个工具兼容识别（见第六节）。

---

2. Cursor —— .cursor/rules/*.mdc（新版）/ .cursorrules（旧版已废弃）

Cursor 早期用根目录单个 .cursorrules，但已被官方标记为 deprecated。现在推荐用 .cursor/rules/ 目录下的 .mdc 文件（注意：必须是 .mdc 后缀，纯 .md 会被静默忽略）。

每个 .mdc 文件带 YAML frontmatter，可以精确控制何时生效：

---
description: React 组件编写规范
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React 组件规范
- 只用函数组件 + TypeScript 接口定义 props
- 用 named export
- 所有样式用 Tailwind，禁止 inline style 和 CSS Module
- hooks 统一放在组件体顶部

四种生效模式：

模式	配置	触发方式
Always	alwaysApply: true	每次对话都加载
Auto Attached	配 globs	编辑匹配文件时自动附加
Agent Requested	仅 description	AI 自行判断相关性
Manual	@规则名	在对话里手动 @ 提及

最佳实践：单文件别超过 500 行；用 @filename 引用代码而不是把代码粘进规则（省 token）；alwaysApply: true 的规则会吃上下文，保持精简。

---

3. GitHub Copilot —— 三套体系并存

Copilot 的规约体系目前最"杂"，但也在快速收敛：

(a) 传统指令文件（仍可用）

• .github/copilot-instructions.md：仓库级指令
• .github/instructions/*.instructions.md：可带 applyTo 按文件类型生效

(b) AGENTS.md（2025-08 起 Copilot Coding Agent 支持）
根目录放 AGENTS.md，也可放嵌套 AGENTS.md 针对子目录生效。Copilot 还会顺带读 CLAUDE.md 和 GEMINI.md。

© 自定义 Agent（2025-11 强化）
用 frontmatter 定义专属角色，比如 .github/agents/test-agent.agent.md：

---
name: test_agent
description: 本项目的测试专家，只写测试不碰业务代码
---

你是测试工程师，为 src/components/ 下的 React 组件写 Jest 单测。

## 命令
- 跑单测：npm test
- 跑 lint：npm run lint

## 边界
- ✅ 只写/改 tests/ 下文件
- 🚫 绝不修改 src/ 业务代码
- 🚫 绝不删除失败用例

GitHub 分析了 2500+ 公开仓库后给出的最佳实践高度一致：命令放前面、给真实代码示例、设清晰边界、技术栈写具体（带版本号）。

---

4. Windsurf —— .windsurfrules / .windsurf/rules/

Windsurf（原 Codeium）用 .windsurfrules（根目录，纯 Markdown），新版也支持 .windsurf/rules/ 目录，支持 mode（always / manual）和全局/项目/子目录分层。

# .windsurfrules
你是一个 Python 后端专家。
- 所有函数必须有类型注解
- 遵循 PEP 8
- 优先用 early return
- 错误要明确 raise，不要吞掉异常

---

5. OpenAI Codex —— AGENTS.md / ~/.codex/

Codex CLI（以及云端 Codex）默认读取仓库根目录的 AGENTS.md，还支持 ~/.codex/ 下的用户级记忆。思路和 Claude 的 CLAUDE.md 基本一致，纯 Markdown、无 frontmatter。

---

6. Gemini CLI —— GEMINI.md / .gemini/

Google 的 Gemini CLI 读取 GEMINI.md（可放项目根或 ~/.gemini/），同时兼容 AGENTS.md。特点是它默认全量加载，不支持 glob 自动匹配，所以内容要更克制。

---

7. Aider —— CONVENTIONS.md / .aider.conf.yml

老牌终端 AI 编程工具 Aider，用 CONVENTIONS.md 声明编码约定，用 .aider.conf.yml 配置模型、仓库映射等。写法偏极客，适合命令行重度用户。

---

8. CodeBuddy / 其他国产 Agent

以 CodeBuddy 为例，它的规约体系更"人格化"：

• SOUL.md：定义 AI 的"灵魂"——性格、边界、价值观
• IDENTITY.md：身份卡（名字、角色、风格）
• USER.md：关于你的画像
• skills/：可复用的技能包（带 SKILL.md + 工作流）

这种"身份 + 记忆 + 技能"的三层结构，是 Claude 单文件 CLAUDE.md 思路的升级版，更适合长期陪伴式开发。

---

三、横向对比一览

工具	规约文件名	格式	分层	Glob 精确匹配	跨工具兼容
Claude Code	CLAUDE.md	纯 MD	根/嵌套	❌	✅ 被多工具识别
Cursor	.cursor/rules/*.mdc	MD+frontmatter	✅ 多层	✅	⚠️ 需转换
Copilot	.github/copilot-instructions.md / AGENTS.md	纯 MD / frontmatter	✅	✅(instructions)	✅
Windsurf	.windsurfrules / .windsurf/rules/	纯 MD	✅	⚠️ mode	⚠️
Codex	AGENTS.md	纯 MD	根/嵌套	❌	✅
Gemini CLI	GEMINI.md	纯 MD	根/用户	❌	✅
Aider	CONVENTIONS.md	纯 MD	根	❌	⚠️

---

四、一份好的规约文件，到底该写什么？

不管用哪个工具，内容结构大同小异。直接给你一个可抄的模板：

# 项目规则（AGENTS.md / CLAUDE.md）

## 1. 项目简介
一句话说清这是什么项目、给谁用、核心目标。

## 2. 技术栈（带版本号）
- 框架：Next.js 15 / React 19
- 语言：TypeScript 5（strict）
- 样式：Tailwind CSS v4
- 数据：Prisma 6 + PostgreSQL
- 包管理：pnpm

## 3. 必跑命令（放最前面！）
- 安装：pnpm install
- 测试：pnpm test
- 构建：pnpm build
- Lint：pnpm lint

## 4. 编码风格（只写"有偏离默认"的决策）
- 函数组件 + named export
- async/await，禁止 .then()
- 错误用具体类型，信息可操作

## 5. 目录结构
- src/ 业务代码
- tests/ 测试
- docs/ 文档

## 6. 边界（明确不让 AI 干嘛）
- 🚫 不提交密钥 / 明文密码
- 🚫 不改动 migration 文件
- ⚠️ 改公共 API 前先问

## 7. 示例（一个好代码的样板）
[贴一段符合规范的真实代码]

几条血泪经验：

1. 命令和边界比风格描述重要——AI 最常栽在"不会跑测试""乱改配置"上。
2. 给真实代码示例，胜过三段散文。一个 snippet 顶三句话。
3. 技术栈写具体版本，别写"React 项目"，写"React 19 + Server Components"。
4. 规则别又臭又长。Cursor 官方建议单文件 < 500 行；alwaysApply 的规则会撑爆上下文。
5. 规则进版本控制（提交到 git），团队才能共享同一套家规。

---

五、跨工具统一：AGENTS.md 开放标准

好消息是，行业正在收敛到一个开放标准：agents.md。

越来越多工具（Claude Code、Copilot、Codex、Gemini CLI、Cursor 也在兼容）开始同时识别 AGENTS.md、CLAUDE.md、GEMINI.md。这意味着你维护一份 AGENTS.md 就能通吃多个 AI 工具，不用为每个 IDE 各写一份。

实践建议：

• 新项目直接建 AGENTS.md 作为主规则文件；
• 需要 Cursor 精确 glob 控制时，再补 .cursor/rules/*.mdc；
• 用 Repomix 这类工具把仓库打包成 AI 友好的上下文，配合规则文件效果更好。

---

六、选型建议

• 只用 Cursor：直接上 .cursor/rules/*.mdc，按模块拆分最爽。
• 只用 Claude Code / Codex / Gemini：一份 AGENTS.md 或 CLAUDE.md 搞定。
• 团队混用多个工具：以 AGENTS.md 为单一事实来源，其余按需补充。
• 长期陪伴式开发（如 vibe coding）：选带"身份+记忆+技能"体系的 Agent（如 CodeBuddy），把家规写进 SOUL.md 和技能包。

---

七、结语

规约文件是 AI Coding 时代最被低估的"杠杆"——写一次，省下你和 AI 之间无数次无效的来回。它的本质不是约束 AI，而是把你对项目的隐性知识显性化、可版本化、可传承。

别再每次都跟 AI 重复"我们用 pnpm"了。花十分钟写一份 AGENTS.md，你会发现 AI 突然"懂事"了。

---