# AGENTS.md

> 相关：[[Agent_as_Code]]、[[上下文体系]]、[[Harness工程]]

## 定义

**AGENTS.md**是AI协作的宪法级配置文件，定义AI的基本行为规则，所有AI工具都从这个文件开始。

**核心思想**：AGENTS.md是AI的"宪法"，约束AI的行为边界。

## 核心特征

### 1. 宪法级
- 最高优先级
- 所有AI工具都读取
- 定义基本行为规则

### 2. 统一入口
- AI从这个文件开始
- 引用其他文档
- 形成完整的上下文

### 3. 可版本化
- 纳入Git管理
- 变更有历史记录
- 可回滚

## 内容结构

### 基本信息
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x, React 18
- 代码规范：阿里巴巴Java开发手册
```

### AI行为规则
```markdown
# AI行为规则
1. 生成代码必须符合代码规范
2. 数据库表必须包含created_at, updated_at字段
3. API接口必须使用RESTful风格
4. 敏感数据必须加密存储
```

### 目录结构
```markdown
# 目录结构
- src/main/java/com/example/project/controller
- src/main/java/com/example/project/service
- src/main/java/com/example/project/repository
```

### 引用文件
```markdown
# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
```

## 完整示例

```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x, React 18
- 代码规范：阿里巴巴Java开发手册

# AI行为规则
1. 生成代码必须符合代码规范
2. 数据库表必须包含created_at, updated_at字段
3. API接口必须使用RESTful风格
4. 敏感数据必须加密存储
5. 所有方法必须有注释
6. 所有API必须有单元测试

# 目录结构
- src/main/java/com/example/project/controller
- src/main/java/com/example/project/service
- src/main/java/com/example/project/repository
- src/main/java/com/example/project/domain
- src/main/java/com/example/project/infrastructure

# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
- 安全规范：./docs/standards/security.md

# 开发流程
1. Plan阶段：创建Plan文档，等待确认
2. 执行阶段：按照Plan实现代码
3. 验证阶段：运行测试，确保通过

# 测试要求
- 单元测试覆盖率 > 80%
- 所有API必须有集成测试
- 关键流程必须有E2E测试
```

## 配置位置

### 项目根目录
```
项目根目录/
├── AGENTS.md              # 宪法级配置
├── .claude/
│   └── AGENTS.md -> ../AGENTS.md  # 软链接
├── .opencode/
│   └── AGENTS.md -> ../AGENTS.md  # 软链接
└── .cursor/
    └── AGENTS.md -> ../AGENTS.md  # 软链接
```

### 软链接实现
```bash
# Linux/Mac
ln -s ../AGENTS.md .claude/AGENTS.md
ln -s ../AGENTS.md .opencode/AGENTS.md
ln -s ../AGENTS.md .cursor/AGENTS.md

# Windows
mklink .claude\AGENTS.md ..\AGENTS.md
mklink .opencode\AGENTS.md ..\AGENTS.md
mklink .cursor\AGENTS.md ..\AGENTS.md
```

## Git管理

```bash
# 添加到Git
git add AGENTS.md
git add .claude/AGENTS.md
git add .opencode/AGENTS.md
git add .cursor/AGENTS.md

# 提交
git commit -m "feat: add AGENTS.md for AI collaboration"
```

## 适用场景

- **团队协作**：多个开发者共享AI配置
- **多项目**：在多个项目间复用配置
- **持续迭代**：配置需要持续演进
- **知识沉淀**：最佳实践需要沉淀

## 优势

- **统一入口**：所有AI工具从这个文件开始
- **一致性**：所有AI工具行为一致
- **可追溯**：配置变更有历史记录
- **易维护**：修改一处，多处生效

## 挑战

- **初始成本**：需要建立完整的配置
- **维护成本**：需要持续维护配置
- **学习曲线**：团队需要理解配置

## 最佳实践

1. **从核心规则开始**：先定义最重要的规则
2. **逐步扩展**：根据实践逐步添加配置
3. **定期Review**：定期审查和优化配置
4. **团队共享**：将配置纳入团队知识管理

## 相关概念

- [[Agent_as_Code]]：AGENTS.md是Agent as Code的核心文件
- [[上下文体系]]：AGENTS.md是上下文体系的宪法级文件
- [[Harness工程]]：AGENTS.md是Harness的组成部分