用 AGENTS.md 统一团队规范

AGENTS.md 是 OpenCode（以及任何 AI 智能体）在仓库中行为的唯一真相源。写得好，所有贡献者——人或 AI——都能在同一个基线上起步。

何时使用此案例

• 你希望所有 AI 生成的 PR 都有统一的代码风格和评审质量。
• 新成员（人或 AI）入职时间过长。
• 团队各部分约定不一致，PR 来回反复。

前置配置

• 在仓库里已安装 OpenCode
• 对团队当前约定（风格、测试、错误处理）有大致概念
• 愿意迭代——初稿一定是错的

步骤

1. 从一个 stub 开始

   在仓库根目录创建一个最小结构的 AGENTS.md。

   # AGENTS.md
   
   ## Project overview
   [一段话：项目做什么，用的什么技术栈]
   
   ## Build, test, lint
   - Build: `npm run build`
   - Test: `npm test`
   - Lint: `npm run lint`
   
   ## Code style
   [语言特定的风格规则]
   
   ## Testing rules
   [何时加测试、覆盖什么、mock 策略]
   
   ## Commit and PR rules
   [提交信息格式、PR 模板、谁评审什么]

2. 让 OpenCode 补全空缺

   指向现有代码库和 stub。它会从代码中推断约定。

   读取项目根目录和我们的 stub AGENTS.md。对每个章节，用现有代码的具体例子补全规则。如果代码库本身不一致，请建议我们 应该 遵循的规则并标注不一致。

3. 加一个”不要做”小节

   显式的禁止项能防止最常见的智能体错误。

   ## Do not
   - Do not add new top-level dependencies without discussion.
   - Do not commit generated files (build/, dist/, node_modules/).
   - Do not bypass the linter to make CI green.

4. 加一个”卡住时”小节

   告诉智能体在不知道答案时该怎么做。

   ## When stuck
   - Search the codebase first (`rg`, `grep -r`).
   - Read the related test file for the expected behavior.
   - If still stuck, ask in #dev-help rather than guessing.

5. 提交并在 PR 模板中引用

   提交 AGENTS.md，并在 .github/pull_request_template.md 中链接它，让评审者能发现偏离。

6. 边学边迭代

   看到重复的 PR 评论就把规则加进 AGENTS.md；规则造成摩擦就删掉。

关键提示词

读取项目根目录和我们的 stub AGENTS.md。对每个章节，用现有代码推断出的具体规则补全，并给出文件与行号示例。加一个”Do not”小节，包含你希望智能体避免的最常见错误。加一个”When stuck”小节，指向这个仓库里真正的真相源（搜索命令、测试文件、聊天频道）。

验证重点

• 新智能体会话启动时读取 AGENTS.md 并遵循规则
• 常见的评审评论减少（风格、漏测试、误提交）
• 文件保持简短（200 行以内）——超过这个长度说明规则太细，反而不实用

常见坑点

• 过度规范：1000 行的 AGENTS.md 会被忽略。保持简短，链接到详细文档。
• 规则过时：约定会变，设置日历提醒每季度审查。
• 没有”Do not”：没有禁止项，智能体会自创偏好。要明确写出来。

相关文档

• 规则 — OpenCode 在每个任务中遵循的项目级指令
• 配置 — 管理 OpenCode 行为的 opencode.json 文件

相关案例

• custom-skill — reason.agents.to-skill
• explore-unfamiliar-codebase — reason.agents.to-explore
• project-scaffold — reason.agents.to-scaffold

相关文档

• 规则
• 配置
• 策略

下一步

• custom-skill — next.agents.to-skill