AGENTS.md 实战用 100 行规则文件让 AI 编程工具秒懂你的全栈项目2026 年AI 生成的代码已占全部 Pull Request 的 27.6%。但每个用过 Claude Code、Cursor 或 Copilot 的全栈开发者都会遇到同一个噩梦AI 助手每次都失忆——不知道你们用 pnpm 还是 npm、不知道 API 层不能写业务逻辑、不知道测试必须跑在提交前。于是它信心满满地生成一堆能用但不合规矩的代码。一、引言规则文件正在成为项目文档的新形态原因很简单每个编码 Agent 在每次会话开始时对你的项目都是一无所知的。它知道怎么写 TypeScript但不知道你们团队用 Pixi 而不是 pip、API client 从不抛异常、vendor/ 目录永远不许动。在 2025 年这些约定靠人肉重复提醒2026 年行业收敛出了一个跨工具标准——AGENTS.md以及它的各平台亲戚Claude Code 的 CLAUDE.md、Cursor 的 .cursor/rules、GitHub Copilot 的 copilot-instructions.md。本质就一句话把入职培训写成文件、提交进 Git让每个 Agent 每次开工前自动读完。这不是文档洁癖而是效率杠杆——规则文件写得好AI 生成的代码通过 Code Review 的概率大幅提升返工成本直线下降。| 文件 | 工具 | 作用域 | 特点 || --- | --- | --- | --- || AGENTS.md | Codex / 跨工具标准 | 仓库级 | 厂商中立2026 年正在收敛为事实标准 || CLAUDE.md | Claude Code | 仓库 / 子目录级 | 支持路径过滤、自动记忆auto-memory || .cursor/rules/*.md | Cursor | glob 精准作用域 | YAML frontmatter 声明命中规则 || copilot-instructions.md | GitHub Copilot | 仓库 / 路径级 | 跟随 GitHub 生态.github/ 目录管理 |二、核心原理为什么规则文件能改变 Agent 的行为编码 Agent 的工作方式决定了规则文件的价值。每次会话开始时模型只会收到系统提示、用户消息和你喂给它的文件内容——它对你项目的全部认知来自本次会话注入的上下文。没有规则文件时Agent 只能从代码里猜测约定看到一半用 pnpm、一半用 npm 的仓库它会随机选一个看到路由里混着裸 SQL它会认为这是被允许的。规则文件的作用是把团队约定从隐性的口头知识变成每次会话都稳定注入的显式上下文。这里有一个关键机制大多数编码工具Claude Code、Cursor、Copilot会在会话启动时自动把规则文件加入上下文并常常在用户 Prompt 之前注入——这意味着规则天然处于指令优先位置比散落在代码里的约定更容易被模型遵守。但机制也有边界上下文越长模型对中后段内容的遵从度越低lost in the middle。所以规则文件的设计铁律是——短、前置、可执行只写默认之外的约定最重要的规则放在文件开头再用 lint 与测试让规则具备物理约束力。三、实战为全栈 monorepo 写一份合格的 AGENTS.md以一个 Next.js 15 前端 FastAPI 后端的 monorepo 为例。核心原则短。编码 Agent 每个会话都读这份文件写得像宪法一样长等于没写——关键规则会被lost in the middle效应淹没# AGENTS.md ## 项目概览 - 前端Next.js 15App Router TypeScript位于 apps/web - 后端FastAPIPython 3.12 SQLAlchemy 2位于 apps/api - 包管理根目录 pnpm workspace后端依赖用 uv禁止 pip 裸装 ## 编码规则只写与默认不同的约定 - 所有 TS 文件必须显式类型标注禁止 any 逃生舱 - API 路由只做参数校验与转发业务逻辑一律放 services/ 层 - 数据库访问必须走 repositories/ 模式禁止路由里写裸 SQL - 新增接口必须配套 Pydantic 响应模型自动生成 OpenAPI 文档 ## 目录结构 - apps/web/src/app/ 页面路由薄层 - apps/web/src/components/ 展示组件 - apps/api/app/services/ 业务逻辑核心别绕过 - apps/api/app/repositories/ 数据访问唯一允许碰 ORM 的地方 ## 测试与提交 - 改动必须补测试前端 vitest后端 pytest - 提交信息遵循 Conventional Commitsfeat/fix/docs/refactor - 提交前必须跑 pnpm lint 与 uv run pytest全绿才允许提交 - 禁止修改 apps/legacy/ 目录历史包袱只读看到没有——只写与默认不同的规则类型标注、分层边界、包管理器选择。这些正是 Agent 默认会做错、而人肉重复提醒成本最高的地方。四、代码实战让规则可执行、可命中3.1 Cursor用 glob 让规则精准命中大 monorepo 里一份文件管全局要么太泛要么太长。Cursor 的 .cursor/rules/ 支持 YAML frontmatter 按文件路径精准命中——后端规则只对 Python 文件生效--- description: 后端服务层规则 globs: apps/api/**/*.py --- - 函数必须有类型注解与 docstring - 异步接口优先 async def - service 层禁止 import models 之外的 ORM 细节 - 抛出领域异常不裸抛 SQLAlchemyError--- description: 前端组件规则 globs: apps/web/src/components/**/*.tsx --- - 组件默认服务端组件需要交互才加 use client - props 一律用 interface 定义并导出 - 禁止内联样式使用 tailwind 工具类3.2 Claude Code子目录级 CLAUDE.md 与防串扰Claude Code 支持子目录级 CLAUDE.mdapps/api/CLAUDE.md 只描述后端约定。monorepo 场景还要防指令串扰——用 claudeMdExcludes 阻止根目录规则在无关目录生效// .claude/settings.json —— 防止大 monorepo 指令串扰 { claudeMdExcludes: { apps/legacy/**: [root], apps/web/**: [apps/api] } }3.3 让规则可执行pre-commit 兜底规则文件写得再好也要有物理校验。AI 生成的代码同样逃不过 pre-commit——规则 钩子 双保险#!/usr/bin/env bash # .githooks/pre-commit —— AI 生成的代码也过不了这关 set -euo pipefail echo 前端检查 npx eslint apps/web/src --max-warnings 0 echo 后端检查 uv run ruff check apps/api echo 测试 uv run pytest apps/api/tests -q配上提交给 Agent 的任务 Prompt形成完整闭环请按 AGENTS.md 实现查询订单详情接口apps/api 1. 先读 AGENTS.md 与 services/ 现有代码保持分层与风格一致 2. 先写 pytest 测试再实现TDD测试要覆盖 404 分支 3. 完成运行 uv run pytest 并汇报结果 4. 只改 apps/api禁止触碰 apps/legacy五、2026 最新演进规则文件的三条最佳实践1.提交进 Git而不是存在用户目录~/.claude/settings.json 这类用户级配置只有你自己受益把 AGENTS.md 提交进仓库整个团队和 CI 里的 Agent才站在同一起跑线。2.警惕静默规则丢失已有多起 Claude Code 在长会话中忽略 CLAUDE.md 的案例——这正是lost in the middle。对策文件保持短核心规则放最前面、长任务拆新会话、关键约束在 Prompt 里再强调一次。3.从规则文件走向自动记忆Claude Code 的 auto-memory 已能在跨会话间积累项目知识AGENTS.md 是静态基线记忆是动态补充——两者配合规则文件仍将长期存在但会越来越薄。六、总结与行动建议5 个关键结论• AGENTS.md 是 2026 年编码 Agent 的入职培训文件跨工具收敛已成定局• 只写与默认不同的规则——包管理器、分层边界、测试要求别写正确的废话• Cursor 用 glob 精准命中、Claude Code 用子目录 excludes 防串扰• 规则 pre-commit 钩子双保险AI 代码也逃不过 lint 与测试• 文件越短越有效核心规则放开头长会话及时拆开。3 个行动建议1. 本周给主项目写第一版 AGENTS.md30 行以内让 Claude Code / Cursor 各跑一个任务对比效果2. 本月补上 .cursor/rules 的 glob 规则与 pre-commit 钩子把规则变成物理约束3. 本季度把规则文件评审纳入 Code Review 流程用AI 代码一次通过率量化规则收益。参考资料Agents.md 社区规范MorphLLM《AGENTS.md Spec (2026)》Anthropic Claude Code 文档Marmelab《Agent Experience: Best Practices for Coding Agent Productivity》(2026-01)Cursor Rules 官方文档。时效性提示各工具对规则文件的支持仍在快速演进建议 3 个月内复核一次新特性auto-memory、subagent 规则继承等。
AGENTS.md 实战用 100 行规则文件让 AI 编程工具秒懂你的全栈项目2026 年AI 生成的代码已占全部 Pull Request 的 27.6%。但每个用过 Claude Code、Cursor 或 Copilot 的全栈开发者都会遇到同一个噩梦AI 助手每次都失忆——不知道你们用 pnpm 还是 npm、不知道 API 层不能写业务逻辑、不知道测试必须跑在提交前。于是它信心满满地生成一堆能用但不合规矩的代码。一、引言规则文件正在成为项目文档的新形态原因很简单每个编码 Agent 在每次会话开始时对你的项目都是一无所知的。它知道怎么写 TypeScript但不知道你们团队用 Pixi 而不是 pip、API client 从不抛异常、vendor/ 目录永远不许动。在 2025 年这些约定靠人肉重复提醒2026 年行业收敛出了一个跨工具标准——AGENTS.md以及它的各平台亲戚Claude Code 的 CLAUDE.md、Cursor 的 .cursor/rules、GitHub Copilot 的 copilot-instructions.md。本质就一句话把入职培训写成文件、提交进 Git让每个 Agent 每次开工前自动读完。这不是文档洁癖而是效率杠杆——规则文件写得好AI 生成的代码通过 Code Review 的概率大幅提升返工成本直线下降。| 文件 | 工具 | 作用域 | 特点 || --- | --- | --- | --- || AGENTS.md | Codex / 跨工具标准 | 仓库级 | 厂商中立2026 年正在收敛为事实标准 || CLAUDE.md | Claude Code | 仓库 / 子目录级 | 支持路径过滤、自动记忆auto-memory || .cursor/rules/*.md | Cursor | glob 精准作用域 | YAML frontmatter 声明命中规则 || copilot-instructions.md | GitHub Copilot | 仓库 / 路径级 | 跟随 GitHub 生态.github/ 目录管理 |二、核心原理为什么规则文件能改变 Agent 的行为编码 Agent 的工作方式决定了规则文件的价值。每次会话开始时模型只会收到系统提示、用户消息和你喂给它的文件内容——它对你项目的全部认知来自本次会话注入的上下文。没有规则文件时Agent 只能从代码里猜测约定看到一半用 pnpm、一半用 npm 的仓库它会随机选一个看到路由里混着裸 SQL它会认为这是被允许的。规则文件的作用是把团队约定从隐性的口头知识变成每次会话都稳定注入的显式上下文。这里有一个关键机制大多数编码工具Claude Code、Cursor、Copilot会在会话启动时自动把规则文件加入上下文并常常在用户 Prompt 之前注入——这意味着规则天然处于指令优先位置比散落在代码里的约定更容易被模型遵守。但机制也有边界上下文越长模型对中后段内容的遵从度越低lost in the middle。所以规则文件的设计铁律是——短、前置、可执行只写默认之外的约定最重要的规则放在文件开头再用 lint 与测试让规则具备物理约束力。三、实战为全栈 monorepo 写一份合格的 AGENTS.md以一个 Next.js 15 前端 FastAPI 后端的 monorepo 为例。核心原则短。编码 Agent 每个会话都读这份文件写得像宪法一样长等于没写——关键规则会被lost in the middle效应淹没# AGENTS.md ## 项目概览 - 前端Next.js 15App Router TypeScript位于 apps/web - 后端FastAPIPython 3.12 SQLAlchemy 2位于 apps/api - 包管理根目录 pnpm workspace后端依赖用 uv禁止 pip 裸装 ## 编码规则只写与默认不同的约定 - 所有 TS 文件必须显式类型标注禁止 any 逃生舱 - API 路由只做参数校验与转发业务逻辑一律放 services/ 层 - 数据库访问必须走 repositories/ 模式禁止路由里写裸 SQL - 新增接口必须配套 Pydantic 响应模型自动生成 OpenAPI 文档 ## 目录结构 - apps/web/src/app/ 页面路由薄层 - apps/web/src/components/ 展示组件 - apps/api/app/services/ 业务逻辑核心别绕过 - apps/api/app/repositories/ 数据访问唯一允许碰 ORM 的地方 ## 测试与提交 - 改动必须补测试前端 vitest后端 pytest - 提交信息遵循 Conventional Commitsfeat/fix/docs/refactor - 提交前必须跑 pnpm lint 与 uv run pytest全绿才允许提交 - 禁止修改 apps/legacy/ 目录历史包袱只读看到没有——只写与默认不同的规则类型标注、分层边界、包管理器选择。这些正是 Agent 默认会做错、而人肉重复提醒成本最高的地方。四、代码实战让规则可执行、可命中3.1 Cursor用 glob 让规则精准命中大 monorepo 里一份文件管全局要么太泛要么太长。Cursor 的 .cursor/rules/ 支持 YAML frontmatter 按文件路径精准命中——后端规则只对 Python 文件生效--- description: 后端服务层规则 globs: apps/api/**/*.py --- - 函数必须有类型注解与 docstring - 异步接口优先 async def - service 层禁止 import models 之外的 ORM 细节 - 抛出领域异常不裸抛 SQLAlchemyError--- description: 前端组件规则 globs: apps/web/src/components/**/*.tsx --- - 组件默认服务端组件需要交互才加 use client - props 一律用 interface 定义并导出 - 禁止内联样式使用 tailwind 工具类3.2 Claude Code子目录级 CLAUDE.md 与防串扰Claude Code 支持子目录级 CLAUDE.mdapps/api/CLAUDE.md 只描述后端约定。monorepo 场景还要防指令串扰——用 claudeMdExcludes 阻止根目录规则在无关目录生效// .claude/settings.json —— 防止大 monorepo 指令串扰 { claudeMdExcludes: { apps/legacy/**: [root], apps/web/**: [apps/api] } }3.3 让规则可执行pre-commit 兜底规则文件写得再好也要有物理校验。AI 生成的代码同样逃不过 pre-commit——规则 钩子 双保险#!/usr/bin/env bash # .githooks/pre-commit —— AI 生成的代码也过不了这关 set -euo pipefail echo 前端检查 npx eslint apps/web/src --max-warnings 0 echo 后端检查 uv run ruff check apps/api echo 测试 uv run pytest apps/api/tests -q配上提交给 Agent 的任务 Prompt形成完整闭环请按 AGENTS.md 实现查询订单详情接口apps/api 1. 先读 AGENTS.md 与 services/ 现有代码保持分层与风格一致 2. 先写 pytest 测试再实现TDD测试要覆盖 404 分支 3. 完成运行 uv run pytest 并汇报结果 4. 只改 apps/api禁止触碰 apps/legacy五、2026 最新演进规则文件的三条最佳实践1.提交进 Git而不是存在用户目录~/.claude/settings.json 这类用户级配置只有你自己受益把 AGENTS.md 提交进仓库整个团队和 CI 里的 Agent才站在同一起跑线。2.警惕静默规则丢失已有多起 Claude Code 在长会话中忽略 CLAUDE.md 的案例——这正是lost in the middle。对策文件保持短核心规则放最前面、长任务拆新会话、关键约束在 Prompt 里再强调一次。3.从规则文件走向自动记忆Claude Code 的 auto-memory 已能在跨会话间积累项目知识AGENTS.md 是静态基线记忆是动态补充——两者配合规则文件仍将长期存在但会越来越薄。六、总结与行动建议5 个关键结论• AGENTS.md 是 2026 年编码 Agent 的入职培训文件跨工具收敛已成定局• 只写与默认不同的规则——包管理器、分层边界、测试要求别写正确的废话• Cursor 用 glob 精准命中、Claude Code 用子目录 excludes 防串扰• 规则 pre-commit 钩子双保险AI 代码也逃不过 lint 与测试• 文件越短越有效核心规则放开头长会话及时拆开。3 个行动建议1. 本周给主项目写第一版 AGENTS.md30 行以内让 Claude Code / Cursor 各跑一个任务对比效果2. 本月补上 .cursor/rules 的 glob 规则与 pre-commit 钩子把规则变成物理约束3. 本季度把规则文件评审纳入 Code Review 流程用AI 代码一次通过率量化规则收益。参考资料Agents.md 社区规范MorphLLM《AGENTS.md Spec (2026)》Anthropic Claude Code 文档Marmelab《Agent Experience: Best Practices for Coding Agent Productivity》(2026-01)Cursor Rules 官方文档。时效性提示各工具对规则文件的支持仍在快速演进建议 3 个月内复核一次新特性auto-memory、subagent 规则继承等。
