LowHow 文档

中文

English

中文

English

深色模式

OpenCode 自定义指令体系实战教程：从零配置 AGENTS.md ​

📚 分类: AI / 开发工具 ⏱️ 预计耗时: 20 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode (任何版本)，一个 Git 项目

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 AGENTS.md 文件的作用和原理
  • [ ] 使用 /init 命令为你的项目自动生成专属指令
  • [ ] 手动编写并配置项目级和全局级的 AI 指令规则
  • [ ] 通过 opencode.json 引入外部规则文件

最终效果 ​

你的 OpenCode 助手将不再是一个“通用 AI”，而是一个熟悉你项目结构、编码规范、甚至知道哪些“坑”不能踩的“项目老兵”。它生成的代码将更符合你的项目风格，减少手动修正的工作量。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求验证方法
OpenCode已安装在终端输入 opencode --version
Git 项目任意一个项目在项目根目录下执行 git status

1. 确认 OpenCode 已安装 ​

bash
$ opencode --version

✅ 验证：如果看到类似 v0.x.x 的输出版本号，说明安装成功。

💡 提示：如果提示命令未找到，请先根据 OpenCode 官方文档完成安装。

第 1 步：使用 /init 命令自动生成项目指令 ​

🎯 目标：让 OpenCode 自动分析你的项目，并生成一份专属的 AGENTS.md 文件。

📝 操作：

  1. 打开终端，进入你的 Git 项目根目录。
  2. 在终端输入以下命令启动 OpenCode：
    bash
    $ opencode
  3. 在 OpenCode 的对话界面中，输入斜杠命令并回车：
    text
    /init
  4. OpenCode 会开始扫描你的项目（如 package.json、tsconfig.json 等）。它可能会问你一两个问题，比如“这个项目的主要技术栈是什么？”或“有什么重要的架构约定吗？”，请如实回答。

✅ 验证： 检查你的项目根目录，是否出现了一个名为 AGENTS.md 的文件。如果原来就有，它会被更新。

🤔 为什么要这样做？/init 命令不是生成一个空洞的模板。它会分析你的项目结构，找出构建、测试命令，并尝试理解你的项目约定。这比让 AI 从头开始猜，效率要高得多。而且它是增量更新，不会粗暴覆盖你已有的内容。

第 2 步：理解并手动编辑 AGENTS.md ​

🎯 目标：了解 AGENTS.md 应该写什么，并手动补充一些关键信息。

📝 操作：

  1. 打开上一步生成的 AGENTS.md 文件。你现在看到的应该是一个初步的指令集。
  2. 一个优秀的 AGENTS.md 通常包含以下几类信息。请对照你的项目，检查并补充：
    • 构建、检查、测试指令：npm run build、npm test 等。
    • 项目架构和目录结构：例如 src/ 放源码，packages/ 是 monorepo 子包。
    • 约定和规则：编码风格（如使用 TypeScript 严格模式）、命名规范、数据库设计模式等。
    • 常见陷阱：例如“注意，这个 API 的 id 字段是字符串，不是数字”。

💡 示例：假设你有一个用 TypeScript 和 pnpm 管理的 monorepo 项目，可以在 AGENTS.md 中添加如下内容：

markdown
# My Awesome Monorepo Project

This is a monorepo managed with pnpm workspaces.

## Project Structure
- `apps/web/` - Next.js 前端应用
- `packages/shared/` - 共享的 TypeScript 类型和工具函数
- `packages/api/` - Express API 服务

## Code Standards
- 所有代码必须使用 TypeScript 严格模式 (`strict: true`)
- 共享的 UI 组件放在 `packages/shared/components/` 下
- API 路由文件命名使用 kebab-case, 如 `user-profile.ts`

## Critical Rules
- **绝对不要**在 `packages/shared/` 中引入任何服务端的 Node.js 模块 (如 `fs`, `path`)
- 修改数据库 schema 后，必须运行 `pnpm db:migrate` 来生成迁移文件

✅ 验证：保存文件后，在 OpenCode 中发起一个新会话，并问它“我们这个项目的代码规范是什么？”。它应该能准确回答出你刚刚在 AGENTS.md 中写下的内容。

⚠️ 注意：AGENTS.md 是给 AI 看的“说明书”，不是给开发者看的 README。请勿将项目介绍、安装步骤等内容写在这里，这会让 AI 混淆重点。

第 3 步：配置全局规则（个人偏好） ​

🎯 目标：设置一个只属于你个人的全局规则，让你的 OpenCode 在所有项目中都遵循你的个人编码风格。

📝 操作：

  1. 在终端中，创建并编辑全局规则文件：
    bash
    $ mkdir -p ~/.config/opencode
$ touch ~/.config/opencode/AGENTS.md
$ code ~/.config/opencode/AGENTS.md   // 用 VS Code 打开编辑，或使用其他编辑器
  2. 在文件中写入你的个人偏好，例如：
    markdown
    # My Personal Preferences

- Always use `const` over `let` and `var`.
- Always use semicolons at the end of statements.
- When writing React components, always use functional components with hooks.
- Prefer `async/await` over `.then()` chains.

✅ 验证：在你任何一个项目中，让 OpenCode 写一段 JavaScript 代码。它应该会遵守你在全局规则中设定的偏好（例如使用分号结尾）。

🤔 为什么要这样做？ 项目级规则（AGENTS.md）是团队共享的，由 Git 管理。而全局规则（~/.config/opencode/AGENTS.md）是个人私有的，不受 Git 控制。这让你可以在不打扰团队其他成员的前提下，强制 AI 遵循你自己的“小癖好”。

第 4 步：引入外部规则文件（进阶） ​

🎯 目标：将项目中已有的、分散的规范文档（如 CONTRIBUTING.md）引入到 AI 的指令体系中，而无需复制粘贴。

📝 操作：

  1. 在项目根目录下，找到或创建一个 opencode.json 文件。
  2. 编辑该文件，使用 instructions 字段来声明外部文件：
    json
    {
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/coding-standards.md",
    ".cursor/rules/*.md"
  ]
}
    • CONTRIBUTING.md 和 docs/coding-standards.md 是具体文件路径。
    • .cursor/rules/*.md 是一个 glob 模式，它会匹配 .cursor/rules/ 目录下所有的 .md 文件。
  3. (可选) 你也可以引用远程的规则文件，用于跨仓库共享规范：
    json
    {
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "https://raw.githubusercontent.com/your-org/shared-rules/main/style.md"
  ]
}
    ⚠️ 注意：远程文件有 5 秒的超时限制，所以请确保链接是稳定的，且文件不会太大。

✅ 验证：重新启动 OpenCode 会话。当你询问某个相关规范时（例如“我们的提交信息格式是什么？”），AI 应该能够从 CONTRIBUTING.md 中找到答案。

💡 提示：

  • 路径支持 glob 模式，这对于 monorepo 中每个子包都有自己的 AGENTS.md 的情况非常有用。
  • 对于 monorepo 项目，推荐使用 opencode.json 的 instructions 字段配合 glob 模式，而不是在 AGENTS.md 里手动罗列所有子包的引用。这种方式更干净，也更不容易遗漏。

进阶技巧（可选） ​

1. 教 AI 按需加载引用 ​

你可以在 AGENTS.md 中指导 AI 如何处理文件引用（例如 @docs/guidelines.md）。OpenCode 不会自动解析这些引用，但你可以通过指令教会它。

在 AGENTS.md 中添加如下内容：

markdown
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. 
They're relevant to the SPECIFIC task at hand.

- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed

2. 从 Claude Code 平滑迁移 ​

如果你之前用过 Claude Code，OpenCode 可以自动读取 CLAUDE.md 作为后备规则。如果你不希望有这种混用，可以通过环境变量精确控制：

bash
export OPENCODE_DISABLE_CLAUDE_CODE=1          # 禁用所有 .claude 支持
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1   # 仅禁用 ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1   # 仅禁用 .claude/skills

常见问题 (FAQ) ​

Q1: 项目级和全局规则冲突了怎么办？A: OpenCode 的优先级是“近的盖远的”。项目级规则（AGENTS.md）的优先级高于全局规则（~/.config/opencode/AGENTS.md）。在同时存在多个规则来源时，它会沿着当前目录向上查找，最先找到的本地文件生效。

Q2: 我修改了 AGENTS.md，但 AI 好像没反应？A: 请确保你保存了文件。然后，在 OpenCode 中开始一个全新的对话。AI 的指令是在每次会话开始时读取的，同一个会话中修改的文件不会生效。

Q3: 我应该把 AGENTS.md 提交到 Git 吗？A: 强烈建议提交。AGENTS.md 沉淀的是团队共识、项目约定和踩坑记录，它和代码一样是项目资产的一部分，应该被版本管理。全局规则则不需要提交。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. AGENTS.md 是项目的“AI 说明书”：它告诉 AI 这个项目的结构、规范和潜规则，是提升 AI 代码质量的关键。
  2. 使用 /init 命令快速入门：让 OpenCode 自动分析项目，生成初始指令，再进行手动微调。
  3. 分层规则体系：项目级规则（团队共享）和全局规则（个人偏好）各司其职，互不干扰。
  4. 引入外部文件：通过 opencode.json 的 instructions 字段，将现有的规范文档纳入 AI 指令体系，避免重复。

© 2026 LowHow