跳到主要内容

AGENTS.md 说明

本文档说明 AGENTS.md 的定位、作用，以及它与 Rule、Skill 的关系。

1. AGENTS.md 是什么​

AGENTS.md 是“给 AI 代理看的仓库内协作说明书”。 它的目标是把团队约定写成机器可执行的规则，减少反复口头说明。

常见内容包括：

  • 代码与文档风格约束
  • 工程流程（测试、验证、提交、评审）
  • 风险边界（哪些操作禁止，哪些需确认）
  • 输出格式和沟通约定

2. 它和 Rule / Skill 的关系​

  • AGENTS.md：总入口，定义本仓库对 AI 的协作规则与执行边界
  • Rule：偏“约束”，告诉 AI 什么必须遵守
  • Skill：偏“方法”，告诉 AI 任务应如何执行

可理解为：AGENTS.md 统筹全局，Rule 保证不越界，Skill 提供可复用做法。

3. 是否只有 Codex 才有 AGENTS.md​

不是。

  • AGENTS.md 这个命名在 Codex 工作流里更常见
  • 其他 AI 编码工具也有类似机制，但文件名和格式可能不同
    • 例如 Cursor 常见的是 .cursor/rules/*.mdc

本质上它们都在做同一件事：把“团队对 AI 的协作规范”固化为项目配置。

4. 本项目放哪里最合适​

建议两层结构：

  1. 仓库根目录放 AGENTS.md（面向 AI 代理执行）
  2. docs/ai/agents-md.md（面向团队成员理解和培训）

这样做的好处是：既有执行规则，也有可阅读文档，避免只有机器懂、人看不懂。

5. AGENTS.md 示例（可直接改造）​

# AGENTS.md

## 目标

- 优先保证正确性、可验证性、可维护性。

## 全局规则

### 1. 语言与注释

- 默认使用中文回答，除非用户明确要求英文。
- 默认使用英文代码注释，除非用户明确要求中文注释。
- 对外暴露的公共 API 必须提供 JSDoc/TSDoc 注释。

### 2. 回答风格

- 回答应简洁、直接，避免重复和冗余描述。
- 先给关键结论，再给必要说明或最小示例。

### 3. 安全与稳健性（最高优先级）

- 严禁硬编码敏感信息（密码、API Key、Token、IP、证书等）。
- 配置必须从环境变量或配置文件读取。
- 对可能失败的操作必须进行错误处理（try-catch 或等效机制），并返回可诊断信息。

### 4. 代码整洁与可维护性

- 函数保持短小，遵循单一职责。
- 命名必须语义化，优先可读性。
- 避免重复逻辑，遵循 DRY。
- 错误处理风格应在项目内保持一致。
- 模块边界清晰、依赖明确，便于扩展与维护。

### 5. 设计模式使用规范（SHOULD）

- 按需使用设计模式，以降低耦合、提升扩展性为目标；禁止为“用模式而用模式”。
- 常用模式参考：
  - Singleton：管理全局唯一实例。
  - Factory Method：封装创建逻辑，避免到处直接 `new`。
  - Strategy：将可变行为做成可替换策略。
  - Observer：处理事件驱动与响应式通知。
  - Decorator：在不改动原类前提下扩展能力。
  - Command：将操作封装为对象，支持队列化与撤销。
  - Adapter：适配不兼容接口。
  - Proxy：在访问前后做控制与增强（缓存、安全、远程代理等）。

## Skills（按场景触发）

- `writing-plans`：当需求是多步骤任务且尚未开始实现时。
- `test-driven-development`：实现功能或修复 bug 前先写失败测试。
- `systematic-debugging`：出现失败测试、报错或异常行为时。
- `verification-before-completion`：准备提交或宣称完成前必须触发。

## 默认执行流程

1. 明确需求与边界
2. 选择并触发对应 Skill
3. 实施变更
4. 运行验证（测试、构建、静态检查）
5. 输出变更清单与验证结果

你可以把这个示例作为仓库根目录 AGENTS.md 的起点，再按项目特点增删规则。