OpenCode 中文社区

Appearance

3.3 项目初始化：让 AI 读懂你的项目 ​

💡 一句话总结：用 /init 命令生成 AGENTS.md，让 AI 了解你的项目规范和偏好。

学完你能做什么 ​

  • 理解为什么需要项目初始化
  • 用 /init 生成项目规则文件
  • 审核和调整生成的规则
  • 知道规则文件放在哪里

核心思路 ​

为什么需要初始化 ​

没有初始化时，你每次对话都要告诉 AI：

  • 这是什么项目
  • 用什么技术栈
  • 代码风格是什么
  • 有什么特殊规范

初始化后，这些信息会保存在 AGENTS.md 文件里，AI 每次都会自动读取。

规则文件位置 ​

OpenCode 会按以下顺序查找规则文件：

位置作用范围
项目根目录/AGENTS.md当前项目
项目根目录/CLAUDE.md兼容 Claude Code
~/.config/opencode/AGENTS.md全局（所有项目）
~/.claude/CLAUDE.md全局（兼容 Claude Code）

💡 查找机制：OpenCode 会从当前目录开始向上遍历，直到工作目录的根目录，找到的第一个规则文件会被使用。

跟我做 ​

第 1 步：进入项目目录 ​

bash
cd ~/your-project
opencode

第 2 步：执行初始化 ​

输入：

/init

你应该看到：AI 开始分析项目结构、技术栈、代码风格。

/init 命令会：

  • 扫描项目文件和目录结构
  • 检测构建、测试、lint 命令
  • 分析代码风格和命名规范
  • 如果发现 Cursor 规则，会自动整合
  • 如果 AGENTS.md 已存在，会改进而非覆盖
  • 生成约 150 行的规则文件

第 3 步：审核生成的规则 ​

AI 会生成一个 AGENTS.md 文件，内容类似：

markdown
# SST v3 Monorepo Project

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

## Project Structure

- `packages/` - Contains all workspace packages
- `infra/` - Infrastructure definitions
- `sst.config.ts` - Main SST configuration

## Code Standards

- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/`
- Functions go in `packages/functions/`

检查这些内容是否正确。

第 4 步：修改规则（如有需要） ​

用编辑器打开 AGENTS.md，添加你的补充：

markdown
## Additional Rules
- Always use Chinese comments
- Prefer async/await over callbacks
- Error messages should be user-friendly

第 5 步：验证规则生效 ​

输入：

这个项目用的什么技术栈？

你应该看到：AI 回答的内容应该和 AGENTS.md 里定义的一致。

进阶：使用 opencode.json 加载更多规则 ​

除了 AGENTS.md，你还可以在配置中指定额外的规则文件：

json
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    "packages/*/AGENTS.md"
  ]
}

instructions 支持的特性：

  • 相对路径：从项目目录向工作目录根查找
  • Glob 模式：如 packages/*/AGENTS.md 匹配多个文件
  • 绝对路径：直接指定完整路径
  • URL：支持 https:// 加载远程规则（5 秒超时）
  • Home 目录：以 ~/ 开头自动展开

规则文件的加载和合并 ​

加载顺序 ​

OpenCode 按以下顺序加载规则：

  1. 项目规则：从当前目录向上遍历查找 AGENTS.md 或 CLAUDE.md
  2. 全局规则：加载 ~/.config/opencode/AGENTS.md
  3. 配置规则：加载 opencode.json 中 instructions 指定的所有文件

合并机制 ​

所有找到的规则文件会被合并后一起提供给 AI。这意味着：

  • 你可以在项目级规则中定义通用规范
  • 在全局规则中定义个人偏好
  • 在 instructions 中引用团队共享的标准文档
  • 规则之间互不覆盖，全部生效

团队协作 ​

提交 AGENTS.md 到 Git ​

将项目的 AGENTS.md 提交到版本控制，确保团队成员使用相同的项目规范。

Monorepo 的处理 ​

对于 Monorepo 项目，建议使用 instructions 配置统一加载所有子项目的规则：

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

检查点 ​

✅ 全部通过才能继续：

  • [ ] /init 能成功生成 AGENTS.md
  • [ ] 文件内容正确描述了项目
  • [ ] AI 能回答关于项目的问题

踩坑提醒 ​

现象原因解决
AI 不遵守规则可能没在项目目录下启动确认当前目录有 AGENTS.md
规则内容不对AI 分析错误手动修改 AGENTS.md
想用全局规则每个项目都适用放到 ~/.config/opencode/AGENTS.md

🎉 恭喜你完成了必修阶段！ ​

接下来可以根据你的身份选择场景实战课程：

微信群