---
name: how-to-create-new-skill
description: "团队新增 AI 技能规则的指导规范。适用于任何开发人员为本项目贡献、编写新 AI 规则的贡献规范。"
globs: ["base/**/*.md", "frontend/**/*.md", "backend/**/*.md", "devops/**/*.md", "meta/**/*.md", "README.md"]
alwaysApply: false
updated: 2026-05-22
---

# 团队新增 AI 技能规则的指导规范

> [!IMPORTANT]
> 技能库是团队集体工程智慧的结晶。为防止技能库膨胀、失效或产生误导，任何开发人员为本项目新建 AI 技能规则时，必须严格遵守本项元规范声明的格式与评审门槛。

## 1. 适用场景

当您因为项目架构升级、引入新框架（如 Next.js App Router 或者是 FastAPI）、发生高频事故，或对高频 Code Review 意见进行提炼而需要为团队新建/修改一条 AI 规则文件时。

## 2. 操作规则

1. **选择正确的存放目录 (Structured Storage)**：
   - 基础/强制性红线 -> 放于 `base/` 目录下。
   - 前端专属规范 -> 放于 `frontend/` 目录下。
   - 后端专属规范 -> 放于 `backend/` 目录下。
   - 部署/监控运维 -> 放于 `devops/` 目录下。
   - 规则文件命名一律使用小写中划线格式（例如 `react-hooks-standards.md`）。
2. **声明精准的 YAML 元数据块 (Precise Frontmatter)**：
   - 必须在 Markdown 文件首行以 `---` 包裹提供完整的 YAML 元数据：
     - `name`：规则的唯一短标识（如 `react-components`）。
     - `description`：高信息密度的简短目的描述，供主流 AI 引擎在对话时进行精准匹配加载。
     - `globs`：限定匹配生效的文件 glob 模式数组（如 `["**/*.tsx", "src/hooks/**/*.ts"]`）。
     - `alwaysApply`：仅有最高安全红线和 PR 格式等底线规则设为 `true`，其余专业规则务必设为 `false`，防 Token 溢出与规则误用。
3. **强制包含核心 5 大板块 (Five Must-Have Sections)**：
   - 每一个新技能文件内部，必须显式包含并填充以下五个二级标题板块：
     - `## 1. 适用场景`
     - `## 2. 操作规则` (清晰具体、具有动作指向的指令条目)
     - `## 3. 禁止事项`
     - `## 4. 验证方式` (本地可以运行的测试或静态校验命令)
     - `## 5. 代码对比示例` (1:1 完整的 Bad/Good 对比)

## 3. 禁止事项

- 严禁空发文字描述。禁止在没有提供具体“验证方式”和“代码对比示例”的情况下提交纯文字口号式空洞规范。

## 4. 验证方式

- 运行 Markdown 语法格式校验工具；如果仓库已安装 `markdownlint-cli`，执行 `markdownlint "**/*.md"`。
- 运行 `bash scripts/sync-trae-skills.sh --source . --dest /tmp/ai-skills-sync-check` 验证该新文件是否能够被正确分类探测并复制成功。Windows 环境使用 `scripts\sync-trae-skills.bat <source> <dest>` 执行等价验证。

## 5. 标准 YAML 头模板

````markdown
---
name: backend-redis-cache
description: "Redis 缓存层操作规范。限制循环调用 Redis、定义 key 命名空间及防缓存击穿锁隔离逻辑。"
globs: ["backend/services/cache/**/*.py", "backend/views/cached_*.py"]
alwaysApply: false
updated: 2026-05-22
---

# Redis 缓存操作规范

## 1. 适用场景

当新增或修改 Redis 缓存读写、缓存 key 设计、缓存失效策略或防击穿逻辑时生效。

## 2. 操作规则

- 缓存 key 必须包含稳定命名空间、业务对象类型和唯一标识，例如 `user:profile:{userId}`。
- 热点缓存必须设置合理 TTL，并对高并发回源路径使用互斥锁或单飞机制防止缓存击穿。

## 3. 禁止事项

- 禁止在循环中逐条同步调用 Redis 造成 N+1 访问。
- 禁止将用户敏感信息明文写入共享缓存 key。

## 4. 验证方式

- 运行缓存层单元测试，覆盖命中、未命中、过期和回源失败场景。
- 检查日志或指标，确认高并发回源不会出现重复击穿。

## 5. 代码对比示例

### 错误示例

```python
for user_id in user_ids:
    redis.get(f"profile:{user_id}")
```

### 正确方向

```python
keys = [f"user:profile:{user_id}" for user_id in user_ids]
profiles = redis.mget(keys)
```
````