项目名称的AGENTS.md文件

项目名称的AGENTS.md文件

【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md

开发环境配置

• 使用pnpm dlx turbo run where <project_name>快速定位项目
• 运行pnpm install --filter <project_name>安装项目依赖
• 使用pnpm create vite@latest <project_name>创建新项目

测试指南

• 运行pnpm test执行项目测试
• 修复所有类型错误和测试失败
• 修改代码后运行pnpm lint确保代码规范

提交规范

• PR标题格式：[<project_name>] <标题>
• 提交前确保所有测试通过
• 更新相关文档

## 如何实施AGENTS.md最佳实践 ### 基础配置步骤 **第一步：创建AGENTS.md文件** 在项目根目录创建AGENTS.md文件，包含以下基础信息： ```bash # 创建基础AGENTS.md文件 echo "# 项目名称 - AGENTS.md" > AGENTS.md echo "" >> AGENTS.md echo "## 开发环境配置" >> AGENTS.md echo "- 项目使用Node.js版本：$(node --version)" >> AGENTS.md echo "- 包管理器：$(which pnpm >/dev/null 2>&1 && echo 'pnpm' || echo 'npm')" >> AGENTS.md

第二步：添加项目特定指南

根据项目特点添加具体指导：

## 项目架构说明 - 前端：React + TypeScript + Vite - 后端：Node.js + Express - 数据库：PostgreSQL ## 开发工作流 1. 从main分支创建功能分支 2. 运行开发服务器：pnpm dev 3. 编写测试用例 4. 提交前运行完整测试套件 ## 常见问题解决 - 如果热重载失效，重启开发服务器 - 类型错误优先修复，再处理逻辑问题 - 依赖冲突时删除node_modules重新安装

大型项目的分层配置

对于包含多个子项目的Monorepo架构，AGENTS.md支持分层配置：

project-root/ ├── AGENTS.md # 根项目通用指南 ├── packages/ │ ├── frontend/ │ │ └── AGENTS.md # 前端特定指南 │ ├── backend/ │ │ └── AGENTS.md # 后端特定指南 │ └── shared/ │ └── AGENTS.md # 共享库指南

分层配置优势：

• 每个子项目可以有特定配置
• AI助手自动读取最近的AGENTS.md文件
• 避免配置冲突和重复
• 支持项目特定的开发模式

常见技术挑战与解决方案

问题1：AI助手不理解项目结构

症状：AI助手无法正确导航项目目录，频繁使用ls命令扫描文件系统。

解决方案：

## 项目导航指南 - 使用`pnpm dlx turbo run where <package_name>`快速定位包位置 - 避免使用`ls`命令扫描目录树 - 项目结构：`src/`包含源代码，`tests/`包含测试文件

问题2：依赖管理混乱

症状：AI助手在错误的位置安装依赖，导致构建失败。

解决方案：

## 依赖管理规范 - 始终在项目根目录运行`pnpm install` - 使用`--filter`参数为特定包安装依赖 - 锁定文件更新后重启开发服务器

问题3：测试执行不一致

症状：AI助手运行错误的测试命令或忽略测试失败。

解决方案：

## 测试执行流程 1. 运行完整测试套件：`pnpm test` 2. 修复所有类型错误 3. 修复所有测试失败 4. 运行代码检查：`pnpm lint` 5. 添加或更新相关测试用例

高级配置技巧

集成现有AI工具

AGENTS.md与主流AI开发工具无缝集成：

Aider配置：

# .aider.conf.yml read: AGENTS.md

Gemini CLI配置：

// .gemini/settings.json { "agentGuidelines": "AGENTS.md" }

性能优化建议

开发服务器管理：

• 始终使用npm run dev（或pnpm dev、yarn dev）进行开发
• 禁止在AI会话中运行npm run build，这会禁用热重载
• 依赖更新后重启开发服务器

缓存策略：

• AI助手应利用构建缓存
• 避免重复安装依赖
• 合理使用TurboRepo的缓存机制

错误处理最佳实践

类型错误优先：

1. 先修复所有TypeScript类型错误
2. 再处理逻辑错误
3. 最后优化代码风格

测试失败处理：

1. 理解测试失败的根本原因
2. 修复代码而不是修改测试（除非测试本身有误）
3. 确保所有测试在提交前通过

避坑指南：常见配置错误

错误1：在错误目录运行命令

错误做法：在项目根目录运行pnpm test，导致所有子项目测试都被执行。

正确做法：

# 进入目标项目目录 cd packages/frontend # 运行该项目测试 pnpm test # 或者使用过滤功能 pnpm turbo run test --filter frontend

错误2：忽略热重载失效

问题：开发服务器热重载失效后继续开发。

解决方案：

## 开发服务器维护 - 热重载失效时立即重启开发服务器 - 避免在开发过程中运行生产构建 - 定期清理`.next`缓存目录

错误3：配置信息过时

问题：AGENTS.md文件未随项目更新。

维护策略：

1. 将AGENTS.md纳入代码审查流程
2. 项目架构变更时更新AGENTS.md
3. 定期检查配置的准确性

实际应用场景

新成员快速上手

当新开发者（或AI助手）加入项目时，AGENTS.md提供：

1. 环境配置：快速搭建开发环境
2. 工作流程：了解项目开发规范
3. 测试策略：掌握质量保障要求
4. 部署流程：了解发布步骤

多工具协作环境

在团队使用多种AI编码工具时，AGENTS.md确保：

• 一致性：所有工具使用相同的项目指南
• 效率：减少重复配置时间
• 质量：统一的代码标准和测试要求

开源项目维护

对于开源项目，AGENTS.md帮助贡献者：

• 理解项目架构和设计决策
• 遵循贡献规范
• 正确运行测试套件
• 提交符合标准的PR

迁移现有项目到AGENTS.md

逐步迁移策略

第一步：创建基础AGENTS.md从现有文档中提取核心信息：

• 开发环境要求
• 构建和测试命令
• 代码风格指南
• 贡献规范

第二步：向后兼容为现有工具创建符号链接：

# 重命名现有文件并创建符号链接 mv AGENT.md AGENTS.md ln -s AGENTS.md AGENT.md

【免费下载链接】agents.mdAGENTS.md — a simple, open format for guiding coding agents项目地址: https://gitcode.com/GitHub_Trending/ag/agents.md