词元广场TOKPUB.COM - 欢迎您，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
项目初始化：让 AI 读懂你的项目
💡 一句话总结：用 /init命令生成 AGENTS.md，让 AI 了解你的项目规范和偏好。
📝 课程笔记
学完你能做什么
/init 生成项目规则文件你现在的困境
什么时候用这一招
🎒 开始前的准备
确保你已经完成以下事项：
核心思路
为什么需要初始化
AGENTS.md 文件里，AI 每次都会自动读取。规则文件位置
| 位置 | 作用范围 |
|---|---|
项目根目录/AGENTS.md | 当前项目 |
项目根目录/CLAUDE.md | 兼容 Claude Code |
~/.config/opencode/AGENTS.md | 全局（所有项目） |
~/.claude/CLAUDE.md | 全局（兼容 Claude Code） |
$OPENCODE_CONFIG_DIR/AGENTS.md | 全局（通过环境变量指定） |
💡 查找机制
跟我做
第 1 步：进入项目目录
在项目根目录下初始化，生成的规则才是针对这个项目的。
第 2 步：执行初始化
让 AI 分析项目并生成规则文件。
/init高级用法
无默认快捷键，需手动输入 /init
/init 特别关注 TypeScript 类型安全和错误处理/init 命令会：.cursor/rules/、.cursorrules）或 Copilot 规则（.github/copilot-instructions.md），会自动整合AGENTS.md 已存在，会改进而非覆盖第 3 步：审核生成的规则
AI 生成的规则可能不完全准确，需要人工审核。
AGENTS.md 文件，内容类似：进阶：使用 opencode.json 加载更多规则
AGENTS.md，你还可以在配置中指定额外的规则文件：{
"$schema": "https://opencode.ai/config.json",
"instructions": [
"CONTRIBUTING.md",
"docs/guidelines.md",
"packages/*/AGENTS.md"
]
}instructions 支持的特性：packages/*/AGENTS.md 匹配多个文件https:// 或 http:// 加载远程规则（5 秒超时）~/ 开头自动展开{
"instructions": [
"~/team-rules/typescript.md",
"https://example.com/company-coding-standards.md",
"docs/**/*.md"
]
}instructions 指定的文件会与 AGENTS.md 合并。第 4 步：修改规则（如有需要）
补充 AI 没发现的规范，或修正错误。
AGENTS.md，添加你的补充：第 5 步：验证规则生效
确认 AI 真的读取了你的规则。
这个项目用的什么技术栈？规则文件的加载和合并
加载顺序
1.
AGENTS.md 或 CLAUDE.md2.
~/.config/opencode/AGENTS.md 或 ~/.claude/CLAUDE.md3.
OPENCODE_CONFIG_DIR 环境变量，加载其中的 AGENTS.md4.
opencode.json 中 instructions 指定的所有文件💡 URL 超时
instructions 支持从远程 URL 加载规则文件，但会使用 5 秒超时限制。合并机制
instructions 中引用团队共享的标准文档团队协作
提交 AGENTS.md 到 Git
💡 团队协作
AGENTS.md 提交到版本控制，确保团队成员使用相同的项目规范。Monorepo 的处理
instructions 配置统一加载所有子项目的规则：{
"instructions": ["packages/*/AGENTS.md"]
}进阶技巧：在 AGENTS.md 中引用外部文件
AGENTS.md 中显式指示 AI 读取外部文件：AGENTS.md 简洁，同时引用详细指南检查点 ✅
全部通过才能继续
/init 能成功生成 AGENTS.md踩坑提醒
| 现象 | 原因 | 解决 |
|---|---|---|
| AI 不遵守规则 | 可能没在项目目录下启动 | 确认当前目录有 AGENTS.md |
| 规则内容不对 | AI 分析错误 | 手动修改 AGENTS.md |
| 想用全局规则 | 每个项目都适用 | 放到 ~/.config/opencode/AGENTS.md 或 ~/.claude/CLAUDE.md |
| 规则没生效 | 配置文件路径错误 | 检查 opencode.json 中的 instructions 路径 |
| 多个项目共用规则 | 复制规则文件不方便 | 使用 instructions 配置或符号链接 |
本课小结
1.
2.
/init 生成 AGENTS.md，包括带参数和快捷键3.
4.
opencode.json 的 instructions 加载更多规则5.
6.
7.
下一课预告
进入第四阶段【场景实战】，根据你的身份选择学习路线：