# AI 技能库 (ai-skills) 团队快速上手指南

本仓库是团队统一的 **AI 技能库 (AI Skills Library)**，用于集中管理、版本控制和分发团队在开发中沉淀的架构经验、安全红线、编码规范及事故防范规则。

通过将 AI 规则“代码化”，我们消除了个人配置散落、过期或风格不一致的问题，确保所有团队成员的 AI 辅助编程助手（如 **Trae AI**、**Cursor** 等）能够以统一且高水准的上下文为日常开发提供建议。

---

## 1. 技能库核心目录结构

本仓库的规则采用场景化分组，避免将所有规则塞入单一巨大文件而导致 AI 上下文爆炸。

```text
ai-skills/
├── base/                   # 🚀 基础规则：全员、全项目必须强制加载的底线规则
│   ├── coding-style.md     # 通用代码风格与最佳实践
│   ├── pr-review.md        # Pull Request 描述模板与自检指南
│   ├── security-rules.md   # 安全红线（禁止硬编码密钥、敏感数据合规等）
│   └── testing.md          # 单元测试与 Mock 编写标准
├── frontend/               # 🎨 前端规则：前端工程专用
│   ├── react-components.md # React 组件与状态管理规范
│   ├── web-vitals.md       # 性能与 Web Vitals 优化建议
│   └── accessibility.md    # 无障碍 (a11y) 实践
├── backend/                # ☕ 后端规则：后端与 API 架构规则
│   ├── api-design.md       # RESTful API 设计与版本控制
│   ├── error-handling.md   # 健壮的异常处理与日志记录规范
│   └── spring-boot-patterns.md # Spring Boot / Java 高性能模式
├── devops/                 # 🛠️ 运维规则：容器、CI/CD 与观测性规范
│   ├── ci-cd.md            # GitHub Actions / GitLab CI 规范
│   └── observability.md    # Prometheus / Grafana 指标与链路追踪要求
└── meta/                   # ⚙️ 技能库治理：如何编写与演进规则
    ├── how-to-create-new-skill.md # 新增技能指南与 Markdown 模板
    └── repeated-feedback-to-skill.md # 如何将 Code Review 重复反馈转化为技能
```

---

## 2. 一键导入：全局用户规则 (User Rules)

全局规则对您本机上的所有项目生效。推荐将团队底线与安全规则 (`base/` 下的所有规则) 导入到全局中。

### 💡 Windows 环境

在 Windows 环境下，全局规则文件存储在 `%USERPROFILE%\.trae\user_rules.md` (即 `C:\Users\<用户名>\.trae\user_rules.md`)。您可以通过以下两种方式导入：

#### 方式 A：运行一键导入脚本（推荐，全自动合并）
打开 **CMD 命令行**，切换到本技能库的根目录，直接运行以下命令：
```cmd
:: 运行此脚本无需管理员权限，它会自动将 base/*.md 合并后安全写入全局配置文件
call scripts\import-global-rules.bat
```

#### 方式 B：手动复制导入
1. 打开 Trae IDE，点击 AI 侧边栏右上角的 **设置（齿轮图标） -> 规则 (Rules)**。
2. 在 **Personal Rules** 区域，点击 **“+ 创建 user_rules.md”**（如已存在则直接点击编辑）。
3. 打开技能库 `base/` 目录下的 Markdown 文件（例如 `security-rules.md` 和 `coding-style.md`），将其中的核心内容手动复制粘贴至 Trae 编辑器中保存。

---

### 🍎 macOS / Linux 环境

在 macOS/Linux 环境下，可以通过简单的终端命令合并并写入全局路径下：

```bash
# 确保目标配置目录存在
mkdir -p ~/.trae

# 将 base 下的所有 markdown 规则合并写入全局 user_rules.md
cat ~/ai-skills/base/*.md > ~/.trae/user_rules.md
```

---

## 3. 一键同步：已有项目规则 (Project Rules)

项目规则保存在具体项目的隐藏目录 `<项目根目录>\.trae\rules\` 中，**优先级高于全局规则**。为了不让无关的规则污染 AI 上下文，我们使用免管理员特权的智能探测脚本，按技术栈精准导入。

### 💡 Windows 环境

在已有项目的开发中，您无需手动拷贝规则，只需通过 CMD 一键注入即可：

1. 打开 **CMD 命令行**，使用 `cd` 切换到您**已有项目的根目录**：
   ```cmd
   cd /d D:\workspace\my-existing-project
   ```
2. 调用技能库中的同步脚本，并传入**技能库的绝对路径**（假设技能库解压在 `D:\ai-skills`）：
   ```cmd
   call D:\ai-skills\scripts\sync-trae-skills.bat D:\ai-skills
   ```

---

### 🍎 macOS / Linux 环境

在 macOS/Linux 的**已有项目根目录**中执行以下命令（通过环境变量 `SKILLS_REPO` 指定技能库的绝对路径）：

```bash
# 假设技能库克隆在 ~/ai-skills
SKILLS_REPO=~/ai-skills bash ~/ai-skills/scripts/sync-trae-skills.sh
```

---

### 🔍 智能探测与分发逻辑

同步脚本运行时，会在已有项目中自动探测以下文件并精准注入规则：
*   **强制注入**：不论什么项目，强制同步 `base/` 目录下的安全、测试与规范红线。
*   **前端项目（检测到 package.json）**：自动载入 `frontend/` 下的 React / Web Vitals 等前端专属规则。
*   **Java 后端（检测到 pom.xml / gradle）**：自动载入 `backend/` 下的 Spring Boot / 错误处理后端规则。
*   **平台工程（检测到 Dockerfile / k8s）**：自动载入 `devops/` 下的 CI-CD 与可观测性运维规则。

---

## 4. 高级项目集成方式（强烈推荐）

为避免团队成员手动执行同步，建议在项目配置中实现**自动化注入**。

### A. 前端项目自动集成 (`package.json`)

在您的前端项目中，可以将同步指令绑定到 `prepare` 钩子中，这样每次执行 `npm install` / `pnpm install` 时，AI 规则都会自动更新：

```json
"scripts": {
  "prepare": "node -e \"const os = require('os'); const { execSync } = require('child_process'); if (os.platform() === 'win32') { execSync('..\\\\ai-skills\\\\scripts\\\\sync-trae-skills.bat', { stdio: 'inherit' }); } else { execSync('bash ../ai-skills/scripts/sync-trae-skills.sh', { stdio: 'inherit' }); }\""
}
```

### B. 多技术栈通用集成 (`Makefile`)

如果项目使用 `Makefile` 管理常用指令，可以增加如下目标：

```makefile
.PHONY: sync-skills
sync-skills:
ifeq ($(OS),Windows_NT)
	@cmd /c ..\ai-skills\scripts\sync-trae-skills.bat ..\ai-skills
else
	@bash ../ai-skills/scripts/sync-trae-skills.sh --source ../ai-skills
endif
```

---

## 5. 规则在 IDE 中的生效机制

以 **Trae AI** 为例，同步成功后，规则文件将位于项目根目录的 `.trae/rules/*.md` 中。

1. **自动感知**：Trae AI 会自动扫描并读入 `.trae/rules/` 下的所有 Markdown 文件作为 Project Rules。
2. **规则优先级**：**项目规则 (Project Rules) > 个人全局规则 (User Rules)**。如果在特定项目中遇到规则冲突，Trae 将优先遵循项目规则，从而确保团队标准的强一致性。
3. **效果确认**：您可以在 AI 聊天对话框中直接输入 “*请根据当前项目的 Trae Project Rules 对以下代码进行审查*” 来验证规则是否已正确加载。

---

## 6. 如何为本库贡献新技能 (Prompts as Code)

技能库是一个像代码一样持续演进的系统。我们鼓励“**同一个问题在 CR 或生产事故中出现超过 3 次，就必须沉淀为一条 AI 技能**”的原则。

### 6.1 技能文件规范

所有新技能必须采用结构化的 Markdown 文件，放置于相应目录下，且必须包含 YAML 元数据 (Frontmatter)：

```markdown
---
name: backend-api-error-handling
owner: backend-team-leader      # 维护人，负责规则的跟进与废弃
scope: backend/**/*.py           # 适用文件范围
required: true                  # 是否是该目录下的强制加载规则
updated: 2026-05-22             # 更新日期
---

# 后端 API 错误处理规则

## 适用场景
当你修改后端 API、服务层或外部服务调用代码时，必须使用本规则。

## 核心规则
1. 外部 API 调用必须设置明确的超时时间（timeout）。
2. 禁止使用裸 exception 捕获吞掉错误，必须至少记录 warning 级别的上下文日志。

## 禁止事项
- 禁止硬编码任何凭据、Token、内部 IP。
- 禁止为了规避测试报错而直接删除断言或 Mock。

## 验证方式
修改完成后，必须在终端执行以下命令进行自检：
```bash
pytest tests/ -v
ruff check .
```

## 常见错误与正确示例
- **错误示范**：
  ```python
  try:
      resp = requests.get(url)
  except Exception:
      pass
  ```
- **正确示范**：
  ```python
  try:
      resp = requests.get(url, timeout=5)
  except requests.RequestException as exc:
      logger.error(f"Failed to fetch external resources: {url}", exc_info=exc)
      raise ServiceUnavailable("External dependency error") from exc
  ```
```

### 6.2 提交贡献流程

1. 本地在 `ai-skills` 对应分类目录（如 `backend/`）下创建或修改 Markdown 规则。
2. 创建 Git 分支，提交变更并推送。
3. 提起 **Pull Request**，指定相关维护人 (Owner) 进行 Review。
4. **Review 重点**：
   - 规则是否语义明确、可执行，避免空洞的“写出高质量代码”。
   - 是否包含明确的“验证方式/自检命令”。
   - 是否包含反面教材（错误示范）和正确方向示范。
5. 合并入 `main` 分支后，全员即可通过同步脚本拉取最新规则。