OpenCode Rules 规则与指令系统完全指南

Rules 是 OpenCode 中最直接的行为控制机制。通过在项目中创建规则文件，你可以精确地告诉 AI 编程助手：你用什么技术栈、遵循什么编码风格、有哪些项目约定。本文将完整覆盖 AGENTS.md 规则文件、指令系统、自动提示词，以及如何通过提示词工程最大化 AI 的产出质量。

规则文件体系

OpenCode 使用多个层级的规则文件，优先级从高到低：

规则文件类型

| 文件 | 位置 | 优先级 | 作用 |
|------|------|--------|------|
| AGENTS.md | 项目根目录 | 最高 | 项目专属规则 |
| CLAUDE.md | 项目根目录 | 高（兼容） | 兼容 Claude Code 规则 |
| .opencode/instructions.md | 项目 .opencode 目录 | 中 | 补充指令 |
| ~/.config/opencode/AGENTS.md | 用户目录 | 低 | 全局规则 |
| 系统 Prompt | 内置 | 最低 | OpenCode 默认行为 |

规则合并机制

多层规则会合并生效（非覆盖），后加载的规则追加到上下文。这意味着：

• 全局规则设定基线行为
• 项目规则添加项目特有的约定
• 高层级可以覆盖低层级的同主题内容（因为模型会优先考虑最近的信息）

AGENTS.md 完整编写指南

基本结构

# 项目名称 / 概述

简要说明项目是什么。

## 技术栈

- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Go 1.22 + Gin
- 数据库：PostgreSQL 16
- 缓存：Redis

## 编码规范

### 命名约定

- React 组件使用 PascalCase：`UserProfile.tsx`
- 工具函数使用 camelCase：`formatDate.ts`
- 常量使用 UPPER_SNAKE_CASE：`MAX_RETRY_COUNT`
- Go 中接口使用 `-er` 后缀：`Reader`、`Writer`

### TypeScript 规范

- 严格模式必须开启
- 禁止使用 `any`，优先使用 `unknown`
- 导出的函数必须有 JSDoc 注释
- React 组件使用函数式组件 + Hooks

### Go 规范

- 使用 `gofmt` 格式化
- 错误处理不能忽略，必须处理或显式 `_`
- context.Context 必须作为第一个参数

## 项目结构

src/
├── components/ # 通用 UI 组件
├── features/ # 功能模块（按业务拆分）
├── hooks/ # 自定义 Hooks
├── lib/ # 工具函数库
├── pages/ # 页面组件
└── types/ # 类型定义

## 架构约定

- 状态管理使用 Zustand
- API 请求统一通过 `src/lib/api.ts` 中的封装函数
- 路由使用 React Router v6
- 测试框架使用 Vitest + React Testing Library

## Git 规范

- 提交信息遵循 Conventional Commits：`feat:`、`fix:`、`refactor:` 等
- 分支命名：`feat/description`、`fix/description`、`chore/description`
- 提交前必须通过 lint 和 typecheck

## 测试规范

- 所有 API 端点必须有集成测试
- React 组件必须有快照测试或行为测试
- 测试文件放在 `__tests__/` 目录或与源文件同目录的 `.test.ts`
- 运行测试：`npm run test`

进阶：行为指令

AGENTS.md 不仅可以描述项目规范，还可以指示 AI 在特定场景下的行为：

## AI 行为指令

### 代码修改时
- 修改文件前先阅读文件内容
- 遵循现有的代码风格和模式
- 修改完成后运行 lint 和 typecheck
- 不要引入项目中未使用的第三方库

### 创建新文件时
- 参考同级目录下已有文件的命名和结构
- 自动添加 license header
- 确保 import 顺序：React → 第三方 → 项目内

### 安全约束
- 永远不要在任何文件中写入硬编码的密码、Token 或 Key
- 使用环境变量或配置文件管理敏感信息
- 不要修改 .env 文件中的已有值

提示词工程（Prompt Engineering）

除了规则文件，掌握提示词工程技巧可以在每次对话中更精准地控制 AI 的行为。

1. 角色设定

你现在是一个资深的 React 性能优化专家。请分析这段代码的性能瓶颈...

2. 约束条件

请满足以下约束：
- 不使用第三方库
- 兼容 TypeScript 5.0+
- 支持 SSR
- 包体积不超过 5KB

3. 输出格式控制

请用以下格式回复：
1. 问题分析（3-5 句话）
2. 解决方案（代码块）
3. 注意事项（列表）
4. 替代方案（如有）

4. 分步执行

请按以下步骤执行：
1. 先分析当前代码结构
2. 确认需要修改的文件列表
3. 逐个文件进行修改
4. 最后运行测试验证

5. 反面约束

请修改这段代码，但是：
- 不要改动公共 API 签名
- 不要改变返回值的结构
- 不要删除任何现有注释
- 不要引入 breaking change

auto_prompt.md 自动提示词

在项目根目录创建 auto_prompt.md，OpenCode 会在每次会话开始时自动将其内容注入上下文。这相当于一个「自带记忆」的功能。

# auto_prompt.md

## 当前焦点

我正在开发用户认证模块的重构工作。

## 已知问题

- 旧认证系统使用 JWT 存储在 localStorage（计划改为 httpOnly cookie）
- 需要保持与旧 API 的向后兼容

## 进行中的任务

- [ ] 实现新的 session-based 认证中间件
- [ ] 迁移现有的 JWT 验证逻辑
- [ ] 更新前端 AuthContext

## 关键决策

- 选择了 iron-session 作为 session 库
- Session 过期时间设为 7 天
- 密码加密使用 bcrypt，cost factor = 12

这样每次打开 OpenCode 时，AI 都会记住当前的工作上下文。

项目指令文件

.opencode/instructions.md 作为 AGENTS.md 的补充，适合放置更详细的 AI 行为指南：

# Instructions

## 代码生成策略

1. 生成代码前，先搜索项目中是否已有类似实现
2. 优先复用现有组件和工具函数
3. 如果引入新依赖，先确认是否真的必要
4. 复杂逻辑添加注释，但避免冗余注释

## 错误处理模式

- 后端：使用统一的错误响应格式
- 前端：在 API 层统一处理错误，组件层只关注业务逻辑

## 回答风格

- 代码修改完成后，简要说明改了什么
- 不生成没有实际作用的解释性文字
- 遇到不确定的地方主动询问

实战：完整的规则文件参考

以下是一个适用于 TypeScript 全栈项目的完整 AGENTS.md 模板：

# My App

全栈 SaaS 应用：React 前端 + NestJS 后端 + PostgreSQL 数据库。

## 技术栈

- 前端：React 18, TypeScript, Tailwind CSS, TanStack Query
- 后端：NestJS, Prisma ORM, PostgreSQL
- 工具：Vitest, Playwright, ESLint, Prettier

## 目录约定

apps/web/ # 前端应用
apps/api/ # 后端 API
packages/shared/ # 共享类型和工具

## 代码规范

- 缩进使用 2 空格
- 字符串使用单引号
- 文件末尾留空行
- ESM import 语法
- 类型优先于 interface（除非需要合并声明）

## 提交前检查

npm run lint
npm run typecheck
npm run test

## 常用命令

npm run dev # 启动开发服务器
npm run build # 构建生产版本
npm run test:watch # 监听模式测试
npm run db:migrate # 运行数据库迁移

提示词模板集

代码审查

请对以下代码进行 Code Review，关注：
- 逻辑正确性
- 安全漏洞（SQL 注入、XSS、CSRF）
- 性能问题（N+1 查询、内存泄漏）
- 可维护性（命名、结构、注释）
请按严重程度排列问题。

Bug 排查

我遇到了以下问题：
[描述问题和复现步骤]

请帮我：
1. 分析可能的原因（按可能性排序）
2. 给出排查步骤
3. 提供解决方案
先不要修改代码，只做分析。

性能优化

请分析这段代码的性能瓶颈，按影响程度排列：
1. 最大的性能瓶颈是什么？
2. 如何优化？（给出代码）
3. 优化后的预期提升？

小结

Rules 系统从简单的项目描述到复杂的 AI 行为控制，形成了多层次的指令体系：

• AGENTS.md 定义项目的「宪法」
• instructions.md 补充 AI 的行为指南
• auto_prompt.md 提供会话的「工作记忆」
• 提示词工程 在每次对话中精准控制 AI

下一篇我们将深入 OpenCode 的 MCP 服务器系统，学习如何通过 Model Context Protocol 为 AI 接入无限工具生态。