mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-11-03 10:58:22 +08:00
docs(agents): rules-manager技能改为AGENTS.md单处索引并保留前缀约定兜底
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: "ulthon-rules-manager"
|
||||
description: "零散规则管理技能。指导智能体在 `.agents/rules/` 目录下新增、维护模块级/场景级规则文件,并同步更新 AGENTS.md 与 PROJECT.md 的规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。"
|
||||
description: "零散规则管理技能。指导智能体在 `.agents/rules/` 目录下新增、维护模块级/场景级规则文件,并在 AGENTS.md 的项目信息节维护规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。"
|
||||
---
|
||||
|
||||
# 零散规则管理(Rules Manager)
|
||||
@@ -14,6 +14,8 @@ Rules 可包含以下类型的内容:
|
||||
- **约定**:惯例、默认行为(如目录结构、文件配对)
|
||||
- **设计决策**:某个功能的设计方案与背景(如多节点协调方案、认证架构选型)
|
||||
|
||||
项目自有信息的归属:项目的运行方式等基础信息记录在根 `AGENTS.md` 的「项目信息」节(建议项,见该节注释);不可协商的业务硬约束仅在项目确有此类铁律时才建为 `project-*` 规则文件;某一方面内容过于复杂(如部署涉及多套流程、多环境差异)时,可拆分为独立规则文件并在原处引用指向。
|
||||
|
||||
## Rules 与 Skills 的边界
|
||||
|
||||
### 核心原则:按主题单一文档
|
||||
@@ -44,21 +46,6 @@ Rules 可包含以下类型的内容:
|
||||
| 操作流程(含必要的设计背景) | Skill | 测试工作流(含设计哲学)、Scheme 定义(含字段约定)、定时器(含多节点设计) |
|
||||
| 致命铁律(如架构分层) | Skill 中的独立章节 | Base/App 架构铁律(在 ulthon-base-app-architecture 技能里) |
|
||||
|
||||
## PROJECT.md 与子规则的关系
|
||||
|
||||
`PROJECT.md` 是项目规则的**精简入口**,只包含两部分:
|
||||
|
||||
1. 一段项目概述(服务于谁、解决什么问题、核心能力)——智能体理解业务语境的起点
|
||||
2. `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`),并在原文件中引用指向。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
@@ -122,9 +109,9 @@ Rules 可包含以下类型的内容:
|
||||
|
||||
不满足条件时:
|
||||
- 如果是全局性规则 → 记录到 `AGENTS.md`(需框架作者身份确认)
|
||||
- 如果是项目整体定位 → 记录到 `.agents/PROJECT.md` 的「项目概述」段落(保持精简)
|
||||
- 如果是项目整体定位 → 记录到根 `AGENTS.md` 的「项目信息」节(保持精简)
|
||||
- 如果是易变的状态描述(模块清单、依赖列表等)→ **不记录为规则**,让智能体从代码/配置中读取
|
||||
- 如果是稳定的业务硬约束或模式决策 → 创建 `project-*` 子规则文件,并在 PROJECT.md 的索引中登记
|
||||
- 如果是稳定的业务硬约束或模式决策 → 创建 `project-*` 子规则文件,并在 AGENTS.md 项目信息节的规则索引中登记
|
||||
|
||||
### 2. 确定命名与来源
|
||||
|
||||
@@ -140,27 +127,24 @@ Rules 可包含以下类型的内容:
|
||||
- **可验证**:有明确的对/错判断标准
|
||||
- **有边界**:明确写出作用域,避免被误用到其他模块
|
||||
|
||||
### 4. 更新索引(必须)
|
||||
### 4. 更新索引
|
||||
|
||||
新增规则后,必须同步更新两处索引:
|
||||
新增规则后,更新一处索引(根 `AGENTS.md`):
|
||||
|
||||
**AGENTS.md(框架规则索引)**:
|
||||
在「零散规则」章节的「框架内置规则索引」表中新增一行(仅 `ulthon-` 前缀的规则)。
|
||||
- `ulthon-` 前缀的规则:在「零散规则」章节的「框架内置规则索引」表中新增一行。
|
||||
- `project-` 前缀的规则:在「项目信息」节的规则索引清单中新增一行。
|
||||
|
||||
**PROJECT.md(项目业务规则索引)**:
|
||||
在「规则索引」章节的索引表中新增一行(仅 `project-` 前缀的规则)。
|
||||
|
||||
两个索引职责互斥:`ulthon-` 前缀只进 AGENTS.md,`project-` 前缀只进 PROJECT.md。框架更新(操作 `ulthon-*`)不污染项目业务索引,项目维护(操作 `project-*`)不污染框架索引。
|
||||
若「项目信息」节尚无规则索引清单,提醒开发者建立(索引是建议项,非硬性要求)。索引缺失时,`.agents/rules/` 目录的 `project-` 前缀约定仍可被发现,作为兜底。
|
||||
|
||||
### 5. 迁移现有内容(如适用)
|
||||
|
||||
如果规则内容原本以其他形式散落记录(如 AGENTS.md / PROJECT.md 的内联描述、聊天记录、issue 等),抽取为独立规则文件后,应在原位置替换为指向规则文件的引用,保留可追溯性。
|
||||
如果规则内容原本以其他形式散落记录(如 AGENTS.md 的内联描述、聊天记录、issue 等),抽取为独立规则文件后,应在原位置替换为指向规则文件的引用,保留可追溯性。
|
||||
|
||||
## 读取规则
|
||||
|
||||
智能体在以下场景应主动查阅 `.agents/rules/`:
|
||||
|
||||
1. 首次接触项目时,先看 `AGENTS.md` 的「框架内置规则索引」了解框架规则,再看 `.agents/PROJECT.md` 的「规则索引」了解项目业务规则
|
||||
1. 首次接触项目时,先看 `AGENTS.md` 的「框架内置规则索引」了解框架规则,再看根 `AGENTS.md` 的「项目信息」节中的规则索引(如有)了解项目业务规则
|
||||
2. 涉及特定模块开发时,查找该模块是否有对应的规则文件
|
||||
3. 用户提到某个模块有特殊约束时,查找对应规则
|
||||
|
||||
@@ -168,8 +152,8 @@ Rules 可包含以下类型的内容:
|
||||
|
||||
- 规则内容变更时,同步更新文件内容和索引中的说明列
|
||||
- 规则过期时,标记为"已废弃"或直接删除,并从索引中移除
|
||||
- 框架更新时,只操作 `ulthon-` 前缀的规则文件与 AGENTS.md 的索引,不动 `project-` 前缀的文件与 PROJECT.md 的索引
|
||||
- 项目业务规则维护时,只操作 `project-` 前缀的规则文件与 PROJECT.md 的索引,不动 `ulthon-` 前缀的文件与 AGENTS.md 的索引
|
||||
- 框架更新时,只操作 `ulthon-` 前缀的规则文件与 AGENTS.md 的「框架内置规则索引」,不动 `project-` 前缀的文件
|
||||
- 项目业务规则维护时,只操作 `project-` 前缀的规则文件与 AGENTS.md 项目信息节的规则索引,不动 `ulthon-` 前缀的文件与「框架内置规则索引」
|
||||
|
||||
## 索引格式
|
||||
|
||||
@@ -184,5 +168,4 @@ Rules 可包含以下类型的内容:
|
||||
|
||||
链接路径以索引文件自身位置为基准写相对路径:
|
||||
- AGENTS.md 在项目根目录,用 `./.agents/rules/...`
|
||||
- PROJECT.md 在 `.agents/`,用 `./rules/...`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user