| name | crafting-rules |
| description | 创建或修改 OpenCode 规则文件时使用。帮助从对话历史中提取模式、分析项目约定(AGENTS.md、linter、package.json),并生成格式正确的规则。触发条件:用户想创建规则、固化重复指令、跨会话持久化指导、或为特定文件/主题定制 Agent 行为。 |
Crafting Rules
规则是注入到系统提示中的 Markdown 文件,用于引导 Agent 行为。
基本结构:
---
globs:
- '**/*.ts'
keywords:
- 'vitest'
---
# 规则标题
- 规则内容:具体、可执行的指令。
字段说明
| 字段 | 类型 | 用途 |
|---|
globs | string[] | 上下文中任一文件匹配时触发 |
keywords | string[] | 用户最新提示匹配关键词时触发 |
alwaysApply | boolean | 始终应用 |
匹配规则:
- 两个字段都是可选的;无 frontmatter 表示始终应用
globs 和 keywords 同时存在时,任一匹配即触发(OR 逻辑)
- 不支持
globs AND keywords;需要此行为请拆分为多条规则
匹配策略选择
| 场景 | 推荐方式 |
|---|
| 针对特定文件/目录的代码规则 | globs |
| 针对某个主题(可能不涉及文件) | keywords |
| 两种情况都应触发 | globs + keywords |
| 全局标准(语气、结构、安全、提交规范) | 无条件 |
重要约束: 关键词匹配是大小写不敏感的词边界前缀匹配。例如 test 会匹配 tests 和 testing。
存储位置
~/.config/opencode/rules/ - 个人偏好,跨项目生效
.opencode/rules/ - 项目/团队约定,仓库级行为
何时创建规则
应该创建规则的信号:
- 明确指令:「总是做 X」「永远不要 Y」「记住...」「从现在起...」
- 重复修正:用户多次修正同一个 Agent 行为
- 一致偏好:风格/流程指导(测试、提交、PR、错误处理)
- 挫折信号:「我之前说过」「又来了」
分析问题:
- 这是反复出现的情况,还是当前任务的一次性需求?
- 适用于特定文件还是所有工作?
- 是否已有规则/配置覆盖?(AGENTS.md、lint 配置、Prettier 等)
- 是否与项目约定冲突?
创建流程:
- 识别行为差异(应该改变什么?)
- 确定作用域(globs、keywords 或无条件)
- 检查现有规则/配置是否重叠或冲突
- 起草最小化规则(一个概念一条规则)
- 选择存储位置(全局 vs 项目)
关键词 keywords 选择指南
匹配机制: 关键词使用大小写不敏感的词边界前缀匹配。短/泛化关键词容易过度匹配。
避免使用(Denylist)
| 类别 | 示例 |
|---|
| 泛化名词 | code, file, project, repo, bug, issue, change |
| 常见动词 | add, update, remove, fix, make, create, implement |
| 过宽主题 | testing, performance, security, deployment, database, api |
| 单词缩写 | ci, cd, db, ui, ux |
推荐使用(Allowlist)
| 类别 | 示例 |
|---|
| 工具/框架名 | vitest, jest, pytest, playwright, cypress, eslint, prettier, typescript, terraform, kubernetes |
| 复合短语 | unit test, integration test, snapshot test, lint rule, error boundary, api endpoint, rest api |
| 高意图动词 | refactor, rollback, migrate, deprecate |
考虑 denylist 关键词时的替代方案:
- 优先用 globs(文件作用域)
- 或替换为复合短语/工具名
关键词自检:
- 这个关键词是否可能出现在不该触发规则的提示中?
- 是否可能因前缀匹配成为其他词的一部分?
- 能否改用 globs 限定作用域?
规则编写原则
- 使用命令式:「做 X」「优先 Y」「避免 Z」
- 可执行:Agent 能直接遵循的指令
- 最小化:不重复通用最佳实践
- 示例优先:模式微妙时用示例代替描述
示例
Glob 作用域:TypeScript 约定
---
globs:
- '**/*.ts'
- '**/*.tsx'
---
# TypeScript
- 优先用 `type` 而非 `interface`(除非需要声明合并)
- 避免 `any`;使用 `unknown` 并收窄类型
Keyword 作用域:单元测试指导
---
keywords:
- 'unit test'
- 'integration test'
- 'vitest'
- 'jest'
---
# Unit Tests
- 遵循 Arrange-Act-Assert 模式
- 测试命名:`it('should <expected> when <condition>')`
无条件:全局代码风格
# Code Style
- 优先早返回而非深层嵌套
- 将魔法数字提取为命名常量
组合作用域:部署安全(OR 逻辑)
---
globs:
- '**/deploy/**'
- '**/*.tf'
keywords:
- 'terraform'
- 'kubernetes'
- 'production'
- 'rollback'
---
# Deployment
- 禁止硬编码密钥;使用环境变量或密钥管理器
- 任何生产变更计划必须包含回滚步骤