一、为什么需要 AGENTS.md？

AGENTS.md 是 OpenCode 中最重要的文件之乀。它相当于一份「项目说明书」，告诉 AI：

• 项目的结构和架构
• 使用的技术栈
• 编码规范和约定
• 构建、测试、lint 命令
• 需要特别注意的事项

没有 AGENTS.md，AI 就像一个新加入的开发者，需要从零摸索你的项目。有了它，AI 能快速理解上下文，做出更准确的判断。

二、使用 /init 自动生成

最简单的创建方式是在 OpenCode TUI 中运行：

/init

这会自动：

1. 扫描项目的 package.json、tsconfig、目录结构等
2. 分析构建命令、测试框架、lint 配置
3. 询问一些关键问题
4. 生成或更新 AGENTS.md

建议将 AGENTS.md 提交到 Git，供整个团队共享。

如果项目已有 AGENTS.md，/init 会增量改进而非直接覆盖。

三、手工编写 AGENTS.md

3.1 基本结构

# 项目名称

这是项目的总体描述。

## 项目结构

描述项目的目录组织和各模块职责。

## 技术栈

- 语言：TypeScript 5.x
- 框架：Next.js 15
- 数据库：PostgreSQL + Prisma
- 测试：Vitest + Playwright

## 代码规范

- 使用 strict 模式 TypeScript
- 优先使用函数组件 + hooks
- 使用 tailwind 编写样式
- 所有 API 路由需要权检查

## 常用命令

- `npm run dev` — 启动开发服务器
- `npm run build` — 构建
- `npm test` — 运行单元测试
- `npm run lint` — 代码检查
- `npm run typecheck` — 类型检查

3.2 完整示例

以 SST v3 项目的 AGENTS.md 为例：

# SST v3 Monorepo Project

This is an SST v3 monorepo with TypeScript.
The project uses bun workspaces for package management.

## Project Structure

- `packages/` — Contains all workspace packages (functions, core, web, etc.)
- `infra/` — Infrastructure definitions split by service
- `sst.config.ts` — Main SST configuration with dynamic imports

## Code Standards

- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`

## Monorepo Conventions

- Import shared modules using workspace names: `@my-app/core/example`
- Run tests in affected packages only: `npx nx test --affected`

四、多条指令（Custom Instructions）

除于项目根目录的 AGENTS.md，你还可以通过 instructions 配置多个指令文件：

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

也支持远程 URL：

{
  "instructions": [
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

远程文件以 5 秊超时获取。所有指令文件会与 AGENTS.md 合并提供给 AI。

五、多层级规则系统

OpenCode 从多个位置查找规则文件，按以下优先级：

5.1 项目级规则

项目皂录录结构的 AGENTS.md，仅在该项目目录下生效。

5.2 全局规则

~/.config/opencode/AGENTS.md，应用于所有 OpenCode 会话，适合接个人偏好规则。

5.3 Claude Code 兼容

从 Claude Code 迁移的用户可以保留原有文件：

• 项目规则：CLAUDE.md（如果不存在 AGENTS.md 则使用）
• 全局规则：~/.claude/CLAUDE.md

可以通过环境变量禁用兼容模式：

export OPENCODE_DISABLE_CLAUDE_CODE=1
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1

5.4 优先级

优先级	文件	作用域
最高	项目 AGENTS.md	当前项目
中	~/.config/opencode/AGENTS.md	全部项目
低	~/.claude/CLAUDE.md	全部项目（兼容）

六、高级技巧

6.1 模块化规则

在 AGENTS.md 中指导 AI 按需加载外部文件：

## External File Loading

CRITICAL: When you encounter a file reference (e.g., @rules/general.md),
use your Read tool to load it on a need-to-know basis.

Instructions:
- Do NOT preemptively load all references
- Follow references recursively when needed

## References

For TypeScript code style: @docs/typescript-guidelines.md
For React patterns: @docs/react-patterns.md
For API design: @docs/api-standards.md
For testing: @test/testing-guidelines.md

6.2 使用 Glob 模式共享规则

在 monorepo 中，可以用 glob 模式共享规则：

{
  "instructions": [
    "packages/*/AGENTS.md",
    "docs/*.md"
  ]
}

6.3 使用 opencode.json 管理

推荐优先使用 instructions 字段而非在 AGENTS.md 中手动引用：

{
  "instructions": [
    "docs/development-standards.md",
    "test/testing-guidelines.md",
    "packages/core/CONTRIBUTING.md"
  ]
}

七、编写最佳实践

1. 具体明确：不要写 “Write good code”，而要写 “Use strict TypeScript, no any types”
2. 可验证：列出可运行的命令，如 npm run typecheck
3. 定期更新：项目架构变化时同步更新 AGENTS.md
4. 团队共享：提交到 Git 仓库，在 PR 中审查 AGENTS.md 的变更
5. 避免冲突：全局规则放个人偏好，项目规则放团队规范
6. 引用命令：告诉 AI 先运行什么命令来验证修改

## Verification

Before considering a task done, run:
1. `npm run typecheck` — TypeScript 类型检查
2. `npm test` — 单元测试
3. `npm run lint` — 代码规范检查

八、总结

AGENTS.md 是 OpenCode 理解项目的关键桥梁。通过本文，你学会了：

• 使用 /init 自动生成项目规则
• 手工编写쯺细化的项目说明
• 通过 instructions 管理多文件规则
• 理解多层级规则的优先级和合并策略
• 模块化规则管理等高级技巧

下一篇文章将介绍 OpenCode 的安全控制体糷——工具的权限管理。