# @clipboard-health/ai-rules 中文文档

规范地址：https://npmcn.com/package/%40clipboard-health/ai-rules/

版本：2\.50\.28
npm 元数据更新时间：2026-10-09T20:50:35.238Z
中文译文更新时间：2026-11-10T04:59:05.166Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40clipboard-health/ai-rules
原文对照：https://npmcn.com/package/%40clipboard-health/ai-rules/?lang=original
项目主页：https://github.com/ClipboardHealth/core-utils#readme
源码仓库：https://github.com/ClipboardHealth/core-utils

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：114 kB，45 个文件
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2025-10-13T18:06:13.581Z
- 最新版本发布：2026-10-09T01:19:25.512Z
- 近 30 天下载量：2090（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：500（近 12 个月 475 个）

## 中文简介

为一致的编码标准预建的AI代理规则.

## 安装

```sh
npm install @clipboard-health/ai-rules
```

也可以使用：`pnpm add @clipboard-health/ai-rules`、`yarn add @clipboard-health/ai-rules`、`bun add @clipboard-health/ai-rules`

## README

# @clipboard-health/ai-rules (英语)

为一致的编码标准预建的AI代理规则. 使用基于检索的方法: 在 `AGENTS.md` 指向复制 `.rules/` 需要时代理读取的文件.

## 目录

-   [安装](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-install)
-   [使用量](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-usage)
    -   [快速启动](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-quick-start)
    -   [包含/执行规则](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-includeexclude-rules)
    -   [更新规则](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-updating-rules)
-   [现行规则](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-available-rules)
-   [贡献规则](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-contributing-rules)
-   [从v1移徙](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-migration-from-v1)
-   [地方发展指挥部](https://npmcn.com/package/%40clipboard-health/ai-rules/#readme-local-development-commands)

## 安装

```bash
npm install --save-dev @clipboard-health/ai-rules
```

## 使用量

### 快速启动

1.  如果你有一个存在 `AGENTS.md` 和(或) `CLAUDE.md` 文件中的文件,将其重命名为 `OVERLAY.md`。同步脚本附加此文件的内容生成 `AGENTS.md` 因此它被装入LLM代理上下文.
    
2.  选择匹配您的工程类型的配置 :
    
    | 简介 | 包括 | 用于 |
    | --- | --- | --- |
    | `common` | 常见 | TypeScript 库, 通用项目 |
    | `frontend` | 常见 + 前端 | 反应应用程序,网络应用程序 |
    | `backend` | 常见 + 后端 | NestJS服务,APIs |
    | `fullstack` | 常见 + 前端 +后端 | 单相机、全相机 |
    | `datamodeling` | 数据建模 | DBT 数据建模 |
    
3.  把它加进你的 `package.json`数字 :
    
    ```json
    {
      "scripts": {
        "sync-ai-rules": "node ./node_modules/@clipboard-health/ai-rules/scripts/sync.js [PROFILE_NAME]",
        "postinstall": "node --run sync-ai-rules"
      }
    }
    ```
    
4.  运行 :
    
    ```bash
    npm install  # Runs postinstall automatically
    ```
    
5.  提交生成的文件 :
    
    ```bash
    git add .rules/ AGENTS.md CLAUDE.md
    git commit -m "feat: add AI coding rules"
    ```
    

### 包含/执行规则

微调使用哪些规则同步 `--include` 财务报告和审定财务报表 `--exclude`数字 :

```bash
# Backend profile without MongoDB rules
node sync.js backend --exclude backend/mongodb

# Common profile plus one backend rule
node sync.js common --include backend/architecture

# Multiple overrides
node sync.js backend --exclude backend/mongodb backend/postgres --include frontend/testing
```

不明规则的ID被跳过 警告,所以僵化 `--include`编号 :`--exclude` 永不中断安装.

更新您的 `package.json` 脚本相应:

```json
{
  "scripts": {
    "sync-ai-rules": "node ./node_modules/@clipboard-health/ai-rules/scripts/sync.js backend --exclude backend/mongodb"
  }
}
```

### 更新规则

当我们发布新的规则或改进:

```bash
# Update the package
npm update @clipboard-health/ai-rules

# The postinstall script automatically syncs the latest files
npm install

# Review the changes
git diff .rules/ AGENTS.md

# Commit the updates
git add .rules/ AGENTS.md CLAUDE.md
git commit -m "chore: update AI coding rules"
```

规则偶尔被拆分,所以每个都带有更窄的检索触发器. 如果你给个人规则编号 `--include` 而不是取一个完整类别, 请在升级后检查 diff 是否为新的 id: stale `--include` 继续解决,所以你失去了 分出规则,没有警告.

## 现行规则

每个规则的"何时阅读"文本都来自 `description` 字段在规则文件的 YAML 前题中——用于生成的真理的单一来源 `AGENTS.md` 指数和下表.

### 后端

| 规则ID | 何时读取 |
| --- | --- |
| `backend/architecture` | 搭建NestJS模块、服务、重置:三级、微服务、ts-rest合同 |
| `backend/asyncMessaging` | 与队列、 同步消息或背景任务合作; 规划其展开或回滚; 添加事件依赖行为 |
| `backend/infrastructure` | 提供基础设施:Terraform、Docker、ECS、DNS |
| `backend/mongodb` | 与MongoDB/Mongoose合作:计划、指数、查询、交易、迁移 |
| `backend/notifications` | 通过敲门执行通知:推动通知、深层链接、工作流程设计 |
| `backend/postgres` | 与 Postgres 合作: 列类型、 方案变化、 查询模式、 Prisma TypedSQL |
| `backend/restApiDesign` | 设计 REST API: JSON: API, 认证, 验证, pagination, ts-rest 合同, DTOs |
| `backend/serviceTests` | 写入服务测试:测试数据、背景工作、错误处理、迁移 |

### 常见

| 规则ID | 何时读取 |
| --- | --- |
| `common/aiRules` | 编辑剪贴板代理指令:共享规则,寄存器覆盖,或生成.rules,AGENTS.md,和 CLAUDE.md 文件 |
| `common/ciRunners` | 写入或编辑 GitHub 动作工作流程:选择运行中的跑者,跑者 OS 和 egress 约束 |
| `common/commentsAndCopy` | 写入代码注释、文件、 UI 副本或标识名称 |
| `common/configuration` | 添加配置、秘密或第三方依赖:SSM、LOUSTDAKLY、DB、国家预防机制软件包 |
| `common/containerRegistry` | 选择或拉出容器图像: Dockerfile from, 编译服务, CI 工作流程图像 |
| `common/coreLibraries` | 添加依赖性、 执行功能或调试涉及 @ clipboard- health/ \* 库的错误 |
| `common/dateTime` | 使用日期、时间、时区或日期比较 |
| `common/errorHandling` | 返回或扔出错误: 服务结果、 服务错误、 错误 |
| `common/featureFlags` | 创建或管理特征标记:命名、生命周期、SDK使用、Zod schemas |
| `common/gitWorkflow` | 写入承诺信件、 PR 标题和描述, 或审查拉动请求 |
| `common/groundtruth` | 根据剪贴板具体情况做出工程决定 |
| `common/libraryAuthoring` | 授权共享库代码 : @ clippboard- health/ \* 软件包或服务内部共享库模块( 如 src/ lib) |
| `common/localChecks` | 正在本地进行类型检查、 提示或测试以验证更改 |
| `common/loggingObservability` | 增加记录、衡量、监测或可观察性:水平、上下文、PII、数据犬 |
| `common/rulesEngine` | 写入或修改 @ clipboard- health/ rules- engine 规则函数 |
| `common/testing` | 写作单位测试:常规,命名,结构 |
| `common/typeScript` | 写入任意类型脚本代码 |

### 数据建模

| 规则ID | 何时读取 |
| --- | --- |
| `datamodeling/analytics` | 查询分析数据: dbt- mcp, 雪花, 源列, 输出格式 |
| `datamodeling/castingDbtStagingModels` | Dbt 置放模型中的数据类型 |
| `datamodeling/dbtModelDevelopment` | 开发 dbt 模型或诊断计划及摄取失败 |
| `datamodeling/dbtYamlDocumentation` | 写入 dbt YAML 文档和计划文件 |

### 前端

| 规则ID | 何时读取 |
| --- | --- |
| `frontend/architecture` | 前端架构:基于特性的文件组织,其中商业逻辑存在 |
| `frontend/customHooks` | 创建自定义钩: 命名, 共享状态与复数 |
| `frontend/dataFetching` | 执行数据获取、 API 响应定着和错误处理: React Query、 MSW、 Playwright、 缓存、 解析Api |
| `frontend/designSystem` | 从设计系统或 Figma 执行 UI: 偏好共享组件, 主题浏览, 可选代码连接 |
| `frontend/e2eTesting` | 为已注册的关键流量选择和写 Playwright E2E 测试 |
| `frontend/reactComponents` | 构建用户界面组件:结构、组成、模式、底页、交互式元素、a11y、故事书 |
| `frontend/renderScope` | 添加或重组 React 状态、 上下文、 勾钩返回、 站点值、 隐藏查询/ 订阅或列表过滤 |
| `frontend/styling` | 带有MUI sx道具的样式组件:主题符,间隔,无 CSS/ 常设委员会 |
| `frontend/testing` | 写入前端测试: React Testing 库, 组件测试 |

## 贡献规则

一个规则只有在边疆模型没有它会做错事情的情况下才能获得它的地位:剪贴板特有决定,图书库选择,命名,和来之不易的Gotchas. 不要添加教程、通用最佳做法或任何已经执行的线条.

增加或修改一项规则:

1.  编辑或创建规则文件 `rules/<category>/` 带有前题 `description` ("何时读"正文.
2.  运行 `npx tsx scripts/populateReadme.ts` 重新生成上表(如果漂移,测试失败).
3.  新建类别为目录 `rules/`;不需要登记.

## 从v1移徙

v2 替换单曲 `AGENTS.md` 采用基于检索的方法。 规则文件现在被输入您的重播 `.rules/`。 。 。 .

1.  更新软件包 :
    
    ```bash
    npm install --save-dev @clipboard-health/ai-rules@latest
    ```
    
2.  运行安装以触发同步 :
    
    ```bash
    npm install
    ```
    
3.  添加 `.rules/` 承诺:
    
    ```bash
    git add .rules/ AGENTS.md CLAUDE.md
    git commit -m "feat!: update ai-rules to v2 retrieval-based approach"
    ```
    

## 地方发展指挥部

见 [`package.json`](https://npmcn.com/package/%40clipboard-health/ai-rules/package.json) `scripts` 用于命令列表.

## 常见问题

### @clipboard-health/ai-rules 是什么？

为一致的编码标准预建的AI代理规则\.注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

### 如何安装 @clipboard-health/ai-rules？

在项目目录运行 npm install @clipboard-health/ai-rules，或使用 pnpm add / yarn add / bun add。

### @clipboard-health/ai-rules 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/clipboard-health\_\_ai-rules 是否存在。

### @clipboard-health/ai-rules 可以商用吗？

@clipboard-health/ai-rules 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @clipboard-health/ai-rules 的下载量有多少？

根据 npm 官方下载统计，@clipboard-health/ai-rules 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,090 次，日均约 70 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @clipboard-health/ai-rules 还在维护吗？

最新版本 2\.50\.28 发布于 2026/10/09（1 个月前）；至今共发布 500 个版本，其中过去 12 个月发布了 475 个；首次发布于 2025/10/14。作者已将其标记为弃用，新项目建议寻找替代方案。