7.6 KiB
.agents/rules/ 目录下新增、维护模块级/场景级规则文件，并同步更新 AGENTS.md 与 PROJECT.md 的规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。"
零散规则管理（Rules Manager）
核心概念
零散规则（Rules） 是模块级/场景级的专属知识，不适合放在全局 AGENTS.md 中展开。存放在 .agents/rules/ 目录下，每条规则一个独立文件，通过索引被智能体发现和引用。
Rules 可包含以下类型的内容：
- 约束：不能怎么做、必须怎么做（如命名约定、分层铁律）
- 约定：惯例、默认行为（如目录结构、文件配对）
- 设计决策：某个功能的设计方案与背景（如多节点协调方案、认证架构选型）
Rules 与 Skills 的边界
| 维度 | Rule（规则） | Skill（技能） |
|---|---|---|
| 核心问题 | "是什么""不能做什么""为什么这样设计" | "怎么做""一步步如何完成" |
| 知识形态 | 静态声明（A 对应 B、禁止 C） | 动态流程（第 1 步...第 2 步...） |
| 触发时机 | 涉及某模块时需先了解其规则 | 需要执行某操作时按步骤调用 |
| 典型例子 | URL 映射规则、目录约定、多节点设计 | CURD 生成流程、定时任务配置、菜单创建 |
判断方法：如果内容主要是"告知性"的（让智能体知道某个事实/约束/设计），放 Rule。如果内容主要是"操作性"的（让智能体按步骤完成某件事），放 Skill。
灰色地带处理：部分内容混合了规则和操作（如 Base/App 架构文档既有铁律又有场景指南），此时保留为 Skill，因为其核心价值在"指导如何操作"。
PROJECT.md 与子规则的关系
PROJECT.md 是项目规则的精简入口，只包含两部分：
- 一段项目概述（服务于谁、解决什么问题、核心能力）——智能体理解业务语境的起点
project-*规则索引（导航到具体业务规则）
稳定的业务约束和模式决策拆分到 project-* 子规则文件，不在 PROJECT.md 中展开。易变的状态描述（模块清单、依赖列表、技术栈等）不记录为规则，让智能体从代码/配置中读取——强行记录只会导致规则与代码脱节。
必备子规则：project-dev-runtime-deploy.md（记录本项目实际采用的开发/运行/部署模式）。每个项目都应有此文件，因为智能体需要知道"这个项目怎么跑"才能正确执行命令、调试、部署。该文件为开放式骨架——不限于框架预设的 stack，WAMP、宝塔、Docker、源码直传等任何实际模式都如实记录。
可选子规则：project-business-constraints.md（记录不可协商的业务硬约束，如数据一致性、安全强制、合规要求）。仅当项目有此类铁律时才创建。
模式子规则的灵活性：默认合并为一个 project-dev-runtime-deploy.md（三章节：开发方式 / 运行方式 / 部署方式）。若某一方面内容过于复杂（如部署涉及多套流程、多环境差异），可拆分为独立子规则（如 project-deploy-detail.md），并在原文件中引用指向。
目录结构
.agents/rules/
├── .README # 目录说明与格式规范
├── ulthon-timer-multi-node.md # 框架内置规则示例
├── project-xxx.md # 使用者业务规则示例
└── ...
命名约定
| 前缀 | 含义 | 维护者 | 约束 |
|---|---|---|---|
ulthon- |
框架内置规则 | 框架作者 | 随框架更新分发 |
project- |
使用者业务规则 | 开发者 | 不被框架更新影响 |
文件名使用小写英文 + 短横线，语义清晰，例如：
ulthon-timer-multi-node.mdulthon-upload-storage.mdproject-order-stock-lock.mdproject-wechat-auth.md
规则文件格式模板
# 规则名称
> 来源：框架内置（ulthon-）或 使用者业务（project-）
> 作用域：适用的模块/文件/场景
> 触发条件：智能体何时应加载此规则
## 规则内容
（具体的可执行规则，每条应可验证）
## 相关文件
（关联的代码路径、配置路径等）
## 相关技能
（如有对应的 Skill，用相对链接引用）
必填章节：规则内容
按需章节：相关文件、相关数据表、相关命令、相关技能
新增规则流程
1. 判断是否需要新增规则
满足以下条件之一时，应建议新增规则：
- 某个模块有独特的开发约束，不适合写在全局
AGENTS.md - 开发过程中发现了可复用的约定，值得记录
- 用户明确要求"记录这条规则"/"这个模块有约束"
判断标准——什么适合做规则：
- ✅ 适合：稳定的约束、约定、设计决策（选定后很少变化，代码中无直接对应）
- ❌ 不适合：易变的状态描述（模块清单、依赖列表、技术栈清单等）——这些在代码/配置中已有，智能体需要时自行读取，强行记录只会导致规则与代码脱节
不满足条件时：
- 如果是全局性规则 → 记录到
AGENTS.md（需框架作者身份确认） - 如果是项目整体定位 → 记录到
.agents/PROJECT.md的「项目概述」段落（保持精简） - 如果是易变的状态描述（模块清单、依赖列表等）→ 不记录为规则，让智能体从代码/配置中读取
- 如果是稳定的业务硬约束或模式决策 → 创建
project-*子规则文件，并在 PROJECT.md 的索引中登记
2. 确定命名与来源
- 框架内置规则：
ulthon-{模块}-{场景}.md - 使用者业务规则：
project-{模块}-{场景}.md
3. 编写规则文件
在 .agents/rules/ 下创建文件，按格式模板填写。
规则内容要求：
- 可执行：智能体能直接据此行动
- 可验证：有明确的对/错判断标准
- 有边界：明确写出作用域，避免被误用到其他模块
4. 更新索引（必须）
新增规则后，必须同步更新两处索引：
AGENTS.md（框架级索引）：
在「零散规则」章节的索引表中新增一行（仅 ulthon- 前缀的规则）。
PROJECT.md（全量索引）： 在「规则索引」章节的索引表中新增一行（所有前缀的规则）。
5. 迁移现有内容
如果规则内容原本记录在 PROJECT.md 的「增量规则记录」章节，迁移后应将该章节的对应内容替换为指向规则文件的引用（而非直接删除，保留历史痕迹）。
读取规则
智能体在以下场景应主动查阅 .agents/rules/：
- 首次接触项目时，通过
AGENTS.md或PROJECT.md的索引了解有哪些规则 - 涉及特定模块开发时，查找该模块是否有对应的规则文件
- 用户提到某个模块有特殊约束时，查找对应规则
维护规则
- 规则内容变更时，同步更新文件内容和索引中的说明列
- 规则过期时，标记为"已废弃"或直接删除，并从索引中移除
- 框架更新时，只操作
ulthon-前缀的规则文件，不动project-前缀的文件
索引格式
索引表统一使用以下格式：
| 规则文件 | 来源 | 作用域 | 说明 |
|---------|------|--------|------|
| ulthon-timer-multi-node.md | 框架 | 定时任务相关 | 多节点协调规则 |
| project-order-stock-lock.md | 业务 | 订单模块 | 库存锁定规则 |