# ai-rule-packs

**Repository Path**: defiphoenix/ai-rule-packs

## Basic Information

- **Project Name**: ai-rule-packs
- **Description**: ai所必需的rule和skill的集合。并且按照类型分类。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @lvxiaohui/ai-rule-packs

为项目选择、安装和维护 AI 开发规范。内置跨语言工程规范、语言规范和框架专项 Skill，可将同一份源内容生成到 Cursor、Codex 和 Trae。

你可以只选择项目实际使用的分类，也可以在项目中添加自己的 Rule 和 Skill。Rule 记录长期约束，Skill 提供按任务触发的工作流程；选择框架分类不意味着必须使用其中所有可选库。

## 快速开始

需要 Node.js 18.18 或以上版本。在需要接入规范的项目根目录执行：

```bash
npm install -D @lvxiaohui/ai-rule-packs

# 查看内置分类
npx ai-rule-packs list

# 预览：选择通用、JavaScript 和 Vue 3 规范，目标为 Codex
npx ai-rule-packs plan --category=common,javascript,vue3 --mode=compile --targets=codex --json

# 安装源内容，并生成 Codex 的 AGENTS.md 和 Skills
npx ai-rule-packs compile --category=common,javascript,vue3 --targets=codex

# 也可以把源内容放到目标项目中的 team-rules/
npx ai-rule-packs compile --output-root=team-rules --category=common,javascript,vue3
```

参数使用 `--选项=值` 的写法。上例中的分类按项目技术栈替换；TypeScript 项目可增加 `typescript`，React Web 项目可将 `vue3` 换成 `react18`。

`@lvxiaohui/ai-rule` 是本包的编译依赖，正常安装本包会一并安装它，无需为了使用 `ai-rule-packs` 再手动声明。当前依赖版本为 `3.0.2`。

## 选择分类

| 用途                                         | 分类 ID                                   |
| -------------------------------------------- | ----------------------------------------- |
| 跨语言工程治理、需求、实施、调试、审查和验证 | `common`                                  |
| JavaScript、TypeScript 与 Node.js            | `javascript`、`typescript`、`node`        |
| React 18 及以上 Web 项目                     | `react18`                                 |
| Vue 2、Vue 3                                 | `vue2`、`vue3`                            |
| Go、Gin、GORM                                | `go`、`gin`、`gorm`                       |
| Java、Spring Boot、Maven、MyBatis            | `java`、`spring-boot`、`maven`、`mybatis` |
| Python、项目工具、pytest                     | `python`、`python-tooling`、`pytest`      |
| FastAPI、Django、SQLAlchemy                  | `fastapi`、`django`、`sqlalchemy`         |
| Cocos Creator 3.8 及以上                     | `cocos3-8`                                |
| 原生微信小程序                               | `wechat-miniprogram`                      |
| 游戏美术与 2D UI 资产生产                    | `game-art`                                |

例如，Vue 3 + TypeScript 可选择 `common,typescript,vue3`，Go + Gin 可选择 `common,go,gin`，原生微信小程序可选择 `common,javascript,wechat-miniprogram`；使用 TypeScript 时再增加 `typescript`。分类之间没有自动安装依赖关系，语言、运行时和框架分类按实际需要组合。

Router、Pinia、Vuex、Redux、Zustand 等专项 Skill 只在项目实际采用对应方案、且当前任务涉及该方案时使用；它们不会要求安装这些业务依赖。Vue 2 和 Vue 3 按项目主版本选择。`react18` 不自动覆盖 React Native、Next.js 或 RSC 专属规范。

## 命令

| 命令       | 行为                                                             |
| ---------- | ---------------------------------------------------------------- |
| `list`     | 列出源目录中的全部分类和文件数量；`--json` 可查看文件列表        |
| `validate` | 校验整个源目录的 Rule/Skill 格式，不写目标项目                   |
| `plan`     | 生成安装计划，不写目标项目；编译模式额外执行临时目录 dry-run     |
| `install`  | 安装到输出目录；默认是 `.ai-rules/`，`--mode=compile` 时同时编译 |
| `compile`  | 先安装，再编译；强制使用编译模式                                 |

当前没有交互式分类选择向导，可以直接传参数，也可以使用配置文件。不指定命令时默认执行 `install`；未指定分类且配置中也没有分类时，会选择全部分类。建议首次使用显式指定 `--category`。

`list` 和 `validate` 处理整个源目录，不按 `--category` 筛选。

### 选项

| 选项                            | 说明                                                                     |
| ------------------------------- | ------------------------------------------------------------------------ |
| `--category=common,javascript`  | 选择分类，可重复传入                                                     |
| `--targets=cursor,codex,trae`   | 编译目标；默认选择这三个目标                                             |
| `--target-root=../my-project`   | 安装和编译的目标项目，默认当前目录                                       |
| `--output-root=team-rules`      | 目标项目内的源内容目录，默认 `.ai-rules`                                  |
| `--source=./team-packs`         | 自定义资源源目录，默认使用本包内置的 `packs/`                            |
| `--overlay=./team-packs`        | 增加扩展资源源目录，可重复传入；后面的来源优先                           |
| `--config=./rules.config.json`  | 指定安装配置文件；默认查找 `.ai-rule-packs.json`                         |
| `--mode=raw` / `--mode=compile` | 仅安装源内容 / 安装后编译                                                |
| `--dry-run`                     | 阻止目标项目写入；编译模式会在临时目录执行预览                           |
| `--force`                       | 允许更新有归属的源文件，包括本地修改；也允许清理已选分类的失效受管理文件 |
| `--json`                        | 输出命令结果 JSON                                                        |
| `--help` / `-h`                 | 查看帮助                                                                 |

`--force` 不是忽略所有保护：无归属的同名源文件仍不覆盖，也不会传给下游编译器以强制覆盖生成文件。

## 配置文件

在项目根目录创建 `.ai-rule-packs.json`，保存分类和目标选择：

```json
{
  "categories": ["common", "javascript", "vue3"],
  "outputRoot": ".ai-rules",
  "overlayRoots": ["./team-packs"],
  "outputMode": "compile",
  "targets": ["codex"],
  "force": false,
  "dryRun": false
}
```

之后执行：

```bash
npx ai-rule-packs plan --json
npx ai-rule-packs install
```

可选字段还包括 `sourceRoot`、`overlayRoots`、`targetRoot` 和 `outputRoot`。`outputRoot` 是相对于目标项目根目录的可移植相对目录，默认是 `.ai-rules`，不能使用绝对路径或 `..` 穿越项目根目录。不设置 `sourceRoot` 时读取本包资源，不需要在业务项目中创建 `packs/`。`overlayRoots` 是按顺序排列的扩展目录，支持相对路径和绝对路径；后面的扩展目录优先于前面的来源。

命令行参数覆盖配置中的同名字段。存在安装配置文件时，相对的源/目标路径按该文件所在目录解析；没有配置文件时按当前目录解析。显式指定不存在的配置文件会报错。数组字段被覆盖时整体替换，重复的 `--category` 会在命令行中合并。

本包配置 `.ai-rule-packs.json` 控制资源安装；编译器配置 `.ai-rules.config.json` 控制 ai-rule 读取和转换源内容。两者用途不同。使用 `compile` 或 `--mode=compile` 时，安装器会把 `outputRoot` 作为 ai-rule 的 `sourceDir`，同时保留编译器配置中的其他设置；如果直接运行 `npx ai-rule`，则应在 `.ai-rules.config.json` 中把 `sourceDir` 设置为同一个目录。

输出目录切换时，已由本工具管理的旧目录内容仍遵循 manifest 冲突保护；选中分类的旧文件需要使用 `--force` 才会清理。未选中的分类会保留，manifest 可以同时记录多个输出目录中的文件。

## 安装与生成结果

选择 `common,javascript,vue3` 后，源内容保留分类结构。下面使用默认的 `outputRoot=.ai-rules`：

```text
.ai-rules/
├── common/
│   ├── rules/*.mdc
│   └── skills/<name>/SKILL.md
├── javascript/
│   ├── rules/*.mdc
│   └── skills/<name>/SKILL.md
└── vue3/
    ├── rules/*.mdc
    └── skills/<name>/SKILL.md
.ai-rule-packs-manifest.json
```

Skill 的 references 和附属资源随目录一起复制。`.ai-rule-packs-manifest.json` 记录本工具管理的源文件及其 hash，用于判断更新、冲突和清理归属，不应手工改写或随意删除。

源 Skill 中的 `rules/...` 和 `skills/<name>/...` 是 `@lvxiaohui/ai-rule` 的分类根路径引用；raw 模式保留这类源引用，编译模式会将其映射到目标 Agent 的实际路径。Skill 内的 `references/...`、`assets/...` 和 `scripts/...` 则按 Skill 根目录的普通相对路径解析。四个 common 工作流 Skill 同时标注了稳定 Skill ID，便于 raw 模式下直接交接。

编译由 `@lvxiaohui/ai-rule` 完成：

| 目标   | Rule 输出                             | Skill 输出                           |
| ------ | ------------------------------------- | ------------------------------------ |
| Cursor | `.cursor/rules/<category>-<rule>.mdc` | `.cursor/skills/<category>-<skill>/` |
| Codex  | 项目根目录 `AGENTS.md`                | `.agents/skills/<category>-<skill>/` |
| Trae   | `.trae/rules/<category>-<rule>.md`    | `.trae/skills/<category>-<skill>/`   |

Codex 将各分类的 Rule 正文汇总到一个 `AGENTS.md`，每条以 `## Rule: common:00-engineering-governance` 这样的标题区分，并保留来源元数据。当前没有额外的分类总标题或分割线；Skill 和 references 不会全文塞入 `AGENTS.md`。

生成文件是源内容的转换结果，修改应落在 `outputRoot` 指定的源目录。生成归属由 `<outputRoot>/.generated-manifest.json` 跟踪，和安装器 manifest 是两份独立清单。

编译器读取 `outputRoot` 中的全部分类，或按该项目的编译器配置筛选。安装命令中的 `--category` 控制本次安装范围，不会自动卸载其他已安装分类，也不等于编译时仅使用这些分类。

## 添加项目自己的 Rule 和 Skill

在 `@lvxiaohui/ai-rule` 配置的 `sourceDir` 下创建分类。默认目录是 `.ai-rules`；`project` 只是表示项目自定义内容的推荐名称，也可以使用 `company`、`team` 或其他分类名。不要使用根级 `rules/` 或 `skills/`，3.x 要求保留分类层：

```text
.ai-rules/
├── common/                 # 从规则包安装
├── javascript/             # 从规则包安装
└── project/                # 项目自己维护
    ├── rules/
    │   └── 00-project.mdc
    └── skills/
        └── project-review/
            ├── SKILL.md
            └── references/ # 有需要时创建
```

Rule 示例 `.ai-rules/project/rules/00-project.mdc`：

```markdown
---
description: 本项目的开发约束，适用于本仓库的修改任务。
globs: []
alwaysApply: true
---

# 项目开发约束

- 修改 API 前先核对本项目的接口文档和调用方。
- 按本项目已确认的验证命令提供交付证据。
```

Skill 的 `SKILL.md` 至少包含与目录一致的 `name` 和非空 `description`，正文写清触发条件、步骤和停止条件：

```markdown
---
name: project-review
description: 审查本项目接口变更时使用；不用于其他项目或纯文案修改。
---

# 接口变更审查

1. 核对接口文档、调用方和兼容性。
2. 记录已执行的验证和待确认项。
3. 无法确认接口契约时，暂停给出通过结论。
```

不在内置 `sourceRoot` 或 `overlayRoots` 中的自定义分类不归本包安装器管理，重新安装内置分类不会删除它。只要它位于编译器的 `sourceDir` 下，且没有被 `categories` 排除，编译时就会包含它。

只修改项目源内容、无需重新安装规则包时，可单独使用编译器。需要稳定调用其 CLI 时，将编译器显式加入项目开发依赖：

```bash
npm install -D @lvxiaohui/ai-rule@3.0.2
npx ai-rule validate
npx ai-rule compile --target=codex --no-strict --dry-run
npx ai-rule compile --target=codex --no-strict
```

本包的 `compile` 命令会先执行安装，因此在已安装分类存在本地修改时会先报告冲突；它不是“仅重新生成”的命令。

## 更新和定制已安装分类

### 更新到规则包提供的内容

先升级开发依赖，再预览和应用规则更新。例如：

```bash
npm install -D @lvxiaohui/ai-rule-packs
npx ai-rule-packs plan --category=common,javascript --force --json
npx ai-rule-packs install --category=common,javascript --force
```

确认源内容后再编译。`--force` 会替换受管理文件的本地修改，执行前用版本控制保存需要保留的内容。

| 目标源文件状态                     | 默认行为                         | 使用 `--force`   |
| ---------------------------------- | -------------------------------- | ---------------- |
| 不存在                             | 安装                             | 安装             |
| 与来源内容相同                     | 跳过，不重写                     | 跳过，不重写     |
| 受管理，来源有更新                 | 报 `CONFLICT_UPDATE`             | 更新             |
| 受管理，目标被本地修改且不同于来源 | 报 `CONFLICT_MODIFIED`           | 用来源内容替换   |
| 无归属，且与来源内容不同           | 报 `CONFLICT_UNMANAGED`          | 仍拒绝覆盖       |
| 已选分类中，来源已删除的受管理文件 | 目标仍存在时报 `CONFLICT_REMOVE` | 删除该受管理文件 |

未选分类保留；用户新增的无归属文件不按失效文件清理。内容相同的无归属文件不会被自动认领。

### 保留团队或项目定制

补充项目规则时，优先写入独立 `project` 分类，并明确它补充哪些约束。分类名称和排列顺序不会自动产生覆盖优先级；对已有规则的例外，应明确适用范围和依据，避免互相矛盾。

如果需要扩展或替换 `common` 等分类，可在任意目录维护自有源目录，例如：

```text
team-packs/
├── common/
│   └── rules/10-testing.mdc
└── company/
    ├── rules/00-company.mdc
    └── skills/company-review/SKILL.md
```

通过配置或命令行指定：

```bash
npx ai-rule-packs compile --overlay=./team-packs --category=common,company
```

来源按分类合并：扩展源中的新分类会加入结果；同一分类中的不同文件会补充；同一分类、同一相对路径的 Rule 会由扩展源覆盖内置 Rule；同名 Skill 会由扩展源整体替换。多个 `overlayRoots` 按配置顺序处理，后面的来源优先。最终仍保留 `<outputRoot>/<category>/{rules,skills}` 结构，再由 `@lvxiaohui/ai-rule` 生成目标文件。

扩展源覆盖只表示来源组合，不会绕过目标项目的 manifest 冲突保护。目标文件被用户修改时仍按默认冲突策略处理。直接编辑已安装分类也可以，但下次默认安装会报告冲突；使用 `--force` 会替换受管理的源文件。不要通过修改生成的 `AGENTS.md` 或目标编辑器文件维护定制。

## 预览、冲突与兼容边界

- `plan` 和 `--dry-run` 不写目标项目；编译预览在临时目录中只放入本次计划的源文件，不包含目标项目已有的其他分类、编译器配置和生成文件，不能证明实际目标无冲突。
- `--json` 安装计划当前展示本次资源条目的写入/跳过动作，尚未展示单独的过期文件删除清单；使用 `--force` 更新时，还需要核对 manifest 与源文件差异。
- 已有手写或手改的 `AGENTS.md`、Cursor/Trae 生成文件可能阻止编译。先备份并迁移其中需要保留的内容到源分类，再处理冲突；本包不会合并手写生成文件。
- 安装成功后编译失败，已经安装的 `outputRoot` 源内容会保留，命令返回非零退出码。根据诊断修正配置或生成文件冲突后重新编译。
- 当前编译调用使用 `--no-strict` 并保留诊断。Codex 的 `RULE_SCOPE_LOSS` 表示 Rule 的 scope 元数据被保留为注释，不能等同于原来的自动匹配语义；仍需在正文写清适用边界。
- 编译器三个内置插件目前处于 `preview` 状态，本地格式和编译验证不等于真实编辑器已正确加载和执行。请在项目实际使用的 Agent 中验证效果。

## License

MIT