175 lines
4.2 KiB
Markdown
Executable File
175 lines
4.2 KiB
Markdown
Executable File
# 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的组成部分
|