#AGENTS.md 与项目初始化

OpenCode 通过 /init 自动生成 AGENTS.md，与 Codex、Cursor 等共同遵循 AGENTS.md 开放标准。

#/init 做了什么？

在 TUI 执行：

/init

OpenCode 会：

1. 扫描项目结构（语言、包管理、测试命令等）
2. 在仓库根生成 AGENTS.md
3. 写入构建/测试/目录约定等摘要

建议： 生成后人工审阅，删去错误推断，补上团队特有规则。

#AGENTS.md 应写什么？

推荐包含：

• 项目一句话描述
• 安装依赖命令（npm install / pnpm i / uv sync）
• 测试、lint、类型检查命令
• 目录结构说明（src/、packages/）
• PR / commit 约定
• 禁止事项（勿提交 .env、勿 force push main）

示例：

# AGENTS.md

## 项目
Monorepo：前端 `apps/web`，API `packages/api`。

## 命令
- 安装：`pnpm install`
- 测试：`pnpm test`
- Lint：`pnpm lint`

## 约定
- API 变更需更新 OpenAPI 文档
- 不要修改 lockfile 除非依赖确实变更

#@ 文件引用

TUI 中可用 @path 精确引用：

@src/auth/login.ts 解释登录流程

这比让 Agent 盲目 glob 更省 token、更准确。支持文件与目录。

#与 opencode.json 的分工

AGENTS.md 适合 给人也看得懂的规范；opencode.json 适合 机器可执行的策略（permission、model）。

#反馈闭环

Agent 重复犯错时：

1. 对话中纠正
2. 要求更新 AGENTS.md：「把这条规则写进 AGENTS.md」
3. Code Review 合并

配合 pre-commit、CI，把软规则变成硬检查。

#多目录 / Monorepo

在子包下工作时，OpenCode 从 Git 根向下加载上下文。可在子包添加更具体的 AGENTS.md（若工具链支持嵌套；OpenCode 主要使用根目录 /init 产物，复杂 monorepo 建议在根 AGENTS.md 中用章节区分 package）。

#验证

初始化后，在 Plan 模式询问：

根据 AGENTS.md，我们的测试命令是什么？

若回答正确，说明上下文已加载。

#下一步

• Agent 与权限系统
• 架构与运行机制