为AI代码助手编写项目说明书AGENTS.md：提升生成代码质量与一致性

1. 从“会写代码”到“写好代码”为什么你的AI助手需要一份说明书最近和几个团队的技术负责人聊天发现一个挺有意思的现象大家给新来的实习生或者初级工程师做项目交接时都会花不少时间整理一份详尽的“Onboarding文档”里面会写清楚项目的架构、核心模块、编码规范、部署流程甚至是一些“祖传”的坑位和黑话。但当我们把AI代码助手比如GitHub Copilot、Cursor、Claude Code或者各种本地部署的大模型引入工作流时却常常期望它“无师自通”直接就能写出符合我们团队特定要求的、高质量的代码。这其实是个挺大的认知偏差。我们潜意识里把AI助手当成了一个“全知全能”的超级程序员但实际上它更像是一个天赋极高但缺乏上下文和经验的“实习生”。你如果不告诉它项目的技术栈偏好、目录结构规范、代码风格要求它就只能基于其训练数据中的“大众平均”水平来生成代码。结果就是你可能会得到一段语法正确、逻辑也没大毛病但就是和你项目现有代码格格不入的“陌生代码”。你需要花时间去调整缩进、修改命名、重构导入语句甚至纠正一些因为不了解项目特定业务逻辑而导致的错误假设。所以“AGENTS.md”这个想法的核心价值就在这里它是一份专门写给AI代码助手的“项目说明书”。它不是替代你给人类同事写的README而是作为README的一个强力补充旨在将AI助手的输出质量从一个“通用及格线”拉升到“项目优秀线”。我自己的体验是自从在项目根目录维护了一个简单的.cursorrules文件这是Cursor编辑器支持的一种AI指令文件或者一个更通用的AGENTS.md文件后AI生成代码的“开箱即用率”提升了至少50%沟通成本大大降低。2. AGENTS.md的核心构成不止是技术栈列表一份有效的AGENTS.md绝不仅仅是把package.json里的依赖项再罗列一遍。它的目标是构建一个完整的“项目上下文”让AI能站在项目现有代码的基础上进行创作和修改。根据我过去半年在多个TypeScript/React全栈项目中的实践我认为它应该包含以下几个层次的信息。2.1 项目元信息与核心约束这是最基础的一层目的是让AI快速定位项目的“身份”和“边界”。项目技术栈与版本这需要非常精确。例如你不能只写“使用React”而应该写“使用React 18并启用了新的并发特性如useTransition”。对于TypeScript要写明tsconfig.json中的关键配置比如strict: true、moduleResolution: bundler如果用了Vite等。这能防止AI生成基于React 16类组件或宽松TypeScript检查的代码。核心工具与框架列出关键的开发工具。例如构建工具Vite版本号配置了特定的插件如vitejs/plugin-react。路由React Router DOM v6.4使用数据APIcreateBrowserRouter,loader,action。状态管理Zustand并说明是否使用了中间件如persist。HTTP客户端axios并说明项目中封装的实例基地址和拦截器逻辑。UI库Ant Design v5并说明主题定制方式和按需引入配置。测试框架Vitest React Testing Library测试文件位于__tests__目录。绝对禁止与强制要求这是减少“废话”和错误的关键。比如“本项目使用函数组件和React Hooks禁止使用类组件。”“所有组件必须使用named export禁止default export。”“使用Tailwind CSS进行样式编写禁止内联style和单独的.css文件。”“接口响应数据格式统一为{ code: number, data: T, message: string }处理错误时请检查code ! 0。”2.2 代码风格与架构范式这一层是让AI生成的代码在风格上和现有代码库“融为一体”减少格式调整的摩擦。命名规范详细说明各种命名规则。变量/函数使用camelCase。函数名以动词开头如fetchUserData、validateInput。组件使用PascalCase。页面组件放在src/pages/下通用组件放在src/components/下。接口/类型使用PascalCase并以I前缀或Type后缀区分根据团队习惯如IUserProfile或UserProfileType。常量使用UPPER_SNAKE_CASE定义在src/constants/目录。文件命名组件文件使用.tsx工具函数使用.ts。文件命名与默认导出的组件名严格一致。目录结构约定给出一个清晰的路径地图。src/ ├── api/ # 所有API请求封装按模块划分文件 ├── assets/ # 静态资源 ├── components/ # 通用组件 │ ├── common/ # 跨项目通用组件按钮、弹窗 │ └── business/ # 业务相关组件 ├── constants/ # 常量定义 ├── hooks/ # 自定义Hooks ├── pages/ # 页面组件与路由一一对应 ├── stores/ # Zustand状态仓库 ├── types/ # 全局类型定义 ├── utils/ # 工具函数 └── main.tsx告诉AI“创建新页面时请在src/pages/下新建目录并在src/router/index.tsx中注册路由。”特定模式与习惯这些是团队在长期实践中形成的“肌肉记忆”对AI来说却是新知识。“发起请求必须使用src/api/下封装好的函数禁止在组件中直接写axios.get。”“在Zustand store中状态更新请使用set函数并遵循(state) ({ ...state, key: newValue })的范式。”“表单验证使用react-hook-form配合zod模式Schema定义在组件同目录下的schema.ts文件中。”2.3 业务逻辑与领域知识这是最高阶也是最难描述清楚的一层但它对生成代码的正确性至关重要。你需要把那些“只可意会”的业务规则明确化。核心领域实体及其关系用简单的描述定义关键业务对象。例如“User用户对象包含id、name、email和role字段。role枚举值为‘admin‘、‘editor‘、‘viewer‘。”“Article文章对象属于一个User作者拥有status字段其工作流为‘draft‘ - ‘review‘ - ‘published‘ - ‘archived‘。”关键业务流程描述用户完成一个动作的完整路径。例如“文章发布流程”作者在草稿页点击“提交审核”。系统将文章状态置为‘review‘并生成一条通知给所有具有‘editor‘角色的用户。编辑在后台列表看到待审核文章可以“通过”或“驳回”。若通过文章状态变为‘published‘并生成发布时间戳若驳回状态回退为‘draft‘并必须填写驳回理由。外部服务集成约定说明与第三方服务交互的规则。“图片上传统一调用uploadService.uploadImage(file)它返回一个CDN的URL字符串请将这个URL存储到数据库。”“发送短信使用notificationService.sendSMS(phoneNumber, templateCode, params)模板已在管理后台配置。”把这些信息提供给AI后当你提示它“帮我写一个文章发布按钮的点击处理函数”时它就有很大概率生成一个包含了状态检查、API调用、成功/失败提示、以及可能的状态更新和导航逻辑的、更贴合业务的代码片段。3. 实战为你的Next.js项目创建一份AGENTS.md光讲理论有点虚我们直接来看一个为虚构的“TechBlog平台”Next.js 14项目编写的AGENTS.md实例。我会逐段解释为什么这么写。# AI助手项目指南 (AGENTS.md) ## 项目概览 这是一个基于Next.js 14 (App Router) 构建的技术博客平台。使用TypeScript并采用了严格的代码规范。请在设计任何代码或解决方案时以此文件中的约定为最高准则。 ## 技术栈与配置 - **框架**: Next.js 14.2.0使用App Router。所有页面位于app/目录下使用React Server Components (RSC) 作为默认。 - **语言**: TypeScript 5.xtsconfig.json中启用strict: true。 - **样式**: Tailwind CSS v3.4已配置tailwindcss/forms和tailwindcss/typography插件。**禁止**使用任何其他CSS-in-JS库或内联style。 - **UI组件**: shadcn/ui (基于Radix UI)。组件已通过npx shadcnlatest add [component]安装至components/ui/。请优先使用这些现有组件。 - **数据库ORM**: PrismaSchema定义在prisma/schema.prisma中客户端位于lib/prisma.ts。 - **认证**: NextAuth.js v5 (Beta)使用Prisma适配器。会话信息通过auth()函数获取。 - **HTTP客户端**: 服务端使用原生fetch客户端我们封装了lib/axios-client.ts**禁止**在客户端直接使用axios或fetch。 - **状态管理**: 服务端状态通过React Cache和Server Actions管理。简单的客户端全局状态使用Zustand复杂表单状态使用react-hook-form。 ## 绝对规则 1. **组件定义**: 所有React组件必须使用function关键字声明**禁止**使用箭头函数或类组件。 2. **导出方式**: 仅允许export default导出页面组件在app/**/page.tsx中。所有其他组件、函数、常量必须使用named export。 3. **数据获取**: 在Server Component中直接使用async/await获取数据。在Client Component中必须使用useEffect配合我们封装的axios-client或使用SWR/TanStack Query如果该模块已配置。 4. **路径别名**: 项目配置了/*指向./src/*。请始终使用/components/Layout而非相对路径../../components/Layout。 5. **错误处理**: 所有可能失败的异步操作API调用、数据库查询必须用try-catch包裹并使用toast函数来自sonner库提示用户。 ## 目录结构与约定src/ ├── app/ # Next.js App Router 主目录 │ ├── (auth)/ # 认证相关路由组 │ ├── (dashboard)/ # 仪表盘路由组 │ ├── api/ # API Routes (Next.js) │ │ └── trpc/ # tRPC路由器如果使用 │ ├── blog/ # 博客文章页面 │ └── layout.tsx # 根布局 ├── components/ # 共享组件 │ ├── ui/ # shadcn/ui 基础组件 (禁止修改) │ ├── shared/ # 跨功能共享组件 │ └── blog/ # 博客功能专用组件 ├── lib/ # 工具库、配置、数据库客户端 │ ├── prisma.ts # Prisma Client 单例 │ ├── utils.ts # 纯工具函数 │ └── validations.ts # Zod 表单验证模式 ├── hooks/ # 自定义 React Hooks ├── stores/ # Zustand 状态存储 ├── types/ # 全局TypeScript类型定义 └── styles/ # 全局样式仅globals.css## 代码风格 - **命名**: - 组件PascalCase如BlogEditor。 - 函数/变量camelCase如formatPublishedDate。 - 常量UPPER_SNAKE_CASE如API_ENDPOINTS。 - 类型/接口PascalCase不加I前缀如BlogPost。 - **Imports排序**: 1. React/Next.js核心库。2. 第三方库。3. 内部别名路径(/*)。4. 相对路径。每组用空行分隔。 - **Tailwind类排序**: 建议使用prettier-plugin-tailwindcss自动排序。手动编写时遵循“布局 - 盒模型 - 排版 - 视觉 - 其他”的粗略顺序。 ## 业务逻辑要点 - **博客文章(Post)状态**: ‘DRAFT‘ | ‘PUBLISHED‘ | ‘ARCHIVED‘。只有作者和管理员可以编辑DRAFT。PUBLISHED的文章对所有访客可见。 - **评论系统**: 评论支持Markdown预览。发布前会经过内置关键词过滤列表见lib/filter-keywords.ts。用户可编辑或删除自己的评论管理员可删除任何评论。 - **图片处理**: 用户上传的图片通过uploadthing服务处理返回的URL格式为https://utfs.io/f/[fileKey]。请将此完整URL存入数据库Post.featuredImage字段。 ## 示例创建新组件 当被要求创建BlogCard组件时请遵循以下模式 tsx // src/components/blog/BlogCard.tsx import { Card, CardHeader, CardTitle, CardContent } from ‘/components/ui/card‘; import { Badge } from ‘/components/ui/badge‘; import type { BlogPost } from ‘/types/blog‘; interface BlogCardProps { post: BlogPost; } export function BlogCard({ post }: BlogCardProps) { return ( Card className“hover:shadow-lg transition-shadow“ CardHeader div className“flex justify-between items-start“ CardTitle className“text-xl“{post.title}/CardTitle Badge variant“outline“{post.status}/Badge /div p className“text-sm text-muted-foreground“ By {post.author.name} · {formatDate(post.publishedAt)} /p /CardHeader CardContent p className“line-clamp-2“{post.excerpt}/p /CardContent /Card ); } // 工具函数应定义在单独的文件中此处仅为示例 function formatDate(date: Date) { return new Intl.DateTimeFormat(‘en-US‘).format(date); }这份AGENTS.md已经具备了相当的指导性。它从技术栈、硬性规则、目录结构、代码风格一直深入到业务逻辑并给出了一个具体的组件示例作为“模板”。AI助手在生成代码时会极大地参考这里的约束。 ## 4. 如何让AI“读懂”并应用你的AGENTS.md 创建了文件只是第一步关键在于如何让AI助手在每次交互时都能“看到”并“理解”这份说明书。不同的工具和场景下策略有所不同。 **策略一置于项目根目录并显式引用通用法** 最简单的方法就是将AGENTS.md或.cursorrules、.aider.md取决于你的AI工具放在项目根目录。像Cursor这类深度集成的编辑器会自动读取这些文件中的指令作为上下文。对于其他通过聊天界面交互的AI如ChatGPT、Claude你需要在开启一个新对话或新的代码任务时手动将这份文件的内容粘贴进去并加上一句指令“以下是我项目的开发规范AGENTS.md请你在后续所有代码生成和修改中严格遵守。” 这相当于给AI进行了一次“项目初始化培训”。 **策略二利用IDE插件或项目级配置进阶法** 一些高级玩法可以做到更自动化。例如在VS Code中你可以使用“CodeGPT”或“Continue”等插件它们允许你设置项目级别的“自定义指令”Custom Instructions。你可以把AGENTS.md的核心内容提炼进去。这样只要在该项目下使用插件这些指令就会自动生效。对于团队协作可以将这个配置文件如.continuerc.json提交到代码库确保所有成员使用的AI助手都遵循同一套标准。 **策略三分场景拆解与动态提示精准法** AGENTS.md可能内容很多而AI的上下文窗口是有限的。我们可以将其拆解成几个部分在特定场景下动态提供。 - **全局配置**包含技术栈、绝对规则等在项目初始化或解决复杂问题时提供。 - **组件开发指南**当AI正在编写一个React组件时你可以提示它“请参考我们项目的组件规范函数声明、命名导出、Tailwind样式来编写。” - **API交互指南**当需要写数据获取逻辑时提示它“根据项目约定在Client Component中请使用lib/axios-client进行请求并处理错误toast。” 一个关键技巧是**在提出具体编码请求前先给AI“划定范围”**。比如不要直接说“写一个登录表单”而是说“根据我们的AGENTS.md使用Next.js 14 App Router、shadcn/ui组件、react-hook-form with zod请创建一个登录页面组件路径在app/(auth)/login/page.tsx。” 这样AI从一开始就被引导到了正确的方向上。 ## 5. 维护AGENTS.md一个持续迭代的活文档 AGENTS.md不是一份一劳永逸的静态文档。随着项目演进、技术栈更新、团队形成新的最佳实践它也需要不断更新。我的经验是把它当成一个“活文档”来维护。 **何时更新** 1. **技术栈升级**比如从Next.js 13升级到14并启用了App Router那么关于页面结构、数据获取方式的描述就必须更新。 2. **引入新库或模式**团队决定用TanStack Query替代一部分Zustand的用法或者引入了tRPC就需要在文档中增加相应的章节和示例。 3. **踩坑后的经验固化**当团队发现某种写法容易导致Bug并形成了新的规避模式时就应该把它写成一条“规则”加入AGENTS.md。例如“发现useEffect中直接设置状态可能导致无限循环请使用useCallback包装函数或使用useRef记录依赖。” 4. **代码审查中的高频问题**如果Code Review中反复出现同一类风格或架构问题比如滥用any类型、组件内逻辑过于臃肿就可以将对应的规范写得更明确、更具体。 **如何维护** 建议将AGENTS.md纳入版本控制如Git它的变更应该像源代码一样被审查。可以在团队内设立一个简单的规则任何对项目开发规范有影响的决策或变更都需要同步更新AGENTS.md。甚至可以将“更新AGENTS.md”作为相关任务卡Ticket的一项子任务。 一个更工程化的做法是将AGENTS.md中的一些绝对规则如命名规范、禁止使用的API通过ESLint、Prettier、TypeScript严格模式等工具进行自动化检查。这样AI生成的代码如果违反规则在保存时就会被自动纠正或报错形成“文档定义规则工具强制执行”的闭环。 ## 6. 效果评估与常见问题排错 引入AGENTS.md后如何判断它是否真的起了作用可以从以下几个维度来评估 **1. 代码生成的一次通过率**观察AI生成的代码片段在不做或只做极少修改的情况下就能直接融入项目、通过代码风格检查、甚至能正确运行的比例是否提高了。你可以记录一下在引入AGENTS.md前后针对同一个中等复杂度的功能请求如“创建一个带搜索和分页的数据表格”你需要反馈多少次“这里不对要按我们的规范来改”。 **2. 提示词的简化和精准化**以前你可能需要写很长的提示词“用React函数组件写一个模态框要用Tailwind CSS按钮用shadcn的Button状态用useState管理要有打开关闭逻辑……” 现在有了AGENTS.md作为背景你的提示词可以变得更简洁“创建一个新增用户的模态框组件UserCreateModal。” AI会自动套用已知的框架、UI库和状态管理范式。 **3. 团队新人/AI的融入速度**对于新加入项目的工程师AGENTS.md同样是一份极佳的入门指南。他可以快速了解项目的技术选型和代码风格。同理一个配置好的AI助手其行为就像一个熟悉项目的老手减少了团队成员在代码风格和理解上的一致性成本。 当然这个过程不会一帆风顺可能会遇到一些问题 **问题一AI“忘记”或“无视”了AGENTS.md中的规则。** 这通常是因为上下文长度限制或AI的注意力机制导致的。**解决方案**对于非常重要的核心规则如“禁止使用类组件”可以在每次对话开始时用一两句话简要重申。或者将AGENTS.md拆分成几个更聚焦的小文件如STYLE-GUIDE.md、ARCHITECTURE.md在需要时分别提供。 **问题二AGENTS.md中的规则与现有代码库存在冲突。** 例如文档说“全部使用函数组件”但项目里遗留了一些类组件。这会让AI困惑。**解决方案**在AGENTS.md中明确说明这种历史遗留情况。“本项目目前主要使用函数组件。尽管存在少量历史遗留的类组件如src/legacy/目录下的但所有**新代码**必须使用函数组件。请不要以旧代码作为范例。” **问题三规则写得过于死板扼杀了AI的创造性。** 比如规定所有组件都必须用某种固定的模式可能导致生成的代码僵化。**解决方案**AGENTS.md的定位是“规范”和“最佳实践”而不是“唯一解”。在描述规则时多用“优先使用”、“推荐”、“除非有特殊理由否则应……”这样的措辞而非绝对的“必须”。同时保留一个“例外情况说明”的章节描述在何种特殊场景下可以打破常规并说明理由。 从我个人的实践来看维护一份AGENTS.md所花费的少量时间在提升AI编码效率、减少代码审查摩擦、保持代码库一致性方面带来的回报是巨大的。它本质上是一种“基础设施投资”将团队的知识和规范沉淀下来不仅服务于AI也服务于每一个项目成员。