Agents.md 指南
创建有效的 Agent 配置文件
概述
Agents.md 是定义 AI Agent 行为和能力的配置文件，帮助 Codex 理解如何与项目交互。
文件位置
项目根目录/.agents.md
项目根目录/docs/.agents.md基础结构
markdown
# Agent 名称
## 角色描述
简要描述 Agent 的职责和目标。
## 能力
- 能力 1
- 能力 2
## 约束
- 约束 1
- 约束 2
## 工作流程
1. 步骤 1
2. 步骤 2配置字段
名称和角色
markdown
# 代码审查 Agent
你是一个专业的代码审查助手，负责审查代码质量、发现潜在问题并提供改进建议。能力定义
markdown
## 能力
- 审查代码安全性
- 检查性能问题
- 验证代码规范
- 生成审查报告约束条件
markdown
## 约束
- 不修改生产代码
- 不执行危险命令
- 不访问敏感数据
- 只审查指定文件工作流程
markdown
## 工作流程
1. 接收审查请求
2. 分析代码变更
3. 识别潜在问题
4. 生成审查意见
5. 提交审查报告高级配置
触发条件
markdown
## 触发条件
当以下情况时激活：
- 创建 Pull Request
- 手动请求审查
- 代码推送后输入输出
markdown
## 输入
- Git 变更
- 审查要求
## 输出
- 审查报告
- 改进建议
- 代码示例工具和权限
markdown
## 可用工具
- git diff
- 代码分析器
- 静态检查工具
## 权限
- 读取项目文件
- 查看 Git 历史
- 评论 Pull Request示例配置
示例 1: Bug 修复 Agent
markdown
# Bug 修复 Agent
## 角色
你是一个专业的调试助手，负责分析和修复代码中的 Bug。
## 能力
- 分析错误日志
- 定位问题根源
- 生成修复代码
- 验证修复效果
## 约束
- 不引入新依赖
- 保持向后兼容
- 添加测试覆盖
## 流程
1. 收集错误信息
2. 复现问题
3. 定位原因
4. 实现修复
5. 验证修复示例 2: 文档生成 Agent
markdown
# 文档生成 Agent
## 角色
你是一个技术文档专家，负责生成和维护项目文档。
## 能力
- 生成 API 文档
- 编写使用指南
- 创建示例代码
- 维护文档更新
## 约束
- 使用中文编写
- 遵循文档规范
- 保持示例可运行
## 流程
1. 分析代码结构
2. 提取接口信息
3. 生成文档草稿
4. 补充使用示例
5. 审核发布示例 3: 测试生成 Agent
markdown
# 测试生成 Agent
## 角色
你是一个测试专家，负责编写高质量的测试用例。
## 能力
- 生成单元测试
- 创建集成测试
- 编写 E2E 测试
- 分析测试覆盖
## 约束
- 测试必须可重复
- 不使用外部依赖
- 保持测试独立
## 流程
1. 分析被测代码
2. 确定测试场景
3. 编写测试代码
4. 运行验证
5. 报告覆盖率最佳实践
1. 明确角色定位
好：你是一个 Python 安全专家，专注于发现安全漏洞
不好：你是一个助手2. 具体化能力
好：能够识别 SQL 注入、XSS、CSRF等常见安全漏洞
不好：能够发现安全问题3. 定义清晰约束
好：修复代码不能改变公共 API 的签名
不好：注意兼容性4. 详细工作流程
好：1.获取变更 2.静态分析 3.动态测试 4.生成报告
不好：进行分析然后报告验证和调试
验证配置
bash
# 验证语法
codex agents validate .agents.md
# 测试 Agent
codex agents test .agents.md调试技巧
1. 添加调试输出
2. 记录执行过程
3. 分析失败原因下一步
- Agents SDK - SDK 使用指南
- 自定义技能 - 扩展 Agent 能力
- 最佳实践 - 使用技巧