AGENTS.md

AGENTS.md 是写给 AI 编码助手的项目说明文件。它用于记录长期有效的项目规则，让 Deep Code 在这个仓库中工作时知道如何安装依赖、运行测试、修改代码、提交变更，以及遵守哪些团队约定。

如果你经常在提示词里重复说明“先运行哪个测试”“不要修改哪个目录”“PR 描述要包含什么”，就适合把这些内容写进 AGENTS.md。

适合写什么

AGENTS.md 适合保存当前项目的稳定规则：

项目结构和重要目录
安装、开发、构建、测试命令
代码风格、命名约定、格式化要求
测试要求和验证步骤
提交、PR、发布流程
安全、配置、凭据处理注意事项
只对本仓库有效的 AI 协作规则

不适合写入 AGENTS.md 的内容：

一次性任务要求，例如“这次只改登录页”
复杂可复用工作流，此类内容更适合写成 Agent Skill
外部系统连接信息，此类能力更适合通过 MCP 配置
API Key、密码、Token 等敏感信息

创建文件

在项目中运行：

/init

Deep Code 会帮助你创建或更新 AGENTS.md。你也可以手动创建：

touch AGENTS.md

如果你希望把说明放在 Deep Code 专用目录中，也可以使用：

mkdir -p .deepcode
touch .deepcode/AGENTS.md

常见选择：

文件	适合场景
`AGENTS.md`	希望项目中的不同 AI 编码工具都能读取
`.deepcode/AGENTS.md`	希望规则只面向 Deep Code
`~/.deepcode/AGENTS.md`	个人默认偏好，适用于没有项目说明的仓库

写作原则

写具体命令

推荐：

## 开发命令
 
- `npm install` — 安装依赖。
- `npm test` — 运行全部测试。
- `npm run build` — 执行类型检查并构建 CLI。

避免：

完成前运行常用命令。

写明确规则

推荐：

## 测试
 
修改行为时需要新增或更新测试。完成前，测试相关修改运行 `npm test`，代码修改运行 `npm run build`。

避免：

确保一切正常。

写项目事实

推荐：

## 项目结构
 
- `src/` 存放应用代码。
- `tests/` 存放自动化测试。
- `docs/` 存放面向用户的文档。

避免：

这是一个普通的 TypeScript 项目。

写安全边界

推荐：

## 安全
 
不要提交 API Key 或 Token。本地凭据放在 `~/.deepcode/settings.json`，项目示例中的敏感信息需要脱敏。

避免：

注意保护密钥。

示例

下面是一个较完整的 AGENTS.md 示例：

# 仓库指南
 
## 项目结构
 
- `src/` 存放应用代码。
- `src/tests/` 存放自动化测试。
- `docs/` 存放面向用户的文档。
- `config/` 存放项目配置示例。
 
## 开发命令
 
- `npm install` — 安装依赖。
- `npm test` — 运行自动化测试。
- `npm run build` — 运行检查并构建 CLI。
 
## 代码风格
 
使用 TypeScript。保持代码清晰，优先使用明确命名，并遵循现有格式风格。不要引入无关重构。
 
## 测试
 
修改行为时需要添加测试。优先运行范围最小的相关测试；条件允许时，完成前运行 `npm test` 或 `npm run build`。
 
## AI 助手注意事项
 
- 不要提交密钥或本地生成文件。
- 保留用户已有修改。
- 说明无法执行的验证步骤。

与 Skills、MCP 的区别

工具	适合放什么
`AGENTS.md`	当前仓库的长期规则、命令、风格、验证步骤
Agent Skill	可复用工作流、领域知识、模板、脚本、参考资料
MCP	GitHub、浏览器、数据库等外部工具和实时数据

常见组合：

在 AGENTS.md 中写“这个项目怎么做”
在 Agent Skill 中写“这类任务怎么做”
用 MCP 提供“需要连接外部服务才能做”的能力

维护建议

项目命令变化后及时更新
删除已经过期的规则
避免写太长，优先保留高频、重要、容易出错的约定
不要写敏感信息
如果规则只适用于某次任务，直接写在当前对话中即可