sampx/crafting-rules

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 等）
• 是否与项目约定冲突？

创建流程：

1. 识别行为差异（应该改变什么？）
2. 确定作用域（globs、keywords 或无条件）
3. 检查现有规则/配置是否重叠或冲突
4. 起草最小化规则（一个概念一条规则）
5. 选择存储位置（全局 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

- 禁止硬编码密钥；使用环境变量或密钥管理器
- 任何生产变更计划必须包含回滚步骤