docs(agents): 落实按主题单一文档原则,合并规则到对应技能

- AGENTS.md 代码分层铁律精简为入口摘要,链接指向技能详情
- 合并 ulthon-timer-multi-node 规则到 ulthon-timer 技能(多节点协调章节)
- 合并 ulthon-database-design 规则到 ulthon-scheme-definition 技能(含字段约定、组件类型)
- 合并 ulthon-testing 规则到 ulthon-testing 技能(含设计哲学、决策树、测试约束)
- rules-manager 边界原则从规则/技能二分改为按主题单一文档
- AGENTS.md 通用基础规范中表结构规范链接改向技能
- 工作流索引中三个技能描述扩充(明确承载原规则内容)
This commit is contained in:
augushong
2026-07-19 09:07:42 +08:00
parent 1f91abe9d2
commit e392db007a
8 changed files with 340 additions and 430 deletions

View File

@@ -16,16 +16,33 @@ Rules 可包含以下类型的内容:
## Rules 与 Skills 的边界
| 维度 | Rule规则 | Skill技能 |
|------|-------------|---------------|
| 核心问题 | "是什么""不能做什么""为什么这样设计" | "怎么做""一步步如何完成" |
| 知识形态 | 静态声明A 对应 B、禁止 C | 动态流程(第 1 步...第 2 步... |
| 触发时机 | 涉及某模块时需先了解其规则 | 需要执行某操作时按步骤调用 |
| 典型例子 | URL 映射规则、目录约定、多节点设计 | CURD 生成流程、定时任务配置、菜单创建 |
### 核心原则:按主题单一文档
**判断方法**如果内容主要是"告知性"的(让智能体知道某个事实/约束/设计),放 Rule。如果内容主要是"操作性"的(让智能体按步骤完成某件事),放 Skill
**默认情况下,一个主题只应有一个文档**如果某个主题既有设计决策("为什么"、"约束"),又有操作流程("怎么做"),应合并为一个文档,避免分散维护导致的重复和遗漏
**灰色地带处理**:部分内容混合了规则和操作(如 Base/App 架构文档既有铁律又有场景指南),此时保留为 Skill因为其核心价值在"指导如何操作"
合并方向:**优先合并到 Skill**。Skill 作为"按场景调用"的入口更符合实际触发逻辑——智能体在执行任务时按需打开,单文件就能完整理解
### 何时保留独立的 Rule
只有满足以下条件之一时,才创建独立的 Rule 文件:
- **纯静态声明**:内容只有约束/约定/设计决策,没有"按步骤操作"的流程如命名约定、URL 映射规则、目录约定、文件级覆盖机制)
- **跨多个 Skill 共享**:约束被多个技能共同引用,独立出来更便于复用
- **不依附于任何具体操作场景的全局铁律**
### 反例:不要为同一主题拆分 Rule + Skill
例如「测试」主题:
- 错误做法Rule 讲"设计哲学 + 4 层模型"Skill 讲"如何运行测试"——读者需要打开两个文件才能完整理解,且边界容易模糊导致重复
- 正确做法:合并为一个 Skill"设计哲学"作为开篇章节,"如何运行"作为操作章节
### 归属判断表
| 内容性质 | 归属 | 例子 |
|---------|------|------|
| 纯约束/约定/设计决策(无操作流程) | Rule | 命名规范、URL 映射、目录约定、文件级覆盖机制 |
| 操作流程(含必要的设计背景) | Skill | 测试工作流含设计哲学、Scheme 定义(含字段约定)、定时器(含多节点设计) |
| 致命铁律(如架构分层) | Skill 中的独立章节 | Base/App 架构铁律(在 ulthon-base-app-architecture 技能里) |
## PROJECT.md 与子规则的关系