第十一章：AI 编程的“规则文件”体系（instructions.md / prompts.md / agents.md 全解）
🎧
2026 年，AI 编程已经从“调教对话框”进化到了“配置工程化”阶段。不再是把所有指令塞进一个巨大的 .cursorrules 文件，而是采用 instructions.md（规则约束）+ prompts.md（任务模板）+ agents.md（专家角色） 的三层模块化架构。本文将深度解析这套体系的设计哲学、文件规范以及如何在 Cursor、Trae 和 GitHub Copilot 中实战落地，助你构建工业级的 AI 编程工作流。
核心要点
•
上下文工程化：通过分层文件管理，避免 AI 上下文过载，确保核心规则不被杂讯淹没。
•
职责解耦：Instructions 负责“怎么写”，Prompts 负责“做什么”，Agents 负责“谁来做”。
•
跨平台兼容：虽然不同 IDE 目录名不同，但核心的 Markdown 指令文件可以实现高度复用。
•
团队共识：将规则文件提交至 Git 仓库，实现团队编码风格与工程标准的自动化强制执行。
从单文件到模块化：AI 编程的进化
早期的 AI 编程往往依赖于一个单一的配置文件（如 .cursorrules）。然而，随着项目规模的扩大，单文件模式暴露出严重的弊端：
Token 噪音：AI 需要在每次对话中阅读所有规则，即便当前任务与之无关，这既浪费 Token 又分散了 AI 的注意力。
指令冲突：在同一个文件中定义过多的约束，容易导致 AI 在执行时产生矛盾或忽略关键条目。
难以维护：团队协作时，一个巨大的 Markdown 文件极易产生合并冲突（Merge Conflict）。
模块化体系通过“按需加载”解决了这些问题，将通用的编码规范、特定的任务模板和专业的专家人格进行解耦。
三层架构详解：分而治之的艺术
Instructions：持久化的“入职手册”
文件定位：instructions.md（或 .trae/rules/*.md, .cursor/rules/*.mdc）
Instructions 定义了项目的“默认人格”。它通常包含：
•
技术栈声明：项目使用的框架、库及其版本（如 Next.js 14, Tailwind CSS）。
•
编码风格：命名规范、文件结构、Hooks 使用守则。
•
硬性约束：禁止使用的库、必须遵守的安全规范。
Prompts：高效的“标准作业程序”
文件定位：prompts.md（或 .github/prompts/*.prompt.md）
Prompts 是可复用的任务模板。与 Instructions 不同，它们不是始终开启的，而是当你需要执行特定任务时手动或自动触发的。
•
代码审查清单：针对 PR 的检查步骤。
•
测试生成模板：定义如何为不同类型的组件编写单元测试。
•
重构工作流：将旧代码迁移到新架构的标准化步骤。
Agents：专业的“领域专家”
文件定位：agents.md（或 AGENTS.md, .trae/agents/*.md）
Agents 是具有特定能力边界的独立人格。它们拥有自己的一套指令和工具。
•
SRE Agent：专注于分析日志、定位性能瓶颈和修复 CI 失败。
•
UI/UX Agent：专注于组件的视觉一致性、无障碍访问（A11y）和交互细节。
•
Security Agent：专门负责扫描代码漏洞和敏感信息泄露。
工作流架构图
下面的流程图展示了当开发者发起一个请求时，AI 如何组合这三层文件：
实战配置示例
Instructions 示例 (code-style.md)
代码块
Markdown
---
applyTo: "src/**/*.tsx"
---
# React 开发规范
- **组件写法**：统一使用函数式组件 (Arrow Functions)。
- **Props 处理**：必须使用 TypeScript interface 解构 Props。
- **状态管理**：优先使用局部状态，复杂逻辑封装为自定义 Hooks。
- **禁止事项**：禁止在组件内直接写死颜色 Hex 值，必须使用 Tailwind 主题变量。
Prompts 示例 (unit-test.prompt.md)
代码块
Markdown
# 任务：生成 Jest 单元测试
请为当前文件生成测试代码。要求：
代码块
Plain Text
### 3. Agents 示例 (ReviewerAgent.md)
```markdown
# Role: 高级代码审查专家
你是一个极其严苛的代码审查员。你的职责是：
1. **性能**：检查是否存在多余的渲染或内存泄漏。
2. **安全**：识别潜在的 XSS、CSRF 或逻辑漏洞。
主流 IDE 适配指南
#XWOUEiObAFNQ text{white-space:pre}.fb0{stroke:var(--N900-FG, 0.15)}.fx0{stroke-miterlimit:10}.fa1{fill:#bbbfc4}.fx1{font:normal 400 12px MonospacedNumber,LarkHackSafariFont,LarkEmojiFont,LarkChineseQuote,-apple-system,BlinkMacSystemFont,Helvetica Neue,Tahoma,PingFang SC,Microsoft Yahei,Arial,Hiragino Sans GB,sans-serif,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji}.fx2{text-anchor:middle}.fx3{dominant-baseline:central}.fx4{stroke:none}.fc0{fill:var(--text-caption)}.fa2{fill:var(--text-link-disabled)}.fa3{fill:#1f2329}.fx5{font:400 normal 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"}.fx6{text-anchor:start}.fx7{dominant-baseline:alphabetic}.fc1{fill:#ffffff}.fx8{font:700 normal 16px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"}.fc2{fill:rgb(51, 51, 51)}.fx9{font:400 normal 14px LarkHackSafariFont, LarkEmojiFont, "Fira Code", -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, "Noto Sans", Tahoma, "Nimbus Sans L", Arial, "Liberation Sans", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", "Microsoft YaHei", "Wenquanyi Micro Hei", "WenQuanYi Zen Hei", STHeiti, SimHei, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", system-ui}.fc3{fill:rgb(139, 92, 246)}.fb1{fill:var(--N900-FG, 0.15)}.fb2{fill:rgb(225, 228, 232)}.fa4{fill:var(--bg-body)}ABCD12345文件类型GitHub CopilotCursor (MDC)Trae (Rules/Agents)InstructionsPromptsAgentsSkills.github/instructions/*.instructions.md.github/prompts/*.prompt.md.github/agents/*.md.github/skills/.cursor/rules/*.mdcAGENTS.md.trae/rules/*.md.trae/agents/*.md.trae/skills/暂称官方目录 (建议用 MDC) (社区规范)暂无暂无官方目录
最佳实践与常见误区
保持原子化：一个规则文件只讲一件事。如果 code-style.md 超过 100 行，考虑拆分为 ui-style.md 和 api-logic.md。
路径精准匹配：利用 applyTo 或 paths 字段，确保 CSS 规则不会被推送到后端代码中，从而节省 Token。
定期清理：随着 AI 模型的升级，有些旧的指令（如“不要返回重复的代码”）AI 已经默认做得很好了，可以从规则中移除。
避免模糊表述：
◦
❌ 错误：请尽量写注释。
◦
✅ 正确：每个导出的函数必须包含 JSDoc 注释，说明参数和返回值类型。
总结
AI 编程的规则文件体系不仅仅是几个 Markdown 文件的堆砌，它是 “人机协作协议” 的具象化。通过 instructions.md 建立共识，通过 prompts.md 沉淀流程，通过 agents.md 扩展能力，你正在为你的代码库建立一套自动化的、智能的“工程防线”。
现在就开始清理你那个巨大的配置文件，拥抱模块化架构吧！