第二十七课：编写高质量 AGENTS.md

学习目标

• 掌握 AGENTS.md 的编写规范和最佳实践
• 了解常见错误和避免方法
• 学会分析优秀的 AGENTS.md 示例

一、结构规范

一个高质量的 AGENTS.md 应该包含以下部分：

1.1 项目概述

简短描述项目的用途和技术栈：

## 项目概述
这是一个电商后台管理系统，使用 Next.js 14 + Prisma + PostgreSQL。

1.2 环境设置

列出所有必要的命令：

## 环境设置
- 安装依赖：pnpm install
- 数据库迁移：pnpm prisma migrate dev
- 启动开发：pnpm dev
- 运行测试：pnpm test
- 代码检查：pnpm lint

1.3 代码规范

定义编码风格和约定：

## 代码规范
- 使用 TypeScript 严格模式
- 组件使用 PascalCase 命名
- 工具函数使用 camelCase 命名
- 使用 ESLint + Prettier 格式化
- 提交信息遵循 Conventional Commits

1.4 测试指南

说明如何编写和运行测试：

## 测试指南
- 单元测试：使用 Vitest
- E2E 测试：使用 Playwright
- 测试文件命名：*.test.ts
- 运行所有测试：pnpm test
- 运行特定测试：pnpm test -- -t "test name"

1.5 项目结构

描述目录结构和文件组织：

## 项目结构
- src/app：Next.js App Router 页面
- src/components：React 组件
- src/lib：工具函数和配置
- prisma：数据库 schema 和迁移
- public：静态资源

二、最佳实践

2.1 保持简洁

AGENTS.md 应该简洁明了，只包含代理需要的信息。避免：

• 过于详细的项目历史
• 与代理无关的信息
• 重复的内容

2.2 使用具体命令

提供可直接执行的命令，而非模糊的描述：

# 好的写法
- 运行测试：pnpm test

# 不好的写法
- 运行测试（使用项目的测试框架）

2.3 包含常见问题

如果项目有已知的坑或特殊处理，应该记录：

## 已知问题
- Node.js 版本需要 18+
- 首次运行需要创建 .env.local 文件
- Prisma 生成需要在 migrate 之后执行

2.4 定期更新

AGENTS.md 应该随着项目发展而更新，保持与项目实际状态一致。

三、常见错误

3.1 过于冗长

AGENTS.md 不是项目文档，不需要包含所有信息。只包含代理需要的关键信息。

3.2 描述模糊

避免使用模糊的描述，如"使用项目的测试框架"。应该明确指出使用什么框架。

3.3 不更新

AGENTS.md 如果不更新，会误导代理。应该定期检查和更新。

四、优秀示例分析

# AGENTS.md

## 项目概述
Next.js 14 电商后台，使用 App Router + Server Components。

## 快速开始
pnpm install
cp .env.example .env.local
pnpm prisma migrate dev
pnpm dev

## 开发规范
- 组件：src/components/，使用 shadcn/ui
- 页面：src/app/，使用 Server Components
- API：src/app/api/，使用 Route Handlers
- 数据库：Prisma，schema 在 prisma/schema.prisma

## 测试
pnpm test          # Vitest 单元测试
pnpm test:e2e      # Playwright E2E

## 部署
推送到 main 自动部署到 Vercel。

五、本课小结

要点	说明
结构	概述→设置→规范→测试→结构
最佳实践	简洁、具体、包含问题、定期更新
常见错误	冗长、模糊、不更新

下一步

下一课我们将了解多层级配置。