feat(rules): 新增零散规则管理机制

- 新增 .agents/rules/ 目录,存放模块级/场景级独立规则文件
- 新增 ulthon-rules-manager 技能,指导规则的新增/索引/格式
- 新增 ulthon-timer-multi-node 规则文件(从 PROJECT.md 迁移)
- AGENTS.md 新增「零散规则」章节,含框架级规则索引表
- PROJECT.md 新增「规则索引」章节,含全量规则索引表
- 命名约定:ulthon- 前缀为框架内置,project- 前缀为使用者业务
This commit is contained in:
augushong
2026-06-01 21:26:16 +08:00
parent 5941a61b80
commit f867c42a72
5 changed files with 225 additions and 19 deletions

View File

@@ -0,0 +1,126 @@
---
name: "ulthon-rules-manager"
description: "零散规则管理技能。指导智能体在 `.agents/rules/` 目录下新增、维护模块级/场景级规则文件,并同步更新 AGENTS.md 与 PROJECT.md 的规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。"
---
# 零散规则管理Rules Manager
## 核心概念
**零散规则**是针对特定模块或场景的约束,不适合放在全局 `AGENTS.md` 中展开。它们存放在 `.agents/rules/` 目录下,每条规则一个独立文件,通过索引被智能体发现和引用。
**和 Skills 的区别**Skills 是"按场景调用的工作流说明"怎么做Rules 是"特定模块的约束/约定"(不能怎么做 / 必须遵守什么)。
## 目录结构
```
.agents/rules/
├── .README # 目录说明与格式规范
├── ulthon-timer-multi-node.md # 框架内置规则示例
├── project-xxx.md # 使用者业务规则示例
└── ...
```
## 命名约定
| 前缀 | 含义 | 维护者 | 约束 |
|------|------|--------|------|
| `ulthon-` | 框架内置规则 | 框架作者 | 随框架更新分发 |
| `project-` | 使用者业务规则 | 开发者 | 不被框架更新影响 |
文件名使用小写英文 + 短横线,语义清晰,例如:
- `ulthon-timer-multi-node.md`
- `ulthon-upload-storage.md`
- `project-order-stock-lock.md`
- `project-wechat-auth.md`
## 规则文件格式模板
```markdown
# 规则名称
> 来源框架内置ulthon-)或 使用者业务project-
> 作用域:适用的模块/文件/场景
> 触发条件:智能体何时应加载此规则
## 规则内容
(具体的可执行规则,每条应可验证)
## 相关文件
(关联的代码路径、配置路径等)
## 相关技能
(如有对应的 Skill用相对链接引用
```
必填章节:`规则内容`
按需章节:`相关文件``相关数据表``相关命令``相关技能`
## 新增规则流程
### 1. 判断是否需要新增规则
满足以下条件之一时,应建议新增规则:
- 某个模块有独特的开发约束,不适合写在全局 `AGENTS.md`
- 开发过程中发现了可复用的约定,值得记录
- 用户明确要求"记录这条规则"/"这个模块有约束"
不满足条件时:
- 如果是全局性规则 → 记录到 `AGENTS.md`(需框架作者身份确认)
- 如果是项目业务概述 → 记录到 `.agents/PROJECT.md`
### 2. 确定命名与来源
- 框架内置规则:`ulthon-{模块}-{场景}.md`
- 使用者业务规则:`project-{模块}-{场景}.md`
### 3. 编写规则文件
`.agents/rules/` 下创建文件,按格式模板填写。
规则内容要求:
- **可执行**:智能体能直接据此行动
- **可验证**:有明确的对/错判断标准
- **有边界**:明确写出作用域,避免被误用到其他模块
### 4. 更新索引(必须)
新增规则后,必须同步更新两处索引:
**AGENTS.md框架级索引**
在「零散规则」章节的索引表中新增一行(仅 `ulthon-` 前缀的规则)。
**PROJECT.md全量索引**
在「规则索引」章节的索引表中新增一行(所有前缀的规则)。
### 5. 迁移现有内容
如果规则内容原本记录在 `PROJECT.md` 的「增量规则记录」章节,迁移后应将该章节的对应内容替换为指向规则文件的引用(而非直接删除,保留历史痕迹)。
## 读取规则
智能体在以下场景应主动查阅 `.agents/rules/`
1. 首次接触项目时,通过 `AGENTS.md``PROJECT.md` 的索引了解有哪些规则
2. 涉及特定模块开发时,查找该模块是否有对应的规则文件
3. 用户提到某个模块有特殊约束时,查找对应规则
## 维护规则
- 规则内容变更时,同步更新文件内容和索引中的说明列
- 规则过期时,标记为"已废弃"或直接删除,并从索引中移除
- 框架更新时,只操作 `ulthon-` 前缀的规则文件,不动 `project-` 前缀的文件
## 索引格式
索引表统一使用以下格式:
```markdown
| 规则文件 | 来源 | 作用域 | 说明 |
|---------|------|--------|------|
| ulthon-timer-multi-node.md | 框架 | 定时任务相关 | 多节点协调规则 |
| project-order-stock-lock.md | 业务 | 订单模块 | 库存锁定规则 |
```