ulthon_admin/.agents/skills/ulthon-rules-manager/SKILL.md

name: "ulthon-rules-manager" description: "零散规则管理技能。指导智能体在 .agents/rules/ 目录下新增、维护模块级/场景级规则文件，并在 AGENTS.md 的项目信息节维护规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。"

零散规则管理（Rules Manager）

核心概念

零散规则（Rules） 是模块级/场景级的专属知识，不适合放在全局 AGENTS.md 中展开。存放在 .agents/rules/ 目录下，每条规则一个独立文件，通过索引被智能体发现和引用。

Rules 可包含以下类型的内容：

• 约束：不能怎么做、必须怎么做（如命名约定、分层铁律）
• 约定：惯例、默认行为（如目录结构、文件配对）
• 设计决策：某个功能的设计方案与背景（如多节点协调方案、认证架构选型）

项目自有信息的归属：项目的运行方式等基础信息记录在根 AGENTS.md 的「项目信息」节（建议项，见该节注释）；不可协商的业务硬约束仅在项目确有此类铁律时才建为 project-* 规则文件；某一方面内容过于复杂（如部署涉及多套流程、多环境差异）时，可拆分为独立规则文件并在原处引用指向。

Rules 与 Skills 的边界

核心原则：按主题单一文档

默认情况下，一个主题只应有一个文档。如果某个主题既有设计决策（"为什么"、"约束"），又有操作流程（"怎么做"），应合并为一个文档，避免分散维护导致的重复和遗漏。

合并方向：优先合并到 Skill。Skill 作为"按场景调用"的入口更符合实际触发逻辑——智能体在执行任务时按需打开，单文件就能完整理解。

何时保留独立的 Rule

只有满足以下条件之一时，才创建独立的 Rule 文件：

• 纯静态声明：内容只有约束/约定/设计决策，没有"按步骤操作"的流程（如命名约定、URL 映射规则、目录约定、文件级覆盖机制）
• 跨多个 Skill 共享：约束被多个技能共同引用，独立出来更便于复用
• 不依附于任何具体操作场景的全局铁律

反例：不要为同一主题拆分 Rule + Skill

例如「测试」主题：

• 错误做法：Rule 讲"设计哲学 + 4 层模型"，Skill 讲"如何运行测试"——读者需要打开两个文件才能完整理解，且边界容易模糊导致重复
• 正确做法：合并为一个 Skill，"设计哲学"作为开篇章节，"如何运行"作为操作章节

归属判断表

内容性质	归属	例子
纯约束/约定/设计决策（无操作流程）	Rule	命名规范、URL 映射、目录约定、文件级覆盖机制
操作流程（含必要的设计背景）	Skill	测试工作流（含设计哲学）、Scheme 定义（含字段约定）、定时器（含多节点设计）
致命铁律（如架构分层）	Skill 中的独立章节	Base/App 架构铁律（在 ulthon-base-app-architecture 技能里）

目录结构

.agents/rules/
├── .README                    # 目录说明与格式规范
├── ulthon-module-structure.md   # 框架内置规则示例
├── project-xxx.md             # 使用者业务规则示例
└── ...

命名约定

前缀	含义	维护者	约束
ulthon-	框架内置规则	框架作者	随框架更新分发
project-	使用者业务规则	开发者	不被框架更新影响

文件名使用小写英文 + 短横线，语义清晰，例如：

• ulthon-module-structure.md
• ulthon-upload-storage.md
• project-order-stock-lock.md
• project-wechat-auth.md

规则文件格式模板

# 规则名称

> 来源：框架内置（ulthon-）或 使用者业务（project-）
> 作用域：适用的模块/文件/场景
> 触发条件：智能体何时应加载此规则

## 规则内容

（具体的可执行规则，每条应可验证）

## 相关文件

（关联的代码路径、配置路径等）

## 相关技能

（如有对应的 Skill，用相对链接引用）

必填章节：规则内容 按需章节：相关文件、相关数据表、相关命令、相关技能

新增规则流程

1. 判断是否需要新增规则

满足以下条件之一时，应建议新增规则：

• 某个模块有独特的开发约束，不适合写在全局 AGENTS.md
• 开发过程中发现了可复用的约定，值得记录
• 用户明确要求"记录这条规则"/"这个模块有约束"

判断标准——什么适合做规则：

• ✅ 适合：稳定的约束、约定、设计决策（选定后很少变化，代码中无直接对应）
• ❌ 不适合：易变的状态描述（模块清单、依赖列表、技术栈清单等）——这些在代码/配置中已有，智能体需要时自行读取，强行记录只会导致规则与代码脱节

不满足条件时：

• 如果是全局性规则 → 记录到 AGENTS.md（需框架作者身份确认）
• 如果是项目整体定位 → 记录到根 AGENTS.md 的「项目信息」节（保持精简）
• 如果是易变的状态描述（模块清单、依赖列表等）→ 不记录为规则，让智能体从代码/配置中读取
• 如果是稳定的业务硬约束或模式决策 → 创建 project-* 子规则文件，并在 AGENTS.md 项目信息节的规则索引中登记

2. 确定命名与来源

• 框架内置规则：ulthon-{模块}-{场景}.md
• 使用者业务规则：project-{模块}-{场景}.md

3. 编写规则文件

在 .agents/rules/ 下创建文件，按格式模板填写。

规则内容要求：

• 可执行：智能体能直接据此行动
• 可验证：有明确的对/错判断标准
• 有边界：明确写出作用域，避免被误用到其他模块

4. 更新索引

新增规则后，更新一处索引（根 AGENTS.md）：

• ulthon- 前缀的规则：在「零散规则」章节的「框架内置规则索引」表中新增一行。
• project- 前缀的规则：在「项目信息」节的规则索引清单中新增一行。

若「项目信息」节尚无规则索引清单，提醒开发者建立（索引是建议项，非硬性要求）。索引缺失时，.agents/rules/ 目录的 project- 前缀约定仍可被发现，作为兜底。

5. 迁移现有内容（如适用）

如果规则内容原本以其他形式散落记录（如 AGENTS.md 的内联描述、聊天记录、issue 等），抽取为独立规则文件后，应在原位置替换为指向规则文件的引用，保留可追溯性。

读取规则

智能体在以下场景应主动查阅 .agents/rules/：

1. 首次接触项目时，先看 AGENTS.md 的「框架内置规则索引」了解框架规则，再看根 AGENTS.md 的「项目信息」节中的规则索引（如有）了解项目业务规则
2. 涉及特定模块开发时，查找该模块是否有对应的规则文件
3. 用户提到某个模块有特殊约束时，查找对应规则

维护规则

• 规则内容变更时，同步更新文件内容和索引中的说明列
• 规则过期时，标记为"已废弃"或直接删除，并从索引中移除
• 框架更新时，只操作 ulthon- 前缀的规则文件与 AGENTS.md 的「框架内置规则索引」，不动 project- 前缀的文件
• 项目业务规则维护时，只操作 project- 前缀的规则文件与 AGENTS.md 项目信息节的规则索引，不动 ulthon- 前缀的文件与「框架内置规则索引」

索引格式

索引表统一使用以下格式（3 列；"来源"通过文件名前缀 ulthon-/project- 已表达，不单列）：

| 规则文件 | 作用域 | 说明 |
|---------|--------|------|
| [ulthon-module-structure.md](./.agents/rules/ulthon-module-structure.md) | 模块结构相关 | 模块目录组织规则 |
| [project-order-stock-lock.md](./.agents/rules/project-order-stock-lock.md) | 订单模块 | 库存锁定规则 |

链接路径以索引文件自身位置为基准写相对路径：

• AGENTS.md 在项目根目录，用 ./.agents/rules/...